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

# 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

# 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

# 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

# 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

# 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

# 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:

ssh-copy-id -i ~/.ssh/id_ed25519.pub user@new-node-ip

2. Test connectivity:

ssh -i ~/.ssh/id_ed25519 user@new-node-ip "hostname"

3. Add to inventory (inventory/hosts.ini):

[docker_nodes]
new_node ansible_host=10.0.0.XXX ansible_user=user

4. Verify:

ansible new_node -m ping

Creating a New Playbook

1. Create file in playbooks/ directory:

---
- name: My New Playbook
  hosts: all
  gather_facts: true
  
  tasks:
    - name: Example task
      ansible.builtin.debug:
        msg: "Hello from {{ inventory_hostname }}"

2. Validate syntax:

ansible-playbook playbooks/my-playbook.yml --syntax-check

3. Lint the playbook:

ansible-lint playbooks/my-playbook.yml

4. Test in check mode:

ansible-playbook playbooks/my-playbook.yml --check

5. Execute:

ansible-playbook playbooks/my-playbook.yml

Troubleshooting Connection Issues

# 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

# 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)