Inventory

File	Purpose
`hosts.ini`	Static localhost, for playbooks that run on the controller
`proxmox.proxmox.yml`	Dynamic inventory — discovers every VM and LXC from the Proxmox API

Setup

ansible-galaxy collection install -r ../collections/requirements.yml
cp ../.env.example ../.env      # then fill in PROXMOX_URL and PROXMOX_TOKEN_SECRET
export $(cat ../.env | grep -v '^#' | xargs)

The token is created in Proxmox under Datacenter → Permissions → API Tokens as root@pam!ansible; the secret is shown once. The plugin config reads both values from the environment, so nothing credential-shaped lives in this directory.

Verify before running anything against it:

ansible-inventory -i proxmox.proxmox.yml --graph
ansible-inventory -i proxmox.proxmox.yml --host <hostname>
ansible all -i proxmox.proxmox.yml -m ping

Groups it builds

Group	Contents
`virtual_machines`	QEMU VMs
`containers`	LXC containers
`type_qemu`, `type_lxc`	Same split, from the plugin’s keyed group
`tag_<name>`	One per Proxmox tag — `tag_docker`, `tag_production`, …
`status_running`, `status_stopped`	By power state
`node_<name>`	By Proxmox node
`debian`, `ubuntu`, `production`, `staging`, `development`	Convenience aliases for the matching tags

Tags are the useful axis; set them in Proxmox as web;production;debian. Playbooks in this repo target proxmox_all_running and tag_docker.

ansible_host is composed from the guest’s own interface data — eth0 for LXC, eth0/ens18 from the qemu-guest-agent for VMs — falling back to the inventory hostname when neither reports an address. A VM with no guest agent therefore resolves by name.

Results are cached for 5 minutes in /tmp/ansible_proxmox_cache; rm -rf it after changing tags rather than waiting.

Semaphore

Put the credentials in a Variable Group (PROXMOX_TOKEN_SECRET, PROXMOX_URL) rather than a .env — Semaphore masks those in job logs. Add the inventory as type File pointing at ansible/inventory/proxmox.proxmox.yml, then attach the variable group to the task template as its environment.

Troubleshooting

Plugin not found — the collection is missing; install community.proxmox.

No hosts — check the API answers at all:

curl -k "$PROXMOX_URL/api2/json/cluster/resources" \
  -H "Authorization: PVEAPIToken=root@pam!ansible=$PROXMOX_TOKEN_SECRET"

SSL errors — validate_certs is already false here for the self-signed cluster certificate.