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 ↩ ↩²