> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ankra.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/guides/proxmox-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.

<Note>
  Proxmox VE credentials are managed from the **portal or API** - there is no `ankra credentials proxmox` CLI command.
</Note>

## 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](#tailscale-and-headscale-optional)).

## Creating a Proxmox VE API Credential

<Steps>
  <Step title="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**
  </Step>

  <Step title="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.
  </Step>
</Steps>

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.

<Note>
  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.
</Note>

## 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.

<Note>
  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.
</Note>

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.

<Note>
  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.
</Note>

For Proxmox clusters you also need an [SSH key credential](/platform/credentials/ssh-key), 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.