Stateless Orchestrator

The orchestrator is the heart of flex.plane, and it has no database. This is the single most important architectural decision in the platform, and it shapes everything else.

Understand the design

Most virtualization platforms like VMware vCenter, OpenStack Nova, or Harvester store their view of the world in a database. VMs, networks, storage pools, users, all maintained as rows in PostgreSQL or etcd entries. This creates a fundamental problem: the platform's state can drift from reality. A VM that exists in the database but not in the hypervisor. A network that was deleted out-of-band. A user whose roles were updated but the cache has not expired yet.

flex.plane takes a different approach. The orchestrator derives all state from the systems that actually own it:

When you query for VMs, the orchestrator asks Proxmox. When you check compute profiles, it reads a Kubernetes ConfigMap. When it validates your role, it inspects your OIDC token claims from Zitadel. There is no intermediate state store.

See where state lives

Every piece of data in flex.plane has a clear owner:

The orchestrator is a read-through gateway for all of these systems. It translates GraphQL queries into the appropriate API calls, aggregates the results, and returns a unified response.

Why ConfigMaps?

For configuration data that does not belong in any external system (compute profiles, storage profiles, catalog entries), flex.plane uses Kubernetes ConfigMaps. These are simple, version-controlled, and already managed by the Kubernetes cluster where the orchestrator runs. No additional database required.

Non-intrusive by design

The stateless design makes flex.plane fundamentally non-intrusive. If the orchestrator goes down, workloads continue running untouched. You can uninstall flex.plane entirely and your VMs, networks, and storage remain exactly as they are in Proxmox. The platform is a management layer, not a runtime dependency.

One exception: Kubernetes clusters provisioned through flex.plane use Cluster API (CAPI), which runs control plane components in the management cluster. If the management cluster is unavailable, existing Kubernetes workloads continue running, but cluster scaling, upgrades, and lifecycle operations are paused until the management cluster is restored.

Appreciate the trade-offs

The stateless design has real advantages and honest trade-offs.

Advantages

• No state drift. What you see is what actually exists. The orchestrator cannot disagree with Proxmox because it asks Proxmox every time.
• Zero-downtime restarts. You can restart or redeploy the orchestrator at any time. No migrations, no data loss, no recovery procedures.
• Simplified operations. No database backups, no replication lag, no schema migrations, no connection pooling headaches. One fewer system to monitor and maintain.
• Non-intrusive. If the orchestrator goes down, workloads continue running untouched. The platform is a management layer, not a runtime dependency. You can uninstall it without affecting workloads.

Trade-offs

• Per-request fan-out. Every request reaches out to the relevant systems. A "list all VMs" query touches every Proxmox cluster. In practice, this is fast: the orchestrator caches zone and host topology, and Proxmox API calls are local to each node via the agent. Response times for typical operations are well under a second. This is not a limiting factor for interactive portal use or most API integrations.
• No historical data. The orchestrator does not track what happened in the past. If you need audit logs, metrics history, or event streams, those come from the individual systems (Proxmox logs, Kubernetes events, Zitadel audit trail).
• System dependency. If Proxmox is unreachable, the orchestrator cannot show you your VMs. If the mesh network is down between the orchestrator and a zone, that zone becomes invisible. The orchestrator is only as available as the systems it queries.

The stateless approach extends to other components too. The scheduler queries Proxmox node resources at decision time to place VMs. No component maintains its own state.