docs: [#10] add troubleshooting for VM IP detection issue

- Document the 'No IP assigned yet' issue in Terraform outputs
- Explain root cause: stale Terraform state vs actual VM DHCP lease
- Add comprehensive troubleshooting steps with solutions
- Include prevention tips and alternative methods
- Add new 'make refresh-state' command for easy state synchronization
- Update both quick-start and detailed setup documentation
- Improve command tables and cross-references

This addresses the common confusion when make status shows no IP
while virsh domifaddr shows the VM has a valid IP address.

Author: josecelano

Makefile

@@ -1,5 +1,5 @@
 # Makefile for Torrust Tracker Local Testing Infrastructure
-.PHONY: help init plan apply destroy test clean status ssh install-deps console vm-console lint lint-yaml lint-shell lint-markdown
+.PHONY: help init plan apply destroy test clean status refresh-state ssh install-deps console vm-console lint lint-yaml lint-shell lint-markdown
 
 # Default variables
 VM_NAME ?= torrust-tracker-demo
@@ -79,6 +79,12 @@ status: ## Show current infrastructure status
 	@echo "Infrastructure status:"
 	cd $(TERRAFORM_DIR) && tofu show
 
+refresh-state: ## Refresh Terraform state to detect IP changes
+	@echo "Refreshing Terraform state..."
+	cd $(TERRAFORM_DIR) && tofu refresh
+	@echo "Updated outputs:"
+	cd $(TERRAFORM_DIR) && tofu output
+
 ssh: ## SSH into the VM
 	@echo "Connecting to VM..."
 	@VM_IP=$$(virsh domifaddr $(VM_NAME) | grep ipv4 | awk '{print $$4}' | cut -d'/' -f1); \

infrastructure/docs/local-testing-setup.md

@@ -310,6 +310,7 @@ tofu refresh
    - Verify firewall rules
 
 6. **VM deployment timeout (can't get IP address)**
+
    - **Symptoms**: VM starts but times out waiting for DHCP lease
    - **Cause**: Cloud-init setup takes time (package installation, system
      configuration, reboot)
@@ -318,4 +319,57 @@ tofu refresh
    - **Check**: Use `virsh console torrust-tracker-demo` or
      `virt-viewer spice://127.0.0.1:5900` to monitor boot progress
 
+7. **Terraform/OpenTofu shows "No IP assigned yet" but VM has IP**
+
+   - **Symptoms**: `make status` shows:
+
+     ```text
+     connection_info = "VM created, waiting for IP address..."
+     vm_ip = "No IP assigned yet"
+     ```
+
+     But `virsh domifaddr torrust-tracker-demo` shows an IP address.
+
+   - **Root Cause**: Terraform libvirt provider state is not synchronized with
+     the actual VM network state. This happens because:
+
+     - DHCP lease assignment timing varies
+     - Terraform state becomes stale after cloud-init completes
+     - The provider doesn't automatically refresh network interface information
+
+   - **Solution**: Refresh the Terraform state to synchronize with libvirt:
+
+     ```bash
+     # Method 1: Refresh Terraform state
+     cd infrastructure/terraform
+     tofu refresh
+
+     # Method 2: Use the make command (if available)
+     make refresh-state
+
+     # Verify the fix
+     tofu output
+     ```
+
+   - **Prevention**: The IP detection issue can be minimized by:
+
+     - Waiting 2-3 minutes after `make apply` before checking IP
+     - Using `virsh domifaddr VM_NAME` to get IP directly from libvirt
+     - Adding automatic refresh to the Makefile status command
+
+   - **Alternative**: Get the IP directly from libvirt without Terraform:
+
+     ```bash
+     # Get IP address directly
+     virsh domifaddr torrust-tracker-demo
+
+     # Or use in scripts
+     VM_IP=$(virsh domifaddr torrust-tracker-demo | grep ipv4 | awk '{print $4}' | cut -d'/' -f1)
+     echo "VM IP: $VM_IP"
+     ```
+
+   - **Why This Happens**: The libvirt provider checks `network_interface[0].addresses`
+     which is populated asynchronously. The VM gets its IP from DHCP, but Terraform's
+     cached state doesn't reflect this until explicitly refreshed.
+
 ### Logs and Debugging

infrastructure/docs/quick-start.md

@@ -134,14 +134,15 @@ make destroy
 
 ## 📋 Available Commands
 
-| Command        | Description                 |
-| -------------- | --------------------------- |
-| `make help`    | Show all available commands |
-| `make test`    | Run complete test suite     |
-| `make apply`   | Deploy VM                   |
-| `make ssh`     | Connect to VM               |
-| `make destroy` | Remove VM                   |
-| `make status`  | Show infrastructure status  |
+| Command              | Description                                  |
+| -------------------- | -------------------------------------------- |
+| `make help`          | Show all available commands                  |
+| `make test`          | Run complete test suite                      |
+| `make apply`         | Deploy VM                                    |
+| `make ssh`           | Connect to VM                                |
+| `make destroy`       | Remove VM                                    |
+| `make status`        | Show infrastructure status                   |
+| `make refresh-state` | Refresh Terraform state to detect IP changes |
 
 ## 🔧 Troubleshooting
 
@@ -151,6 +152,19 @@ make destroy
 2. **VM won't start**: Check with `sudo kvm-ok` that virtualization is enabled
 3. **SSH connection fails**: VM might still be booting, wait 2-3 minutes
 4. **libvirt file ownership errors**: Run `make fix-libvirt` to fix permissions
+5. **"No IP assigned yet" issue**: If `make status` shows no IP but VM is running:
+
+   ```bash
+   # Check if VM actually has an IP
+   virsh domifaddr torrust-tracker-demo
+
+   # If IP is shown, refresh Terraform state
+   make refresh-state
+   ```
+
+   **Why this happens**: Terraform's state can become stale after cloud-init completes.
+   The VM gets its IP from DHCP, but Terraform doesn't automatically detect this change.
+   See [detailed troubleshooting](local-testing-setup.md#troubleshooting) for more info.
 
 ### Getting Help