From Scripted Chaos to Clean API: Proxmox Cluster Setup with Ansible Done Right with the New proxmox_cluster Module

Until now, automating Proxmox cluster setups with Ansible often meant relying on hacky shell or command module usages within playbooks/roles and dealing with poor error handling. That changes with my new Ansible modules, proxmox_cluster and proxmox_cluster_join and if you’re following me, you might have already found this as a sneak peek in my post about how BoxyBSD boosted the Proxmox ecosystem. These tools leverage the official Proxmox API, enabling direct and reliable cluster creation and also joining a cluster. Already available in the upstream Ansible Community Proxmox collection, they include robust error handling and support for both user and token-based authentication.
Usage
Using this new module is pretty straightforward and simply requires only one task for creating and also joining a Proxmox cluster:
- name: Create a Proxmox VE Cluster
community.proxmox.proxmox_cluster:
state: present
api_host: proxmoxhost
api_user: root@pam
api_password: password123
api_ssl_verify: false
link0: 10.10.1.1
link1: 10.10.2.1
cluster_name: "devcluster"
- name: Join a Proxmox VE Cluster
community.proxmox.proxmox_cluster:
state: present
api_host: proxmoxhost
api_user: root@pam
api_password: password123
master_ip: "{{ primary_node }}"
fingerprint: "{{ cluster_fingerprint }}"
cluster_name: "devcluster"
While you can now easily create and join a Proxmox cluster, obtaining the join information from a cluster in an automated way is also interesting. No worries – my proxmox_cluster_info module has you covered! Just as easy as creating and joining, you can also gather the required join information from a cluster member by running the following task:
- name: List existing Proxmox VE cluster join information
community.proxmox.proxmox_cluster_join_info:
api_host: proxmox1
api_user: root@pam
api_password: "{{ password | default(omit) }}"
api_token_id: "{{ token_id | default(omit) }}"
api_token_secret: "{{ token_secret | default(omit) }}"
register: proxmox_cluster_join
Afterwards, you can simply access the attributes pve_addr, pve_fp, qourum_votes, ring0_addr, nodeid and name from the registered variable.
Resources
- Ansible Community Documentation for proxmox_cluster module
- Ansible Community proxmox_cluster module commit
- Ansible Community Proxmox Repository