Ansible Role: PVE Helper Script

Unattended deployment of Proxmox Helper Scripts from the community-scripts/ProxmoxVE repository. Upstream documentation can be found here: Unattended Deployments Guide

Important

Disclaimer: AI was used in the creation of this role. It's been tested across multiple scripts, but you should do so as well before using this in production.

S/O to Jeff Geerling and Debops who I used as a best practices benchmark for var naming, README format, and more.

Requirements

None (tested with Ansible 2.17.12, Python 3.10.12, Jinja 3.0.3)

Templates

None

Files

None

Role Variables

Required Variables

Variable	Required	Default Value	Description
pve_helper_script__app_name	Yes	""	The name of the helper script to execute (e.g., debian, ubuntu, alpine). Must match a script name from the Proxmox Helper Scripts repository.
pve_helper_script__var_ctid	Yes	""	The container ID (CTID) to assign to the new LXC container. Must be unique on the Proxmox VE host.
pve_helper_script__var_hostname	Yes	""	The hostname to assign to the new LXC container.

Core Resource Variables

Variable	Required	Default Value	Description
pve_helper_script__var_cpu	No	2	Number of CPU cores to allocate to the container.
pve_helper_script__var_ram	No	2048	Amount of RAM (in MB) to allocate to the container.
pve_helper_script__var_disk	No	8	Disk size (in GB) to allocate to the container.

Deployment Configuration Variables

Variable	Required	Default Value	Description
pve_helper_script__install_mode	No	"default"	Installation mode for the helper script. Typically default or advanced.
pve_helper_script__shell_timeout	No	600	Timeout (in seconds) for the shell command execution.
pve_helper_script__script_environment	No	"prod"	Script repository environment. Options: prod (uses community-scripts/ProxmoxVE), dev (uses community-scripts/ProxmoxVED).
pve_helper_script__var_verbose	No	"no"	Enable verbose output from the helper script. Set to "yes" for detailed logging.
pve_helper_script__var_ipv6_method	No	"none"	IPv6 configuration method. Options: none, static, slaac, dhcp.
pve_helper_script__var_net	No	"dhcp"	Network configuration method. Options: dhcp, static.
pve_helper_script__var_unprivileged	No	1	Create an unprivileged container. Set to 0 for privileged container.
pve_helper_script__var_ssh	No	"yes"	Enable SSH in the container. Set to "no" to disable.
pve_helper_script__var_ssh_authorized_key	No	null	SSH public key to add to the container's authorized_keys file.
pve_helper_script__var_tags	No	""	Comma-separated list of tags to assign to the container. The role automatically prepends ansible_managed and ansible.pve-helper-script tags to any tags you specify.

Optional Helper Script Variables

The following variables map directly to helper script parameters and are only included in the command if defined and non-empty:

Variable	Required	Default Value	Description
pve_helper_script__var_template_storage	No	Omit	Storage location for container templates.
pve_helper_script__var_container_storage	No	Omit	Storage location for container volumes.
pve_helper_script__var_apt_cacher	No	Omit	APT cache proxy URL.
pve_helper_script__var_apt_cacher_ip	No	Omit	APT cache proxy IP address.
pve_helper_script__var_brg	No	Omit	Bridge interface name.
pve_helper_script__var_fuse	No	Omit	Enable FUSE support.
pve_helper_script__var_gpu	No	Omit	GPU passthrough configuration.
pve_helper_script__var_gateway	No	Omit	Network gateway IP address.
pve_helper_script__var_ipv6_static	No	Omit	Static IPv6 address.
pve_helper_script__var_keyctl	No	Omit	Enable keyctl support.
pve_helper_script__var_mac	No	Omit	MAC address for the container.
pve_helper_script__var_mknod	No	Omit	Enable mknod support.
pve_helper_script__var_mount_fs	No	Omit	Filesystem mount options.
pve_helper_script__var_mtu	No	Omit	Network MTU size.
pve_helper_script__var_nesting	No	Omit	Enable container nesting.
pve_helper_script__var_ns	No	Omit	Namespace configuration. Must be provided as -nameserver=1.1.1.1
pve_helper_script__var_os	No	Omit	Operating system variant/version.
pve_helper_script__var_protection	No	Omit	Container protection settings.
pve_helper_script__var_pw	No	Omit	Root password for the container.
pve_helper_script__var_searchdomain	No	Omit	DNS search domain.
pve_helper_script__var_ssh_import_glob	No	Omit	SSH key import glob pattern.
pve_helper_script__var_storage	No	Omit	Storage pool name.
pve_helper_script__var_timezone	No	Omit	Timezone for the container.
pve_helper_script__var_tun	No	Omit	Enable TUN/TAP device. Must be "yes" or "no" when defined.
pve_helper_script__var_udhcpc_fix	No	Omit	Apply udhcpc fix.
pve_helper_script__var_full_verbose	No	Omit	Enable full verbose output.
pve_helper_script__var_version	No	Omit	OS version to install.
pve_helper_script__var_vlan	No	Omit	VLAN ID for network configuration.

