Glossary

This glossary defines the terms, concepts, and technologies referenced throughout the flex.plane documentation.

Platform terms

Orchestrator

The central API service of flex.plane. It exposes the GraphQL API, aggregates state from Proxmox, Kubernetes, and the mesh network, and coordinates all platform operations. The orchestrator is stateless by design. It has no database and derives all state from neighboring systems at request time.

Agent

A daemon that runs on each Proxmox node. The agent serves three roles: it acts as an authenticating reverse proxy for the local Proxmox API, manages OS image staging and edge gateway operations, and enrolls the node into the mesh network. Agents communicate with the orchestrator over gRPC through the Tailscale mesh.

Portal

The web-based management dashboard built with Nuxt 3. It provides a graphical interface for all operations available through the GraphQL API: VM management, networking, Kubernetes clusters, VDC administration, and platform configuration.

Zone

An availability zone, a grouping of one or more Proxmox hosts that share a failure domain. Typically, a zone corresponds to a Proxmox cluster or a rack within a data center. Zones are discovered automatically through the Tailscale mesh network.

Host

A physical or virtual server running Proxmox VE with the flex.plane agent installed. Hosts belong to a zone and run virtual machines. Each host exposes CPU, memory, and storage metrics through the API.

VDC (Virtual Datacenter)

A logical isolation boundary within a tenant. VDCs provide separate networking, resource quotas, user access controls, and firewall policies. Each VDC can contain its own VMs, networks, Kubernetes clusters, and load balancers. VDC scoping is transparent to the GraphQL schema, controlled via the FlexPlane-VDC-ID HTTP header.

Tenant

The top-level organizational unit. A tenant represents a single flex.plane deployment and contains all VDCs, users, and resources. Tenants are identified by a name and domain.

Resource terms

VM (Virtual Machine)

A virtual machine running on a Proxmox hypervisor. VMs are created from OS images, sized with compute profiles, and connected to virtual networks. Each VM has a unique ID, a set of network interfaces (up to 4), attached disks, and lifecycle operations (start, stop, reboot, delete).

Network

A virtual network (VNet) that provides Layer 2 connectivity between VMs. Networks are defined with an IP range (CIDR notation) and a gateway address. VMs connect to networks through network interfaces, receiving IP addresses either automatically or as static assignments.

Compute Profile

A reusable template that defines CPU and memory allocation for VMs. For example, a "Medium" profile might specify 4 vCPUs and 8192 MiB of RAM. Compute profiles are tenant-wide and shared across all VDCs.

Storage Profile

A reusable template that defines disk tier, I/O limits, and zone-to-storage-pool mappings. Storage profiles abstract the underlying Proxmox storage pools, allowing administrators to offer named tiers like "SSD Standard" or "NVMe Performance" with defined read/write MB/s limits.

Image

An OS template used to create new VMs. The image catalog stores metadata (name, version, download URL, checksum) and the agent handles staging the actual image files onto node storage. Images are typically cloud-init compatible Linux distributions (Ubuntu, Debian, Rocky Linux, etc.).

Load Balancer

A service that distributes traffic across multiple VMs. Load balancers support TCP forwarding rules, path-based HTTP routing, and optional TLS termination or passthrough. They are deployed as components of the flexgateway chart.

Edge Gateway

A network appliance at the VDC boundary that provides NAT (Network Address Translation), firewalling, and bandwidth limiting. Edge gateways connect VDC networks to external networks and enforce security policies. They run on Proxmox nodes and are managed by the agent.

Kubernetes Cluster

A managed Kubernetes cluster provisioned and operated by flex.plane. Control plane components (etcd, API server, controller manager, scheduler) run as pods in the management cluster via the flexkube chart. Worker nodes run as VMs on Proxmox, managed by Cluster API (CAPI).

Node Pool

A group of Kubernetes worker nodes with identical configuration: same compute profile, region, zone, and taints. Node pools can be scaled independently. Each pool has between 0 and 10 nodes.

Technology terms

Proxmox VE

An open-source virtualization platform based on KVM and LXC. flex.plane uses Proxmox as the hypervisor for running VMs. The orchestrator communicates with Proxmox through its REST API, proxied by the agent.

Zitadel

An open-source identity management platform that provides OIDC (OpenID Connect) authentication. flex.plane uses Zitadel for user authentication, role management, and VDC membership. Zitadel is deployed as part of the identity Helm chart.

CAPI (Cluster API)

A Kubernetes sub-project that provides declarative APIs for cluster lifecycle management. flex.plane uses CAPI to provision and manage Kubernetes clusters on Proxmox infrastructure. The flexkube chart deploys the control plane, while CAPI manages the worker node VMs.

GraphQL

A query language for APIs developed by Meta. flex.plane uses GraphQL (via gqlgen) for its entire API surface. The schema-first approach means the .graphqls files define the contract, and Go resolvers are generated from them.

gRPC

A high-performance RPC framework developed by Google. flex.plane uses gRPC for communication between the orchestrator and agents over the Tailscale mesh. The service definition lives in pkg/agent/agent.proto.

WireGuard Mesh

A peer-to-peer VPN based on the WireGuard protocol. flex.plane uses Tailscale (or Headscale, the open-source control server) to create a secure mesh network between all Proxmox nodes and the orchestrator. This mesh provides encrypted communication, service discovery, and is the foundation for the agent proxy architecture.

Headscale

An open-source, self-hosted implementation of the Tailscale control server. The orchestrator runs an embedded Headscale instance to manage the mesh network. Agents connect to Headscale during enrollment and maintain persistent WireGuard tunnels.