ansible-collection-infrastructure/roles/proxmox_lxc_provision/README.md

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 if an LXC exists by lxc_vmid or lxc_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
proxmox_delegate_host	Inventory hostname for delegated tasks (pct commands). Use this to inherit ansible_become_password from inventory.	{{ proxmox_api_host }}

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"
proxmox_delegate_host: "proxmox_server"  # inventory hostname for become_password

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 or lxc_hostname already exists, the role will skip provisioning and exit gracefully. Sets lxc_exists fact for use in subsequent tasks.

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