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](https://pve.proxmox.com/wiki/Linux_Container#pct_container_images) 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`
- `post-clone.yml`: Post-clone configuration (passwords, SSH host key regeneration). Runs against the new container; depends on the `system_setup` role.
- `edit-config.yml`: Edits `/etc/pve/lxc/<vmid>.conf` directly to add ID mappings and NVIDIA GPU passthrough entries. Must be delegated to the Proxmox host.

## 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` |
| `lxc_unprivileged` | Create as an unprivileged container | `true` |
| `lxc_mounts` | Dict of additional bind mounts (e.g. `{ mp0: "/srv/data,mp=/data" }`) | - |
| `lxc_onboot` | Start container on Proxmox host boot | `false` |
| `lxc_startup` | Startup order string passed to Proxmox (e.g. `order=1,up=30`) | - |
| `lxc_timezone` | Timezone inside the container (e.g. `Europe/Berlin`) | - |
| `lxc_nvidia_gpu_mount` | Add NVIDIA GPU passthrough entries via `edit-config.yml` | `false` |
| `gpu_device_id` | Major device number for `/dev/nvidia*` (required when `lxc_nvidia_gpu_mount` is true) | - |
| `uvm_device_id` | Major device number for `/dev/nvidia-uvm*` (required when `lxc_nvidia_gpu_mount` is true) | - |
| `lxc_id_mappings` | Multi-line `lxc.idmap:` block written into the container config by `edit-config.yml` | - |


## Example Playbook

### Prerequisites

Set up your Proxmox API connection variables in group vars:

```yaml
# 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

```yaml
- 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

```yaml
- 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:

```yaml
- 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

```yaml
---
- 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
```