Repository navigation
Alerts
Information about things that may cause issues or have been noticed as problems in the past.
The cloudcodger.proxmox_client.add_guest_host role requires that all VMs have the QEMU Guest Agent pre-installed in the OS and enabled for the guest machine. Otherwise, it cannot obtain the IP address of the VMs. The Builder-Playbook was written to assist with creating custom Cloud-Init images that contain the qemu-guest-agent pre-installed.
The token_secret for API tokens are very sensitive. For this reason, they are read from files (for example, ~/.pve_tokens/lab-s1m0ne-pve-ansible.token and ~/.pve_tokens/lab-s1m0ne-pve-inventory.token) to prevent them from being saved in the git repository by accident. The correct tokens must be located in these files and are created the first time the pve.yml playbook is run. When using multiple Ansible control nodes, keeping these tokens in sync across all them is left as an exercise for the reader. If you loose a token, it can be recreated by using the PVE UI to delete the API token and running the pve.yml playbook again to create a new one.
The community.proxmox.proxmox currently has a bug that breaks the idempotency of the module when description or tags is used. The current version changes the hwaddr of the CT, which makes it unreachable. Which causes other plays trying to access the CT to fail.
Cloud-Init images used to create VMs must already exist on the PVE node where the VM is being created and located under Storage configured with the import content type. Typically located in the local storage. When stored on non-shared storage like local, each image file will need to be copied to every PVE node on which VMs will be created from it.
The import content type was added in Proxmox VE 8.2. Before that, the workaround was to create the images/00 directory for VMID 00 in the local storage on each PVE node and place the images there, which was also required to allow Disk Image content. It is possible that some code still references this old workaround.
When a PVE cluster is first created, the url: will use a self signed certificate. Either the PVE node referenced in the url: must first be configured to have a valid certificate or validate_certs: must be set to false.
Setting want_facts: to true along with setting keyed_groups: and compose: variables will allow the plugin to gather additional facts for the dynamically generated hosts.
This can be very beneficial for a small PVE cluster but has limitations.
- As the number of guest machines increases, gathering these additional facts takes a proportionally longer amount of time.
- It cannot determine the IP address of a VM using DHCP (^not actually sure about this).
The keyed_groups: section will create an Ansible group for each tag on the guest machines. This allows a playbook to create a set of machines with a specific tag that a playbook can reference in hosts:. The compose: section used in this showcase will set ansible_host to the IP address of the guest machine when possible.
The pmxcfs is a database-driven file system that is based on FUSE, so the behavior is POSIX like. But some features are simply not implemented. This causes the ansible.posix.authorized_key module to get Task failed: Module failed: [Errno 1] Operation not permitted: '/etc/pve/priv/authorized_keys' when run on a non-clustered PVE node.
Ansible has removed (or is removing) the Proxmox modules that were part of the community.general Ansible collection. All playbooks and roles are either in the process of or have been updated to reference their new location in the community.proxmox collecion. Please go ahead and report any that have not been updated and they will be added to the work needing done.
As of July 2026, the proxmoxer python module is at version 2.3.0 and has not been upgraded to be compatible with Python 3.13.x or newer. A combination of issues have come up in trying to get the module to work for the proxmox_openssh Ansible Collection.
First is the fact that this requires the Python openssh_wrapper module which has been abandoned for some time and requires the pipes module. The pipes module has been removed from Python 3.13. This alone could be remedied with the following command on Debian.
sed -i 's/import pipes/import shlex/; s/pipes.quote/shlex.quote/' ~/.venv/lib/python3.*/site-packages/openssh_wrapper.pyOr on Mac.
sed -i '' 's/import pipes/import shlex/; s/pipes.quote/shlex.quote/' ~/.pyenv/versions/${PYENV_VERSION}/lib/python3.*/site-packages/openssh_wrapper.pyThere is an open bug report for this issue at issue 198.
Second is a change that causes the following error.
Task failed: Module failed: ProxmoxAnsible.get_storages() got an unexpected keyword argument 'type'
At this time the best option is to stay with Python3.12 or Python3.11 (on Debian 12).
Note that some commands use a specific inventory file like -i lab-minimal/pve.yml instead of the directory. When the entire directory is used, it attempts to build the inventory from all the files in the directory. When running a playbook before the PVE cluster has been created, the dynamic inventory plugin will fail and display an error. The play may continue to run, but this avoids the error and any confusion it may cause.
This will still cause the playbook to use the group_vars and host_vars located next to the file.
Some of the Ansible modules used have recently changed the default behavior for validating SSL certificates to true. In order to run these before you have created any valid certificates, you can run this command to switch the behaviour back to being false.
export PROXMOX_VALIDATE_CERTS=false