Ansible Role: proxmox_lxc_provision

Description

This Ansible role manages the provision of LXC containers and templates on a Proxmox host. By default the role will create and start an LXC container. It allows creating a new container from a container image or cloning an existing container or template container.

It also includes tasks which may be used individually:

clone.yml: Creates a new LXC container by cloning another container or template
convert.yml: Converts an LXC container to a template
create.yml: Creates a new LXC container
delete.yml: Deletes an LXC container given its vmid or hostname
start.yml: Starts an LXC container
stop.yml: Stops an LXC container
update.yml: Updates an existing LXC container
wait.yml: Waits for SSH to be available on the container
check-exists.yml: Checks the existence of the LXC with the given hostname

Requirements

Ansible 2.12 or higher
Python 3.6 or higher
requests
proxmoxer
passlib

Role Variables

Required Proxmox API Variables

Variable	Description	Example
`proxmox_api_host`	The IP address or hostname of the Proxmox server	`192.168.1.10`
`proxmox_api_user`	The username for Proxmox authentication, typically in format `username@realm`	`ansible@pve`
`proxmox_api_token_id`	The API token ID used for authentication	`token`
`proxmox_api_token_secret`	The secret key associated with the API token	`xxx-yyy-zzz`
`proxmox_node`	The name of the Proxmox node to target	`pve01`

Optional Proxmox API Variables

Variable	Description	Default
`proxmox_api_port`	The port on which the Proxmox API is listening	`8006`
`proxmox_api_validate_certs`	Whether to validate SSL certificates	`false`

Required Container Variables

Variable	Description	Example
`lxc_template`	The OS template to create the LXC from. Mutually exclusive with `lxc_clone_from`	`local:vztmpl/debian-12_amd64.tar.zst`
`lxc_clone_from`	The vmid of the container or template to clone. Mutually exclusive with `lxc_template`	`201`
`lxc_hostname`	The hostname for the container	`my-container`
`lxc_vmid`	The VM ID for the container	`100`

Optional Container Variables

Variable	Description	Default
`lxc_clone_type`	Clone type when using `lxc_clone_from`	`full`
`lxc_storage`	Target storage for the container	`local-zfs`
`lxc_size`	Disk size in GB	`16`
`lxc_disk`	The target storage and storage size	`local-zfs:16`
`lxc_password`	The password for the root account	-
`lxc_cores`	The number of CPU cores	`4`
`lxc_memory`	Memory size in MB	`2048`
`lxc_swap`	Swap memory size in MB	`2048`
`lxc_ipv4`	The IPv4 address	`dhcp`
`lxc_ipv6`	The IPv6 address	`auto`
`lxc_gateway`	The default gateway	`10.0.0.1`
`lxc_nameserver`	DNS nameserver	`10.0.0.7`
`lxc_pubkey_file`	Path to SSH public key file	`~/.ssh/id_ed25519.pub`
`lxc_features`	List of container features	`["nesting=1"]`
`lxc_tags`	Tags for the container	`["ansible-managed"]`
`lxc_start`	Start container after creation	`true`

Example Playbook

Prerequisites

Set up your Proxmox API connection variables in group vars:

# group_vars/all.yml
proxmox_api_host: "10.0.1.1"
proxmox_api_port: 8006
proxmox_api_user: "automation@pve"
proxmox_api_token_id: "mytoken"
proxmox_api_token_secret: "{{ vault_proxmox_token }}"
proxmox_api_validate_certs: false
proxmox_node: "pve01"

Creating a new LXC from template

- name: Create and start an LXC container
  hosts: localhost
  connection: local
  vars:
    lxc_vmid: 100
    lxc_hostname: new-debian-container
    lxc_template: "local:vztmpl/debian-12_amd64.tar.zst"
    lxc_ipv4: "10.0.0.99/24"
  roles:
    - role: proxmox_lxc_provision

Creating a new LXC by cloning an existing container

- name: Clone an LXC container
  hosts: localhost
  connection: local
  vars:
    lxc_vmid: 101
    lxc_hostname: cloned-container
    lxc_clone_from: 200
    lxc_ipv4: "10.0.0.100/24"
  roles:
    - role: proxmox_lxc_provision

Idempotent Behavior

The role includes idempotency checking. If a container with the specified lxc_vmid already exists, the role will skip provisioning and exit gracefully.

Using Standalone Tasks

When using individual task files via tasks_from, you must set module_defaults at the play level since the tasks bypass the role's main entry point:

- name: Convert container to a template
  hosts: localhost
  module_defaults:
    community.proxmox.proxmox:
      api_host: "{{ proxmox_api_host }}"
      api_port: "{{ proxmox_api_port }}"
      api_user: "{{ proxmox_api_user }}"
      api_token_id: "{{ proxmox_api_token_id }}"
      api_token_secret: "{{ proxmox_api_token_secret }}"
      validate_certs: "{{ proxmox_api_validate_certs }}"
      node: "{{ proxmox_node }}"
  vars:
    lxc_hostname: "{{ lxc_hostname }}"
  tasks:
    - include_role:
        name: proxmox_lxc_provision
        tasks_from: convert

Creating an LXC Container and Converting it to a Template

---
- name: Create and start an LXC container
  hosts: localhost
  connection: local
  vars:
    lxc_vmid: "{{ lxc_vmid }}"
    lxc_hostname: "{{ lxc_hostname }}"
    lxc_template: "local:vztmpl/debian-12_amd64.tar.zst"
    lxc_ipv4: "10.0.0.99/24"
  roles:
    - role: proxmox_lxc_provision

# Run configuration tasks on the container...

- name: Convert the created container to a template
  hosts: localhost
  module_defaults:
    community.proxmox.proxmox:
      api_host: "{{ proxmox_api_host }}"
      api_port: "{{ proxmox_api_port }}"
      api_user: "{{ proxmox_api_user }}"
      api_token_id: "{{ proxmox_api_token_id }}"
      api_token_secret: "{{ proxmox_api_token_secret }}"
      validate_certs: "{{ proxmox_api_validate_certs }}"
      node: "{{ proxmox_node }}"
  vars:
    lxc_hostname: "{{ lxc_hostname }}"
  tasks:
    - include_role:
        name: proxmox_lxc_provision
        tasks_from: convert