homelab/ansible/QUICK-REFERENCE.md

# Ansible Quick Reference

## Current Environment Status

**Last Validated:** April 13, 2026  
**Status:** 🟢 OPERATIONAL  
**Managed Nodes:** 4 (Watchtower, Heimdall, Waldorf, PVE01)

---

## Quick Commands

### Health Checks

```bash
# Basic connectivity test
ansible all -m ping

# Full environment validation
./validate-environment.sh

# Check Ansible version
ansible --version

# List all managed hosts
ansible-inventory --graph
```

### Ad-Hoc Commands

```bash
# Execute command on all nodes
ansible all -m command -a "uptime"

# Execute with privilege escalation
ansible all -m command -a "whoami" --become

# Check disk space on all nodes
ansible all -m shell -a "df -h /"

# Gather facts from specific group
ansible docker_nodes -m setup
```

### Playbook Operations

```bash
# Syntax check
ansible-playbook playbooks/test-connection.yml --syntax-check

# Dry run (check mode)
ansible-playbook playbooks/test-connection.yml --check

# Execute playbook
ansible-playbook playbooks/test-connection.yml

# Run with verbose output
ansible-playbook playbooks/test-connection.yml -vvv

# Limit to specific hosts
ansible-playbook playbooks/test-connection.yml --limit heimdall
```

### Ansible Vault Operations

```bash
# View encrypted file
ansible-vault view inventory/group_vars/all/vault.yml

# Edit encrypted file
ansible-vault edit inventory/group_vars/all/vault.yml

# Encrypt a file
ansible-vault encrypt path/to/file.yml

# Decrypt a file
ansible-vault decrypt path/to/file.yml

# Change vault password
ansible-vault rekey inventory/group_vars/all/vault.yml
```

### Linting & Quality

```bash
# Lint specific playbook
ansible-lint playbooks/test-connection.yml

# Lint all playbooks
ansible-lint playbooks/*.yml

# Lint with strict mode
ansible-lint --strict playbooks/

# Show configuration
ansible-config list
ansible-config dump --only-changed
```

---

## Inventory Groups

The inventory is organized into hardware and functional groups:

### Hardware Groups
- **control_plane** - Watchtower (Ansible control node)
- **docker_nodes** - Heimdall, Waldorf
- **physical_servers** - Heimdall, Waldorf
- **raspberry_pi** - Watchtower
- **proxmox_cluster** - PVE01

### Functional Groups
- **core_services** - Heimdall (Komodo, Gitea, Traefik)
- **media_services** - Waldorf (Plex, Tunarr)
- **nfs_clients** - Heimdall, Waldorf

### Targeting Examples

```bash
# All Docker hosts
ansible docker_nodes -m ping

# Only physical servers
ansible physical_servers -m command -a "lsblk"

# Just the control plane
ansible control_plane -m setup

# NFS clients only
ansible nfs_clients -m shell -a "df -h /mnt/appdata"
```

---

## Files & Directories

```
ansible/
├── ansible.cfg                    # Main configuration
├── inventory/
│   ├── hosts.ini                 # Node definitions
│   └── host_vars/                # Per-host variables
├── group_vars/
│   └── all.yml                   # Global variables
├── vault/
│   └── .vault_pass               # Vault password (gitignored)
├── playbooks/
│   ├── test-connection.yml       # Basic connectivity test
│   ├── gather-node-facts.yml     # System discovery
│   ├── quick-facts.yml           # Rapid diagnostics
│   ├── onboard-nodes.yml         # Node initialization
│   └── onboard-proxmox.yml       # Proxmox setup
├── roles/
│   └── proxmox_post_install/     # Custom role
└── validate-environment.sh       # Health check script
```

---

## Configuration Highlights

### ansible.cfg Key Settings

