Architecture
One physical hub runs the management plane. Workload clusters are never K3s agents of the hub — they register to OCM over WireGuard and receive platform manifests via ManifestWork.
Layers
| Layer | Object | Role |
|---|---|---|
| Infrastructure | Hub inventory host | K3s, OCM, Harbor, console, fleet-site / fleet-edge — not a ManagedCluster |
| Site | FleetSite | Logical location: edge.ingress[], optional hubGateway, jumphost |
| Cluster | ManagedCluster + FleetClusterJoin | Standalone K3s data plane, fleet.site label, capabilities, ingress binding |
| App | FleetApp + FleetChart | Helm install on a named Ready cluster; optional FleetAppRoute for public URLs |
Site ingress
Each FleetSite declares named ingress entries. Clusters select one withspec.edge.ingressId. Optional hubGateway enables hub-fronted public URLs for that site.
| Ingress method | Behavior |
|---|---|
port_forward | WAN port-forwards to spoke Traefik NodePorts; one cluster per entry |
reverse_proxy | External reverse proxy terminates TLS; many clusters may share an entry |
Sites with no ingress rows and no hubGateway have no fleet-managed WAN path. Per-app FleetApp routes use hub, site, or none.
Network planes
Each node has a management LAN address for the K3s API, etcd, and Calico. Greenfield clusters also run wg-umkim — a /32 on the fleet overlay so the hub reaches spoke NodePorts without public routing.
Controllers on the hub
| Controller | Role |
|---|---|
| fleet-site | Sites, FleetClusterJoin bootstrap, node/storage/platform ops, optional YAIDAP provisioner, FleetApp / FleetChart, edge ConfigMaps |
| fleet-edge | FleetAppRoute reconcile: hub Traefik fragments, spoke Ingress ManifestWorks, ACME |
| fleet-console-auth | Session RBAC and proxy to fleet-site APIs |
L0 site provisioning (optional)
Sites may bind an optional YAIDAP provisioner on a jumphost for L0 metal and VM work — TempXE PXE install, libvirt guest create, hardware discovery — before UMKIM takes over at SSH-ready with FleetClusterJoin enroll and bootstrap. The hub stores native Ansible inventory and syncs it to the jumphost; connector Jobs run ansible-playbook on the site.
Optional spoke platform
KubeVirt (Multus + CDI + KubeVirt) is an optional platform add-on on Ready workload clusters — not a FleetApp chart install. Operators enable it at create or after Ready, optionally with LAN Multus for L2-attached VMs. Guest lifecycle runs through the hub API and consoleVirtual machines view.
Deep dives live on the docs site: fleet model, network planes, YAIDAP, Fleet KubeVirt platform, site provisioning, hub install lifecycle.