4625f2cb1e
- Update all examples to show new defaults (ignore_dnssec_records, ignore_soa_records, validate_records) - Add verbose output examples throughout documentation - Show global dns_server parameter usage - Remove all references to deprecated parallel_zones parameter - Update QUICK_START.md with new best practices - Update README.md with new feature descriptions - Update module EXAMPLES with verbose flag and current defaults - Update all example playbooks (nsupdate_zone_example.yml, sample_zone_format.yml) - Simplify examples by relying on sensible defaults
140 lines
4.2 KiB
Markdown
140 lines
4.2 KiB
Markdown
# 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.
|