infra-automation/cheatsheets/inventory.md

# Inventory Cheatsheet

Quick reference for Ansible inventory management.

## Quick Commands

### List Hosts
```bash
# Static inventory
ansible all -i inventories/development/hosts.yml --list-hosts

# SSH config dynamic
ansible all -i plugins/inventory/ssh_config_inventory.py --list-hosts

# Libvirt dynamic
ansible all -i plugins/inventory/libvirt_kvm.py --list-hosts
```

### View Inventory Structure
```bash
# List all groups and hosts
ansible-inventory -i <inventory> --list

# Show as graph
ansible-inventory -i <inventory> --graph

# Specific host details
ansible-inventory -i <inventory> --host <hostname>
```

### Test Connectivity
```bash
# Ping all hosts
ansible all -i <inventory> -m ping

# Ping specific group
ansible kvm_guests -i <inventory> -m ping

# Verbose output
ansible all -i <inventory> -m ping -vvv
```

## Inventory Locations

| Inventory | Path | Type |
|-----------|------|------|
| Static Dev | `inventories/development/hosts.yml` | Static YAML |
| SSH Parser | `plugins/inventory/ssh_config_inventory.py` | Dynamic Script |
| Libvirt | `plugins/inventory/libvirt_kvm.py` | Dynamic Script |

## Common Groups

| Group | Description | Inventory |
|-------|-------------|-----------|
| `all` | All hosts | All |
| `external_hosts` | Public-facing hosts | All |
| `hypervisors` | KVM hypervisors | All |
| `kvm_guests` | All VMs | All |
| `running_vms` | Running VMs only | Libvirt |
| `dns_servers` | DNS/DHCP servers | All |
| `mail_servers` | Mail servers | All |
| `development` | Dev/test hosts | All |

## Dynamic Inventory Usage

### SSH Config Parser
```bash
# List inventory
python3 plugins/inventory/ssh_config_inventory.py --list

# Host details
python3 plugins/inventory/ssh_config_inventory.py --host pihole

# Use with ansible
ansible all -i plugins/inventory/ssh_config_inventory.py -m ping
```

### Libvirt Dynamic
```bash
# Set environment
export LIBVIRT_DEFAULT_URI="qemu+ssh://grok@grok.home.serneels.xyz/system"
export LIBVIRT_HYPERVISOR_NAME="grokbox"

# List VMs
python3 plugins/inventory/libvirt_kvm.py --list

# Use with ansible
ansible running_vms -i plugins/inventory/libvirt_kvm.py -m setup
```

## Playbook Execution

### Single Inventory
```bash
ansible-playbook -i inventories/development/hosts.yml site.yml
```

### Multiple Inventories
```bash
ansible-playbook \
  -i inventories/development/hosts.yml \
  -i plugins/inventory/libvirt_kvm.py \
  site.yml
```

### With Limits
```bash
# Limit to specific group
ansible-playbook -i <inventory> --limit kvm_guests site.yml

# Limit to specific host
ansible-playbook -i <inventory> --limit pihole site.yml

# Multiple limits
ansible-playbook -i <inventory> --limit "dns_servers:mail_servers" site.yml
```

## Variable Precedence

From lowest to highest:
1. `group_vars/all.yml`
2. `group_vars/<group_name>.yml`
3. `host_vars/<hostname>.yml`
4. Playbook vars
5. Extra vars (`-e`)

## Debugging

### Validate Inventory
```bash
# Syntax check
ansible-inventory -i <inventory> --list > /dev/null

# YAML validation
yamllint inventories/development/hosts.yml
```

### Connection Test
```bash
# Test SSH connectivity
ansible all -i <inventory> -m ping -vvv

# Check Python interpreter
ansible all -i <inventory> -m setup -a "filter=ansible_python_version"

# Verify become/sudo
ansible all -i <inventory> -m shell -a "whoami" --become
```

### View Effective Variables
```bash
# All variables for a host
ansible-inventory -i <inventory> --host <hostname> --yaml

# Specific variable
ansible <hostname> -i <inventory> -m debug -a "var=ansible_user"
```

## Common Issues

### SSH Config Parser
**Issue:** Hosts missing
**Fix:** Check `~/.ssh/config` syntax and permissions

### Libvirt Dynamic
**Issue:** `python3-libvirt` not found
**Fix:** `apt-get install python3-libvirt` (Debian) or `dnf install python3-libvirt` (RHEL)

**Issue:** Connection failed
**Fix:** Test SSH: `ssh grok@grok.home.serneels.xyz`

### Static Inventory
**Issue:** YAML errors
**Fix:** Check indentation, validate with `yamllint`

**Issue:** Variables not applied
**Fix:** Check file naming in `group_vars/` matches group name

## Performance Tips

```ini
# ansible.cfg
[defaults]
forks = 20
gathering = smart
fact_caching = jsonfile
fact_caching_timeout = 86400
```

```bash
# SSH connection reuse (~/.ssh/config)
Host *
  ControlMaster auto
  ControlPersist 600s
```

## Quick Setup

```bash
# Create inventory structure
mkdir -p inventories/{production,staging,development}/{group_vars,host_vars}

# Test connectivity
ansible all -i <inventory> -m ping

# Gather facts
ansible all -i <inventory> -m setup --tree /tmp/facts
```

---

**See also:** `/opt/ansible/docs/inventory.md` for complete documentation