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

• Module documentation
• RFC 2136 - DNS UPDATE
• dnspython documentation
• Ansible User guide

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.