Inventory

Synced from the repo

This page is generated from ansible/inventory/README.md. Edit it there — changes here are overwritten on the next build.

This directory contains both static and dynamic inventory configurations.

Inventory Files

Static Inventory

• hosts.ini - Static inventory for localhost testing

Dynamic Inventory

• proxmox.proxmox.yml - Proxmox VE dynamic inventory plugin configuration

Setting Up Proxmox Dynamic Inventory

Prerequisites

1. Install Required Collection

# Install community.proxmox collection
ansible-galaxy collection install community.proxmox

# Or install from requirements
ansible-galaxy collection install -r ../collections/requirements.yml

2. Create API Token in Proxmox

In your Proxmox web interface:

1. Navigate to Datacenter → Permissions → API Tokens
2. Click Add
3. Configure:
   • User: root@pam (or your preferred user)
   • Token ID: ansible
   • Privilege Separation: Uncheck (or configure appropriate permissions)
4. Copy the secret - it will only be shown once!

Configuration

For Local Testing (Using .env File)

# Copy the example file
cp ../.env.example ../.env

# Edit and add your Proxmox token secret
nano ../.env

Add:

PROXMOX_TOKEN_SECRET=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

For Semaphore UI (Using Variable Groups - Recommended)

Semaphore UI has built-in secret management that’s more secure:

1. In Semaphore, go to your project
2. Navigate to Variable Groups
3. Click “New Variable Group”
4. Name it (e.g., “Proxmox Credentials”)
5. Add JSON with your secrets:

{
  "PROXMOX_TOKEN_SECRET": "your-actual-token-secret-here",
  "PROXMOX_URL": "https://proxmox.example.com:8006"
}

Benefits:

• Secrets are automatically masked in logs
• Centralized secret management
• No need for .env files in the repository
• Variables passed securely at runtime

6. Associate the Variable Group with your Task Template

Update Proxmox URL

Edit proxmox.proxmox.yml and update the url field:

url: http://your-proxmox-host:8006

Or use HTTPS with your domain:

url: https://proxmox.yourdomain.com:8006
validate_certs: true  # Set to true if using valid SSL cert

Testing the Inventory

List All Hosts

# From ansible directory
cd /home/unknown224/ubuntu-server-config/ansible

# List all discovered hosts
ansible-inventory -i inventory/proxmox.proxmox.yml --list

# List hosts in graph format
ansible-inventory -i inventory/proxmox.proxmox.yml --graph

# List specific group
ansible-inventory -i inventory/proxmox.proxmox.yml --graph virtual_machines

Test Connectivity

# Ping all Proxmox hosts
ansible all -i inventory/proxmox.proxmox.yml -m ping

# Ping specific group
ansible virtual_machines -i inventory/proxmox.proxmox.yml -m ping

# Ping hosts with specific tag
ansible tag_web -i inventory/proxmox.proxmox.yml -m ping

Get Host Details

# Get details for a specific host
ansible-inventory -i inventory/proxmox.proxmox.yml --host <hostname>

# List all groups
ansible-inventory -i inventory/proxmox.proxmox.yml --list | jq 'keys'

Proxmox Host Grouping

The dynamic inventory automatically creates groups based on:

1. Tags (Recommended)

Tag your VMs/containers in Proxmox (Format: web;production;debian):

• tag_web - Hosts tagged with “web”
• tag_production - Hosts tagged with “production”
• tag_debian - Hosts tagged with “debian”

2. Type

• virtual_machines - All QEMU VMs
• containers - All LXC containers
• type_qemu - QEMU VMs
• type_lxc - LXC containers

3. Status

• status_running - All running hosts
• status_stopped - All stopped hosts

4. Node

• node_pve1 - Hosts on node “pve1”
• node_pve2 - Hosts on node “pve2”

5. Custom Groups

Pre-configured in proxmox.proxmox.yml:

• debian - Hosts tagged with “debian”
• ubuntu - Hosts tagged with “ubuntu”
• production - Hosts tagged with “production”
• staging - Hosts tagged with “staging”
• development - Hosts tagged with “development”

