This is an Ansible Molecule Driver plugin to manage instances on a Proxmox VE hypervisor cluster. Only virtual machines are supported at this time.
- 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
.
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.)
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
.
$ python3 -m venv venv
$ . venv/bin/activate
$ pip3 install ansible-core molecule molecule-proxmox
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
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:
# Secrets file may be encrypted with ansible-vault.
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
driver:
name: molecule-proxmox
options:
# Secrets file may be encrypted with ansible-vault.
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
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
To checkout the source code:
$ git clone https://github.com/meffie/molecule-proxmox
$ cd molecule-proxmox
A Makefile and tox.ini are provided to facilitate development and testing. A Python virtualenv environment may be created with the init target.
$ make init
$ source .venv/bin/activate
Export the following shell environment variables to run the unit tests.
# Connection info:
export PROXMOX_HOST=<proxmox hostname>
export PROXMOX_PORT=<proxmox port>
export PROXMOX_USER=<username@realm> # e.g. root@pam
export PROXMOX_PASSWORD=<password>
export PROXMOX_TOKEN_ID=<id>
export PROXMOX_TOKEN_SECRET=<secret>
export PROXMOX_NODE=<proxmox node name>
export PROXMOX_SSH_USER=<username>
export PROXMOX_SSH_IDENTITY_FILE=<ssh key file for username>
# Template id and names for unit tests:
export PROXMOX_TEMPLATE_VMID=<template vmid to be cloned in by-vmid scenario>
export PROXMOX_TEMPLATE_NAME=<template name to be cloned in by-name scenario>
To run the unit tests in verbose mode:
$ make test
To run the unit tests in quiet mode:
$ make check
Molecule Proxmox Plugin was created by Michael Meffie based on code from Molecule.
The MIT License.