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.9 or higher
Python 3.6 or higher
requests
proxmoxer
passlib

Role Variables

Required Variables

Variable	Description	Example
`container_template`	The OS template to create the LXC from. Mutually exclusive with `clone_from`	`local:vztmpl/debian-12_amd64.tar.zst`
`clone_from`	The vmid of the container or template container to clone the LXC from. Mutually exclusive with `container_template`	`201`

Required Proxmox API Authentication Variables

Note: These should be defined in group_vars/all.yml as part of the proxmox_api_connection dictionary:

# group_vars/all.yml
proxmox_api_connection:
  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 }}"

Variable	Description	Example
`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` (should be stored securely)
`proxmox_api_host`	The IP address or hostname of the Proxmox server	`192.168.1.10`
`proxmox_api_port`	The port on which the Proxmox API is listening	`8006`
`proxmox_node`	The name of the Proxmox node to target	`server1`
`proxmox_api_validate_certs`	Whether to validate SSL certificates (set to false for self-signed certs)	`false`

Optional Variables

Variable	Description	Default
`lxc_clone_type`	Only use with `lxc_clone_from`. Supports `full` and `linked` clones.	`full`
`lxc_storage`	Target storage for the container	`local-zfs`
`lxc_disk`	The target storage and storage size	`local-zfs:16`
`lxc_password`	The password for the root account	`password123`
`lxc_cores`	The number of CPU cores	`4`
`lxc_memory`	Memory size in MB for container	`2048`
`lxc_swap`	Swap memory size in MB	`2048`
`lxc_ipv4`	The IPv4 address	`dhcp`
`lxc_ipv6`	The IPv6 address	`auto`
`lxc_pubkey_file`	The SSH public key for authentication to root user	Creates a temp key in `/tmp`
`lxc_features`	List of additional container features	`- nesting=1`

Example Playbook

Prerequisites

First, set up your Proxmox API connection in group vars:

# group_vars/all.yml
proxmox_api_connection:
  api_host: "10.0.1.1"
  api_port: 8006
  api_user: "automation@pve"
  api_token_id: "mytoken"
  api_token_secret: "{{ vault_proxmox_token }}"
  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_hostname: new-debian-container
    lxc_template: "local:vztmpl/debian-12_amd64.tar.zst"
    lxc_ipv4: "10.0.0.99"
  roles:
    - role: proxmox_lxc_provision

Creating a new LXC by cloning an existing container with vmid 200

- name: Create and start an LXC container
  hosts: localhost
  connection: local
  vars:
    lxc_hostname: new-debian-container
    lxc_clone_from: 200
    lxc_ipv4: "10.0.0.99"
  roles:
    - role: proxmox_lxc_provision

Idempotent Behavior

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

Creating an LXC Container and Converting it to a Template

---
- name: Create and start an LXC container
  hosts: localhost
  connection: local
  vars:
    - container_hostname: "{{ container_hostname }}"
    - os_template: "local:vztmpl/debian-12_amd64.tar.zst"
    - container_ipv4: "10.0.0.99"
  roles:
    - role: proxmox_lxc_provision

# Run configuration tasks on the container
# ...

- name: Convert the created container to a template
  hosts: localhost
  vars:
    container_hostname: "{{ container_hostname }}"
  tasks:
    - include_role:
        name: proxmox_lxc_provision
        tasks_from: convert