Using with Playbooks

Single Inventory

ansible-playbook -i inventory/proxmox.proxmox.yml playbooks/your-playbook.yml

Multiple Inventories

# Use both static and dynamic inventory
ansible-playbook -i inventory/hosts.ini -i inventory/proxmox.proxmox.yml playbooks/your-playbook.yml

Target Specific Groups

---
# playbook example
- name: Configure web servers
  hosts: tag_web
  tasks:
    - name: Install nginx
      apt:
        name: nginx
        state: present

Using with Semaphore UI

Step-by-Step Setup

1. Create Variable Group (for secrets)

• Go to Variable Groups in your project
• Click “New Variable Group”
• Name: Proxmox Credentials
• JSON content:

{
  "PROXMOX_TOKEN_SECRET": "your-actual-token-secret",
  "PROXMOX_URL": "https://proxmox.example.com:8006"
}

• Secrets will be automatically masked in logs

2. Create Inventory

• Go to Inventories
• Click “New Inventory”
• Name: Proxmox Dynamic
• Type: File
• Inventory Path: ansible/inventory/proxmox.proxmox.yml

3. Create Task Template

• Go to Task Templates
• Click “New Template”
• Configure:
  • Name: Deploy to Proxmox VMs
  • Playbook Filename: ansible/playbooks/your-playbook.yml
  • Inventory: Select Proxmox Dynamic
  • Environment (Variable Group): Select Proxmox Credentials

4. Run the Task

• The inventory will automatically discover all running VMs/containers
• Secrets are passed securely at runtime
• Logs will show masked values for sensitive data

Alternative: Using Key Store

For even more secure credential storage:

1. Go to Key Store
2. Add a Login with Password type key
3. Name: Proxmox API Token
4. Username: root@pam!ansible (full token identifier)
5. Password: Your token secret

Then reference this key in your inventory configuration or as an Ansible vault password.

Troubleshooting

“Plugin not found” Error

Install the collection:

ansible-galaxy collection install community.proxmox

Authentication Errors

1. Local testing: Verify token secret in .env file
2. Semaphore: Check Variable Group has correct PROXMOX_TOKEN_SECRET
3. Verify token permissions in Proxmox (ensure token has proper privileges)
4. Ensure user has appropriate privileges for VM/container access
5. Test with curl to verify API access (see command below)

No Hosts Found

1. Verify Proxmox URL is correct
2. Check that VMs/containers are running (filter: status == "running")
3. Test API access:

curl -k "https://proxmox.example.com:8006/api2/json/cluster/resources" \
  -H "Authorization: PVEAPIToken=root@pam!ansible=your-token-secret"

SSL Certificate Errors

If using self-signed certificates, set in proxmox.proxmox.yml:

validate_certs: false

Cache Issues

Clear the inventory cache:

rm -rf /tmp/ansible_proxmox_cache

Best Practices

1. Use Tags - Organize your Proxmox VMs/containers with meaningful tags
2. API Tokens - Prefer API tokens over password authentication
3. Semaphore Variable Groups - Use Semaphore’s built-in secret management for production
4. Local .env Files - Use .env files only for local testing (never commit to git)
5. Limit Scope - Use filters to only include necessary hosts
6. Test First - Always test inventory with ansible-inventory --list before running playbooks
7. Cache Wisely - Use caching for better performance, but clear when changes are made
8. Document Tags - Maintain a list of tag conventions for your infrastructure

Example Workflow

# 1. Tag VMs in Proxmox: "web;production;ubuntu"

# 2. Test inventory
ansible-inventory -i inventory/proxmox.proxmox.yml --graph

# 3. Verify connectivity
ansible tag_web -i inventory/proxmox.proxmox.yml -m ping

# 4. Run playbook
ansible-playbook -i inventory/proxmox.proxmox.yml playbooks/configure-web-servers.yml

# 5. Target specific environment
ansible-playbook -i inventory/proxmox.proxmox.yml playbooks/deploy.yml --limit production

Resources

• Proxmox Inventory Plugin Documentation
• Ansible Inventory Guide
• Proxmox API Documentation