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, and the tenant layer runs workload clusters.
Under Cluster Layer¶
The under cluster hosts all platform components and manages tenant cluster lifecycles. Control plane operations are centralized while tenant workloads remain isolated.
Flux GitOps Controller¶
Flux GitOps Controller provides continuous reconciliation for platform configurations. Flux monitors OCI repositories and ensures the actual platform state matches the desired state defined in configuration.
Cluster API Controllers¶
Cluster API Controllers manage the infrastructure lifecycle for tenant clusters. kMetal ships the KubeVirt infrastructure provider (CAPK), which provisions tenant worker nodes as KubeVirt VMs on the under cluster.
Kamaji Control Plane Manager¶
Kamaji Control Plane Manager implements hosted control planes by running Kubernetes control plane components as pods in the under cluster. This approach reduces resource requirements compared to dedicated control plane machines.
Each tenant control plane operates as an independent Kubernetes API endpoint with dedicated authentication and authorization. Tenant users interact with their control plane identically to traditional Kubernetes clusters.
See Hosted Control Planes for architecture details and operational implications.
MetalLB¶
MetalLB allocates LoadBalancer IPs on the under cluster — for tenant control-plane endpoints (one VIP per tenant by default) and for any platform-facing services. Combined with cert-manager for automated TLS, this gives tenants a reachable, certificate-secured API endpoint without external infrastructure.
Tenant Layer¶
The tenant layer provides physical and logical separation for tenant workloads. Each tenant cluster operates in an isolated environment with dedicated compute, storage, and network resources.
Infrastructure and Network Isolation¶
Network isolation uses VPCs, VLANs, or equivalent technologies to prevent cross-tenant communication. Tenant clusters connect to their hosted control planes through mutual TLS encryption using dedicated endpoints accessible only to authorized nodes and users.
See Tenant Layer for isolation mechanisms and multi-tenancy implementation details.