diff --git a/BUILD_COMPLETE.md b/BUILD_COMPLETE.md index 5d4280d..5606b11 100644 --- a/BUILD_COMPLETE.md +++ b/BUILD_COMPLETE.md @@ -98,8 +98,9 @@ pip install dnspython key_secret: "{{ vault_dns_key }}" key_algorithm: hmac-sha256 protocol: tcp - ignore_record_types: [NS] + # SOA and DNSSEC records are ignored by default ignore_record_patterns: ['^_acme-challenge\..*'] + verbose: true # Show per-record actions zones: - name: example.com dns_server: ns1.example.com diff --git a/COLLECTION_SUMMARY.md b/COLLECTION_SUMMARY.md index 043b871..1ee6c22 100644 --- a/COLLECTION_SUMMARY.md +++ b/COLLECTION_SUMMARY.md @@ -96,6 +96,9 @@ pip install -r requirements.txt valid.nsupdate_zone.nsupdate_zone: key_name: "nsupdate" key_secret: "{{ vault_dns_key }}" + # SOA and DNSSEC records are ignored by default + # Record validation is enabled by default + verbose: true zones: - name: example.com dns_server: ns1.example.com diff --git a/README.md b/README.md index e90b42b..05c5cae 100644 --- a/README.md +++ b/README.md @@ -82,8 +82,10 @@ for more details. key_secret: "{{ vault_dns_key }}" key_algorithm: hmac-sha256 protocol: tcp - ignore_record_types: [NS] + # 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 @@ -110,9 +112,10 @@ for more details. - **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, etc.) -- **Scalable**: Optional parallel processing for multiple zones -- **Safe**: Full check mode support for dry runs +- **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 diff --git a/docs/QUICK_START.md b/docs/QUICK_START.md index c4491c2..f6715cb 100644 --- a/docs/QUICK_START.md +++ b/docs/QUICK_START.md @@ -34,6 +34,8 @@ pip install dnspython value: 192.168.1.10 ``` +**Note**: By default, SOA and DNSSEC records are ignored, and record validation is enabled. + ## DNS Server Setup (BIND Example) 1. **Generate TSIG key:** @@ -173,38 +175,37 @@ dig @ns1.example.com example.com MX records: "{{ zones }}" ``` -### 2. Ignore Dynamic Records +### 2. Ignore Dynamic Records and Use Global Server ```yaml -- name: Update zone (ignore ACME challenges) +- name: Update zone (ignore ACME challenges, use global server) community.general.nsupdate_zone: key_name: "nsupdate" key_secret: "{{ vault_dns_key }}" - ignore_record_types: - - NS + dns_server: ns1.dns.com # Global server for all zones + # SOA and DNSSEC records are ignored by default ignore_record_patterns: - '^_acme-challenge\..*' + verbose: true # Show per-record actions zones: - name: example.com - dns_server: ns1.example.com records: "{{ static_records }}" ``` -### 3. Multiple Zones +### 3. Multiple Zones with Shared Server ```yaml - name: Update all zones community.general.nsupdate_zone: key_name: "nsupdate" key_secret: "{{ vault_dns_key }}" - parallel_zones: true # Process concurrently + dns_server: ns1.dns.com # Shared server for all zones + verbose: true # Show detailed changes zones: - name: example.com - dns_server: ns1.dns.com records: "{{ example_com_records }}" - name: example.org - dns_server: ns1.dns.com records: "{{ example_org_records }}" ``` @@ -246,24 +247,28 @@ dig @ns1.example.com example.com MX protocol: tcp # More reliable for large zones ``` -3. **Ignore server-managed records:** +3. **Leverage defaults:** ```yaml - ignore_record_types: - - NS - - SOA + # SOA and DNSSEC records are ignored by default + # Record validation is enabled by default + # Just add patterns for dynamic records + ignore_record_patterns: + - '^_acme-challenge\..*' ``` -4. **Test with check mode:** +4. **Use verbose mode for visibility:** + ```yaml + verbose: true # See Added, Removed, Changed, Skipped for each record + ``` + +5. **Test with check and diff mode:** ```bash ansible-playbook playbook.yml --check --diff ``` -5. **Keep zone files in version control:** - ``` - zones/ - ├── example.com.yml - ├── example.org.yml - └── example.net.yml +6. **Use global dns_server:** + ```yaml + dns_server: ns1.dns.com # Applies to all zones without dns_server ``` ## Next Steps diff --git a/docs/nsupdate_zone_example.yml b/docs/nsupdate_zone_example.yml index 84b5782..b8108f8 100644 --- a/docs/nsupdate_zone_example.yml +++ b/docs/nsupdate_zone_example.yml @@ -67,12 +67,11 @@ key_name: "{{ dns_key_name }}" key_secret: "{{ dns_key_secret }}" protocol: tcp - ignore_record_types: - - NS - - SOA + # SOA and DNSSEC records are ignored by default ignore_record_patterns: - '^_acme-challenge\..*' - '^_dnsauth\..*' + verbose: true # Show per-record actions zones: - name: example.com dns_server: ns1.example.com @@ -94,29 +93,27 @@ loop: "{{ result.results }}" when: result.results is defined - # Example: Manage multiple zones in parallel - - name: Manage multiple zones concurrently + # Example: Manage multiple zones with global dns_server + - name: Manage multiple zones with shared server valid.nsupdate_zone.nsupdate_zone: key_name: "{{ dns_key_name }}" key_secret: "{{ dns_key_secret }}" - parallel_zones: true + dns_server: ns1.example.com # Global server for all zones + verbose: true zones: - name: example.com - dns_server: ns1.example.com records: - record: 'example.com.' type: A value: 192.168.1.1 - name: example.org - dns_server: ns1.example.com records: - record: 'example.org.' type: A value: 192.168.2.1 - name: example.net - dns_server: ns1.example.com records: - record: 'example.net.' type: A diff --git a/docs/sample_zone_format.yml b/docs/sample_zone_format.yml index 33e831b..1662c93 100644 --- a/docs/sample_zone_format.yml +++ b/docs/sample_zone_format.yml @@ -79,11 +79,10 @@ list_of_nsupdate_zones: key_secret: "{{ dns_tsig_key_secret }}" key_algorithm: hmac-sha256 protocol: tcp - # Ignore NS records at zone apex and ACME challenge records - ignore_record_types: - - NS + # SOA and DNSSEC records are ignored by default ignore_record_patterns: - '^_acme-challenge\..*' + verbose: true # Show detailed per-record actions zones: "{{ list_of_nsupdate_zones }}" register: zone_update_result diff --git a/plugins/modules/nsupdate_zone.py b/plugins/modules/nsupdate_zone.py index 5fe3ff2..0c20797 100644 --- a/plugins/modules/nsupdate_zone.py +++ b/plugins/modules/nsupdate_zone.py @@ -213,16 +213,15 @@ EXAMPLES = r""" value: 192.168.1.99 state: absent -- name: Manage multiple zones with ignore patterns +- name: Manage multiple zones with ignore patterns and verbose output community.general.nsupdate_zone: key_name: "nsupdate" key_secret: "+bFQtBCta7j2vWkjPkAFtgA==" - ignore_record_types: - - NS - - SOA + # SOA and DNSSEC records are ignored by default ignore_record_patterns: - '^_acme-challenge\..*' - '^_dnsauth\..*' + verbose: true # Show per-record actions zones: - name: example.com dns_server: 10.1.1.1