Platform Architecture

kMetal is delivered as a curated bundle of components installed on the under cluster — bare metal, virtualization (KubeVirt/KVM), networking (Kube-OVN), and the Kamaji control-plane manager — wired together to run multiple tenant Kubernetes clusters on shared hardware.

See Platform Components for the component list.

Platform Architecture Overview

kMetal uses two decoupled layers: the under cluster hosts platform components (named undercloud), and the tenant layer runs tenant clusters (named tenantcloud).

Under Cluster Layer

The under cluster is one Kubernetes cluster with two kinds of node, and the split is the architecture.

Control plane nodes run the platform. Every kMetal controller lives here — Kamaji, the Cluster API providers, Capsule, cert-manager, the operator itself — and this is where the infrastructure is managed from. Tenant clusters' control planes run here too, as ordinary Pods.

Worker nodes run nothing of the platform's. Their job is to offer CPU, memory and disk for virtual machines, and those virtual machines are the worker nodes of tenant clusters. (Per-node agents are the exception: the CNI and load-balancer DaemonSets run wherever they have to, because that is what per-node means.)

A tenant cluster therefore straddles both. Its control plane is Pods on the platform's control plane nodes; its workers are VMs on the platform's worker nodes; and those VMs join that control plane exactly as machines join any Kubernetes cluster. From inside the tenant cluster none of this is visible — it is a Kubernetes cluster with an API endpoint and some nodes.

That is what the two layers buy: control planes are consolidated where they are cheap to run and easy to protect, while the capacity tenants actually consume is plain hardware that can be added a rack at a time.

See Platform Components for what those controllers are, and Hosted Control Planes for how a control plane runs as Pods.

Tenant Layer

A tenant's world is their own cluster, and their claim on the under cluster's resources.

Tenants consume. Administrators create. That separation is the point of the model, and it holds at the API: an administrator declares the infrastructure — the platform, the networks it can offer, the Tenants and the Environments they own — while a tenant asks for clusters, addresses and subnets inside what they were given. Neither can do the other's job, and neither has to wait on the other for the routine case.

Tenants may work directly against the under cluster's API with kubectl, creating Cluster objects and network claims in their own Environments. Nothing requires it. The same requests go through the web console, or through whatever GitOps pipeline a tenant already runs, because everything is an object in a namespace they own.

What a tenant gets is isolated on three axes at once: one Kube-OVN VPC per tenant with no route to any other, worker nodes that are separate virtual machines rather than shared kernels, and a control plane of their own with its own certificates and identity.

See Tenant Layer for the isolation mechanisms in detail.