refactor: use module_defaults for proxmox API connection

- Replace YAML merge keys (<<:) with module_defaults block in main.yml
- Simplify connection variables to individual vars instead of dictionary
- Remove redundant connection params from individual task files
- Document standalone task usage requires play-level module_defaults
- Update README examples with new variable pattern

README.md

@@ -43,15 +43,32 @@ ansible-galaxy collection install patrickj.infrastructure
 
 ## Quick Start
 
+### Proxmox API Configuration
+
+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"
+```
+
 ### Basic Proxmox LXC Container Setup
+
 ```yaml
 - name: Create and start an LXC container
   hosts: localhost
   connection: local
   vars:
-    - container_hostname: new-debian-container
+    lxc_vmid: 100
-    - os_template: "local:vztmpl/debian-12_amd64.tar.zst"
+    lxc_hostname: new-debian-container
-    - container_ipv4: "10.0.0.99"
+    lxc_template: "local:vztmpl/debian-12_amd64.tar.zst"
+    lxc_ipv4: "10.0.0.99/24"
   roles:
     - role: proxmox_lxc_provision
 

roles/proxmox_lxc_provision/README.md

@@ -14,9 +14,10 @@ It also includes tasks which may be used individually:
 - `update.yml`: Updates an existing LXC container
 - `wait.yml`: Waits for SSH to be available on the container
 - `check-exists.yml`: Checks the existence of the LXC with the given hostname
+
 ## Requirements
 
-- Ansible 2.9 or higher
+- Ansible 2.12 or higher
 - Python 3.6 or higher
 - requests
 - proxmoxer
@@ -24,126 +25,159 @@ It also includes tasks which may be used individually:
 
 ## Role Variables
 
-### Required Variables
+### Required Proxmox API 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_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` (should be stored securely) |
+| `proxmox_api_token_secret` | The secret key associated with the API token | `xxx-yyy-zzz` |
-| `proxmox_api_host` | The IP address or hostname of the Proxmox server | `192.168.1.10` |
+| `proxmox_node` | The name of the Proxmox node to target | `pve01` |
-| `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 Proxmox API Variables
-### Optional Variables
 
 | Variable | Description | Default |
 |----------|-------------|---------|
-| `lxc_clone_type` | Only use with `lxc_clone_from`. Supports `full` and `linked` clones. | `full` |
+| `proxmox_api_port` | The port on which the Proxmox API is listening | `8006` |
+| `proxmox_api_validate_certs` | Whether to validate SSL certificates | `false` |
+
+### 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 | `password123` |
+| `lxc_password` | The password for the root account | - |
 | `lxc_cores` | The number of CPU cores | `4` |
-| `lxc_memory` | Memory size in MB for container | `2048` |
+| `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_pubkey_file` | The SSH public key for authentication to root user | Creates a temp key in  `/tmp` |
+| `lxc_gateway` | The default gateway | `10.0.0.1` |
-| `lxc_features` | List of additional container features | `- nesting=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
 
-First, set up your Proxmox API connection in group vars:
+Set up your Proxmox API connection variables in group vars:
 
 ```yaml
 # group_vars/all.yml
-proxmox_api_connection:
+proxmox_api_host: "10.0.1.1"
-  api_host: "10.0.1.1"
+proxmox_api_port: 8006
-  api_port: 8006
+proxmox_api_user: "automation@pve"
-  api_user: "automation@pve"
+proxmox_api_token_id: "mytoken"
-  api_token_id: "mytoken"
+proxmox_api_token_secret: "{{ vault_proxmox_token }}"
-  api_token_secret: "{{ vault_proxmox_token }}"
+proxmox_api_validate_certs: false
-  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_vmid: 100
     lxc_hostname: new-debian-container
     lxc_template: "local:vztmpl/debian-12_amd64.tar.zst"
-    lxc_ipv4: "10.0.0.99"
+    lxc_ipv4: "10.0.0.99/24"
   roles:
     - role: proxmox_lxc_provision
 ```
 
