Create FUNDING.yml

Documentation updates which fix: 
* #25 
* #20

.github/FUNDING.yml

@@ -0,0 +1,2 @@
+# These are supported funding model platforms
+open_collective: dominion-solutions-foss/projects/ansible-netbird

.github/ISSUE_TEMPLATE/bug.yml

@@ -28,23 +28,23 @@ body:
     attributes:
       label: Package Version
       description: What version of our Package are you running? Please be as specific as possible
-      placeholder: 2.0.0
+      placeholder: 0.1.5
     validations:
       required: true
   - type: input
-    id: php-version
+    id: python-version
     attributes:
-      label: PHP Version
-      description: What version of PHP are you running? Please be as specific as possible
-      placeholder: 8.2.0
+      label: Python Version
+      description: What version of Python are you running? Please be as specific as possible
+      placeholder: 3.10.12
     validations:
       required: true
   - type: input
-    id: laravel-version
+    id: ansible-version
     attributes:
-      label: Laravel Version
-      description: What version of Laravel are you running? Please be as specific as possible
-      placeholder: 9.0.0
+      label: Ansible Version
+      description: What version of Ansible Core are you running? Please be as specific as possible
+      placeholder: 2.16.4
     validations:
       required: true
   - type: dropdown
@@ -57,6 +57,7 @@ body:
         - macOS
         - Windows
         - Linux
+        - BSD
   - type: textarea
     id: notes
     attributes:

.github/workflows/publish-to-ansible-galaxy.yml

@@ -3,26 +3,27 @@ on:
   release:
     types: [published]
 jobs:
-  update-version:
+  update-version-and-publish:
     permissions:
       contents: write
     runs-on: ubuntu-latest
     steps:
     - uses: actions/checkout@v4
+      with:
+        ref: main
+        token: ${{ secrets.DEVOPS_BOT_PAT }}
 
     - name: Update version
       run: |
         echo "Updating version"
         sed -i "s/version: .*/version: ${{ github.event.release.tag_name }}/g" galaxy.yml
+
     - uses: stefanzweifel/git-auto-commit-action@v4
       with:
-        commit_message: "Update version to ${{ github.event.release.tag_name }}"
+        commit_message: "Update galaxy.yml version to ${{ github.event.release.tag_name }}"
         branch: "main"
-
-  ansible-publish:
-    runs-on: ubuntu-latest
-    steps:
-    - uses: actions/checkout@v4
+        file_pattern: "galaxy.yml"
+        push_options: --force
 
     - uses: ansible/ansible-publish-action@v1.0.0
       with:

CHANGELOG.md

@@ -1,3 +1,95 @@
 # Changelog
 
 All notable changes to this project will be documented in this file.
