Proxmox VE API Credentials

Store a Proxmox VE API URL and token in Ankra - with VM, datastore, and SDN privileges - to provision and manage self-managed Proxmox clusters.

Proxmox VE API credentials store the HTTPS Proxmox API URL and an API token, used to provision and manage self-managed Proxmox VE clusters. The credential is validated when you save it - Ankra calls the Proxmox API (GET /version) and then bootstraps any missing storage and networking (see below). For environments behind an SSH jumphost, the direct probe is skipped and the connection is tested during cluster provisioning instead.

Proxmox VE credentials are managed from the portal or API - there is no ankra credentials proxmox CLI command.

What Ankra Accesses

Ankra drives the Proxmox VE API with your token:

Resource	Operations	Why it’s used
Nodes and cluster	read	Discover nodes, pick VM IDs, and inspect capacity for placement
QEMU VMs	clone, configure, resize, start/stop/reboot, delete	The cluster’s nodes and bastion, cloned from the cloud-init template
QEMU guest agent	exec, read network interfaces	Discover VM addresses and (with Tailscale) run the tailnet join
Storage	read, configure, upload	Find image-capable storage, download cloud images, and build the VM template
SDN (zones, vnets, subnets)	create, read, update, delete	The ankra private network with NAT and DHCP for cluster VMs
Node network interfaces	read, configure	Detect or create the vmbr0 management bridge during bootstrap

The token needs these privileges on the target nodes, storage, and bridges: VM.*, Datastore.Allocate, Datastore.AllocateSpace, Sys.Audit, Sys.Modify, and SDN.Use. Sys.Modify and Datastore.Allocate are only exercised by the one-time bootstrap - after it completes you can remove those two grants if they are not otherwise needed, keeping the runtime VM, Datastore.AllocateSpace, audit, and SDN.Use grants required for provisioning and catalog visibility. Enabling Tailscale additionally requires VM.GuestAgent.Unrestricted (see below).

Creating a Proxmox VE API Credential

1. Create an API token in Proxmox

   1. In the Proxmox VE web UI, go to Datacenter → Permissions → API Tokens
   2. Create a token for a user whose role carries the privileges listed above, and copy the token ID (user@realm!name) and secret
2. Add to Ankra (UI)

   Go to Credentials → Add → Proxmox VE, then provide:

   • Name: a unique identifier - lowercase letters and numbers only, cannot start with a hyphen (e.g. proxmox-lab)
   • API URL: the HTTPS address of your Proxmox API (e.g. https://proxmox.example.com:8006)
   • Token ID and Token Secret: from the previous step
   • Skip TLS certificate verification (tls_insecure in the API): enable only for self-signed certificates on trusted networks

   For environments that are not directly reachable, expand SSH jumphost & Tailscale and set the jumphost host and private key (port defaults to 22, username to root). Optionally attach Tailscale/Headscale to have provisioned VMs join your tailnet (see below).

   Click Test connection, then save.

Saving the credential inspects every online Proxmox node and bootstraps whatever is missing:

• Storage — when no active storage supports VM images, Ankra enables images and rootdir on the local directory storage, or creates local at /var/lib/vz. The import content type is enabled for cloud-image downloads.
• Management bridge — when no Linux bridge exists, Ankra converts the single active Ethernet or bond management interface to vmbr0. Static and manual-method interfaces are supported (including dedicated servers where the provider assigns the IP outside Proxmox’s network config); DHCP-managed interfaces cannot be converted through the Proxmox API and are refused with instructions.
• Private network — Ankra creates the ankra SDN simple zone, vnet, and subnet 10.20.0.0/16 with SNAT and dnsmasq-served DHCP, giving cluster VMs an isolated NAT’d network. Each node needs the dnsmasq package (apt install dnsmasq && systemctl disable --now dnsmasq).
• Cloud-init template — nodes without any VM template get the ankra-ubuntu-24-04 template, built automatically from the Ubuntu 24.04 cloud image.

The network conversion preserves the host address, gateway, uplink, and MTU. It is refused before any live change if the interface is ambiguous, has custom options, or another network change is pending. Do not edit Proxmox networking concurrently while saving the credential.

The token ID and secret can be rotated later from the credential’s page. The API URL is fixed - to point at a different Proxmox installation, create a new credential.

Tailscale and Headscale (optional)

Attach Tailscale/Headscale settings to a Proxmox VE credential and every VM Ankra provisions with it installs Tailscale and joins your tailnet on first boot — each VM getting its own tailnet address, reachable across Proxmox hosts and from your own networks over an encrypted mesh.

Provide both fields, or leave both empty:

• Tailscale login server (login_server in the API) — the Headscale control-server URL (for example https://net.ankra.dev). Tailscale’s own coordination server also works.
• Tailscale auth key (auth_key) — a reusable pre-auth key from your control server.

You can add, change, or remove Tailscale on an existing credential from the credential’s page — no need to delete and recreate it. The stored auth key is never shown back.

Each guest joins with its own tailnet address; it does not import your other subnet routes (accept_routes defaults to false — importing the route for the guest’s own SDN subnet would send its reply traffic into the tailnet and can cut it off from the bastion mid-provisioning). Host-spread clusters use the tailnet address for cross-node traffic: the Proxmox SDN private network is node-local, so a control plane placed on a different host than the bastion is only reachable through the tailnet. Kubeadm advertise/join, haproxy upstreams, etcd peering, and cert SANs all follow the recorded tailnet address once a guest has joined.

The tailnet join runs through the Proxmox QEMU guest agent, which requires the credential’s Proxmox token to hold VM.GuestAgent.Unrestricted — a separate, higher privilege than the read-only VM.GuestAgent.Audit that address discovery already needs. A token with only VM.GuestAgent.Audit provisions fine until Tailscale is configured, then every VM’s tailnet join fails with an API 403 on /agent/exec. Add VM.GuestAgent.Unrestricted to the token’s role before enabling Tailscale on the credential.

For Proxmox clusters you also need an SSH key credential, created from the portal or generated via another provider’s CLI.

Troubleshooting Proxmox VE Credentials

The table below covers the Test connection result in the Ankra UI:

Test connection result	Cause	Solution
Proxmox VE rejected the API token.	The token ID or secret is wrong, or the token’s user lacks access	Re-check the token ID format (user@realm!name) and secret; verify the token’s role has the privileges listed above
Could not reach the Proxmox VE API.	Wrong API URL, the API is not reachable from Ankra, or a TLS failure on a self-signed certificate	Check the URL (HTTPS, usually port 8006); for private environments configure the SSH jumphost; for self-signed certificates enable Skip TLS certificate verification
Proxmox VE returned HTTP <code>.	Unexpected Proxmox-side response	Retry; check the Proxmox node’s task log if it persists
Proxmox credential with jumphost accepted; connection test runs during cluster provisioning.	Not an error - jumphost credentials skip the direct probe	Nothing to do; the tunnel is exercised when a cluster is provisioned

Saving can additionally fail with “Could not configure Proxmox VE storage and networking” - the bootstrap could not complete. Common causes: the token is missing Sys.Modify or Datastore.Allocate, the management interface is DHCP-managed (convert it to a static or manual configuration first), or dnsmasq is not installed on a node. “Proxmox VE infrastructure setup is already running for this organisation or target” means another save is mid-bootstrap against the same installation - wait for it to finish and retry.