Guide: Manage Proxmox LXCs using PCT over SSH with Ansible

[burgerga]

Introduction

Because of some extensive work (ansible-collections/community.general#8424) by @mietzen, the ansible community.general collection¹ now supports managing Proxmox LXCs using PCT over SSH (community.general.proxmox_pct_remote²).
This enables management of Proxmox containers without the need to setup SSH access to the containers themselves.
Below I will show you how to set this up, and give an example of how to use it. Hope this will be useful to you!

Prerequisites

Before we begin, ensure you have the following:

1. A Proxmox server with LXC containers.
2. Ansible installed on your local machine.
3. SSH access to your Proxmox server.

Step-by-Step Guide

Step 1: Install/update the community.general collection

The proxmox_pct_remote connection module is part of the community.general collection from version 10.3.0 onwards. You can install/update it using the following command:

ansible-galaxy collection install -U community.general

Step 2: Create an inventory of your Proxmox LXCs

It is possible to create a static or dynamic inventory. Below is an example of how to create a dynamic inventory using proxmox.inventory³ (for a static example see²)):

# ~/ansible/inventory/proxmox.yml
plugin: community.general.proxmox
url: "http://192.168.2.3:8006" # Proxmox host (replace with your IP/URL)
user: root@pam
password: <YOUR_PASSWORD>
validate_certs: false   
want_facts: true
keyed_groups:
  - key: proxmox_tags_parsed
    separator: ""
    prefix: proxmox_tags_
compose:
  ansible_host: "'192.168.2.3'"
  ansible_connection: "'community.general.proxmox_pct_remote'"
  ansible_user: "'root'"
  ansible_private_key_file: "'~/.ssh/pve'"

Some notes:

• it is also possible to use environment variables or API tokens for the password, see the documentation³.
• the keyed_groups groups proxmox LXCs/VMs by their tags, so for example, all containers tagged with 'docker' will be in the ansible hosts group proxmox_tags_docker
• the compose section is key here, we can use it to add some default variables to the hosts in this inventory. In this case we specify that we want to use the community.general.proxmox_pct_remote connection plugin over SSH to the Proxmox host (192.168.2.3 in my case). Note the double quotes in the compose section, this is because these are Jinja expressions IIRC.

Test the inventory and community.general.proxmox_pct_remote

You can test the inventory by running the following command:

ansible-inventory --list

To test the community.general.proxmox_pct_remote connection plugin, you can run the following command (proxmox_all_running is a group that is created by the inventory plugin):

ansible proxmox_all_running -m ping

(Optional) Speeding it up

By default, the dynamic inventory will be recreated every time you run a playbook. This can be slow if you have many containers. To speed it up, you can cache the inventory, by adding the following to your ansible.cfg:

[defaults]
# Directory containing inventory files
inventory = ./inventory
fact_caching_connection = .cache
fact_caching = jsonfile

[inventory]
cache = True
cache_plugin = jsonfile

In addition, the PCT over SSH it quite slow, because the paramiko ssh plugin (used by this plugin) doesn't support persistent connections. You can use parallel execution to speed it up a bit, by adding the following to your ansible.cfg:

[defaults]
forks = 8 # Number of parallel processes to use

Also gathering facts can be slow, you can disable it by setting gather_facts: false in your playbook. (it can even crash ansible if you have many containers, because many devices are shared between containers, in that case you can use the gather_subset option to limit the facts gathered, for example gather_subset: ["!devices"]).

Example use

You can now use the inventory to run regular playbooks on your Proxmox containers. For example, I use the following playbook (based on https://docs.portainer.io/start/upgrade/docker) to update portainer and the portainer_agent container to 2.27.1 on all my LXCs I tagged in proxmox with docker:

# ~/ansible/playbooks/update_portainer.yml
---
- name: Update portainer
  hosts: portainer
  gather_subset: ["!devices"]
  tasks:
    - name: Update and restart portainer
      community.docker.docker_container:
        name: portainer
        image: portainer/portainer-ce:2.27.1
        state: started
        volumes:
          - "/var/run/docker.sock:/var/run/docker.sock"
          - "portainer_data:/data"
        ports:
          - "9443:9443"
          - "8000:8000"
        restart_policy: "always"
- name: Update portainer_agent
  hosts: proxmox_tags_docker
  gather_subset: ["!devices"]
  tasks:
    - name: Check if portainer_agent container exists
      docker_container_info:
        name: portainer_agent
      register: result
    - name: Update and restart portainer_agent
      community.docker.docker_container:
        name: portainer_agent
        image: portainer/agent:2.27.1
        state: started
        volumes:
          - "/var/run/docker.sock:/var/run/docker.sock"
          - "/var/lib/docker/volumes:/var/lib/docker/volumes"
        ports:
          - "9001:9001"
        restart_policy: "always"
      when: result.exists

Enjoy!

Footnotes

1. https://galaxy.ansible.com/ui/repo/published/community/general/ ↩

2. https://docs.ansible.com/ansible/latest/collections/community/general/proxmox_pct_remote_connection.html ↩ ↩²

3. https://docs.ansible.com/ansible/latest/collections/community/general/proxmox_inventory.html ↩ ↩²

[ZsZs73]

Hello,
Thanks for this guide. I am playing with this and trying to adapt it to fulfill my requirements where:

• no root logins via ssh to PVE are allowed
• no NOPASSWD sudo entries are allowed on the PVE

If I create an admin user on the PVE and add it to the sudo group which has the following permissions according to sudoers:
%sudo ALL=(ALL:ALL) ALL
Then I can interactively log in from my ansible control node to the PVE and run commands with sudo (it asks correctly for the password) but via paramiko it does not work.
I see the following in the auth.log of the PVE:

2025-03-09T19:57:55.275635+01:00 pve1 sshd[3081357]: Accepted publickey for admin from 192.168.x.y port 50854 ssh2: RSA SHA256:KiTBg..REDADCTED...gqr8
2025-03-09T19:57:55.278654+01:00 pve1 sshd[3081357]: pam_unix(sshd:session): session opened for user admin(uid=2000) by (uid=0)
2025-03-09T19:57:55.280114+01:00 pve1 systemd-logind[997]: New session 27287 of user admin.
2025-03-09T19:57:55.293869+01:00 pve1 sshd[3081357]: pam_env(sshd:session): deprecated reading of user environment enabled
2025-03-09T19:57:55.344499+01:00 pve1 sudo: pam_unix(sudo:auth): conversation failed
2025-03-09T19:57:55.346745+01:00 pve1 sudo: pam_unix(sudo:auth): auth could not identify password for [admin]
2025-03-09T19:57:55.348368+01:00 pve1 sshd[3081357]: pam_unix(sshd:session): session closed for user admin
2025-03-09T19:57:55.352480+01:00 pve1 systemd-logind[997]: Session 27287 logged out. Waiting for processes to exit.
2025-03-09T19:57:55.360522+01:00 pve1 systemd-logind[997]: Removed session 27287.

Is it a paramiko limitation that it can not pass password to sudo, or am I missing something?
The closest to the above requirements is the following:

groupadd -g 2000 admins
echo '%admin ALL = (root) NOPASSWD: /usr/sbin/pct' > /etc/sudoers.d/ansible_pct
chmod 440 /etc/sudoers.d/ansible_pct
usermod -G admins admin

But still security people are irritated by this NOPASSWD..
Even the doc says that sudo should be set up without password, but this is not a good practice in my opinion.