Ansible collection: foundata.proxmox

Quelltext

Veröffentlichungen (Releases)

Dokumentation

Probleme (Issues)

Lizenzierung

Primäre Lizenz: GPL-3.0-or-later

Sonstiges

Spenden: Buy us a coffee
Projektbetreuer: foundata
Status: Beta

Die Ansible-Collection foundata.proxmox stellt Ressourcen zur Verwaltung und Nutzung verschiedener Proxmox-Produkte bereit. Dazu gehörten Proxmox Virtual Environment (PVE), Proxmox Backup Server (PBS), Proxmox Datacenter Manager (PDM) und Proxmox Mailgateway (PMG).

Die folgenden Abschnitte listen die README.md-Dateien der wichtigsten enthaltenen Inhalte (z. B. Rollen) auf. Für einen umfassenderen Überblick empfiehlt sich ein Blick in die Quellcode-Repositories.

Dieses Projekt nutzt eine andere Arbeitssprache als Deutsch. Der folgende Abschnitt wurde automatisch aus der README-Datei generiert und liegt daher nur in der Originalsprache vor.

Ansible role: `foundata.proxmox.pve`

The foundata.proxmox.pve Ansible role (part of the foundata.proxmox Ansible collection).

Features

Main features:

Network Configuration
- Interface alternative names: Assign predictable names to NICs via systemd link files (preserves kernel names, avoids udev conflicts)
- Flexible interface definitions: Separate host-specific and shared configurations for bonds, VLANs, bridges, and management interfaces
Firewall Management
- Manage datacenter-level options, policies, and rules (/etc/pve/firewall/cluster.fw), define reusable address references for cleaner rule management etc. pp.
- nftables support: modern firewall backend
Storage Management
- ZFS: pool creation (Automated pool provisioning with mirror, RAIDZ1/2/3 support and extensive disk validation); Create datasets with optional native encryption (AES-256-GCM), passphrase rotation support
- NFS mounts: Network storage integration with reachability checks
- Register storage backends for use in PVE web UI (dir, zfspool types)
Operating system configuration
- IOMMU/PCI passthrough: Automatic detection and GRUB configuration for Intel/AMD IOMMU

Example playbooks, using this role

Configure Proxmox Virtual Environment Servers (PVE)

---

