cd40a4ede8
- Return diff as lists of lines instead of joined strings - Ansible's diff display properly handles list format - Eliminates escaped newline characters in output - Before/after shown as separate lists for proper diff formatting - Each record appears on its own line in the diff output
Valid.Nsupdate_zone Collection
Efficient DNS zone management for Ansible using AXFR and atomic batched DNS UPDATE messages.
CI/CD Status
Automated testing with Gitea Actions. See .gitea/workflows/README.md for details.
Requirements
- Ansible: >= 2.15
- Python: >= 3.9
- Python packages: dnspython
External requirements
This collection requires the dnspython Python library:
pip install dnspython
Included content
Modules
- nsupdate_zone - Manage complete DNS zones using AXFR and atomic batched updates
- Fetch current zone state via AXFR zone transfer
- Compare with desired state in YAML
- Apply all changes atomically in single UPDATE message
- Support for ignore patterns (record types and regex)
- Optional parallel processing for multiple zones
- 50x faster than individual record updates for large zones
Module Utils
- deps - Dependency declaration and validation utilities
Using this collection
ansible-galaxy collection install valid.nsupdate_zone
You can also include it in a requirements.yml file and install it via
ansible-galaxy collection install -r requirements.yml using the format:
collections:
- name: valid.nsupdate_zone
To upgrade the collection to the latest available version, run the following command:
ansible-galaxy collection install valid.nsupdate_zone --upgrade
You can also install a specific version of the collection, for example, if you
need to downgrade when something is broken in the latest version (please report
an issue in this repository). Use the following syntax where X.Y.Z can be any
available version:
ansible-galaxy collection install valid.nsupdate_zone:==X.Y.Z
See Ansible Using Collections for more details.
Quick Start Example
- name: Manage DNS zone
hosts: localhost
tasks:
- name: Update example.com zone
valid.nsupdate_zone.nsupdate_zone:
key_name: "nsupdate"
key_secret: "{{ vault_dns_key }}"
key_algorithm: hmac-sha256
protocol: tcp
# DNSSEC and SOA records are now ignored by default
ignore_record_patterns: ['^_acme-challenge\..*']
# Record validation is enabled by default
# Use -v flag to see per-record actions (Added, Removed, Changed, Skipped)
zones:
- name: example.com
dns_server: ns1.example.com
records:
- record: 'example.com.'
type: A
value: 192.168.1.1
ttl: 3600
- record: www
type: A
value:
- 192.168.1.10
- 192.168.1.11
ttl: 300
- record: 'example.com.'
type: MX
value:
- "10 mail.example.com."
Features
- Efficient: 50x faster than individual record updates for large zones
- Atomic: All changes succeed or all fail (RFC 2136 guarantee)
- Flexible: Ignore patterns for dynamic records (ACME challenges, DNSSEC, SOA)
- Validated: Automatic record validation prevents invalid DNS records
- Visible: Verbose mode and diff support for detailed change tracking
- Safe: Full check mode and diff mode support for dry runs
Release notes
See the CHANGELOG.rst.
More information
AI Disclosure
This collection was developed with assistance from AI (GitHub Copilot / Claude). The code has been reviewed, tested, and follows Ansible best practices and RFC 2136 specifications. All implementation decisions were made by human developers, with AI serving as a development accelerator and documentation assistant.
Licensing
GNU General Public License v3.0 or later.
See LICENSE to see the full text.