Initial commit: loc_az_hci (smom-dbis-138 excluded via .gitignore)

Co-authored-by: Cursor <cursoragent@cursor.com>

docs/network/STATIC_IP_DHCP_COEXISTENCE.md

@@ -0,0 +1,136 @@
+# Static IP vs DHCP Coexistence
+
+## Problem
+
+When VMs are configured with static IP addresses (e.g., 192.168.1.188, 192.168.1.60) on a subnet where the router is also running DHCP, there's a risk of IP conflicts:
+
+- Router's DHCP server may assign the same IPs to other devices
+- This causes network conflicts and connectivity issues
+- VMs may lose network connectivity
+
+## Solutions
+
+### Option 1: DHCP Reservations (Recommended)
+
+Configure your router to reserve specific IP addresses for the VMs' MAC addresses.
+
+**Steps:**
+1. Get VM MAC addresses from Proxmox
+2. Log into your router's admin interface
+3. Find DHCP Reservations / Static DHCP / IP Reservations
+4. Reserve each IP for the corresponding MAC address
+
+**Get MAC addresses:**
+```bash
+ssh root@192.168.1.206
+for vmid in 100 101 102 103; do
+  echo "VM $vmid:"
+  qm config $vmid | grep net0 | grep -o 'virtio=[^,]*'
+done
+```
+
+**Example router configuration:**
+- VM 100 (cloudflare-tunnel): MAC `BC:24:11:D9:F7:DE` → Reserve 192.168.1.188
+- VM 101 (k3s-master): MAC `BC:24:11:C1:75:A2` → Reserve 192.168.1.60
+- VM 102 (git-server): MAC `BC:24:11:ED:A2:F8` → Reserve 192.168.1.121
+- VM 103 (observability): MAC `BC:24:11:9D:5F:E7` → Reserve 192.168.1.82
+
+---
+
+### Option 2: Exclude IPs from DHCP Pool
+
+Configure your router's DHCP pool to exclude the static IP addresses.
+
+**Example:**
+- DHCP Pool: 192.168.1.100 - 192.168.1.254
+- Excluded/Reserved: 192.168.1.1 - 192.168.1.99
+- Static IPs: 192.168.1.188, 60, 70, 80 (within excluded range)
+
+**Router settings:**
+- DHCP Start: 192.168.1.100
+- DHCP End: 192.168.1.254
+- This leaves 192.168.1.1-99 for static assignments
+
+---
+
+### Option 3: Use NAT Network (Best for Isolation)
+
+Use a separate NAT network for VMs, completely isolated from the main network.
+
+**Benefits:**
+- No IP conflicts (VMs on private network 10.0.0.0/24)
+- Network isolation
+- Access via Proxmox host (port forwarding)
+- Router DHCP unaffected
+
+**Implementation:**
+- Run: `./scripts/fix/setup-nat-with-ssh-keys.sh`
+- VMs get IPs: 10.0.0.10, 10.0.0.11, 10.0.0.12, 10.0.0.13
+- Access via: `ssh -p 2222 ubuntu@192.168.1.206` (VM 100)
+
+---
+
+### Option 4: Use DHCP with Cloud-Init
+
+Let VMs get IPs from DHCP, then discover them via QEMU Guest Agent.
+
+**Benefits:**
+- No IP conflicts
+- No router configuration needed
+- IPs discovered dynamically
+
+**Implementation:**
+- Remove `ipconfig0` from VM config
+- Let cloud-init use DHCP
+- Use QEMU Guest Agent to discover IPs
+- Scripts already support this via `get_vm_ip_from_guest_agent()`
+
+**Note:** This is what the guest-agent IP discovery pattern supports!
+
+---
+
+## Current Configuration
+
+Your VMs are currently configured with static IPs:
+- VM 100: 192.168.1.188
+- VM 101: 192.168.1.60
+- VM 102: 192.168.1.121
+- VM 103: 192.168.1.82
+
+**Risk:** If your router's DHCP pool includes these IPs, conflicts will occur.
+
+---
+
+## Recommended Approach
+
+### For Production/Stable Setup:
+**Use Option 1 (DHCP Reservations)** - Best of both worlds:
+- Static IPs for VMs (predictable)
+- Router manages IP assignments (no conflicts)
+- Works with existing network setup
+
+### For Development/Isolation:
+**Use Option 3 (NAT Network)** - Complete isolation:
+- No router configuration needed
+- VMs isolated from main network
+- Access via Proxmox host
+
+### For Maximum Flexibility:
+**Use Option 4 (DHCP + Guest Agent)** - Dynamic discovery:
+- No static IP configuration
+- No router configuration
+- IPs discovered automatically
+- Works with existing scripts
+
+---
+
+## Quick Fix Script
+
+I can create a script to:
+1. Check if IPs are in router's DHCP pool
+2. Switch VMs to DHCP mode
+3. Use guest-agent IP discovery
+4. Update all scripts to use discovered IPs
+
+This would be the most flexible solution and works with your existing guest-agent IP discovery pattern.
+