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

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

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