Using Ansible with Proxmox: PART 1A

If you’ve ever found yourself manually creating VMs in Proxmox over and over, you know how quickly it becomes tedious. That’s where Ansible comes in. By setting up an Ansible Controller inside your Proxmox environment, you can automate repetitive VM and template creation tasks with just a few lines of code.

In this first part, we’ll prepare Proxmox, create an Ansible Controller container, and give it the keys to talk to Proxmox’s API—laying the groundwork for full-blown automation in the next part.

Step 1 – Get Proxmox Up to Date

We start by refreshing and upgrading Proxmox via the web UI (Datacentre → Server name → Updates). This ensures we’re on the latest patches and avoids running into compatibility issues later.

NOTE: You might have to reboot the server after refresh and update.

Step 2 – Upload the VM Template ISOs

Next, we upload the ISO images we’ll use for our VM templates—this could be Windows 10/11, Ubuntu, or Windows Server 2019/2022. These will serve as the base for automated deployments.

---

Step 3 – Create the Ansible Controller

We then spin up a new Ubuntu container in Proxmox, naming it Ansible-Controller-01 with a secure root password. This container will act as our central automation brain.

Top RIGHT of the screen → Blue button “Create CT” (CT - Container) → …

When this is all done, wait for a few seconds, and you’ll then see your Ansible Controller container pop up under the Proxmox server name. Click on it and to your right click the “Start” button. Log in with root and then whatever password you set.

---

Step 4 – Set up User Accounts (PVE & PAM)

Now it’s time to create a dedicated Ansible user in Proxmox.

Step 1 - PVE Account: Create an Ansible user account in the Proxmox VE authentication realm (PVE), allowing access to the web GUI and the resources you configure through it.

Step 2 - PAM Account: Create an Ansible standard Linux (PAM) user account on the Proxmox host, providing credentials for console login (like SSH).

Step 3 - User Permissions: Crucially links the Linux user (from step 2) to Proxmox's permission system (the Linux PAM realm). This is where you define what that Linux user can do within the Proxmox environment.

• We create a custom Proxmox role—i called mine “Ansible_VM_Manager” —that contains only the privileges needed for VM automation. This role is then assigned to the Ansible PAM account at the desired scope (global or node-specific) with permission propagation enabled.

• On the Proxmox host, we also update the sudoers file to allow Ansible PVE user to run specific administrative commands (e.g., apt package management and systemctl service control) without being prompted for a password—essential for seamless Ansible automation.

NOTE: Without step 3, even if the Linux user exists and has a password, Proxmox won't recognize them for its internal permissions and therefore won't allow console access.

I’ll make a separate blogpost on a detailed overview of User permissions and why we do certain things in certain ways for both PVE & PAM.

---

Step 5 – Creating Proxmox API Ansible Token

Now it’s time to create a dedicated Ansible user in Proxmox and generate an API token with the same permissions as root. This token allows Ansible to perform actions like creating and managing VMs without exposing the root account directly. We note down the token ID and secret in a secure location for later use in Ansible Vault

Datacenter → Permissions → API Tokens → Add, choose the user (e.g., Ansible@pam), give it a Token ID (e.g., ansible-token), untick Privilege Separation, and save.

NOTE: Remember to note down the secret key & token id- in either a password manager or an encrypted file somewhere accessible. Later we will save both Token ID and Secret API key securely in Ansible Vault.

---

Step 6 – Set Permissions for the Token

Using either the Proxmox UI or the console, we assign the API token the Ansible_VM_Manager role and make sure the permissions propagate across proxmox. This gives our Ansible Controller the right level of access to manage resources.

Via GUI:

Datacenter → Permissions → Add → API Token Permission, select the token, choose the desired role (e.g., Ansible_VM_Manager), set the path (/ for cluster-wide), enable Propagate, and save.

Via Console:

Temporarily disable history expansion: set +H

Grant the role to the token (cluster-wide with propagation): pveum aclmod / --tokens Ansible01@pam!ansible01-token --roles Ansible_VM_Manager --propagate 1

Re-enable history expansion: set -H

What does this code mean?

• pveum aclmod: The command for modifying Access Control Lists.

• /: The path for which you're setting permissions. In this case, it's the root path, meaning the permissions will apply cluster-wide. You could be more specific (e.g., /vms for VM permissions only) if needed.

• -tokens Ansible@pam!ansible-token: This specifies the API token you're granting permissions to.

  • Ansible@pam: The user associated with the token.

  • !: The separator indicating a token.

  • ansible-token: The Token ID you gave it when creating it in the GUI.

• -roles Ansible_VM_Manager: This assigns the Ansible_VM_Manager role to the token.

• -propagate 1: This ensures the permissions inherit down the object hierarchy (e.g., from / to all VMs, storage, etc.)

---

Step 7 – Prepare the Automation Workspace

So far we have been back and forth from the Proxmox GUI and Proxmox Server console. But now, we’re going to head back to the Ansible Controller container console.

Navigate to the home directory cd .. → mkdir -p ~/Automation/Ansible → touch setup-ansible-controller.sh → Check its there: ls → Create our controller creation script: nano setup-ansible-controller.sh

---

By the end of Part 1A, we’ve got Proxmox updated, our ISOs uploaded, an Ansible Controller container running, and secure API access ready to go. In Part 1B, we’ll bring the Ansible Controller to life by creating a Bash Script that will install Ansible, SSH keys and other important components to this Ansible controller.

If you feel certain steps or lines of code could have been done more efficiently, please let me know. At the end of the day, positive, constructive criticism, is one of the best ways to grow and improve not only as an IT Professional but life in general.

Thanks!