Skip to content

CertiStack: Infrastructure as Code (IaC) Prerequisites & Requirements

This document defines the exact technical requirements, Proxmox VE / PBS prerequisites, RBAC permission matrix, and input variables required to configure a Proxmox cluster for CertiStack via Terraform / OpenTofu.

1. Controller and PVE node prerequisites

Terraform provisions PVE RBAC and an optional reference VM. It does not install CertiStack on PVE and no longer writes a .env file or plan containing credentials. Put the sensitive Terraform outputs directly into the controller secret manager, then configure the controller SSH identity and approved host key separately.

Component Minimum Version Notes
Operating System Proxmox VE 9.x on amd64 The PVE/PBS pair the release evidence covers. Proxmox VE 8.x is not supported until its own release evidence exists. Use the vendor-supported host OS/kernel.
Proxmox SDN libpve-network-perl >= 0.8.0 Required for ephemeral isolated L2/L3 sandboxes
PBS Client PBS 4.x client Required for read-only backup mapping; PBS 3.x, and any unvalidated future major, is not implied.
QEMU Utilities qemu-utils >= 8.0 Provides qemu-img for ephemeral .qcow2 delta overlays
PVE VM scheduling PVE cpuunits Relative CPU weighting is applied in the ephemeral VM configuration; CertiStack does not relocate QEMU processes between host cgroups.
Scratch Storage Local NVMe, SSD, or tmpfs Needs ~20–50 GB volatile space for ephemeral write deltas. Put overlay_storage on a disk the cluster file system (/var/lib/pve-cluster) does not use: a sandbox's first writes can saturate a single root HDD and delay corosync. doctor and every run warn when they share a disk.

Node package verification

Run on each selected PVE node to ensure its existing platform packages can support a temporary worker. This is not a CertiStack application install: 

apt update && apt install -y libpve-network-perl qemu-utils dnsmasq
systemctl reload pvedaemon pveproxy

2. Proxmox VE RBAC Permission Matrix

The controller requires an API token to orchestrate ephemeral VMs and SDN zones. Create a dedicated role and service user with least-privilege permissions. The bootstrap worker SSH identity is a separate, explicitly root-equivalent lab mechanism; Enterprise should replace it with the signed connector described in the deployment model.

Custom Role: CertiStackRole

Privilege Scope Privileges Purpose
VM Lifecycle VM.Allocate, VM.Audit, VM.PowerMgmt, VM.Console Create ephemeral VM, query QMP, boot, stop, destroy
VM Configuration VM.Config.Disk, VM.Config.CPU, VM.Config.Memory, VM.Config.Network, VM.Config.Options, VM.Config.HWType, VM.Config.CDROM Attach the overlay disks and firmware state, set cores and memory (every create sets both), bind the ephemeral SDN VNet, set QGA, machine type and SMBIOS identity, and attach the source's CD-ROM drives empty
SDN Management SDN.Allocate, SDN.Audit, SDN.Use Provision and destroy ephemeral Simple/VXLAN zones & VNets
Storage Datastore.AllocateSpace, Datastore.Audit Allocate ephemeral scratch files if using PVE storage
System Telemetry Sys.Audit Read node RAM, CPU, and task UPID completion status

Without VM.Config.CDROM, the node worker attaches the CD-ROM drives with root's local qm when it runs on the node; otherwise the sandbox VM is created without them and the run says so.

run, doctor and plan read the token's effective privileges on every path a run of the plan touches, before anything is created:

  • /vms/<vmid> for each VM;
  • /sdn and /sdn/zones for an ephemeral sandbox, or the zone itself for a pre-provisioned one;
  • the sandbox VNet;
  • /storage/<overlay storage>;
  • /nodes/<node>. They list every missing privilege at once. A run refuses to start without one it needs, and warns about VM.Config.CDROM, VM.Console and Sys.Audit, which it works around. A pre-provisioned sandbox needs no SDN.Allocate. It needs SDN.Audit on /sdn/zones/<zone>: the run reads the zone and VNet from PVE's zone and VNet lists, which show only what the token may audit, to check that the sandbox is isolated.

User & Token Identity

  • User: certistack-svc@pve
  • Token ID: certistack-svc@pve!automation
  • ACL Path: / (Propagate = true)

3. Proxmox Backup Server (PBS) Prerequisites

CertiStack streams deduplicated disk chunks directly from PBS into hypervisor loopback devices without restoring full images.

Parameter Description Example
PBS_REPOSITORY [user@realm!token@]host[:port]:datastore certistack-ro@[email protected]:8007:backup-anchor
PBS_PASSWORD Token secret or user password f9a8...secret...
PBS_FINGERPRINT SHA-256 TLS cert fingerprint of PBS server 3d:82:54:ab:c1:...
PBS_DATASTORE Target datastore containing VM backup snapshots backup-anchor
PBS_PERMISSIONS PBS ACL: Datastore.Audit, Datastore.Read Read-only access to snapshots; no write permission needed

4. Test Target VM (The Guinea Pig)

For deterministic initial validation, Terraform should provision (or identify) at least one reference golden VM:

  1. Guest OS: Debian 12 cloud-init or Ubuntu 22.04/24.04 cloud-init.
  2. Hardware: 1–2 vCPUs, 1–2 GB RAM, 10–20 GB disk.
  3. Guest Utilities:
  4. qemu-guest-agent installed and enabled (systemctl enable --now qemu-guest-agent).
  5. A basic network service listening (e.g. openssh-server on port 22, nginx on port 80/443).
  6. Backup Job: At least one full backup snapshot taken to the target PBS datastore.

5. Terraform state and controller handoff

Use an encrypted remote state backend with tightly scoped access: Terraform necessarily records the generated PVE token secret in state. Never commit terraform.tfvars, copy state into the controller image, or use generated files as a secret store.

After apply, read the sensitive token output through your protected CI or secret-management workflow and write it, the PBS read credential, SSH identity, approved known_hosts, and optional PVE CA to the controller only. The controller_connection output contains non-secret connection fields.

6. Information Contract for Terraform Inputs

Here is the exact schema of inputs needed to run the Terraform automation:

pve_api_endpoint       = "https://pve-node-01.example.com:8006"   # IP/FQDN of your primary Proxmox VE node
pve_node_name          = "pve-node-01"                # Target PVE node name
pbs_server_ip          = "192.0.2.50"                 # IP of Proxmox Backup Server
pbs_server_port        = 8007                         # PBS API port
pbs_datastore_name     = "backup-anchor"              # Datastore name on PBS/TrueNAS
pbs_cert_fingerprint   = "3d:82:..."                  # SHA-256 fingerprint from PBS dashboard
scratch_storage_pool   = "local"                      # Fast local PVE storage pool for COW overlays
reference_vmid         = 9000                         # VMID for the reference test VM