Automating Proxmox VE Cluster Creation with Ansible

Automating Proxmox VE cluster creation has long meant fragile shell scripts, manual SSH steps, and hard-to-debug Ansible hacks. With the new native Ansible modules proxmox_cluster and proxmox_cluster_info, you can now create and join Proxmox clusters cleanly via the official API—fully idempotent, error-aware, and ready for real-world automation.

Both modules use the official Proxmox VE API, allowing reliable and fully supported cluster creation and join operations. They are already part of the upstream Ansible Community Proxmox collection and offer robust error handling as well as support for password-based and token-based authentication.

Usage

This section explains how to use the new Ansible modules to automate Proxmox cluster creation and joining with minimal configuration.

Using these modules is intentionally simple and requires only a single Ansible task to either create a new Proxmox VE cluster or join an existing one.

Create a Proxmox VE Cluster

Creating a Proxmox VE cluster can now be fully automated using a clean, declarative Ansible task without shell commands or manual intervention.

- 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"

This allows you to easily create a bootstrap cluster by a node. Mostly, you can use the first element of a list containing the Proxmox nodes.

Join a Proxmox VE Cluster

Joining additional nodes to an existing Proxmox VE cluster is just as straightforward and can be fully automated using the same module.

- 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 creating and joining a Proxmox cluster is now easy, retrieving the required join information automatically is often just as important in real-world automation scenarios.

No worries — the proxmox_cluster_info module has you covered. With a single task, you can query an existing cluster member and retrieve all information required for safely joining additional nodes.

- 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 directly access attributes such as pve_addr, pve_fp, quorum_votes, ring0_addr, nodeid, and name from the registered variable and use them in subsequent automation steps.

FAQ

Is proxmox_cluster officially supported?

Yes, it is part of the Ansible Community Proxmox collection.

Does this work with Proxmox VE 8 and 9?

Yes, the module uses the official Proxmox VE API.

Similar Topics on Proxmox Automation

If this topic sparked your interest, you may also want to explore my other Ansible modules for Proxmox VE. For example, proxmox_storage helps manage storage backends like iSCSI, NFS, or Ceph, while proxmox_node focuses on subscriptions, certificates, and node-level configuration. You can also check out my in-depth article on clean Proxmox cluster automation with Ansible or my guide on fully automated Proxmox installations using cloud images. All of these projects share one goal: making day-to-day sysadmin work significantly easier.

Resources

The following resources provide official documentation and further details about the proxmox_cluster module.

• Ansible Community Documentation for proxmox_cluster