First commit

docs/QUICK_START.md

@@ -0,0 +1,279 @@
+# Quick Start Guide - nsupdate_zone Module
+
+## Installation
+
+The module is part of the `community.general` collection:
+
+```bash
+ansible-galaxy collection install community.general
+```
+
+Install Python dependencies:
+
+```bash
+pip install dnspython
+```
+
+## Minimal Example
+
+```yaml
+- name: Update DNS zone
+  community.general.nsupdate_zone:
+    key_name: "nsupdate"
+    key_secret: "your-tsig-key-here=="
+    zones:
+      - name: example.com
+        dns_server: ns1.example.com
+        records:
+          - record: 'example.com.'
+            type: A
+            value: 192.168.1.1
+          
+          - record: www
+            type: A
+            value: 192.168.1.10
+```
+
+## DNS Server Setup (BIND Example)
+
+1. **Generate TSIG key:**
+
+```bash
+tsig-keygen -a hmac-sha256 nsupdate
+```
+
+2. **Configure BIND (`/etc/named.conf`):**
+
+```
+key "nsupdate" {
+    algorithm hmac-sha256;
+    secret "generated-secret-here==";
+};
+
+zone "example.com" {
+    type master;
+    file "/var/named/example.com.zone";
+    allow-update { key nsupdate; };
+    allow-transfer { key nsupdate; };
+};
+```
+
+3. **Reload BIND:**
+
+```bash
+sudo systemctl reload named
+```
+
+## First Playbook
+
+Create `update-dns.yml`:
+
+```yaml
+---
+- name: Manage DNS zones
+  hosts: localhost
+  gather_facts: false
+  
+  tasks:
+    - name: Update example.com zone
+      community.general.nsupdate_zone:
+        key_name: "nsupdate"
+        key_secret: "{{ lookup('env', 'DNS_KEY') }}"
+        key_algorithm: hmac-sha256
+        protocol: tcp
+        zones:
+          - name: example.com
+            dns_server: ns1.example.com
+            records:
+              # Zone apex
+              - record: 'example.com.'
+                type: A
+                value: 192.168.1.1
+                ttl: 3600
+              
+              # Web server
+              - record: www
+                type: A
+                value:
+                  - 192.168.1.10
+                  - 192.168.1.11
+                ttl: 300
+              
+              # Email
+              - record: 'example.com.'
+                type: MX
+                value:
+                  - "10 mail.example.com."
+              
+              - record: mail
+                type: A
+                value: 192.168.1.20
+      register: result
+    
+    - name: Show what changed
+      debug:
+        msg: "Zone {{ item.zone }}: {{ item.changes.adds }} adds, {{ item.changes.deletes }} deletes, {{ item.changes.updates }} updates"
+      loop: "{{ result.results }}"
+```
+
+Run it:
+
+```bash
+export DNS_KEY="your-tsig-key-here=="
+ansible-playbook update-dns.yml
+```
+
+## Verify It Works
+
+Check mode (dry run):
+
+```bash
+ansible-playbook update-dns.yml --check
+```
+
+Verify DNS records:
+
+```bash
+dig @ns1.example.com example.com A
+dig @ns1.example.com www.example.com A
+dig @ns1.example.com example.com MX
+```
+
+## Common Use Cases
+
+### 1. Load Zone from Variable File
+
+**zones/example.com.yml:**
+```yaml
+---
+- record: 'example.com.'
+  type: A
+  value: 192.168.1.1
+
+- record: www
+  type: A
+  value: 192.168.1.10
+```
+
+**Playbook:**
+```yaml
+- name: Load and apply zone
+  hosts: localhost
+  vars_files:
+    - zones/example.com.yml
+  
+  tasks:
+    - name: Update zone
+      community.general.nsupdate_zone:
+        key_name: "nsupdate"
+        key_secret: "{{ vault_dns_key }}"
+        zones:
+          - name: example.com
+            dns_server: ns1.example.com
+            records: "{{ zones }}"
+```
+
+### 2. Ignore Dynamic Records
+
+```yaml
+- name: Update zone (ignore ACME challenges)
+  community.general.nsupdate_zone:
+    key_name: "nsupdate"
+    key_secret: "{{ vault_dns_key }}"
+    ignore_record_types:
+      - NS
+    ignore_record_patterns:
+      - '^_acme-challenge\..*'
+    zones:
+      - name: example.com
+        dns_server: ns1.example.com
+        records: "{{ static_records }}"
+```
+
+### 3. Multiple Zones
+
+```yaml
+- name: Update all zones
+  community.general.nsupdate_zone:
+    key_name: "nsupdate"
+    key_secret: "{{ vault_dns_key }}"
+    parallel_zones: true  # Process concurrently
+    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 }}"
+```
+
+## Troubleshooting
+
+### "AXFR failed: connection timeout"
+
+- Check firewall allows port 53
+- Verify `allow-transfer` in BIND config
+- Test manually: `dig @ns1.example.com example.com AXFR`
+
+### "UPDATE failed: REFUSED"
+
+- Check `allow-update` in BIND config
+- Verify TSIG key matches
+- Check zone name is correct
+
+### "TSIG key error"
+
+- Verify key_secret is base64-encoded
+- Check key_algorithm matches server config
+- Ensure key_name matches server key name
+
+### "CNAME conflict"
+
+- Cannot have CNAME with other record types at same name
+- Remove conflicting records from YAML
+- Or use different subdomain
+
+## Best Practices
+
+1. **Use ansible-vault for keys:**
+   ```bash
+   ansible-vault encrypt_string 'your-key' --name dns_key
+   ```
+
+2. **Use TCP protocol:**
+   ```yaml
+   protocol: tcp  # More reliable for large zones
+   ```
+
+3. **Ignore server-managed records:**
+   ```yaml
+   ignore_record_types:
+     - NS
+     - SOA
+   ```
+
+4. **Test with check 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
+   ```
+
+## Next Steps
+
+- Read full documentation: `docs/nsupdate_zone_guide.md`
+- See examples: `examples/nsupdate_zone_example.yml`
+- Check sample zone: `examples/sample_zone_format.yml`
+
+## Support
+
+For issues and questions:
+- GitHub: https://github.com/ansible-collections/community.general
+- Docs: https://docs.ansible.com/