Ad-Hoc Variables

Pass additional variables to the helper script that are not predefined by the role. This is useful for passing new or experimental helper script parameters without modifying the role code.

Variable	Required	Default Value	Description
pve_helper_script__additional_vars	No	{}	Dictionary of additional variables to pass to the helper script. Variables are automatically formatted and included in the command string. Empty values are automatically skipped. Example: { var_custom_option: "value1", var_another_option: "value2" }

Logging and Debugging Variables

Variable	Required	Default Value	Description
pve_helper_script__enable_script_logging	No	"false"	Enable developer mode logging in the helper script. Set to "true" to enable.
pve_helper_script__env_var_ssh_keys_file	No	""	Path to SSH keys file for the helper script environment. Required to avoid unbound variable errors in unattended mode. Can be set to empty string.
pve_helper_scripts_helper_script_output_log_filename	No	/tmp/ansible_role_pve-helper-script/ctid-{{ pve_helper_script__var_ctid }}_$(date +%Y-%m-%d_%H-%M-%S).log	Path and filename pattern for the helper script output log file. Uses Jinja2 templating for CTID and shell command substitution for timestamp.

Dependencies

None

Example Playbook

Basic Deployment

- name: Deploy Debian LXC Container
  hosts: pve_host
  roles:
    - pve-helper-script
  vars:
    pve_helper_script__app_name: "debian"
    pve_helper_script__var_ctid: 100
    pve_helper_script__var_hostname: "my-debian-container"
    pve_helper_script__var_ssh_authorized_key: "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI..."
    pve_helper_script__var_template_storage: "local"
    pve_helper_script__var_container_storage: "domains"

Advanced Deployment with Custom Resources

- name: Deploy Ubuntu LXC Container with Custom Resources
  hosts: pve_host
  roles:
    - pve-helper-script
  vars:
    pve_helper_script__app_name: "ubuntu"
    pve_helper_script__var_ctid: 101
    pve_helper_script__var_hostname: "my-ubuntu-container"
    pve_helper_script__var_cpu: 4
    pve_helper_script__var_ram: 4096
    pve_helper_script__var_disk: 20
    pve_helper_script__var_ssh_authorized_key: "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI..."
    pve_helper_script__var_template_storage: "local"
    pve_helper_script__var_container_storage: "domains"
    pve_helper_script__var_tun: "yes"
    pve_helper_script__var_nesting: "yes"

Static IP Configuration

- name: Deploy Container with Static IP
  hosts: pve_host
  roles:
    - pve-helper-script
  vars:
    pve_helper_script__app_name: "debian"
    pve_helper_script__var_ctid: 102
    pve_helper_script__var_hostname: "static-ip-container"
    pve_helper_script__var_net: "static"
    pve_helper_script__var_gateway: "192.168.1.1"
    pve_helper_script__var_ssh_authorized_key: "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI..."

Using Ad-Hoc Variables

- name: Deploy Container with Ad-Hoc Variables
  hosts: pve_host
  roles:
    - pve-helper-script
  vars:
    pve_helper_script__app_name: "debian"
    pve_helper_script__var_ctid: 103
    pve_helper_script__var_hostname: "custom-container"
    pve_helper_script__additional_vars:
      var_custom_option: "custom_value"
      var_experimental_feature: "enabled"
      var_another_param: "value"

For Developers and Maintainers

Role Structure

The role follows a modular task structure:

