Prerequisites

This page covers everything you need before connecting your Proxmox nodes to flex.plane — whether you are using the managed SaaS offering or self-hosting the management plane.

Proxmox node requirements

You need at least one Proxmox VE node (version 8.0 or later). This is where your virtual machines will actually run. Each Proxmox node will have the flex.plane agent installed on it.

Requirements per node:

• Proxmox VE 8.0 or later
• Root SSH access (for agent installation)
• Outbound internet access for downloading VM images from public sources (e.g., cloud-images.ubuntu.com). For air-gapped environments, you can host images on an internal HTTP server.

For multi-zone deployments, you can have separate Proxmox clusters in different locations. Each cluster becomes a "zone" in flex.plane.

Network connectivity

The following network paths must be open:

• Proxmox nodes to the mesh control server: The agent uses WireGuard (UDP, typically port 41641) to join the mesh network. Outbound UDP must be allowed from your Proxmox nodes.
• Proxmox nodes to the internet: Required for downloading VM images from public repositories. Not required if you host images internally.

Management cluster requirements (self-hosted only)

Self-hosting flex.plane requires a Kubernetes cluster to run the management plane components (orchestrator, portal, identity).

Kubernetes cluster

You need a cluster with:

• Kubernetes 1.27 or later
• At least 2 GiB of available memory for flex.plane pods
• A storage class for persistent volumes (used by Zitadel's PostgreSQL and the orchestrator's mesh state)
• An ingress controller (e.g., ingress-nginx, Traefik) for exposing the portal and API

This can be a lightweight cluster. A single-node k3s setup works fine for smaller deployments. The management cluster does not run your VM workloads; it only hosts the platform control plane.

Network connectivity

• Management cluster to Proxmox nodes: The mesh overlay handles this via WireGuard (UDP, typically port 41641). The orchestrator and agents communicate exclusively over this encrypted mesh.
• Users to management cluster: HTTPS (443) for the portal, API, and identity provider.

Required tools

Make sure the following tools are installed on your workstation:

Verify your setup:

kubectl version --client
helm version

You should also have a working kubectl context pointing to your management Kubernetes cluster:

kubectl get nodes

Identity provider

flex.plane uses Zitadel for OIDC authentication. You have two options:

Option A: Deploy Zitadel with flex.plane (recommended)

The identity Helm chart bundles Zitadel and PostgreSQL. This is the simplest path and is covered in the Identity Chart guide. No pre-configuration needed, just proceed to the next step.

Option B: Use an existing Zitadel instance

If you already run Zitadel, you can point flex.plane at your existing instance. You will need to:

1. Create a new organization for your flex.plane tenant
2. Create a project within that organization
3. Create an OIDC application (type: web, auth method: PKCE) for the portal
4. Create a machine user with a JWT private key for the orchestrator's Zitadel management API access
5. Set up the role system (see Roles and Permissions)

You will need the following values from your Zitadel instance:

• OIDC issuer URL
• OIDC client ID
• Organization ID
• Project ID
• JWT private key file (for the machine user)

Next steps