daniel/valid.nsupdate_zone
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update all documentation to reflect v1.1.0 features

Browse Source 
- 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
This commit is contained in:
Daniel Akulenok
2026-01-29 20:45:14 +01:00
parent b724c568b9
commit 4625f2cb1e
7 changed files with 48 additions and 41 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
BUILD_COMPLETE.md
View File

@@ -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

3
COLLECTION_SUMMARY.md
View File

@@ -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

11
README.md
View File

@@ -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

45
docs/QUICK_START.md
View File

@@ -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

15
docs/nsupdate_zone_example.yml
View File

@@ -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

5
docs/sample_zone_format.yml
View File

@@ -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

7
plugins/modules/nsupdate_zone.py
View File

@@ -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