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.yaml: Creates a new LXC container by cloning another container or template
convert.yaml: Converts an LXC container to a template
create.yaml: Creates a new LXC container
delete.yaml: Deletes an LXC container given its vmid or hostname
start.yaml: Starts an LXC container
stop.yaml: Stops an LXC container
update.yaml: Updates an existing LXC container
wait.yaml: Waits for SSH to be available on the container

Requirements

Ansible 2.9 or higher
Python 3.6 or higher
requests
proxmoxer
passlib

Role Variables

Required Variables

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

Required Proxmox API Authentication Variables

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
`clone_type`	Only use with `ct_id`. Supports `full` and `linked` clones.	`full`
`container_storage`	Target storage for the container	`local-zfs`
`disk`	The target storage and storage size	`local-zfs:16`
`container_password`	The password for the root account	`password123`
`container_cores`	The number of CPU cores	`4`
`container_memory`	Memory size in MB for container	`2048`
`swap_memory`	Swap memory size in MB	`2048`
`container_ipv4`	The IPv4 address	`dhcp`
`container_ipv6`	The IPv6 address	`auto`
`container_pubkey_file`	The SSH public key for authentication to root user	Creates a temp key in `/tmp`
`container_features`	List of additional container features	`- nesting=1`

Example Playbook

Assuming Proxmox authentication variables are set

Creating a new LXC

- name: Create and start an LXC container
  hosts: localhost
  connection: local
  vars:
    - container_hostname: new-debian-container
    - os_template: "local:vztmpl/debian-12_amd64.tar.zst"
    - container_ipv4: "10.0.0.99"
  roles:
    - role: proxmox-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:
    - container_hostname: new-debian-container
    - ct_id: 200
    - container_ipv4: "10.0.0.99"
  roles:
    - role: proxmox-lxc-provision

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