proxmox adapter

Features

The proxmox module is an Inmanta adapter for Proxmox VE (PVE). It manages a PVE instance declaratively over the PVE REST API (/api2/json), authenticating with an API token. The handler drives full create/read/update/delete lifecycles against PVE, resolves asynchronous PVE tasks (UPID polling) and reconciles power state.

The module covers the main PVE management surfaces:

• Compute — QEMU/KVM virtual machines and LXC containers (UEFI/OVMF boot, cloud-init, PCI passthrough, and a running power-state lifecycle).

• Storage — storage backend definitions, resource pools, HTTP-sourced image/ISO/template downloads (fetched by the node itself), and agent-built config-drive ISOs.

• Networking — Linux bridges, bonds, node DNS, and a NetworkApply action that commits staged /etc/network/interfaces.new changes.

• Access control — users, API tokens and per-path ACL grants.

Api configuration

Every resource references a proxmox::Credentials object that describes how to reach and authenticate against the PVE instance. Authentication uses a PVE API token (no username/password); the handler sends it as an Authorization: PVEAPIToken=<api_token_id>=<api_token_secret> header.

Attribute	Description
url	Base URL of the PVE instance, e.g. https://pve-host:8006
api_token_id	API token id in the form USER@REALM!TOKENID, e.g. root@pam!inmanta
api_token_secret	API token secret (UUID)
verify	Whether to verify the TLS certificate (default false)
agent_autostart	Auto-configure a local std::AgentConfig (default true)
agent_name	Agent name; defaults to url when unset

:bulb: Credentials are provided as model attributes; the module does not read any environment variables or config files at runtime.

Usage example

The example below connects to a PVE instance, creates a VLAN-aware Linux bridge, commits the staged network changes and provisions a QEMU VM attached to the bridges.

import std
import proxmox
import proxmox::resources

# Connection / auth via PVE API token
pve = proxmox::Credentials(
    url="https://pve.example.com:8006",
    api_token_id="root@pam!inmanta",
    api_token_secret="00000000-0000-0000-0000-000000000000",
    verify=false,
)

# A VLAN-aware data bridge, then commit the staged network changes
data = proxmox::resources::LinuxBridge(
    credentials=pve,
    node="pve",
    iface="vmbr1",
    bridge_ports="eno2",
    bridge_vlan_aware=true,
    autostart=true,
    purged=false,
)

apply_network = proxmox::resources::NetworkApply(
    credentials=pve,
    node="pve",
    purged=false,
)
apply_network.requires += data

# A QEMU VM attached to the bridge, started after create
vm = proxmox::resources::QemuVM(
    credentials=pve,
    node="pve",
    vmid=100,
    name="app-vm-1",
    memory=2048,
    cores=2,
    sockets=1,
    cpu="host",
    ostype="l26",
    scsihw="virtio-scsi-pci",
    scsi0="local:32",
    net0="virtio,bridge=vmbr0",
    net1="virtio,bridge=vmbr1,tag=100",
    boot="order=scsi0;net0",
    running=true,
    purged=false,
)
vm.requires += apply_network

Main entities

Base entities (model/_init.cf):

• proxmox::Credentials — connection + API-token auth to a PVE instance; referenced by every resource.

• proxmox::Resource — abstract base for all resources (purgeable, managed, credentials relation).

• proxmox::NodeScopedResource — base for resources bound to a specific PVE node.

Resource entities (model/resources/_init.cf):

• Storage — a PVE storage backend definition (dir, nfs, lvm, zfspool, rbd, …).

• Pool — a PVE resource pool.

• QemuVM — a QEMU/KVM virtual machine (disks, NICs, UEFI/OVMF, cloud-init, PCI passthrough, running power state).

• LxcContainer — an LXC container (template, rootfs, hostname, networking).

• User — a PVE user account in a realm; does not manage passwords.

• APIToken — an API token for a user; the secret is emitted once as a fact on create.

• ACL — a single (path, user_or_group, role) ACL grant.

• LinuxBridge — a Linux bridge network interface on a node.

• BondInterface — a bonded network interface on a node.

• NodeDns — DNS resolver config (/etc/resolv.conf) of a node.

• NetworkApply — action resource that commits staged pending network changes on a node.

• DownloadedImage — an image/ISO/LXC template fetched by the node from an HTTP(S) URL into a storage.

• ConfigDriveISO — a config-drive/cloud-init ISO built by the agent and uploaded to a node storage.

• Module proxmox
• Changelog