- **Inventory:** `inventory/hosts.ini`
- **SSH Key:** `~/.ssh/id_ed25519`
- **Host Key Checking:** Disabled (homelab trusted network)
- **Vault Password:** `vault/.vault_pass`
- **Forks:** 5 (parallel execution limit)
- **Fact Caching:** Enabled (JSON, 1 hour TTL)
- **Privilege Escalation:** sudo (passwordless)

### Security Configuration

- ED25519 SSH keys (modern, fast, secure)
- Ansible Vault for secrets (AES256 encryption)
- Vault password file permissions: 600 (owner read/write only)
- No passwords in inventory files
- StrictHostKeyChecking disabled (acceptable for isolated homelab)

---

## Common Workflows

### Adding a New Managed Node

1. **Generate and copy SSH key:**
```bash
ssh-copy-id -i ~/.ssh/id_ed25519.pub user@new-node-ip
```

2. **Test connectivity:**
```bash
ssh -i ~/.ssh/id_ed25519 user@new-node-ip "hostname"
```

3. **Add to inventory** (`inventory/hosts.ini`):
```ini
[docker_nodes]
new_node ansible_host=10.0.0.XXX ansible_user=user
```

4. **Verify:**
```bash
ansible new_node -m ping
```

### Creating a New Playbook

1. **Create file in playbooks/ directory:**
```yaml
---
- name: My New Playbook
  hosts: all
  gather_facts: true
  
  tasks:
    - name: Example task
      ansible.builtin.debug:
        msg: "Hello from {{ inventory_hostname }}"
```

2. **Validate syntax:**
```bash
ansible-playbook playbooks/my-playbook.yml --syntax-check
```

3. **Lint the playbook:**
```bash
ansible-lint playbooks/my-playbook.yml
```

4. **Test in check mode:**
```bash
ansible-playbook playbooks/my-playbook.yml --check
```

5. **Execute:**
```bash
ansible-playbook playbooks/my-playbook.yml
```

### Troubleshooting Connection Issues

```bash
# Verbose SSH debugging
ansible node_name -m ping -vvvv

# Test raw connectivity (bypasses Python)
ansible node_name -m raw -a "echo test"

# Check SSH key authentication
ssh -vvv -i ~/.ssh/id_ed25519 user@node-ip

# Verify inventory parsing
ansible-inventory --host node_name

# Test privilege escalation
ansible node_name -m command -a "whoami" --become -vv
```

---

## Integration Points

### VSCode Remote Development

1. Open VSCode
2. Install "Remote - SSH" extension
3. Connect to Watchtower: `chester@10.0.0.200`
4. Open folder: `/home/chester/homelab/ansible`
5. Install extensions on remote:
   - Ansible (by Red Hat)
   - YAML (by Red Hat)

### Git Workflow

```bash
# Check status
git status

# Add changed playbooks
git add playbooks/

# Commit with descriptive message
git commit -m "feat(ansible): add system maintenance playbook"

# Push to Gitea
git push origin main
```

---

## Performance Tips

- **Use fact caching** (already enabled) to avoid re-gathering system info
- **Limit playbook scope** with `--limit` flag when testing
- **Increase forks** for large inventories (currently 5)
- **Use pipelining** (already enabled) for faster SSH operations
- **Disable gathering** for simple tasks: `gather_facts: false`

---

## Security Best Practices

✅ **Already Implemented:**
- SSH key-based authentication (no passwords)
- Ansible Vault for sensitive data
- Vault password file secured (600 permissions)
- Passwordless sudo configured safely

⚠️ **Recommendations:**
- Rotate SSH keys annually
- Audit Vault contents quarterly
- Review ansible.log for suspicious activity
- Limit Ansible user privileges where possible

---

## Next Steps

1. **Create comprehensive validation playbook** (validate-connectivity.yml)
2. **Build Docker stack deployment role**
3. **Implement automated system updates playbook**
4. **Set up Molecule for role testing**
5. **Integrate with Komodo for CI/CD automation**

---

**Document Version:** 1.0  
**Last Updated:** April 13, 2026  
**Maintained By:** FrankGPT (Ansible Architect)