1. Input Validation (tasks/main.yml lines 10-59): Validates required variables (pve_helper_script__app_name, pve_helper_script__var_ctid, pve_helper_script__var_hostname), validates script URL accessibility (HTTP 200), and validates optional variable formats (e.g., var_tun must be yes or no)
2. Build Shell Command (tasks/main.yml lines 69-180): Constructs the helper script command with all variables, including required parameters, optional parameters (only if defined and non-empty), ad-hoc variables from pve_helper_script__additional_vars, and automatic tag management
3. Execute Helper Script (tasks/main.yml lines 196-210): Executes the helper script with timeout and environment variables, captures output to log file, and handles error detection
4. Verify Creation & Build Deployment Summary (tasks/main.yml lines 216-290): Extracts deployment information using regex patterns (with ANSI escape code stripping), displays summary, and handles specific error conditions (404 errors, ID already in use)

How It Works

1. The role validates that required variables (pve_helper_script__app_name, pve_helper_script__var_ctid, pve_helper_script__var_hostname) are defined and non-empty.

2. The script URL is validated by checking that it returns HTTP 200 before execution. The URL is constructed from pve_helper_script__script_environment (prod/dev) and pve_helper_script__app_name.

3. A shell command is constructed using Jinja2 templating that includes:

   • All required helper script parameters
   • Optional parameters (only if defined and non-empty)
   • Ad-hoc variables from pve_helper_script__additional_vars dictionary (only if defined and non-empty)
   • Automatic prepending of ansible_managed and ansible.pve-helper-script tags to any user-specified tags
   • Suppression of package upgrade prompt via echo "n"

4. The helper script is executed by downloading it from GitHub and piping the constructed variables:

   echo "n" | \
   mode=default \
   var_ctid=100 \
   ... \
   bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVED/main/ct/debian.sh)"

5. Output is captured to a log file (specified by pve_helper_scripts_helper_script_output_log_filename) and registered for processing.

6. The role extracts deployment summary information (CT ID, hostname, IP address, operating system, URL) using regex patterns and displays it. The URL field is extracted from helper script output when available (typically for services with web UIs) and defaults to "N/A" if not present.

Error Handling

• ID Already in Use: The role detects when a CTID is already in use and fails with a specific error message.
• Command Not Found: The role fails if the helper script command is not found.
• Helper Script Not Found (HTTP 404): The role detects when the helper script URL returns a 404 error (either during validation or execution) and fails with a specific error message indicating the script name is invalid.
• Invalid Script URL: The role validates the script URL before execution and fails if it doesn't return HTTP 200.
• Validation Errors: Required variables are validated before execution, with clear error messages. The var_tun variable is validated to ensure it's either "yes" or "no" when defined.

Logging

• Helper script output is logged to the file specified by pve_helper_scripts_helper_script_output_log_filename (default: /tmp/ansible_role_pve-helper-script/ctid-{CTID}_{timestamp}.log)
• Log files are named with the pattern: ctid-{CTID}_{timestamp}.log where {CTID} is the container ID and {timestamp} is generated at execution time
• Helper script logs are also available in /var/log/community-scripts on the PVE host
• Verbose output can be enabled with pve_helper_script__var_verbose: "yes"
• Developer mode logging can be enabled with pve_helper_script__enable_script_logging: "true" (sets DEV_MODE_LOGS and dev_mode=logs environment variables)

Known Limitations

• Container creation is not idempotent - running the role multiple times with the same CTID will fail if the container already exists. The community.proxmox.proxmox_vm_info module can be used to check for CT ID conflicts prior to role execution.
• The role does not support updating existing containers (application version, resources, etc.)
• Some helper script parameters may not be supported - check the Proxmox Helper Scripts documentation for available options

Troubleshooting

Container ID Already in Use

• Error: ID 'XXX' is already in use.
• Solution: Use a different pve_helper_script__var_ctid value or delete the existing container

Helper Script Not Found (Command)

• Error: command not found in output
• Solution: Verify the pve_helper_script__app_name matches a valid script name from the repository

Helper Script Not Found (HTTP 404)

• Error: curl: (22) The requested URL returned error: 404
• Solution: Verify the pve_helper_script__app_name matches a valid script name from the Proxmox Helper Scripts repository. The script may have been removed or renamed.

Timeout Errors

• Error: Task times out
• Solution: Increase pve_helper_script__shell_timeout value, especially for larger containers or slower networks

Unbound Variable Errors

• Error: Unbound variable in helper script
• Solution: Ensure pve_helper_script__env_var_ssh_keys_file is set (can be empty string)

License

MIT / BSD

Author Information

ramgoat