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