# 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](.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:

```bash
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

```bash
    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:

```yaml
collections:
  - name: valid.nsupdate_zone
```

To upgrade the collection to the latest available version, run the following
command:

```bash
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](https://galaxy.ansible.com/valid/nsupdate_zone):

```bash
ansible-galaxy collection install valid.nsupdate_zone:==X.Y.Z
```

See
[Ansible Using Collections](https://docs.ansible.com/ansible/latest/user_guide/collections_using.html)
for more details.

## Quick Start Example

```yaml
- 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
        verbose: true  # Show per-record actions
        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](CHANGELOG.rst).

## More information

- [Module documentation](plugins/modules/nsupdate_zone.py)
- [RFC 2136 - DNS UPDATE](https://datatracker.ietf.org/doc/html/rfc2136)
- [dnspython documentation](https://dnspython.readthedocs.io/)
- [Ansible User guide](https://docs.ansible.com/ansible/latest/user_guide/index.html)

## 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](LICENSE) to see the full text.