New playbook that wraps the export and configure roles into a safe
IaC pipeline:
1. BACKUP - exports current live state to timestamped backups/ dir
2. PREVIEW - shows read-only diff of what config changes would do
3. APPLY - applies changes (gated behind -e apply=true)
Safety features:
- Preview-only by default (no changes without explicit opt-in)
- Automatic backup before any apply (relative to config_dir, not
playbook_dir, so backups don't land inside the collection tree)
- Strict mode opt-in via -e use_strict=true
- Preview step skippable with -e preview=false to halve API calls
- Rollback by re-applying from a backup directory
- Input validation for required variables
Updated README Quick Start to recommend the safe workflow, and added
api_url clarification note.
list_dns_zone_records() returns null for zones with no records,
causing TypeError when iterating. Same pattern fixed in #20 for
other modules — this one was missed.
Added notes and examples for netbird_group, netbird_setup_key, and
netbird_user explaining that omitting list fields (peers, auto_groups)
on update preserves existing values instead of clearing them.
Changes module behavior so that omitting auto_groups, peers, or
similar list fields on update preserves the existing values instead
of wiping them to [].
Modules changed:
- netbird_setup_key: auto_groups default [] -> None, preserve on update
- netbird_group: peers default [] -> None, preserve on update,
normalize peer dicts to IDs
- netbird_user: auto_groups default [] -> None, preserve on update
Also:
- Reimplement get_current_user() since /api/users/me does not exist.
Now lists users and matches by is_current flag, with explicit error
on multi-user deployments without the flag.
- Configure role: use default(omit) for setup key auto_groups so
the module-level preservation works through the role.
- Configure role: conditional auto_groups resolution (skip when
auto_groups not defined in YAML config).
- Configure role: DNS zone distribution_groups now handles both
group names and raw IDs (falls back to original value when not
found in group_ids map).
- Updated DOCUMENTATION strings to remove stale default: [] and
document preservation behavior.
- Add (items or []) to all find_*_by_* functions across 12 modules.
The NetBird API returns null for empty collections, causing TypeError
when iterating. Affects find_group_by_name, find_policy_by_name,
find_setup_key_by_name, find_user_by_email, find_user_by_name,
find_network_by_name, find_route_by_network_id, find_nsgroup_by_name,
find_zone_by_name, find_posture_check_by_name, find_idp_by_name,
find_invite_by_email, find_token_by_name.
- Add (or []) to sync_routers and sync_resources in netbird_network
for the same reason (new networks have null router/resource lists).
- Fix export role network enrichment: .get('json', []) does not work
on Ansible uri module results. Changed to .json | default([]).
- Fix set_fact parsing in export and configure roles: {{ result | to_json }}
produces a JSON string, not a list. Added | from_json so downstream
loop directives receive proper lists (3 occurrences in configure,
1 in export).
- Use urllib.parse.urlencode for query parameter encoding instead of
raw f-string interpolation to prevent URL breakage with special chars.
Tomas Kloda
tklodaandGitHub
Jack Carter