lae.proxmox: an Ansible role that installs and clusters Proxmox VE

What the role actually installs

The role is published on Ansible Galaxy as lae.proxmox, and the README describes it as installing and configuring Proxmox Virtual Environment 6.x, 7.x, 8.x and 9.x on Debian servers. The stated scope covers both single node PVE installations and PVE clusters with three or more nodes, on Debian Buster (10), Bullseye (11), Bookworm (12) and Trixie (13). The configurable surface is listed explicitly: PVE RBAC definitions covering roles, groups, users and access control lists, PVE storage definitions, datacenter.cfg, HTTPS certificates for the Proxmox web GUI on a bring your own basis, PVE repository selection such as pve-no-subscription or pve-enterprise, and watchdog modules for IPMI and NMI with the matching pve-ha-manager configuration. It also sets up the ZFS module and ZED notification email. The licence is MIT and the default branch is develop.

The clustering path and its prerequisites

With clustering enabled the role does, or lets you do, the parts that are genuinely hard to do by hand. It ensures all hosts can reach one another as root over SSH, it initialises a new PVE cluster or adopts an existing one, it creates or adds new nodes, it sets up Ceph on the cluster, and it creates and manages high availability groups. The SSH requirement is the one to plan for, because root over SSH between the nodes is the foundation everything else is built on. The Ceph step is notable because shared storage for a cluster is a decision with cost attached, and having it in the same role as the cluster creation means a run either provisions the whole thing or leaves you to run the cluster tasks separately. The role also lets you point it at an existing cluster to adopt, which is what you want if the nodes are already installed and you want the configuration managed declaratively.

The quickstart, and why you need a second machine

The quickstart is short, and the README is upfront about an awkward requirement: you need an external machine to the one you are installing Proxmox on, primarily because of the reboot in the middle of the installation. The author notes this may be handled somewhat differently for that use case later, which is a fair signal that the single node path is the less travelled one. The playbook itself is short, since the role does the work.

    - hosts: all
      become: True
      roles:
        - role: geerlingguy.ntp
          vars:
            ntp_manage_config: true
            ntp_servers:
              - clock.sjc.he.net,
              - clock.fmt.he.net,
              - clock.nyc.he.net
        - role: lae.proxmox
          vars:
            pve_group: all
            pve_reboot_on_kernel_update: true

The role and the NTP role are then installed from Galaxy, and the playbook is run against the target host.

    ansible-galaxy install lae.proxmox geerlingguy.ntp

    ansible-playbook install_proxmox.yml -i $SSH_HOST_FQDN, -u $SSH_USER

The trailing comma in the inventory argument is deliberate, since a list is expected, and without it Ansible will try to read a file containing a list of hosts. If the SSH user has a sudo password you pass the -K flag, and if you authenticate by password rather than pubkey you also need -k and sshpass installed. When the run finishes, the web interface is reachable at https://$SSH_HOST_FQDN:8006.

The cluster playbook directory and where the certificates live

For a full cluster the README walks through a directory layout that shows what the role expects. The lab-cluster directory holds a files/ tree with a .key and .pem per node, group_vars/ split into an all file and a per cluster file, an inventory, a roles/requirements.yml, a site.yml and a templates/ directory holding a per cluster interfaces template. The private keys and SSL certificates are the point of that files tree. They are the keys and certificates the role uses to configure the web interface across all the nodes, and the README says they are not necessary if you want to keep using the signed certificates from the CA that Proxmox sets up internally. When you do supply your own, the README suggests encrypting them with Ansible Vault.

    ansible-vault encrypt files/pve01/*.key

The certificate paths are then resolved with a file lookup from the group variables, and the same lookup pattern is used for the private key.

  pve_ssl_private_key: "{{ lookup('file', pve_group + '/' + inventory_hostname + '.key') }}"
  pve_ssl_certificate: "{{ lookup('file', pve_group + '/' + inventory_hostname + '.pem') }}"

That template is how one cluster definition scales to three nodes, since the inventory hostname is substituted at run time.

The group variables that define the whole cluster

The per cluster group variables are where the role's model becomes concrete, and they are worth reading as a configuration schema. pve_group is the group name of the cluster, and the README explains that it is used to ensure all hosts within that group can reach each other and are clustered together, and that the PVE cluster name is set to this group name as well unless pve_cluster_clustername says otherwise, which defaults to proxmox. pve_watchdog set to ipmi enables IPMI watchdog support and configures the HA manager to use it, while None or undefined selects the default Proxmox software watchdog, and any other value is taken as a watchdog kernel module name. pve_cluster_enabled turns on the cluster management tasks. Then there are the content structures: pve_groups for RBAC groups, pve_users with name, email, firstname, lastname and groups, pve_acls mapping a path to roles and groups, and pve_storages with a name, a type, a content list, a path and a maxfiles value.

What the role does not do, and the warning at the top

The README leads with a warning that should shape any decision to adopt it: support for servers provisioned using the Proxmox ISO installer is limited, and you should use Debian as your base. That is a hard boundary, not a caveat, because the role installs Proxmox on Debian servers and expects to own that path. Two other limits follow from the design. The RBAC model is expressed as data in group variables, so a cluster whose permissions need to be more dynamic than a list of users, groups and path based ACLs will need work outside the role. And the cluster name defaults from the inventory group name, so a cluster whose Proxmox name must differ from its Ansible group name needs pve_cluster_clustername set explicitly, which is easy to forget. The alternative to weigh is the plain approach of installing Proxmox by hand or with the vendor's own image and managing the cluster with pvecm, which gives you no declarative source of truth but also no role to maintain.

Maintenance state and the shape of the repository

The repository is not archived, and the last push was on 2026-07-13. The recent release tags are v1.10.1 from 2026-03-02, v1.10.0 from 2025-11-12 and v1.9.4 from 2025-06-19, so the 1.10 line is where the work is, and the default branch is develop rather than a release branch. The tree is the standard Ansible role layout: defaults/, vars/, tasks/, handlers/, files/, templates/ under library/, module_utils/ for anything shared between roles, meta/, tests/ for the role's own test suite, plus a Vagrantfile for a local lab, and the linting configuration with .ansible-lint.yml, .yamllint.yml and an .ansible-lint-ignore file. The primary language is listed as Python, which is the usual convention for roles with custom module_utils. The project is MIT licensed, with a second LICENSE_IMPORTS file alongside the main LICENSE for the code it vendors. The version history in the tags is a slow, steady patch cadence rather than rapid development, and the README is a working document rather than a polished one, with several sentences cut off mid explanation, which is normal for this kind of project but worth knowing before you rely on the docs alone.

Editorial conclusion

Adopt lae.proxmox if you provision Proxmox VE hosts from Debian with Ansible and want the cluster, RBAC, storage and certificates described in a playbook rather than clicked through in the web interface. Do not adopt it if your nodes were built with the Proxmox ISO installer, because the README warns support for that path is limited and tells you to use Debian as your base. Before you run it, read the quickstart requirements closely, especially the need for an external control machine and a reboot in the middle of the install, and decide how you will handle the private keys, since the role reads them from files in the playbook and the README suggests Ansible Vault for that.

Frequently asked questions

Official sources

1. Issues
2. lae/ansible-role-proxmox on GitHub
3. License: MIT
4. README
5. Releases