Molecule Proxmox Plugin

This is an Ansible Molecule Driver plugin to manage instances on a Proxmox VE hypervisor cluster. Only virtual machines are supported at this time.

Requirements

• Access to a Proxmox VE cluster
• One or more virtual machine templates with required setup
• Python package proxmoxer
• Ansible module community.general.proxmox_kvm

The required Python packages are automatically installed when molecule-proxmox is installed with pip.

The proxmox_kvm module is included with the Community.General collection and is automatically installed when Ansible is installed with pip.

Virtual machine template requirements

The molecule instances are created by cloning Proxmox virtual machine templates. You will need to create one or more templates.

Templates have the following requirements.

• A cloud-init drive if any cloud-init settings are used
• networking configured
• Python installed for Ansible
• qemu-guest-agent installed and enabled in Proxmox
• ssh server installed
• user account for Ansible
• An ssh public key must be added to the authorized_keys for the Ansible user account.
• If a non-root user is used for the Ansible user (recommended), that user should be added to the sudoers. (This is not needed for the driver, but will likely be needed for the converge playbook.)

Installation

The molecule-proxmox plugin may be installed with Python pip. A virtualenv is recommended. The following commands install Ansible, Molecule, and the Molecule Proxmox plugin in a virtualenv called venv.

Please note that due to a recent change in molecule this plugin will not work out of the box with molecule >=25.2.0. Therefore you will have to pin the dependency to 25.1.0 or less, until #28 is merged.

$ python3 -m venv venv
$ . venv/bin/activate
$ pip3 install ansible-core molecule==25.1.0 molecule-proxmox

Examples

driver:
  name: molecule-proxmox
  options:
     api_host: <hostname>        # e.g. pve01.example.com
     api_user: <name>@<realm>    # e.g. root@pam
     api_password: "********"
     node: pve01
     ssh_user: tester
     ssh_port: 22022             # default to 22
     ssh_identity_file: /path/to/id_rsa
platforms:
  - name: test01
    template_name: debian11
  - name: test02
    template_name: alma8

driver:
  name: molecule-proxmox
  options:
     api_host: <hostname>        # e.g. pve01.example.com
     api_port: 18006             # custom proxmox port number
     api_user: <name>@<realm>    # e.g. root@pam
     # Optional: Use an API token for Proxmox authentication.
     api_token_id: "********"
     api_token_secret: "*******************************"
     node: pve01
     ssh_user: tester
     ssh_port: 22022             # default to 22
     ssh_identity_file: /path/to/id_rsa
     # Optional: The default template name.
     template_name: debian11
     # Optional: Set the hostname after cloning.
     sethostname: yes
     # Optional: Create the VMs in the pool.
     pool: test
     # Optional: Create Linked clone instead of Full clone.
     full: false
platforms:
  - name: test01
    # Optional: Specify the VM id of the clone.
    newid: 216
  - name: test02
    # Optional: Specify the VM id of the clone.
    newid: 217

driver:
  name: molecule-proxmox
  options:
     proxmox_secrets: /path/to/proxmox_secrets.yml
     node: pve01
     ssh_user: tester
     ssh_port: 22022             # default to 22
     ssh_identity_file: /path/to/id_rsa
     template_name: debian11
platforms:
  - name: test01
  - name: test02

The proxmox_secrets setting specifies the path to an external file with settings for the proxmox API connection, such as api_password. If this is a regular file, it should be a yaml file with the settings to be included. If the file is an executable, the file will be run and the stdout will be combined with the driver options. The output of the script needs to be valid yaml consisting of dictionary keys and values (e.g. api_password: foobar).

The value of proxmox_secrets will be passed into ansible.builtin.cmd. Therefore, any additional argument values will be passed to the script as well.

This allows you to use an external password manager to store the Proxmox API connection settings. For example with a script:

driver:
  name: molecule-proxmox
  options:
     debug: true  # Enable logging proxmox_secrets tasks for troubleshooting
     proxmox_secrets: /usr/local/bin/proxmox_secrets.sh
     node: pve01

$ cat /usr/local/bin/proxmox_secrets.sh
#!/bin/sh
pass proxmox/pve01

Or with a file (which must not be executable):

driver:
  name: molecule-proxmox
  options:
     debug: true  # Enable logging proxmox_secrets tasks for troubleshooting
     proxmox_secrets: $HOME/proxmox_secrets.yaml
     node: pve01

$ cat $HOME/proxmox_secrets.yaml
---
api_host: my-proxmox-host
api_user: my-proxmox-user@pam
api_password: my-secret-password

Finally, a configuration example with many features enabled:

driver:
  name: molecule-proxmox
  options:
     proxmox_secrets: /path/to/proxmox_secrets.yml
     node: pve01
     ssh_user: tester
     ssh_port: 22022             # default to 22
     ssh_identity_file: /path/to/id_rsa
     template_name: debian11
platforms:
  - name: test01
    newid: 1000
    template_name: debian11
    # See https://docs.ansible.com/ansible/latest/collections/community/general/proxmox_kvm_module.html
    # for cloud-init options.
    ciuser: some_user
    cipassword: some_password
    ipconfig:
      ipconfig0: 'ip=192.168.0.2/24,gw=192.168.0.1'
    nameservers:
      - 192.169.0.245

Development

To checkout the source code:

git clone https://github.com/meffie/molecule-proxmox
cd molecule-proxmox

Install tox with pipx, your system package manager, or create a virtualenv.

pipx install tox

Copy the envrc.sample file to .envrc and edit the .envrc for your local proxmox site. Source the .envrc file to to export the environment variables to the current shell.

To run the tests with the latest supported molucule version:

tox -e latest

To list the tox test environments

tox list

To run tests with other versions:

tox -e <testenv> -- [<pytest_options>]

Authors

Molecule Proxmox Plugin was created by Michael Meffie based on code from Molecule.

License

The MIT License.