+
+## Bug Fixes - Parameters - 2024-04-03
+
+### Bug Fixes
+
+Thanks to @ipsecguy for pointing out that there was an issue with the compose variables.
+
+- #28 - The compose parameter is updated to accept a `dict()` now.
+- The documentation has been improved as well.
+- Some small issues around creating bugs / questions have been resolved.
+
+### What's Changed
+
+* Update README.md by @spam-n-eggs in https://github.com/dominion-solutions/ansible-netbird/pull/26
+* Fixes #28 - Tested with a separate inventory. by @spam-n-eggs in https://github.com/dominion-solutions/ansible-netbird/pull/29
+
+**Full Changelog**: https://github.com/dominion-solutions/ansible-netbird/compare/0.1.6...0.2.0
+
+## Fixed an accidental bug in the last release - 2024-03-11
+
+Bug was accidentally released in the last release.  Fixed.
+
+### What's Changed
+
+* Mjh/fix issues with message by @spam-n-eggs in https://github.com/dominion-solutions/ansible-netbird/pull/24
+
+**Full Changelog**: https://github.com/dominion-solutions/ansible-netbird/compare/0.1.5...0.1.6
+
+## Small Bugfixes - 2024-03-11
+
+Minor fixes including:
+
+- #14 Error on bad credentials.
+- #22 Wrapped bad urls in an AnsibleError
+- #20 The issue templates were bad.
+
+### What's Changed
+
+* Mjh/14/error out on bad credentials by @spam-n-eggs in https://github.com/dominion-solutions/ansible-netbird/pull/23
+
+**Full Changelog**: https://github.com/dominion-solutions/ansible-netbird/compare/0.1.4...0.1.5
+
+## Documentation updates - 2024-03-01
+
+Closes #16
+
+### What's Changed
+
+* Updated Readme in a big way. by @spam-n-eggs in https://github.com/dominion-solutions/ansible-netbird/pull/17
+
+**Full Changelog**: https://github.com/dominion-solutions/ansible-netbird/compare/0.1.3...0.1.4
+
+## Securtity Vulnerability Fixes - 2024-02-24
+
+Fixes security vulnerabilities
+
+### What's Changed
+
+* Bump cryptography from 42.0.2 to 42.0.4 by @dependabot in https://github.com/dominion-solutions/ansible-netbird-role/pull/9
+* 'Fixed' Galaxy commit step by @spam-n-eggs in https://github.com/dominion-solutions/ansible-netbird-role/pull/10
+* updated the steps to the galaxy.yml update gets included. by @spam-n-eggs in https://github.com/dominion-solutions/ansible-netbird-role/pull/11
+
+### New Contributors
+
+* @dependabot made their first contribution in https://github.com/dominion-solutions/ansible-netbird-role/pull/9
+
+**Full Changelog**: https://github.com/dominion-solutions/ansible-netbird-role/compare/0.1.2...0.1.3
+
+## Security Vulnerability Fixes - 2024-02-24
+
+Fixes security vulnerabilities
+
+### What's Changed
+
+* Bump cryptography from 42.0.2 to 42.0.4 by @dependabot in https://github.com/dominion-solutions/ansible-netbird-role/pull/9
+* 'Fixed' Galaxy commit step by @spam-n-eggs in https://github.com/dominion-solutions/ansible-netbird-role/pull/10
+
+### New Contributors
+
+* @dependabot made their first contribution in https://github.com/dominion-solutions/ansible-netbird-role/pull/9
+
+**Full Changelog**: https://github.com/dominion-solutions/ansible-netbird-role/compare/0.1.2...0.1.3
+
+## [Bug] Not all groups being found - 2024-02-24
+
+This release fixes a critical bug where not all groups were being found during the list comprehension that was finding all of the groups.
+
+### What's Changed
+
+* Fixed issues with the groups list comprehension by @spam-n-eggs in https://github.com/dominion-solutions/ansible-netbird-role/pull/8
+
+**Full Changelog**: https://github.com/dominion-solutions/ansible-netbird-role/compare/0.1.1...0.1.2

README.md

@@ -1,3 +1,106 @@
-# Ansible Collection - dominion_solutions.netbird
+dominion_solutions.netbird
+---
+This collection allows you to manage your netbird servers.
 
