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