sync

2025-10-19 17:02:16 -05:00
parent 3f31f77bc8
commit 702c71fcff
222 changed files with 2834 additions and 10845 deletions
--- a/ansible/DNS_MANAGEMENT_REFACTOR.md
+++ b/ansible/DNS_MANAGEMENT_REFACTOR.md
@@ -0,0 +1,193 @@
+# DNS Management Refactor - Modular & Repeatable
+
+This document explains the refactoring of DNS management from standalone playbooks to modular, reusable tasks.
+
+## 🎯 **What Changed**
+
+### **Before (Monolithic)**
+```yaml
+# Standalone playbook: add_technitium_dns_entry.yml
+- name: Add entry to Technitium DNS
+  hosts: all
+  tasks:
+    - name: Create DNS entry
+      effectivelywild.technitium_dns.technitium_dns_add_record:
+        # ... hardcoded parameters
+```
+
+### **After (Modular)**
+```yaml
+# Reusable task: tasks/add_technitium_dns_entry.yml
+- name: Create DNS entry for {{ dns_record_name }}
+  effectivelywild.technitium_dns.technitium_dns_add_record:
+    # ... parameterized with variables
+```
+
+## 📁 **New Structure**
+
+```
+ansible/
+├── playbooks/
+│   ├── tasks/
+│   │   └── add_technitium_dns_entry.yml    # ✅ Reusable task file
+│   ├── add_dns_entry.yml                   # ✅ New playbook using task
+│   ├── add_technitium_dns_entry.yml.backup # 📦 Backed up old version
+│   └── roles/
+│       └── dns-manager/                    # ✅ Enhanced role
+│           ├── tasks/main.yml              # Uses task file
+│           └── defaults/main.yml           # Technitium defaults
+└── scripts/
+    └── migrate-dns-references.sh           # ✅ Migration helper
+```
+
+## 🚀 **Usage Examples**
+
+### **1. In Playbooks (Direct Task Include)**
+```yaml
+- name: Add DNS entry for my server
+  hosts: my_servers
+  tasks:
+    - name: Create DNS entry
+      ansible.builtin.include_tasks: tasks/add_technitium_dns_entry.yml
+      vars:
+        dns_record_name: "{{ inventory_hostname }}"
+        dns_zone: "{{ base_domain }}"
+        dns_ip_address: "{{ ansible_default_ipv4.address }}"
+```
+
+### **2. Using the DNS Manager Role**
+```yaml
+- name: Setup cluster DNS
+  hosts: control_plane[0]
+  roles:
+    - role: dns-manager
+      vars:
+        cluster_endpoint: "my-cluster.local.mk-labs.cloud"
+        cluster_vip: "10.1.71.100"
+```
+
+### **3. Using the New Playbook**
+```yaml
+# Import the new modular playbook
+- import_playbook: add_dns_entry.yml
+```
+
+### **4. In Cluster Network Setup**
+```yaml
+- name: Setup complete cluster network
+  ansible.builtin.include_role:
+    name: cluster-network-setup
+  vars:
+    cluster_name: "fastpass"
+    cluster_endpoint: "fastpass.local.mk-labs.cloud"
+    cluster_vip: "10.1.71.53"
+```
+
+## 🔧 **Migration Guide**
+
+### **Automatic Migration**
+```bash
+# Run the migration script to find references
+./scripts/migrate-dns-references.sh
+```
+
+### **Manual Updates**
+
+1. **Replace playbook imports:**
+   ```yaml
+   # OLD
+   - import_playbook: add_technitium_dns_entry.yml
+   
+   # NEW
+   - import_playbook: add_dns_entry.yml
+   ```
+
+2. **Use task includes in roles:**
+   ```yaml
+   - ansible.builtin.include_tasks: tasks/add_technitium_dns_entry.yml
+     vars:
+       dns_record_name: "my-server"
+       dns_ip_address: "10.1.71.100"
+   ```
+
+3. **Use the dns-manager role:**
+   ```yaml
+   - ansible.builtin.include_role:
+       name: dns-manager
+   ```
+
+## 📋 **Variable Reference**
+
+### **Task Variables (`tasks/add_technitium_dns_entry.yml`)**
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `dns_record_name` | `inventory_hostname` | DNS record name |
+| `dns_zone` | `base_domain` | DNS zone |
+| `dns_ip_address` | `ip_address` | IP address for A record |
+| `dns_record_type` | `A` | DNS record type |
+| `dns_ttl` | `360` | TTL in seconds |
+| `dns_create_ptr` | `true` | Create PTR record |
+| `dns_debug` | `true` | Show debug output |
+
+### **DNS Manager Role Variables**
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `cluster_endpoint` | - | Full cluster FQDN |
+| `cluster_vip` | - | Cluster VIP address |
+| `dns_management_enabled` | `true` | Enable DNS management |
+| `use_hosts_file_fallback` | `true` | Add to /etc/hosts |
+| `dns_ttl` | `360` | DNS TTL |
+| `create_ptr_record` | `true` | Create PTR record |
+
+## 🎯 **Benefits**
+
+### ✅ **Modularity**
+- Single task file used across multiple contexts
+- Consistent DNS management approach
+- Easy to maintain and update
+
+### ✅ **Flexibility**
+- Works in playbooks, roles, and standalone
+- Parameterized for different use cases
+- Supports multiple DNS providers (extensible)
+
+### ✅ **Maintainability**
+- One place to update DNS logic
+- Clear variable interface
+- Better error handling and debugging
+
+### ✅ **Integration**
+- Seamlessly integrates with cluster setup
+- Works with existing homelab infrastructure
+- Compatible with Traefik load balancer setup
+
+## 🔄 **Integration with Cluster Setup**
+
+The DNS management now integrates seamlessly with your cluster deployment:
+
+```yaml
+# In fastpass-first-control-plane role
+- name: Setup network infrastructure for FastPass cluster
+  ansible.builtin.include_role:
+    name: cluster-network-setup
+  vars:
+    cluster_name: "{{ cluster_name }}"
+    cluster_endpoint: "{{ control_plane_endpoint }}"
+    cluster_vip: "{{ ansible_default_ipv4.address }}"
+    control_plane_nodes: "{{ groups['fastpass_control_plane'] }}"
+```
+
+This automatically:
+1. ✅ Creates DNS entry for `fastpass.local.mk-labs.cloud`
+2. ✅ Configures Traefik load balancer
+3. ✅ Tests connectivity
+4. ✅ Provides fallback to /etc/hosts
+
+## 🚀 **Next Steps**
+
+1. **Test the refactored approach** with your FastPass cluster
+2. **Extend to other clusters** (Hub, Internal) using the same pattern
+3. **Add support for other DNS providers** if needed
+4. **Create monitoring** for DNS health checks
+
+This modular approach makes your homelab's DNS management much more maintainable and repeatable across all your Kubernetes clusters!