-Documentation for the collection.
+- [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)
+- [Contributing](#contributing)
+- [Contributors](#contributors)
+
+
+# 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/
+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/
+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` |       |
+
+# Contributing
+Please see [CONTRIBUTING.md](https://github.com/dominion-solutions/ansible-netbird/blob/main/.github/CONTRIBUTING.md)
+
+# Contributors
+- [Mark J. Horninger](https://github.com/spam-n-eggs)
+- [All Contributors](https://github.com/dominion-solutions/ansible-netbird/graphs/contributors)

galaxy.yml

@@ -8,7 +8,7 @@ namespace: dominion_solutions
 name: netbird
 
 # The version of the collection. Must be compatible with semantic versioning
-version: 0.1.2
+version: 0.2.0
 
 # The path to the Markdown (.md) readme file. This path is relative to the root of the collection
 readme: README.md

plugins/inventory/netbird.py

@@ -59,9 +59,8 @@ options:
         description: Whether or not to fail if a group or variable is not found.
     compose:
         description: compose variables for Ansible based on jinja2 expression and inventory vars
-        default: False
         required: False
-        type: boolean
+        type: dict
     keyed_groups:
         description: create groups for plugins based on variable values and add the corresponding hosts to it
         type: list
@@ -148,7 +147,10 @@ class InventoryModule(BaseInventoryPlugin, Constructable, Cacheable):
 
     def _get_peer_inventory(self):
         """Get the inventory from the Netbird API"""
-        self.peers = self.client.ListPeers()
+        try:
+            self.peers = self.client.ListPeers()
+        except Exception:
+            raise AnsibleError("Could not retrieve the Netbird inventory.  Check the API Key and URL.")
 
     def _filter_by_config(self):
         """Filter peers by user specified configuration."""
@@ -286,6 +288,9 @@ class NetbirdApi:
         }
         peers = []
         response = requests.request("GET", url, headers=headers)
+        if response.status_code in [401, 404]:
+            raise Exception(f"{response.status_code}: {response.text}\nPlease check the API Key and URL.")
+
         peer_json = json.loads(response.text)
         for current_peer_map in peer_json:
             current_peer = Peer(current_peer_map["hostname"], current_peer_map['dns_label'], current_peer_map["id"], current_peer_map)

requirements.txt

@@ -1,7 +1,7 @@
 ansible>=9.2.0
 ansible-core>=2.16.3
 cffi==1.16.0
-cryptography==42.0.2
+cryptography==42.0.4
 epdb==0.15.1
 Jinja2==3.1.3
 jsonpickle==3.0.3

tests/unit/module_utils/inventories/fixtures/ip_address.netbird.yml

@@ -0,0 +1,13 @@
+---
+plugin: dominion_solutions.netbird.netbird
+api_key: nbp_this_is_a_fake_api_key
+api_url: https://netbird.example.com/api/v1
+ip_style: plain
+strict: No
+netbird_connected: No
+netbird_groups:
+groups:
+keyed_groups:
+compose:
+  ansible_ssh_host: ip
+  ansible_ssh_port: 22

tests/unit/module_utils/inventories/fixtures/only_connected.netbird.yml

@@ -9,3 +9,4 @@ groups:
 strict: No
 keyed_groups:
 compose:
+  ansible_ssh_host: ip

tests/unit/module_utils/inventories/fixtures/peers_spaces_in_group.json

@@ -0,0 +1,74 @@
+[
+    {
+      "accessible_peers_count": 1,
+      "approval_required": false,
+      "city_name": "",
+      "connected": false,
+      "connection_ip": "",
+      "country_code": "",
+      "dns_label": "apple.netbird.cloud",
+      "geoname_id": 0,
+      "groups": [
+        {
+          "id": "3aBcD4eF5gHiJ6kLmNoP",
+          "name": "All",
+          "peers_count": 2
+        },
+        {
+            "id": "2j3k4l5m6n7o8p9q0r1",
+            "name": "Test Group With Spaces",
+            "peers_count": 1
+        }
+      ],
+      "hostname": "apple",
+      "id": "2j3k4l5m6n7o8p9q0r1",
+      "ip": "10.10.10.123",
+      "kernel_version": "",
+      "last_login": "2024-02-10T22:01:27.744131502Z",
+      "last_seen": "2024-02-11T03:21:42.202104672Z",
+      "login_expiration_enabled": true,
+      "login_expired": false,
+      "name": "apple",
+      "os": "Linux Mint 21.3",
+      "ssh_enabled": false,
+      "ui_version": "netbird-desktop-ui/0.25.7",
+      "user_id": "auth0|abc123xyz4567890defg",
+      "version": "0.25.7"
+    },
+    {
+      "accessible_peers_count": 1,
+      "approval_required": false,
+      "city_name": "New York",
+      "connected": true,
+      "connection_ip": "146.123.45.67",
+      "country_code": "US",
+      "dns_label": "banana.netbird.cloud",
+      "geoname_id": 1234567,
+      "groups": [
+        {
+          "id": "2j3k4l5m6n7o8p9q0r1",
+          "name": "Development",
+          "peers_count": 1
+        },
+        {
+          "id": "3aBcD4eF5gHiJ6kLmNoP",
+          "name": "All",
+          "peers_count": 2
+        }
+      ],
+      "hostname": "banana",
+      "id": "hkwJPXNUmGywCLo5S8Wg",
+      "ip": "10.10.10.124",
+      "kernel_version": "",
+      "last_login": "2024-02-02T11:20:05.934889112Z",
+      "last_seen": "2024-02-24T02:59:35.324496386Z",
+      "login_expiration_enabled": false,
+      "login_expired": false,
+      "name": "docker-manager",
+      "os": "Alpine Linux 3.19.1",
+      "ssh_enabled": false,
+      "ui_version": "",
+      "user_id": "",
+      "version": "0.25.5"
+    }
+  ]

tests/unit/module_utils/inventories/fixtures/spaces_in_group.netbird.yml

@@ -0,0 +1,18 @@
+---
+plugin: dominion_solutions.netbird.netbird
+api_key: nbp_this_is_a_fake_api_key
+api_url: https://netbird.example.com/api/v1
+ip_style: plain
+netbird_connected: False
+leading_separator: No
+netbird_groups:
+- "Test Group With Spaces"
+groups:
+  connected: connected
+  ssh_hosts: ssh_enabled
+strict: No
+keyed_groups:
+
+compose:
+  ansible_ssh_host: label
+  ansible_ssh_port: 22

tests/unit/plugins/inventory/test_netbird.py

@@ -58,6 +58,20 @@ def netbird_api_multigroup():
     return mock_netbird_api
 
 
+@pytest.fixture(scope="module")
+def netbird_api_spaces_in_group():
+    mock_netbird_api = NetbirdApi(None, None)
+    response_data = []
+    with open('tests/unit/module_utils/inventories/fixtures/peers_spaces_in_group.json') as peers_file:
+        peers_map = json.load(peers_file)
+        for data in peers_map:
+            response_data.append(Peer(data['hostname'], data['dns_label'], data['id'], data))
+
+    mock_netbird_api.ListPeers = MagicMock(return_value=response_data)
+
+    return mock_netbird_api
+
+
 def test_missing_access_token_lookup(inventory):
     loader = DataLoader()
     inventory._options = {'api_key': None, 'api_url': None}
@@ -111,3 +125,42 @@ def test_with_multiple_groups(inventory, netbird_api_multigroup):
     assert inventory.inventory.groups is not None
     assert 'All' in inventory.inventory.groups
     assert 'Development' in inventory.inventory.groups
+
+
+def test_with_multiple_groups(inventory, netbird_api_multigroup):
+    loader = DataLoader()
+    path = 'tests/unit/module_utils/inventories/fixtures/only_connected.netbird.yml'
+    inventory._build_client = MagicMock()
+    inventory.client = netbird_api_multigroup
+    inventory.parse(InventoryData(), loader, path, False)
+    assert inventory.inventory is not None
+    assert inventory.inventory.hosts is not None
+    assert inventory.inventory.groups is not None
+    assert 'All' in inventory.inventory.groups
+    assert 'Development' in inventory.inventory.groups
+
+
+def test_use_ip_address(inventory, netbird_api_multigroup):
+    loader = DataLoader()
+    path = 'tests/unit/module_utils/inventories/fixtures/ip_address.netbird.yml'
+    inventory._build_client = MagicMock()
+    inventory.client = netbird_api_multigroup
+    inventory.parse(InventoryData(), loader, path, False)
+    assert inventory.inventory is not None
+    assert inventory.inventory.hosts is not None
+    assert inventory.inventory.groups is not None
+    assert 'All' in inventory.inventory.groups
+    assert 'Development' in inventory.inventory.groups
+
+
+def test_use_group_with_spaces(inventory, netbird_api_spaces_in_group):
+    loader = DataLoader()
+    path = 'tests/unit/module_utils/inventories/fixtures/spaces_in_group.netbird.yml'
+    inventory._build_client = MagicMock()
+    inventory.client = netbird_api_spaces_in_group
+    inventory.parse(InventoryData(), loader, path, False)
+    assert inventory.inventory is not None
+    assert inventory.inventory.hosts is not None
+    assert inventory.inventory.groups is not None
+    assert 'All' in inventory.inventory.groups
+    assert 'Test Group With Spaces' in inventory.inventory.groups