Updated Readme in a big way.

2024-03-01 14:00:11 -05:00 · 2024-03-01 14:00:11 -05:00 · c2d11722f8
parent d983d504fc
commit c2d11722f8
1 changed files with 96 additions and 2 deletions
--- a/README.md
+++ b/README.md
@ -1,3 +1,97 @@
-# Ansible Collection - dominion_solutions.netbird
+# dominion_solutions.netbird
+This collection allows you to manage your netbird servers.

-Documentation for the collection.
+- [dominion\_solutions.netbird](#dominion_solutionsnetbird)
+  - [Required Python Libraries](#required-python-libraries)
+  - [Roles](#roles)
+    - [dominion\_solutions.netbird.netbird](#dominion_solutionsnetbirdnetbird)
+  - [Inventories](#inventories)
+    - [dominion\_solutions.netbird.netbird](#dominion_solutionsnetbirdnetbird-1)
+      - [Sample Inventory Setups](#sample-inventory-setups)
+        - [Retrieve All Netbird Peers in the _Development_ group](#retrieve-all-netbird-peers-in-the-development-group)
+        - [Retrieve all Netbird Peers that _are Connected_](#retrieve-all-netbird-peers-that-are-connected)
+        - [A More Complex example](#a-more-complex-example)
+      - [Available data for custom groupings](#available-data-for-custom-groupings)
+
+
+## Required Python Libraries
+- ansible ~=9.2.0
+- requests ~=2.31.0 (If using the inventory plugin)
+
+## Roles
+### dominion_solutions.netbird.netbird
+Applying this role will install the netbird client on the target machine.
+
+[Documentation](https://galaxy.ansible.com/ui/repo/published/dominion_solutions/netbird/content/role/netbird/)
+
+## Inventories
+### dominion_solutions.netbird.netbird
+This is a dynamic inventory generated based on the configuration in the netbird API.
+
+[Documentation](https://galaxy.ansible.com/ui/repo/published/dominion_solutions/netbird/content/inventory/netbird/)
+
+#### Sample Inventory Setups
+##### Retrieve All Netbird Peers in the _Development_ group
+```yaml
+---
+plugin: dominion_solutions.netbird.netbird
+api_url: https://api.netbird.io/api/
+api_key: nbp_this_is_a_fake_api_key
+netbird_groups:
+  - Development
+strict: No
+```
+
+##### Retrieve all Netbird Peers that _are Connected_
+```yaml
+---
+plugin: dominion_solutions.netbird.netbird
+api_key: nbp_this_is_a_fake_api_key
+api_url: https://netbird.example.com/api/v1
+netbird_connected: True
+```
+
+##### A More Complex example
+This example gets all peers in the _All_ group and builds the additional _connected_ and _ssh\_hosts_ groups, based on the keys.
+```yaml
+---
+plugin: dominion_solutions.netbird.netbird
+api_key: nbp_this_is_a_fake_api_key
+api_url: https://netbird.example.com/api/v1
+netbird_connected: False
+leading_separator: No
+netbird_groups:
+- "All"
+groups:
+  connected: connected
+  ssh_hosts: ssh_enabled
+strict: No
+keyed_groups:
+compose:
+  ansible_ssh_host: label
+  ansible_ssh_port: 22
+```
+#### Available data for custom groupings
+Fields are taken directly from the responses at the [Netbird Peers API](https://docs.netbird.io/api/resources/peers#list-all-peers) unless otherwise indicated
+
+| Field                     | Type      | Notes |
+| ------------------------- | --------- | ----- |
+| label                     | `string`  | `label` is a field generated as part of the inventory as an alias to the `dns_label` field. |
+| id                        | `string`  |       |
+| name                      | `string`  |       |
+| ip                        | `string`  |       |
+| connected                 | `boolean` |       |
+| last_seen                 | `string`  | This is is an [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601) UTC Date Time String |
+| os                        | `string`  | An OS Identifier such as `Linux Mint 21.3` or `Alpine Linux 3.19.1` |
+| version                   | `string`  | The version of the Netbird Client that is running on the Peer |
+| groups                    | `object`  | The groups object.  This is parsed into the the groups in the inventory by name.  |
+| enabled                   | `boolean` |       |
+| user_id                   | `string`  |       |
+| hostname                  | `string`  | The hostname part of the FQDN |
+| ui_version                | `string`  | Blank if there's no UI client installed, otherwise a version for the UI such as `netbird-desktop-ui/0.25.7` |
+| dns_label                 | `string`  | The Fully Qualified Domain Name for this peer. |
+| login_expiration_enabled  | `boolean` | Is this peer exempt from login expiration? |
+| login_expired             | `boolean` | Is the login for this expired? |
+| last_login                | `string`  |       |
+| approval_required         | `boolean` |       |
+| accessible_peers_count    | `integer` |       |