- name: "Initialize the foundata.proxmox.pve role"
  hosts: pve_cluster
  gather_facts: false
  tasks:

    - name: "Trigger invocation of the foundata.proxmox.pve role"
      ansible.builtin.include_role:
        name: "foundata.proxmox.pve"
      vars:

        ## It makes moste sense to put these variables into host vars.
        ## This is just done here inline as an example.

        # Storage configuration
        pve_proxmox_storage:
          # Local SSD mirror (low-latency, high-IOPS, SAS)
          - name: "pool1"
            type: "zpool"
            attributes:
              mountpoint: "none"
              vdevs:
                - type: "mirror"
                  disks:
                    - "/dev/disk/by-id/scsi-123"
                    - "/dev/disk/by-id/scsi-234"
              pool_properties:
                ashift: "12"  # 4K sectors (default)

          - name: "pool1/pve-guest-crypt"
            type: "zfs_dataset"
            attributes:
              zfs_properties:
                mountpoint: "/mnt/pool1/pve-guest-crypt" # VMs use zvols, but containers require a mountpoint
                compression: "on"
                atime: "off"
                xattr: "sa"
                acltype: "off"
                encryption: "aes-256-gcm"
                keyformat: "passphrase"
                passphrase: "{{ vault_pwd_pve1_storage }}"
                passphrase_old: [] # List of old passphrases, only needed when changing passphrase
                keylocation: "prompt"

        # Storage Manager (pvesm) configuration
        pve_proxmox_sm:
          # Local SSD mirror (low-latency, high-IOPS, SAS)
          - name: "pve1-guest1"
            type: "zfspool"
            storage_properties:
              pool: "pool1/pve-guest-crypt"
              content:
                - "images" # Virtual machine disks
                - "rootdir" # Container data
              sparse: true # Enable thin provisioning (saves space for unused blocks)
              nodes:
                - "pve1"

        # Network configuration for this specific host
        pve_proxmox_net_ifaces_host_specific:
          sections:

            - title: "Proxmox VE (PVE) main connection (LACP, trunk)"
              interfaces:
                - name: "main1"
                  method: "manual"
                  auto: true
                  iface_properties:
                    mtu: 1500

                - name: "main2"
                  method: "manual"
                  auto: true
                  iface_properties:
                    mtu: 1500

                - name: "bond_main"
                  method: "manual"
                  auto: true
                  iface_properties:
                    bond-slaves: "main1 main2"
                    bond-mode: "802.3ad"
                    bond-miimon: 100
                    bond-lacp-rate: "fast"
                    bond-xmit-hash-policy: "layer2"
                    mtu: 1500


            - title: "Proxmox VE (PVE) management interfaces"
              interfaces:
                - name: "bond_main.0123"
                  method: "manual"
                  auto: true
                  iface_properties:
                    comment: "0123_virt"

                - name: "br0123"
                  method: "static"
                  auto: true
                  comment: |
                    If attaching VMs to this interface is needed some day, the br0020
                    definition has to be moved into /etc/network/interfaces to make it
                    available for the PVE GUI and should be named vmbr0020. Use
                    pve_proxmox_net_ifaces_workload_specific or
                    pve_proxmox_net_ifaces_workload_shared to do so.
                  iface_properties:
                    address: "10.201.20.110/24"
                    gateway: "10.201.20.1"
                    bridge-ports: "bond_main.0020"
                    bridge-stp: "off"
                    bridge-fd: 0
                    comment: "0020_virt (host bridge)"

        pve_proxmox_net_ifaces_workload_specific:
          sections:
            - title: "Corosync link"
              interfaces:
                - name: "sync1"
                  method: "static"
                  auto: true
                  iface_properties:
                    address: "192.168.20.110/24"
                    comment: "Corosync link1 (quad-port NIC, third port)"



        ## It makes moste sense to put these variables into group vars.
        ## This is just done here inline as an example.

        # Network configuration for all PVE hosts (shared data)
        pve_proxmox_net_ifaces_host_shared:
          sections:
            - title: "Proxmox VE (PVE) VLAN interfaces"
              interfaces:
                - name: "bond_main.0001"
                  method: "manual"
                  auto: true
                  iface_properties:
                    comment: "0001_net"

        pve_proxmox_net_ifaces_workload_shared:
          options_before: |
            source /etc/network/interfaces.d/*

          sections:
            - title: "Proxmox VE (PVE) workload bridge interfaces"
              interfaces:
                - name: "vmbr0001"
                  method: "manual"
                  auto: true
                  iface_properties:
                    bridge-ports: "bond_main.0001"
                    bridge-stp: off
                    bridge-fd: 0
                    comment: "0001_net"

Supported tags

It might be useful and faster to only call parts of the role by using tags:

pve_proxmox_os: Manage basic operating system configuration influencing Proxmox Virtual Environment (PVE) (like IOMMU support)
pve_proxmox_network: Manage network and network interface configuration.
pve_proxmox_firewall: Manage firewall configuration.
pve_proxmox_storage: Manage storage configuration.
pve_proxmox_datacenter: Manage the Proxmox Virtual Environment (PVE) datacenter configuration

There are also tags usually not meant to be called directly but listed for the sake of completeness** and edge cases:

pve_proxmox_always, always: Tasks needed by the role itself for internal role setup and the Ansible environment.

Role variables

The following variables can be configured for this role:

Variable	Type	Required	Default	Description (abstract)
`pve_proxmox_tmpbackupfiles`	`bool`	No	`true`	Switch to control whether temporary disaster-safeguard backups of important configuration files should be created before re-writing them via Ansible. When set to `true` (which is the default), the role will: 1. Create a temporary …
`pve_proxmox_iommu_manage`	`bool`	No	`true`	Switch to control if the role should manage input–output memory management unit (IOMMU) related operating system configuration. IOMMU support is needed for PCI and/or GPU passthrough. When set to `true` (which is the default), the role …
`pve_proxmox_net_altnames`	`list`	No	`[]`	List of network interface alternative name definitions for systemd link files (`/etc/systemd/network/10-*.link`). Instead of renaming kernel network devices, this approach assigns alternative names (altnames). This preserves the original …
`pve_proxmox_net_ifaces_host_shared`	`dict`	No	`{}`	Network interface definitions for `/etc/network/interfaces.d/10-host` shared across all hosts in the inventory group. These interfaces are NOT visible in the PVE web UI and are intended for backend networking configurations. Use this variable …
`pve_proxmox_net_ifaces_host_specific`	`dict`	No	`{}`	Network interface definitions for `/etc/network/interfaces.d/10-host` specific to individual hosts. These interfaces are NOT visible in the PVE web UI and are intended for backend networking configurations. Use this variable for host-specific …
`pve_proxmox_net_ifaces_workload_shared`	`dict`	No	`{}`	Network interface definitions for `/etc/network/interfaces` shared across all hosts in the inventory group. These interfaces ARE visible in the PVE web UI and available for assignment to virtual machines and containers. Use this variable for …
`pve_proxmox_net_ifaces_workload_specific`	`dict`	No	`{}`	Network interface definitions for `/etc/network/interfaces` specific to individual hosts. These interfaces ARE visible in the PVE web UI and available for assignment to virtual machines and containers. Use this variable for host-specific …
`pve_proxmox_fw_cluster_options`	`dict`	No	`{}`	Cluster-wide (datacenter) firewall options applied to all PVE hosts. This is a passthrough of original Proxmox VE firewall options. Keys and values are rendered directly into the `[OPTIONS]` section of …
`pve_proxmox_fw_cluster_aliases`	`list`	No	`[]`	Cluster-wide IP aliases for use in firewall rules. Aliases provide speakable, stable names for IP addresses and networks. Once defined, aliases can be referenced in rules, IP sets, and other aliases using the `dc/` syntax. Each alias …
`pve_proxmox_fw_cluster_ipsets`	`list`	No	`[]`	Cluster-wide IP sets for use in firewall rules. IP sets are reusable collections of IP addresses, networks, and aliases. They simplify rule management by allowing a single rule to match multiple addresses. Each IP set generates an …
`pve_proxmox_fw_cluster_securitygroups`	`list`	No	`[]`	Cluster-wide security groups (reusable rule collections). Security groups bundle multiple firewall rules under a single name, allowing them to be applied as a unit to hosts, VMs, or containers. This promotes rule reuse and simplifies …
`pve_proxmox_fw_cluster_rules`	`list`	No	`[]`	Cluster-wide firewall rules applied to all PVE hosts. Rules define traffic filtering policies. Each rule generates a line in the `[RULES]` section of `/etc/pve/firewall/cluster.fw`. Rules can reference aliases (`dc/`), IP sets (`+dc/`), …
`pve_proxmox_fw_node_options`	`dict`	No	`{}`	Node-specific firewall options for this PVE host. This is a passthrough of original Proxmox VE firewall options. Keys and values are rendered directly into the `[OPTIONS]` section of `/etc/pve/nodes//host.fw`. These options only affect …
`pve_proxmox_fw_node_rules`	`list`	No	`[]`	Node-specific firewall rules for this PVE host. Rules defined here only apply to this specific node, not the entire cluster. Each rule generates a line in the `[RULES]` section of `/etc/pve/nodes//host.fw`. The data structure is …
`pve_proxmox_datacentercfg`	`dict`	No	`{}`	Proxmox VE datacenter-wide configuration settings. This variable defines cluster-wide defaults rendered to `/etc/pve/datacenter.cfg`. Since this file resides on pmxcfs (the FUSE-backed cluster filesystem synchronized via Corosync), settings …
`pve_proxmox_storage`	`list`	No	`[]`	List of storage definitions for the PVE host. This variable manages operating system-level storage configuration including ZFS pools, ZFS datasets, and NFS mounts. Each entry defines a storage resource with its type-specific …
`pve_proxmox_storage_force_cleanup`	`bool`	No	`false`	Allow automatic cleanup of existing data on disks for ZFS pool creation. DESTRUCTIVE OPERATION WARNING: When set to `true`, the role will automatically wipe filesystem signatures and ZFS labels from disks that have existing data but whose …
`pve_proxmox_sm`	`list`	No	`[]`	Proxmox VE Storage Manager (pvesm) configuration. This variable defines storage resources visible in the PVE web UI and available for VM/container disk allocation, backups, ISO storage, and container templates. These entries configure …