{"id":13495517,"url":"https://github.com/lae/ansible-role-proxmox","last_synced_at":"2026-03-02T21:12:57.117Z","repository":{"id":11025737,"uuid":"68048671","full_name":"lae/ansible-role-proxmox","owner":"lae","description":"IaC for Proxmox VE clusters.","archived":false,"fork":false,"pushed_at":"2024-09-13T20:21:53.000Z","size":532,"stargazers_count":488,"open_issues_count":22,"forks_count":141,"subscribers_count":23,"default_branch":"develop","last_synced_at":"2024-09-15T07:04:07.419Z","etag":null,"topics":["ansible","hacktoberfest","proxmox","proxmox-cluster","virtualization"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lae.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"ko_fi":"sleepingkyoto","custom":["https://monappy.jp/u/lae"]}},"created_at":"2016-09-12T21:15:44.000Z","updated_at":"2024-09-13T20:57:31.000Z","dependencies_parsed_at":"2024-04-12T21:28:25.474Z","dependency_job_id":"3764b0f7-621d-4e3e-b249-ed7bc2def128","html_url":"https://github.com/lae/ansible-role-proxmox","commit_stats":null,"previous_names":[],"tags_count":30,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lae%2Fansible-role-proxmox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lae%2Fansible-role-proxmox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lae%2Fansible-role-proxmox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lae%2Fansible-role-proxmox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lae","download_url":"https://codeload.github.com/lae/ansible-role-proxmox/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":222395880,"owners_count":16977642,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ansible","hacktoberfest","proxmox","proxmox-cluster","virtualization"],"created_at":"2024-07-31T19:01:35.497Z","updated_at":"2026-03-02T21:12:57.104Z","avatar_url":"https://github.com/lae.png","language":"Python","funding_links":["https://ko-fi.com/sleepingkyoto","https://monappy.jp/u/lae"],"categories":["Python","virtualization","ansible"],"sub_categories":[],"readme":"[![Galaxy Role](https://img.shields.io/badge/ansible--galaxy-proxmox-blue.svg)](https://galaxy.ansible.com/lae/proxmox/)\n\nlae.proxmox\n===========\n\nInstalls and configures Proxmox Virtual Environment 6.x/7.x/8.x/9.x on Debian servers.\n\nThis role allows you to deploy and manage single-node PVE installations and PVE\nclusters (3+ nodes) on Debian Buster (10), Bullseye (11), Bookworm (12) and Trixie (13). You are able to\nconfigure the following with the assistance of this role:\n\n  - PVE RBAC definitions (roles, groups, users, and access control lists)\n  - PVE Storage definitions\n  - [`datacenter.cfg`][datacenter-cfg]\n  - HTTPS certificates for the Proxmox Web GUI (BYO)\n  - PVE repository selection (e.g. `pve-no-subscription` or `pve-enterprise`)\n  - Watchdog modules (IPMI and NMI) with applicable pve-ha-manager config\n  - ZFS module setup and ZED notification email\n\nWith clustering enabled, this role does (or allows you to do) the following:\n\n  - Ensure all hosts can connect to one another as root over SSH\n  - Initialize a new PVE cluster (or possibly adopt an existing one)\n  - Create or add new nodes to a PVE cluster\n  - Setup Ceph on a PVE cluster\n  - Create and manage high availability groups\n\nWARNING: Support for servers provisioned using the Proxmox ISO installer is limited. Use Debian as your base.\n\n## Quickstart\n\nThe primary goal for this role is to configure and manage a\n[Proxmox VE cluster][pve-cluster] (see example playbook), however this role can\nbe used to quickly install single node Proxmox servers.\n\nI'm assuming you already have [Ansible installed][install-ansible]. You will\nneed to use an external machine to the one you're installing Proxmox on\n(primarily because of the reboot in the middle of the installation, though I\nmay handle this somewhat differently for this use case later).\n\nCopy the following playbook to a file like `install_proxmox.yml`:\n\n    - hosts: all\n      become: True\n      roles:\n        - role: geerlingguy.ntp\n          vars:\n            ntp_manage_config: true\n            ntp_servers:\n              - clock.sjc.he.net,\n              - clock.fmt.he.net,\n              - clock.nyc.he.net\n        - role: lae.proxmox\n          vars:\n            pve_group: all\n            pve_reboot_on_kernel_update: true\n\nInstall this role and a role for configuring NTP:\n\n    ansible-galaxy install lae.proxmox geerlingguy.ntp\n\nNow you can perform the installation:\n\n    ansible-playbook install_proxmox.yml -i $SSH_HOST_FQDN, -u $SSH_USER\n\nIf your `SSH_USER` has a sudo password, pass the `-K` flag to the above command.\nIf you also authenticate to the host via password instead of pubkey auth, pass\nthe `-k` flag (make sure you have `sshpass` installed as well). You can set\nthose variables prior to running the command or just replace them. Do note the\ncomma is important, as a list is expected (otherwise it'll attempt to look up a\nfile containing a list of hosts).\n\nOnce complete, you should be able to access your Proxmox VE instance at\n`https://$SSH_HOST_FQDN:8006`.\n\n## Deploying a fully-featured PVE 9.x cluster\n\nCreate a new playbook directory. We call ours `lab-cluster`. Our playbook will\neventually look like this, but yours does not have to follow all of the steps:\n\n```\nlab-cluster/\n├── files\n│   └── pve01\n│       ├── lab-node01.local.key\n│       ├── lab-node01.local.pem\n│       ├── lab-node02.local.key\n│       ├── lab-node02.local.pem\n│       ├── lab-node03.local.key\n│       └── lab-node03.local.pem\n├── group_vars\n│   ├── all\n│   └── pve01\n├── inventory\n├── roles\n│   └── requirements.yml\n├── site.yml\n└── templates\n    └── interfaces-pve01.j2\n\n6 directories, 12 files\n```\n\nFirst thing you may note is that we have a bunch of `.key` and `.pem` files.\nThese are private keys and SSL certificates that this role will use to configure\nthe web interface for Proxmox across all the nodes. These aren't necessary,\nhowever, if you want to keep using the signed certificates by the CA that\nProxmox sets up internally. You may typically use Ansible Vault to encrypt the\nprivate keys, e.g.:\n\n    ansible-vault encrypt files/pve01/*.key\n\nThis would then require you to pass the Vault password when running the playbook.\n\nLet's first specify our cluster hosts. Our `inventory` file may look like this:\n\n```\n[pve01]\nlab-node01.local\nlab-node02.local\nlab-node03.local\n```\n\nYou could have multiple clusters, so it's a good idea to have one group for each\ncluster. Now, let's specify our role requirements in `roles/requirements.yml`:\n\n```\n---\n- src: geerlingguy.ntp\n- src: lae.proxmox\n```\n\nWe need an NTP role to configure NTP, so we're using Jeff Geerling's role to do\nso. You wouldn't need it if you already have NTP configured or have a different\nmethod for configuring NTP.\n\nNow, let's specify some group variables. First off, let's create `group_vars/all`\nfor setting NTP-related variables:\n\n```\n---\nntp_manage_config: true\nntp_servers:\n  - lab-ntp01.local iburst\n  - lab-ntp02.local iburst\n```\n\nOf course, replace those NTP servers with ones you prefer.\n\nNow for the flesh of your playbook, `pve01`'s group variables. Create a file\n`group_vars/pve01`, add the following, and modify accordingly for your environment.\n\n```\n---\npve_group: pve01\npve_watchdog: ipmi\npve_ssl_private_key: \"{{ lookup('file', pve_group + '/' + inventory_hostname + '.key') }}\"\npve_ssl_certificate: \"{{ lookup('file', pve_group + '/' + inventory_hostname + '.pem') }}\"\npve_cluster_enabled: yes\npve_groups:\n  - name: ops\n    comment: Operations Team\npve_users:\n  - name: admin1@pam\n    email: admin1@lab.local\n    firstname: Admin\n    lastname: User 1\n    groups: [ \"ops\" ]\n  - name: admin2@pam\n    email: admin2@lab.local\n    firstname: Admin\n    lastname: User 2\n    groups: [ \"ops\" ]\npve_acls:\n  - path: /\n    roles: [ \"Administrator\" ]\n    groups: [ \"ops\" ]\npve_storages:\n  - name: localdir\n    type: dir\n    content: [ \"images\", \"iso\", \"backup\" ]\n    path: /plop\n    maxfiles: 4\npve_ssh_port: 22\n\ninterfaces_template: \"interfaces-{{ pve_group }}.j2\"\n```\n\n`pve_group` is set to the group name of our cluster, `pve01` - it will be used\nfor the purposes of ensuring all hosts within that group can connect to each\nother and are clustered together. Note that the PVE cluster name will be set to\nthis group name as well, unless otherwise specified by `pve_cluster_clustername`.\nLeaving this undefined will default to `proxmox`.\n\n`pve_watchdog` here enables IPMI watchdog support and configures PVE's HA\nmanager to use it. Use `None` or leave this undefined to use the default\nproxmox software watchdog. If set to anything else, the value is expected to be\na watchdog kernel module.\n\n`pve_ssl_private_key` and `pve_ssl_certificate` point to the SSL certificates for\npvecluster. Here, a file lookup is used to read the contents of a file in the\nplaybook, e.g. `files/pve01/lab-node01.key`. You could possibly just use host\nvariables instead of files, if you prefer.\n\n`pve_cluster_enabled` enables the role to perform all cluster management tasks.\nThis includes creating a cluster if it doesn't exist, or adding nodes to the\nexisting cluster. There are checks to make sure you're not mixing nodes that\nare already in existing clusters with different names.\n\n`pve_groups`, `pve_users`, and `pve_acls` authorizes some local UNIX users (they\nmust already exist) to access PVE and gives them the Administrator role as part\nof the `ops` group. Read the **User and ACL Management** section for more info.\n\n`pve_storages` allows to create different types of storage and configure them.\nThe backend needs to be supported by [Proxmox][pvesm]. Read the **Storage\nManagement** section for more info.\n\n`pve_metric_servers` allows you to configure a metric server for the PVE cluster.\nThis is useful if you want to use InfluxDB, Graphite or other (with telegraf).\n\n`pve_ssh_port` allows you to change the SSH port. If your SSH is listening on\na port other than the default 22, please set this variable. If a new node is\njoining the cluster, the PVE cluster needs to communicate once via SSH.\n\n`pve_manage_ssh` (default true) allows you to disable any changes this module\nwould make to your SSH server config. This is useful if you use another role\nto manage your SSH server. Note that setting this to false is not officially\nsupported, you're on your own to replicate the changes normally made in\n`ssh_cluster_config.yml` and `pve_add_node.yml`.\n\n`interfaces_template` is set to the path of a template we'll use for configuring\nthe network on these Debian machines. This is only necessary if you want to\nmanage networking from Ansible rather than manually or via each host in PVE.\nYou should probably be familiar with Ansible prior to doing this, as your method\nmay involve setting host variables for the IP addresses for each host, etc.\n\nLet's get that interface template out of the way. Feel free to skip this file\n(and leave it undefined in `group_vars/pve01`) otherwise. Here's one that I use:\n\n```\n# {{ ansible_managed }}\nauto lo\niface lo inet loopback\n\nallow-hotplug enp2s0f0\niface enp2s0f0 inet manual\n\nauto vmbr0\niface vmbr0 inet static\n    address {{ lookup('dig', ansible_fqdn) }}\n    gateway 10.4.0.1\n    netmask 255.255.255.0\n    bridge_ports enp2s0f0\n    bridge_stp off\n    bridge_fd 0\n\nallow-hotplug enp2s0f1\nauto enp2s0f1\niface enp2s0f1 inet static\n    address {{ lookup('dig', ansible_hostname + \"-clusternet.local\") }}\n    netmask 255.255.255.0\n```\n\nYou might not be familiar with the `dig` lookup, but basically here we're doing\nan A record lookup for each machine (e.g. lab-node01.local) for the first\ninterface (and configuring it as a bridge we'll use for VM interfaces), and then\nanother slightly modified lookup for the \"clustering\" network we might use for\nCeph (\"lab-node01-clusternet.local\"). Of course, yours may look completely\ndifferent, especially if you're using bonding, three different networks for\nmanagement/corosync, storage and VM traffic, etc.\n\nFinally, let's write our playbook. `site.yml` will look something like this:\n\n```\n---\n- hosts: all\n  become: True\n  roles:\n    - geerlingguy.ntp\n\n# Leave this out if you're not modifying networking through Ansible\n- hosts: pve01\n  become: True\n  serial: 1\n  tasks:\n    - name: Install bridge-utils\n      apt:\n        name: bridge-utils\n\n    - name: Configure /etc/network/interfaces\n      template:\n        src: \"{{ interfaces_template }}\"\n        dest: /etc/network/interfaces\n      register: _configure_interfaces\n\n    - block:\n      - name: Reboot for networking changes\n        shell: \"sleep 5 \u0026\u0026 shutdown -r now 'Networking changes found, rebooting'\"\n        async: 1\n        poll: 0\n\n      - name: Wait for server to come back online\n        wait_for_connection:\n          delay: 15\n      when: _configure_interfaces is changed\n\n- hosts: pve01\n  become: True\n  roles:\n    - lae.proxmox\n```\n\nBasically, we run the NTP role across all hosts (you might want to add some\nnon-Proxmox machines), configure networking on `pve01` with our separate cluster\nnetwork and bridge layout, reboot to make those changes take effect, and then\nrun this Proxmox role against the hosts to setup a cluster.\n\nAt this point, our playbook is ready and we can run the playbook.\n\nEnsure that roles and dependencies are installed:\n\n    ansible-galaxy install -r roles/requirements.yml --force\n    pip install jmespath dnspython\n\n`jmespath` is required for some of the tasks involving clustering. `dnspython`\nis only required if you're using a `dig` lookup, which you probably won't be if\nyou skipped configuring networking. We pass `--force` to `ansible-galaxy` here\nso that roles are updated to their latest versions if already installed.\n\nNow run the playbook:\n\n    ansible-playbook -i inventory site.yml -e '{\"pve_reboot_on_kernel_update\": true}'\n\nThe `-e '{\"pve_reboot_on_kernel_update\": true}'` should mainly be run the first\ntime you do the Proxmox cluster setup, as it'll reboot the server to boot into\na PVE kernel. Subsequent runs should leave this out, as you want to sequentially\nreboot servers after the cluster is running.\n\nTo specify a particular user, use `-u root` (replacing `root`), and if you need\nto provide passwords, use `-k` for SSH password and/or `-K` for sudo password.\nFor example:\n\n    ansible-playbook -i inventory site.yml -K -u admin1\n\nThis will ask for a sudo password, then login to the `admin1` user (using public\nkey auth - add `-k` for pw) and run the playbook.\n\nThat's it! You should now have a fully deployed Proxmox cluster. You may want\nto create Ceph storage on it afterwards (see Ceph for more info) and other\ntasks possibly, but the hard part is mostly complete.\n\n\n## Example Playbook\n\nThis will configure hosts in the group `pve01` as one cluster, as well as\nreboot the machines should the kernel have been updated. (Only recommended to\nset this flag during installation - reboots during operation should occur\nserially during a maintenance period.) It will also enable the IPMI watchdog.\n\n    - hosts: pve01\n      become: True\n      roles:\n        - role: geerlingguy.ntp\n            ntp_manage_config: true\n            ntp_servers:\n              - clock.sjc.he.net,\n              - clock.fmt.he.net,\n              - clock.nyc.he.net\n        - role: lae.proxmox\n            pve_group: pve01\n            pve_cluster_enabled: yes\n            pve_reboot_on_kernel_update: true\n            pve_watchdog: ipmi\n\n## Role Variables\n\n*About default values: Some of the default values are selected at run time and so can differ from the example listed here.*\n\n```\n[variable]: [default] #[description/purpose]\npve_group: proxmox # host group that contains the Proxmox hosts to be clustered together\n# Proxmox repository configuration\npve_repository:\n  uris: http://download.proxmox.com/debian/pve\n  suites: \"{{ ansible_distribution_release }}\"\n  components: pve-no-subscription # change to enterprise if needed (although TODO further configuration may be needed)\n# pve_repository_line: \"\" # apt-repository configuration, backward compatibility, prefer to use pve_repository instead\npve_remove_subscription_warning: true # patches the subscription warning messages in proxmox if you are using the community edition\npve_extra_packages: [] # Any extra packages you may want to install, e.g. ngrep\npve_run_system_upgrades: false # Let role perform system upgrades\npve_run_proxmox_upgrades: true # Let role perform Proxmox VE upgrades\npve_check_for_kernel_update: true # Runs a script on the host to check kernel versions\npve_reboot_on_kernel_update: false # If set to true, will automatically reboot the machine on kernel updates\npve_reboot_on_kernel_update_delay: 60 # Number of seconds to wait before and after a reboot process to proceed with next task in cluster mode\npve_remove_old_kernels: true # Currently removes kernel from main Debian repository\n# pve_default_kernel_version: # version to pin proxmox-default-kernel to (see https://pve.proxmox.com/wiki/Roadmap#Kernel_6.8)\npve_pcie_passthrough_enabled: false # Set this to true to enable PCIe passthrough.\npve_iommu_passthrough_mode: false # Set this to true to allow VMs to bypass the DMA translation. This might increase performance for IOMMU passthrough.\npve_iommu_unsafe_interrupts: false # Set this to true if your system doesn't support interrupt remapping.\npve_mediated_devices_enabled: false # Set this to true if your device supports gtv-g and you wish to enable split functionality.\npve_pcie_ovmf_enabled: false # Set this to true to enable GPU OVMF PCI passthrough.\npve_pci_device_ids: [] # List of pci device ID's (see https://pve.proxmox.com/wiki/Pci_passthrough#GPU_Passthrough).\npve_vfio_blacklist_drivers: [] # List of device drivers to blacklist from the Proxmox host (see https://pve.proxmox.com/wiki/PCI(e)_Passthrough).\npve_pcie_ignore_msrs: false # Set this to true if passing through to Windows machine to prevent VM crashing.\npve_pcie_report_msrs: true # Set this to false to prevent dmesg system from logging msrs crash reports.\npve_watchdog: none # Set this to \"ipmi\" if you want to configure a hardware watchdog. Proxmox uses a software watchdog (nmi_watchdog) by default.\npve_watchdog_ipmi_action: power_cycle # Can be one of \"reset\", \"power_cycle\", and \"power_off\".\npve_watchdog_ipmi_timeout: 10 # Number of seconds the watchdog should wait\npve_zfs_enabled: no # Specifies whether or not to install and configure ZFS packages\n# pve_zfs_options: \"\" # modprobe parameters to pass to zfs module on boot/modprobe\n# pve_zfs_zed_email: \"\" # Should be set to an email to receive ZFS notifications\npve_zfs_create_volumes: [] # List of ZFS Volumes to create (to use as PVE Storages). See section on Storage Management.\npve_ceph_enabled: false # Specifies wheter or not to install and configure Ceph packages. See below for an example configuration.\n# Proxmox Ceph Repository\npve_ceph_repository:\n  uris: http://download.proxmox.com/debian/ceph-{{ pve_ceph_default_version }}\n  suites: \"{{ ansible_distribution_release }}\"\n  components: \"{{ pve_ceph_debian_component }}\"\n#pve_ceph_repository_line: \"\" # apt-repository configuration, backward compatibility, prefer to use pve_ceph_repository instead\npve_ceph_network: \"{{ (ansible_default_ipv4.network +'/'+ ansible_default_ipv4.netmask) | ansible.utils.ipaddr('net') }}\" # Ceph public network\n# pve_ceph_cluster_network: \"\" # Optional, if the ceph cluster network is different from the public network (see https://pve.proxmox.com/pve-docs/chapter-pveceph.html#pve_ceph_install_wizard)\npve_ceph_nodes: \"{{ pve_group }}\" # Host group containing all Ceph nodes\npve_ceph_mon_group: \"{{ pve_group }}\" # Host group containing all Ceph monitor hosts\npve_ceph_mgr_group: \"{{ pve_ceph_mon_group }}\" # Host group containing all Ceph manager hosts\npve_ceph_mds_group: \"{{ pve_group }}\" # Host group containing all Ceph metadata server hosts\npve_ceph_osds: [] # List of OSD disks\npve_ceph_pools: [] # List of pools to create\npve_ceph_fs: [] # List of CephFS filesystems to create\npve_ceph_crush_rules: [] # List of CRUSH rules to create\n# pve_ssl_private_key: \"\" # Should be set to the contents of the private key to use for HTTPS\n# pve_ssl_certificate: \"\" # Should be set to the contents of the certificate to use for HTTPS\npve_roles: [] # Added more roles with specific privileges. See section on User Management.\npve_groups: [] # List of group definitions to manage in PVE. See section on User Management.\npve_users: [] # List of user definitions to manage in PVE. See section on User Management.\npve_storages: [] # List of storages to manage in PVE. See section on Storage Management.\npve_metric_servers: [] # List of metric servers to configure in PVE.\npve_datacenter_cfg: {} # Dictionary to configure the PVE datacenter.cfg config file.\npve_domains_cfg: [] # List of realms to use as authentication sources in the PVE domains.cfg config file.\npve_no_log: true # Set this to false if you need to debug the content via run logs for certain configuration tasks, such as for storage or SSL.\n```\n\nTo enable clustering with this role, configure the following variables appropriately:\n\n```\npve_cluster_enabled: no # Set this to yes to configure hosts to be clustered together\npve_cluster_clustername: \"{{ pve_group }}\" # Should be set to the name of the PVE cluster\npve_manage_hosts_enabled : yes # Set this to no to NOT configure hosts file (case of using vpn and hosts file is already configured)\n```\n\nThe following variables are used to provide networking information to corosync.\nThese are known as ring0_addr/ring1_addr or link0_addr/link1_addr, depending on\nPVE version. They should be IPv4 or IPv6 addresses. You can also configure the\n[priority of these interfaces][pvecm-network-priority] to hint to corosync\nwhich interface should handle cluster traffic (lower numbers indicate higher\npriority). For more information, refer to the [Cluster Manager][pvecm-network]\nchapter in the PVE Documentation.\n\n```\n# pve_cluster_addr0: \"{{ defaults to the default interface ipv4 or ipv6 if detected }}\"\n# pve_cluster_addr1: \"another interface's IP address or hostname\"\n# pve_cluster_addr0_priority: 255\n# pve_cluster_addr1_priority: 0\n```\n\nYou can set options in the datacenter.cfg configuration file:\n\n```\npve_datacenter_cfg:\n  keyboard: en-us\n```\n\nYou can also configure [HA manager groups][ha-group] (deprecated since Proxmox VE 9.0):\n```\npve_cluster_ha_groups: [] # List of HA groups to create in PVE.\n```\n\nThis example creates a group \"lab_node01\" for resources assigned to the\nlab-node01 host:\n```\npve_cluster_ha_groups:\n  - name: lab_node01\n    comment: \"My HA group\"\n    nodes: \"lab-node01\"\n    nofailback: 0\n    restricted: 0\n```\n\nAll configuration options supported in the datacenter.cfg file are documented\nin the [Proxmox manual datacenter.cfg section][datacenter-cfg].\n\nIn order for live reloading of network interfaces to work via the PVE web UI,\nyou need to install the `ifupdown2` package. Note that this will remove\n`ifupdown`. You can specify this using the `pve_extra_packages` role variable.\n\nYou can set realms / domains as authentication sources in the `domains.cfg` configuration file.\nIf this file is not present, only the `Linux PAM` and `Proxmox VE authentication server` realms\nare available. Supported types are `pam`, `pve`, `ad` and `ldap`.\nIt’s possible to automatically sync users and groups for LDAP-based realms (LDAP \u0026 Microsoft Active Directory) with `sync: true`.\nOne realm should have the `default: 1` property to mark it as the default:\n\n```\npve_domains_cfg:\n  - name: pam\n    type: pam\n    attributes:\n      comment: Linux PAM standard authentication\n  - name: pve\n    type: pve\n    attributes:\n      comment: Proxmox VE authentication server\n  - name: ad\n    type: ad\n    attributes:\n      comment: Active Directory authentication\n      domain: yourdomain.com\n      server1: dc01.yourdomain.com\n      default: 1\n      secure: 1\n      server2: dc02.yourdomain.com\n  - name: ldap\n    type: ldap\n    sync: true\n    attributes:\n      comment: LDAP authentication\n      base_dn: CN=Users,dc=yourdomain,dc=com\n      bind_dn: \"uid=svc-reader,CN=Users,dc=yourdomain,dc=com\"\n      bind_password: \"{{ secret_ldap_svc_reader_password }}\"\n      server1: ldap1.yourdomain.com\n      user_attr: uid\n      secure: 1\n      server2: ldap2.yourdomain.com\n```\n\n## Dependencies\n\nThis role does not install NTP, so you should configure NTP yourself, e.g. with\nthe `geerlingguy.ntp` role as shown in the example playbook.\n\nWhen clustering is enabled, this role makes use of the `json_query` filter,\nwhich requires that the `jmespath` library be installed on your control host.\nYou can either `pip install jmespath` or install it via your distribution's\npackage manager, e.g. `apt-get install python-jmespath`.\n\n## User and ACL Management\n\nYou can use this role to manage users and groups within Proxmox VE (both in\nsingle server deployments and cluster deployments). Here are some examples.\n\n```\npve_groups:\n  - name: Admins\n    comment: Administrators of this PVE cluster\n  - name: api_users\n  - name: test_users\npve_users:\n  - name: root@pam\n    email: postmaster@pve.example\n  - name: lae@pam\n    email: lae@pve.example\n    firstname: Musee\n    lastname: Ullah\n    groups: [ \"Admins\" ]\n  - name: pveapi@pve\n    password: \"Proxmox789\"\n    groups:\n      - api_users\n  - name: testapi@pve\n    password: \"Test456\"\n    enable: no\n    groups:\n      - api_users\n      - test_users\n  - name: tempuser@pam\n    expire: 1514793600\n    groups: [ \"test_users\" ]\n    comment: \"Temporary user set to expire on 2018年  1月  1日 月曜日 00:00:00 PST\"\n    email: tempuser@pve.example\n    firstname: Test\n    lastname: User\n```\n\nRefer to `library/proxmox_user.py` [link][user-module] and\n`library/proxmox_group.py` [link][group-module] for module documentation.\n\nFor managing roles and ACLs, a similar module is employed, but the main\ndifference is that most of the parameters only accept lists (subject to\nchange):\n\n```\npve_roles:\n  - name: Monitoring\n    privileges:\n      - \"Sys.Modify\"\n      - \"Sys.Audit\"\n      - \"Datastore.Audit\"\n      - \"VM.Monitor\"\n      - \"VM.Audit\"\npve_acls:\n  - path: /\n    roles: [ \"Administrator\" ]\n    groups: [ \"Admins\" ]\n  - path: /pools/testpool\n    roles: [ \"PVEAdmin\" ]\n    users:\n      - pveapi@pve\n    groups:\n      - test_users\n```\n\nRefer to `library/proxmox_role.py` [link][user-module] and\n`library/proxmox_acl.py` [link][acl-module] for module documentation.\n\n## Storage Management\n\nYou can use this role to manage storage within Proxmox VE (both in single\nserver deployments and cluster deployments). For now, the only supported types\nare `dir`, `rbd`, `nfs`, `cephfs`, `lvm`,`lvmthin`, `zfspool`, `btrfs`, `cifs`\nand `pbs`. Here are some examples.\n\n```\npve_storages:\n  - name: dir1\n    type: dir\n    content: [ \"images\", \"iso\", \"backup\" ]\n    path: /ploup\n    disable: no\n    maxfiles: 4\n  - name: ceph1\n    type: rbd\n    content: [ \"images\", \"rootdir\" ]\n    nodes: [ \"lab-node01.local\", \"lab-node02.local\" ]\n    username: admin\n    pool: rbd\n    krbd: yes\n    monhost:\n      - 10.0.0.1\n      - 10.0.0.2\n      - 10.0.0.3\n  - name: nfs1\n    type: nfs\n    content: [ \"images\", \"iso\" ]\n    server: 192.168.122.2\n    export: /data\n  - name: lvm1\n    type: lvm\n    content: [ \"images\", \"rootdir\" ]\n    vgname: vg1\n  - name: lvmthin1\n    type: lvmthin\n    content: [ \"images\", \"rootdir\" ]\n    vgname: vg2\n    thinpool: data\n  - name: cephfs1\n    type: cephfs\n    content: [ \"snippets\", \"vztmpl\", \"iso\" ]\n    nodes: [ \"lab-node01.local\", \"lab-node02.local\" ]\n    monhost:\n      - 10.0.0.1\n      - 10.0.0.2\n      - 10.0.0.3\n  - name: pbs1\n    type: pbs\n    content: [ \"backup\" ]\n    server: 192.168.122.2\n    username: user@pbs\n    password: PBSPassword1\n    datastore: main\n    namespace: Top/something # Optional\n  - name: zfs1\n    type: zfspool\n    content: [ \"images\", \"rootdir\" ]\n    pool: rpool/data\n    sparse: true\n  - name: btrfs1\n    type: btrfs\n    content: [ \"images\", \"rootdir\" ]\n    nodes: [ \"lab-node01.local\", \"lab-node02.local\" ]\n    path: /mnt/proxmox_storage\n    is_mountpoint: true\n  - name: cifs1\n    server: cifs-host.domain.tld\n    type: cifs\n    content: [ \"snippets\", \"vztmpl\", \"iso\" ]\n    share: sharename\n    subdir: /subdir\n    username: user\n    password: supersecurepass\n    domain: addomain.tld\n  - name: empty-dir\n    type: dir\n    path: /mnt/empty-dir\n    content: [ \"images\", \"rootdir\" ]\n    create_subdirs: false\n```\n\nRefer to https://pve.proxmox.com/pve-docs/api-viewer/index.html for more information.\n\nCurrently the `zfspool` type can be used only for `images` and `rootdir` contents.\nIf you want to store the other content types on a ZFS volume, you need to specify\nthem with type `dir`, path `/\u003cPOOL\u003e/\u003cVOLUME\u003e` and add an entry in\n`pve_zfs_create_volumes`. This example adds a `iso` storage on a ZFS pool:\n\n```\npve_zfs_create_volumes:\n  - rpool/iso\npve_storages:\n  - name: iso\n    type: dir\n    path: /rpool/iso\n    content: [ \"iso\" ]\n```\n\nRefer to `library/proxmox_storage.py` [link][storage-module] for module\ndocumentation.\n\n## Ceph configuration\n\n*This section could use a little more love. If you are actively using this role\nto manage your PVE Ceph cluster, please feel free to flesh this section more\nthoroughly and open a pull request! See issue #68.*\n\n**PVE Ceph management with this role is experimental.** While users have\nsuccessfully used this role to deploy PVE Ceph, it is not fully tested in CI\n(due to a lack of usable block devices to use as OSDs in Travis CI). Please\ndeploy a test environment with your configuration first prior to prod, and\nreport any issues if you run into any.\n\nThis role can configure the Ceph storage system on your Proxmox hosts. The\nfollowing definitions show some of the configurations that are possible.\n\n```\npve_ceph_enabled: true\npve_ceph_network: '172.10.0.0/24'\npve_ceph_cluster_network: '172.10.1.0/24'\npve_ceph_nodes: \"ceph_nodes\"\npve_ceph_osds:\n  # OSD with everything on the same device\n  - device: /dev/sdc\n  # OSD with block.db/WAL on another device\n  - device: /dev/sdd\n    block.db: /dev/sdb1\n  # encrypted OSD with everything on the same device\n  - device: /dev/sdc\n    encrypted: true\n  # encrypted OSD with block.db/WAL on another device\n  - device: /dev/sdd\n    block.db: /dev/sdb1\n    encrypted: true\n  # NVME OSD\n  - device: /dev/nvme0n1\n    crush.device.class: NVMe\n# Crush rules for different storage classes\n# By default 'type' is set to host, you can find valid types at\n# (https://docs.ceph.com/en/latest/rados/operations/crush-map/)\n# listed under 'TYPES AND BUCKETS'\npve_ceph_crush_rules:\n  - name: replicated_rule\n    type: osd # This is an example of how you can override a pre-existing rule\n  - name: ssd\n    class: ssd\n    type: osd\n    min-size: 2\n    max-size: 8\n  - name: hdd\n    class: hdd\n    type: host\n# 2 Ceph pools for VM disks which will also be defined as Proxmox storages\n# Using different CRUSH rules\npve_ceph_pools:\n  - name: ssd\n    pgs: 128\n    rule: ssd\n    application: rbd\n    storage: true\n# This Ceph pool uses custom size/replication values\n  - name: hdd\n    pgs: 32\n    rule: hdd\n    application: rbd\n    storage: true\n    size: 2\n    min-size: 1\n# This Ceph pool uses custom autoscale mode : \"off\" | \"on\" | \"warn\"\u003e (default = \"warn\")\n  - name: vm-storage\n    pgs: 128\n    rule: replicated_rule\n    application: rbd\n    autoscale_mode: \"on\"\n    storage: true\n# This Ceph pool uses erasure-coding (EC) instead of replicated (default)\n  - name: hydra-rbd1\n    # For erasure code: size, min_size, and rule will be used for the\n    # replicated *metadata* pool, but *not* for the erasure coded data pool.\n    # See https://pve.proxmox.com/wiki/Deploy_Hyper-Converged_Ceph_Cluster\n    size: 3\n    min_size: 2\n    autoscale_mode: \"warn\"\n    storage: true\n    application: rbd\n    pgs: 1024\n    # Using \"erasure\" will use pveceph to create a new error coding (EC) pool\n    # plus the needed replicated pool to store the RBD omap and other metadata.\n    # In the end, there will be a \u003cpool name\u003e-data and \u003cpool name\u003e-metadata pool. \n    protection_strategy: \"erasure-coding\" # \"replicated\" (default) or \"erasure-coding\"\n    k: 3 # Erasure code data blocks, only valid and required for EC pool\n    m: 2 # Erasure code parity blocks, only valid and required for EC pool\npve_ceph_fs:\n# A CephFS filesystem not defined as a Proxmox storage\n  - name: backup\n    pgs: 64\n    rule: hdd\n    storage: false\n    mountpoint: /srv/proxmox/backup\n```\n\n`pve_ceph_network` by default uses the `ansible.utils.ipaddr` filter, which\nrequires the `netaddr` library to be installed and usable by your Ansible\ncontroller.\n\n`pve_ceph_nodes` by default uses `pve_group`, this parameter allows to specify\non which nodes install Ceph (e.g. if you don't want to install Ceph on all your\nnodes).\n\n`pve_ceph_osds` by default creates unencrypted ceph volumes. To use encrypted\nvolumes the parameter `encrypted` has to be set per drive to `true`.\n\n## PCIe Passthrough\n\nThis role can be configured to allow PCI device passthrough from the Proxmox host to VMs. This feature is not enabled by default since not all motherboards and CPUs support this feature. To enable passthrough, the devices CPU must support hardware virtualization (VT-d for Intel based systems and AMD-V for AMD based systems). Refer to the manuals of all components to determine whether this feature is supported or not. Naming conventions of will vary, but is usually referred to as IOMMU, VT-d, or AMD-V.\n\nBy enabling this feature, dedicated devices (such as a GPU or USB devices) can be passed through to the VMs. Along with dedicated devices, various integrated devices such as Intel or AMD's integrated GPU's are also able to be passed through to VMs.\n\nSome devices are able to take advantage of Mediated usage. Mediated devices are able to be passed through to multiple VMs to share resources, while still remaining usable by the host system. Splitting of devices is not always supported and should be validated before being enabled to prevent errors. Refer to the manual of the device you want to pass through to determine whether the device is capable of mediated usage (Currently this role only supports GVT-g; SR-IOV is not currently supported and must be enable manually after role completion).\n\nThe following is an example configuration which enables PCIe passthrough:\n\n```yaml\npve_pcie_passthrough_enabled: true\npve_iommu_passthrough_mode: true\npve_iommu_unsafe_interrupts: false\npve_mediated_devices_enabled: false\npve_pcie_ovmf_enabled: false\npve_pci_device_ids:\n  - id: \"10de:1381\"\n  - id: \"10de:0fbc\"\npve_vfio_blacklist_drivers:\n  - name: \"radeon\"\n  - name: \"nouveau\"\n  - name: \"nvidia\"\npve_pcie_ignore_msrs: false\npve_pcie_report_msrs: true\n```\n\n`pve_pcie_passthrough_enabled` is required to use any PCIe passthrough functionality. Without this enabled, all other PCIe related fields will be unused.\n\n`pve_iommu_passthrough_mode` enabling IOMMU passthrough mode might increase device performance. By enabling this feature, it allows VMs to bypass the default DMA translation which would normally be performed by the hyper-visor. Instead, VMs pass DMA requests directly to the hardware IOMMU.\n\n`pve_iommu_unsafe_interrupts` is required to be enabled to allow PCI passthrough if your system doesn't support interrupt remapping. You can find check whether the device supports interrupt remapping by using `dmesg | grep 'remapping'`. If you see one of the following lines:\n\n- \"AMD-Vi: Interrupt remapping enabled\"\n- \"DMAR-IR: Enabled IRQ remapping in x2apic mode\" ('x2apic' can be different on old CPUs, but should still work)\n\nThen system interrupt remapping is supported and you do not need to enable unsafe interrupts. Be aware that by enabling this value your system can become unstable.\n\n`pve_mediated_devices_enabled` enables GVT-g support for integrated devices such as Intel iGPU's. Not all devices support GVT-g so it is recommended to check with your specific device beforehand to ensure it is allowed.\n\n`pve_pcie_ovmf_enabled` enables GPU OVMF PCI passthrough. When using OVMF you should select 'OVMF' as the BIOS option for the VM instead of 'SeaBIOS' within Proxmox. This setting will try to opt-out devices from VGA arbitration if possible.\n\n`pve_pci_device_ids` is a list of device and vendor ids that is wished to be passed through to VMs from the host. See the section 'GPU Passthrough' on the [Proxmox WIKI](https://pve.proxmox.com/wiki/Pci_passthrough) to find your specific device and vendor id's. When setting this value, it is required to specify an 'id' for each new element in the array.\n\n`pve_vfio_blacklist_drivers` is a list of drivers to be excluded/blacklisted from the host. This is required when passing through a PCI device to prevent the host from using the device before it can be assigned to a VM. When setting this value, it is required to specify a 'name' for each new element in the array.\n\n`pve_pcie_ignore_msrs` prevents some Windows applications like GeForce Experience, Passmark Performance Test and SiSoftware Sandra from crashing the VM. This value is only required when passing PCI devices to Windows based systems.\n\n`pve_pcie_report_msrs` can be used to enable or disable logging messages of msrs warnings. If you see a lot of warning messages in your 'dmesg' system log, this value can be used to silence msrs warnings.\n\n## Metrics Server Configuration\n\nYou can configure metric servers in Proxmox VE using the `pve_metric_servers` role variable. Below is an example configuration for different types of metric servers:\n\n```yaml\npve_metric_servers:\n  - id: influxdb1\n    port: 8086\n    server: influxdb.example.com\n    type: influxdb\n    protocol: http\n    organization: myorg\n    bucket: mybucket\n    token: mytoken\n    timeout: 30\n    max_body_size: 25000000\n    verify_certificate: true\n  - id: graphite1\n    port: 2003\n    server: graphite.example.com\n    type: graphite\n    protocol: tcp\n    path: mygraphitepath\n    mtu: 1500\n```\n\n### Configuration Variables\n\n- `id`: (required) Unique identifier for the metric server.\n- `port`: (optional) Port of the metric server. Default is `8089`.\n- `server`: (required) DNS name or IP address of the metric server.\n- `type`: (optional) Type of metric server. Possible values: `influxdb`, `graphite`. Default is `influxdb`.\n- `protocol`: (optional) Protocol used to send metrics. Possible values: `udp`, `tcp`, `http`, `https`. Default is `udp`.\n- `disable`: (optional) Disable the metric server. Default is `false`.\n- `organization`: (optional) Organization name. Available only for influxdb with the http v2 API.\n- `bucket`: (optional) Bucket name for influxdb. Useful only with the http v2 API or compatible.\n- `token`: (optional) InfluxDB access token. Required only when using the http v2 API.\n- `path`: (optional) Graphite root path. Available only for graphite.\n- `api_path_prefix`: (optional) API path prefix inserted between `\u003chost\u003e:\u003cport\u003e/` and `/api2/`. Useful if the InfluxDB service is running behind a reverse proxy. Available only for influxdb with the http v2 API.\n- `timeout`: (optional) Timeout in seconds. Available only for influxdb with the http v2 API or Graphite TCP socket.\n- `max_body_size`: (optional) Maximum body size in bytes. Available only for influxdb with the http v2 API. Default is `25000000`.\n- `mtu`: (optional) MTU for UDP metric transmission.\n- `verify_certificate`: (optional) Verify SSL certificate. Available only for influxdb with https.\n\n## Non-default scenarios and other use cases\n\n### Preventing upgrade to Linux kernel 6.8\n\nProxmox 8.2 introduces Linux 6.8, which may cause issues in some deployments.\nTo work around this, you can pin the kernel version used to 6.5 by adding the following role variable:\n\n```yaml\npve_default_kernel_version: 1.0.1\n```\n\nThis creates a pin on the `proxmox-default-kernel` package, which is [the method suggested by PVE](https://pve.proxmox.com/wiki/Roadmap#Kernel_6.8).\nIt can be later removed by unsetting this role variable.\n\n## Troubleshooting\n\n### The APT installation of proxmox-ve no longer responds, Ansible aborts, the SSH session stops.\n\nAdd this section to your ``ansible.cfg``.\n\n```yaml\n[ssh_connection]\nssh_args = -o ServerAliveInterval=20\n```\n[Reference Issue](https://github.com/lae/ansible-role-proxmox/issues/279)\n\n### Proxmox doesn't boot/does not update GRUB config correctly.\n\nThere is no known issue for this, however the following error message is silently ignored because of a false positive on certain systems using ZFS:\n\n```\n$ sudo update-grub\n\u003c...\u003e\n/usr/sbin/grub-probe: error: unknown filesystem.\n\u003c...\u003e\n```\n\nWhile this error is outside the scope of this role to fix, please open an issue with details if this ignore masks a true positive for your system.\n\n## Developer Notes\n\nWhen developing new features or fixing something in this role, you can test out\nyour changes by using Vagrant (only libvirt is supported currently). The\nplaybook can be found in `tests/vagrant` (so be sure to modify group variables\nas needed). Be sure to test any changes on all supported versions of Debian (update the\nVagrantfile locally to use `debian/bookworm64`, `debian/bullseye64`, or `debian/buster64`) before submitting a PR.\n\nYou can also specify an apt caching proxy (e.g. `apt-cacher-ng`, and it must\nrun on port 3142) with the `APT_CACHE_HOST` environment variable to speed up\npackage downloads if you have one running locally in your environment. The\nvagrant playbook will detect whether or not the caching proxy is available and\nonly use it if it is accessible from your network, so you could just\npermanently set this variable in your development environment if you prefer.\n\nFor example, you could run the following to show verbose/easier to read output,\nuse a caching proxy, and keep the VMs running if you run into an error (so that\nyou can troubleshoot it and/or run `vagrant provision` after fixing):\n\n    APT_CACHE_HOST=10.71.71.10 ANSIBLE_STDOUT_CALLBACK=debug vagrant up --no-destroy-on-error\n\n## Contributors\n\nMusee Ullah ([@lae](https://github.com/lae), \u003clae@lae.is\u003e) - Main developer  \nFabien Brachere ([@Fbrachere](https://github.com/Fbrachere)) - Storage config support  \nGaudenz Steinlin ([@gaundez](https://github.com/gaudenz)) - Ceph support, etc  \nRichard Scott ([@zenntrix](https://github.com/zenntrix)) - Ceph support, PVE 7.x support, etc  \nThoralf Rickert-Wendt ([@trickert76](https://github.com/trickert76)) - PVE 6.x support, etc  \nEngin Dumlu ([@roadrunner](https://github.com/roadrunner))  \nJonas Meurer ([@mejo-](https://github.com/mejo-))  \nOndrej Flidr ([@SniperCZE](https://github.com/SniperCZE))  \nniko2 ([@niko2](https://github.com/niko2))  \nChristian Aublet ([@caublet](https://github.com/caublet))  \nGille Pietri ([@gilou](https://github.com/gilou))  \nMichael Holasek ([@mholasek](https://github.com/mholasek))  \nAlexander Petermann ([@lexxxel](https://github.com/lexxxel)) - PVE 8.x support, etc  \nBruno Travouillon ([@btravouillon](https://github.com/btravouillon)) - UX improvements   \nTobias Negd ([@wu3rstle](https://github.com/wu3rstle)) - Ceph support  \nPendaGTP ([@PendaGTP](https://github.com/PendaGTP)) - Ceph support  \nJohn Marion ([@jmariondev](https://github.com/jmariondev))  \nfoerkede ([@foerkede](https://github.com/foerkede)) - ZFS storage support  \nGuiffo Joel ([@futuriste](https://github.com/futuriste)) - Pool configuration support  \nAdam Delo ([@ol3d](https://github.com/ol3d)) - PCIe Passthrough Support\nAntoine Thys ([@thystips](https://github.com/thystips)) - Metric Servers Support\n\n[Full list of contributors](https://github.com/lae/ansible-role-proxmox/graphs/contributors)\n\n[pve-cluster]: https://pve.proxmox.com/wiki/Cluster_Manager\n[install-ansible]: http://docs.ansible.com/ansible/intro_installation.html\n[pvecm-network]: https://pve.proxmox.com/pve-docs/chapter-pvecm.html#_separate_cluster_network\n[pvecm-network-priority]: https://pve.proxmox.com/pve-docs/chapter-pvecm.html#_Corosync_Redundancy\n[pvesm]: https://pve.proxmox.com/pve-docs/chapter-pvesm.html\n[user-module]: https://github.com/lae/ansible-role-proxmox/blob/master/library/proxmox_user.py\n[group-module]: https://github.com/lae/ansible-role-proxmox/blob/master/library/proxmox_group.py\n[acl-module]: https://github.com/lae/ansible-role-proxmox/blob/master/library/proxmox_group.py\n[storage-module]: https://github.com/lae/ansible-role-proxmox/blob/master/library/proxmox_storage.py\n[datacenter-cfg]: https://pve.proxmox.com/wiki/Manual:_datacenter.cfg\n[ceph_volume]: https://github.com/ceph/ceph-ansible/blob/master/library/ceph_volume.py\n[ha-group]: https://pve.proxmox.com/wiki/High_Availability#ha_manager_groups\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flae%2Fansible-role-proxmox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flae%2Fansible-role-proxmox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flae%2Fansible-role-proxmox/lists"}