From adcdc02088f065990016cf16798c73170d5c4a3e Mon Sep 17 00:00:00 2001 From: Jack Carter <128555021+SunsetDrifter@users.noreply.github.com> Date: Mon, 18 May 2026 14:27:12 +0200 Subject: [PATCH] docs: add Ansible IaC guide for tenant configuration Document the community.ansible_netbird collection for managing NetBird resources (users, groups, setup keys, policies, networks, DNS, posture checks) declaratively via the REST API. Adds a new Infrastructure as Code subsection under Self-Host NetBird with room for future entries. Cross-links from the Automated Setup PAT bootstrap page since the collection is the natural next step after obtaining the first token. --- src/components/NavigationDocs.jsx | 7 ++ src/pages/selfhosted/automated-setup.mdx | 2 +- src/pages/selfhosted/iac/ansible.mdx | 121 +++++++++++++++++++++++ 3 files changed, 129 insertions(+), 1 deletion(-) create mode 100644 src/pages/selfhosted/iac/ansible.mdx diff --git a/src/components/NavigationDocs.jsx b/src/components/NavigationDocs.jsx index 709852c6a..44afab397 100644 --- a/src/components/NavigationDocs.jsx +++ b/src/components/NavigationDocs.jsx @@ -509,6 +509,13 @@ export const docsNavigation = [ links: [ { title: 'Quickstart Guide', href: '/selfhosted/selfhosted-quickstart' }, { title: 'Automated Setup', href: '/selfhosted/automated-setup' }, + { + title: 'Infrastructure as Code', + isOpen: false, + links: [ + { title: 'Ansible', href: '/selfhosted/iac/ansible' }, + ], + }, { title: 'Maintenance', isOpen: false, diff --git a/src/pages/selfhosted/automated-setup.mdx b/src/pages/selfhosted/automated-setup.mdx index 3bf115139..5c65203e7 100644 --- a/src/pages/selfhosted/automated-setup.mdx +++ b/src/pages/selfhosted/automated-setup.mdx @@ -94,7 +94,7 @@ curl -fsS "${NETBIRD_URL}/api/users" \ -H "Authorization: Token ${NETBIRD_PAT}" ``` -Common bootstrap tasks include creating users, service users, setup keys, groups, policies, and routes through the NetBird API. +Common bootstrap tasks include creating users, service users, setup keys, groups, policies, and routes through the NetBird API. To run these declaratively from a playbook, see [Configure NetBird with Ansible](/selfhosted/iac/ansible). For long-running automation, create a dedicated service user and PAT after bootstrap. Then delete or let the setup PAT expire. diff --git a/src/pages/selfhosted/iac/ansible.mdx b/src/pages/selfhosted/iac/ansible.mdx new file mode 100644 index 000000000..f4d646b58 --- /dev/null +++ b/src/pages/selfhosted/iac/ansible.mdx @@ -0,0 +1,121 @@ +export const description = 'Manage NetBird users, groups, peers, setup keys, policies, networks, DNS, and posture checks declaratively with the community.ansible_netbird collection.' + +# Configure NetBird with Ansible + +The [`community.ansible_netbird`](https://github.com/netbirdio/ansible-netbird) collection manages NetBird resources — users, groups, peers, setup keys, policies, networks, DNS, posture checks, and identity providers — declaratively against the [NetBird REST API](/api/introduction). Use it to define your tenant configuration in version control and reapply it from CI. + +The collection talks to the API of an existing NetBird instance. It does not install the NetBird client on machines and does not deploy the self-hosted server. It works against any NetBird tenant — cloud or self-hosted — that you can reach with a Personal Access Token. + +## Requirements + +- Ansible 2.12 or newer. +- Python 3.6 or newer on the Ansible control node. +- The Management API URL for your NetBird instance, for example `https://netbird.example.com`. +- A Personal Access Token (PAT) for a NetBird admin or service user. + +For a brand-new self-hosted instance with no users yet, see [Automated setup with a Personal Access Token](/selfhosted/automated-setup) to obtain the first PAT. + +## Install the collection + +The collection is not yet published to Ansible Galaxy. Build and install it from source: + +```bash +git clone https://github.com/netbirdio/ansible-netbird.git +cd ansible-netbird +ansible-galaxy collection build +ansible-galaxy collection install community-ansible_netbird-*.tar.gz +``` + +## Authenticate + +Modules accept credentials as parameters, environment variables, or role variables. Environment variables are the simplest for local runs and CI: + +```bash +export NETBIRD_API_URL="https://netbird.example.com" +export NETBIRD_API_TOKEN="nbp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" +``` + + +Set `api_url` to the base URL of your NetBird instance — do not include `/api`. The collection appends API paths automatically. + + + +Store the PAT in Ansible Vault, your CI's secret store, or an environment variable — never commit it to source control. + + +## First playbook + +This playbook creates a group and a reusable setup key bound to that group. Save it as `netbird.yml`: + +```yaml {{ title: 'netbird.yml' }} +- name: Configure NetBird tenant + hosts: localhost + gather_facts: false + tasks: + - name: Create a group for servers + community.ansible_netbird.netbird_group: + name: servers + state: present + register: servers_group + + - name: Create a reusable setup key for servers + community.ansible_netbird.netbird_setup_key: + name: server-enrollment + key_type: reusable + expires_in: 604800 + auto_groups: + - servers + state: present + register: setup_key + + - name: Show the setup key + ansible.builtin.debug: + msg: "Setup key: {{ setup_key.setup_key.key }}" + when: setup_key.changed +``` + +Run it against your tenant: + +```bash +ansible-playbook netbird.yml +``` + +Re-running the playbook is safe — every module is idempotent and reports `changed` only when the API state differs from the playbook. + +## What you can manage + +The collection ships a module for each resource type. Most useful ones: + +- **Users and service users** — `netbird_user` +- **Groups** — `netbird_group` +- **Peers** — `netbird_peer` (SSH, login expiration, name) +- **Setup keys** — `netbird_setup_key` (one-off or reusable, with auto-group assignment) +- **Policies** — `netbird_policy` +- **Networks, routers, and resources** — `netbird_network`, `netbird_network_router`, `netbird_network_resource` +- **DNS nameserver groups** — `netbird_nameserver_group` +- **Posture checks** — `netbird_posture_check` +- **Identity providers** — `netbird_identity_provider` +- **Personal access tokens** — `netbird_token` +- **Read any resource** — `netbird_info` + +For example playbooks covering each module, see [`examples/`](https://github.com/netbirdio/ansible-netbird/tree/main/examples) in the upstream repository. + +## Troubleshooting + +### Authentication fails with 401 or 403 + +- Confirm the PAT belongs to a user with admin permissions in the tenant. +- Confirm `NETBIRD_API_URL` points at the base URL without a trailing `/api` segment. +- Confirm the PAT has not expired or been revoked in the Dashboard. + +### TLS verification fails + +If your self-hosted instance uses an internal certificate authority, either install the CA on the control node's trust store or set `validate_certs: false` on the module call. Disabling certificate validation removes a defense against on-path attacks — prefer trusting the CA. + +### Setup keys are not visible in the playbook output + +Setup key values are masked by default. Use `register` on the task and reference `result.setup_key.key` in a `debug` task, as shown above. Store the value in a secret manager rather than printing it in CI logs. + +### Resources are not updated as expected + +For modules like `netbird_user`, `netbird_group`, and `netbird_setup_key`, omitting a list field (for example `auto_groups` or `peers`) preserves the existing value rather than clearing it. To remove all members, pass an explicit empty list (`[]`).