-### Creating a new LXC by cloning an existing container with vmid 200
+### Creating a new LXC by cloning an existing container
+
 ```yaml
-- name: Create and start an LXC container
+- name: Clone an LXC container
   hosts: localhost
   connection: local
   vars:
-    lxc_hostname: new-debian-container
+    lxc_vmid: 101
+    lxc_hostname: cloned-container
     lxc_clone_from: 200
-    lxc_ipv4: "10.0.0.99"
+    lxc_ipv4: "10.0.0.100/24"
   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.
+The role includes idempotency checking. If a container with the specified `lxc_vmid` already exists, the role will skip provisioning and exit gracefully.
 
+### 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.general.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
 
-#### 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 }}"
+    lxc_vmid: "{{ lxc_vmid }}"
-    - os_template: "local:vztmpl/debian-12_amd64.tar.zst"
+    lxc_hostname: "{{ lxc_hostname }}"
-    - container_ipv4: "10.0.0.99"
+    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
+# Run configuration tasks on the container...
-# ...
 
 - name: Convert the created container to a template
   hosts: localhost
+  module_defaults:
+    community.general.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:
-    container_hostname: "{{ container_hostname }}"
+    lxc_hostname: "{{ lxc_hostname }}"
   tasks:
     - include_role:
         name: proxmox_lxc_provision

roles/proxmox_lxc_provision/defaults/main.yml

@@ -1,4 +1,9 @@
 ---
+# Proxmox API connection defaults (optional)
+proxmox_api_port: 8006
+proxmox_api_validate_certs: false
+
+# LXC defaults
 lxc_template: "local:vztmpl/debian-12-standard_12.12-1_amd64.tar.zst"
 lxc_cores: 4
 lxc_memory: 2048

roles/proxmox_lxc_provision/tasks/check-exists.yml

@@ -1,7 +1,6 @@
 ---
 - name: Query Proxmox for existing LXCs
-  community.proxmox.proxmox_lxc_info:
+  community.proxmox.proxmox_lxc_info: {}
-    <<: "{{ proxmox_api_connection }}"
   register: proxmox_lxcs
 
 - name: Check if LXC with hostname already exists

roles/proxmox_lxc_provision/tasks/clone.yml

@@ -1,7 +1,6 @@
 ---
 - name: Create a full clone of the container
   community.general.proxmox:
-    <<: "{{ proxmox_api_connection }}"
     vmid: "{{ lxc_vmid | default(0) }}"
     clone: "{{ lxc_clone_from }}"
     clone_type: "{{ lxc_clone_type }}"

roles/proxmox_lxc_provision/tasks/convert.yml

@@ -1,8 +1,7 @@
 ---
-- ansible.builtin.include_tasks: stop.yaml
+- ansible.builtin.include_tasks: stop.yml
+
 - name: Convert container to template
   community.general.proxmox:
-    <<: "{{ proxmox_api_connection }}"
-
-    state: template
     hostname: "{{ lxc_hostname }}"
+    state: template

roles/proxmox_lxc_provision/tasks/create.yml

@@ -1,7 +1,6 @@
 ---
 - name: Create an LXC container
   community.general.proxmox:
-    <<: "{{ proxmox_api_connection }}"
     vmid: "{{ lxc_vmid | default(omit) }}"
     hostname: "{{ lxc_hostname }}"
     password: "{{ lxc_password }}"

roles/proxmox_lxc_provision/tasks/delete.yml

@@ -1,8 +1,8 @@
 ---
-- ansible.builtin.include_tasks: stop.yaml
+- ansible.builtin.include_tasks: stop.yml
+
 - name: Delete a container
   community.general.proxmox:
-    <<: "{{ proxmox_api_connection }}"
     vmid: "{{ lxc_vmid | default(omit) }}"
     hostname: "{{ lxc_hostname | default(omit) }}"
     state: absent

roles/proxmox_lxc_provision/tasks/main.yml

@@ -1,7 +1,18 @@
 ---
+- name: Proxmox LXC provision
+  module_defaults:
+    community.general.proxmox: &proxmox_defaults
+      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 }}"
+    community.proxmox.proxmox_lxc_info: *proxmox_defaults
+  block:
     - name: Check if container exists
       community.general.proxmox:
-    <<: "{{ proxmox_api_connection }}"
         vmid: "{{ lxc_vmid }}"
         state: current
       register: existing_container
@@ -20,26 +31,30 @@
       when: lxc_clone_from is defined
       block:
         - name: Clone from template
-      ansible.builtin.include_tasks: clone.yaml
+          ansible.builtin.include_tasks:
+            file: clone.yml
           register: clone_result
 
         - name: Update container
-      ansible.builtin.include_tasks: update.yaml
+          ansible.builtin.include_tasks:
+            file: update.yml
           vars:
             lxc_vmid: "{{ clone_result.vmid }}"
           register: lxc_result
 
     - name: Create the new container
-  ansible.builtin.include_tasks: create.yaml
+      ansible.builtin.include_tasks:
+        file: create.yml
       when: lxc_template is defined and lxc_clone_from is undefined
 
     - name: Start the created container and wait for ssh
       vars:
         lxc_vmid: "{{ lxc_result.vmid }}"
-  ansible.builtin.include_tasks: "{{ item }}"
+      ansible.builtin.include_tasks:
+        file: "{{ item }}"
       loop:
-    - start.yaml
+        - start.yml
-    - wait.yaml
+        - wait.yml
       when: lxc_start
 
     - name: Post clone updates
@@ -47,4 +62,5 @@
       delegate_to: "{{ lxc_hostname }}"
       block:
         - name: Include post-clone tasks
-      ansible.builtin.include_tasks: post-clone.yaml
+          ansible.builtin.include_tasks:
+            file: post-clone.yml

roles/proxmox_lxc_provision/tasks/start.yml

@@ -1,7 +1,6 @@
 ---
 - name: Start the LXC container
   community.general.proxmox:
-    <<: "{{ proxmox_api_connection }}"
     vmid: "{{ lxc_result.vmid }}"
     state: started
   register: start_result

roles/proxmox_lxc_provision/tasks/stop.yml

@@ -1,10 +1,9 @@
 ---
 - name: Stop container if it is running
   community.general.proxmox:
-    <<: "{{ proxmox_api_connection }}"
     vmid: "{{ lxc_vmid | default(omit) }}"
     hostname: "{{ lxc_hostname | default(omit) }}"
-    state: "stopped"
+    state: stopped
   register: stop_result
   failed_when: |-
     stop_result.failed and

roles/proxmox_lxc_provision/tasks/update.yml

@@ -1,10 +1,9 @@
 ---
 - name: Update an LXC container
   community.general.proxmox:
-    <<: "{{ proxmox_api_connection }}"
     vmid: "{{ lxc_vmid }}"
     hostname: "{{ lxc_hostname }}"
-    password: "{{ lxc_password | default(omit) }}" # Updating password does not work
+    password: "{{ lxc_password | default(omit) }}"
     cores: "{{ lxc_cores }}"
     memory: "{{ lxc_memory }}"
     swap: "{{ lxc_swap }}"