Skip to main content

Architecture Overview

Kube-DC turns one Kubernetes management cluster into a multi-tenant platform for virtual machines, containers, managed databases, object storage, and Managed Clusters. Users work with Organizations and Projects; controllers translate those product objects into Kubernetes, identity, networking, storage, and observability resources.

Start with the product model​

The product model uses an art-directed layout, PatternFly-aligned styling, responsive scrolling, and a print-safe light theme.

Kube-DC product hierarchyA management cluster contains the acme and example Organizations. The acme Organization contains production and development Projects. The production Project contains virtual machines, container workloads, databases and object storage, and a Managed Cluster.containsPROJECT: PRODUCTION · WORKLOAD CAPABILITIESPLATFORMTENANCYGOVERNED WORKLOAD BOUNDARIESManagement clustercontains OrganizationsOrganization: acmeidentity · membership · quotaOrganization: exampleindependent tenant boundaryProject: productionbacking namespacededicated VPCProject: developmentbacking namespacededicated VPCVirtual machinesProject workloadContainersProject workloadData servicesdatabasesobject storageManaged ClusterseparateKubernetes APIOrganization governance and Project isolation are different boundaries.A Managed Cluster retains its own API, authorization, and CNI boundaries.
Kube-DC product hierarchy. Organizations are tenant boundaries; Projects are governed workload boundaries inside an Organization.
  • An Organization is the tenant boundary for identity, membership, billing, shared quota, and policy.
  • A Project is the governed workload boundary inside an Organization. Its Kubernetes implementation is a backing namespace named {organization}-{project} plus a dedicated Kube-OVN VPC.
  • A Managed Cluster is a separate Kubernetes API and control plane provisioned from a Project. Do not use cluster when the underlying object is only a Project or backing namespace.

Management plane​

This diagram preserves the established relationships while making the two control loops explicit. Local, repository-approved SVG icons identify the access surfaces and management services without becoming the primary carrier of meaning.

Kube-DC management planeUsers and operators access Kube-DC through the console, admin console, or CLI. These access surfaces call Kubernetes and backend APIs. The APIs feed Kube-DC controllers, which reconcile Keycloak; Kube-OVN, Multus, and Envoy Gateway; KubeVirt, Kamaji, and Cluster API; CSI and Rook Ceph; OpenBao, External Secrets, and cert-manager; and Grafana, Mimir, and Loki. Separately, the Fleet repository supplies desired installation state to Flux, which installs and configures the management cluster.reconcilesdesired stateACCESS PATHINSTALLATION CONTROLMANAGEMENT CLUSTER · CONTROL AND PLATFORM SERVICESUsers and operatorsplatform consumersConsole, admin console, CLIaccess surfacesPlatform APIsKubernetes + backendKube-DC controllersreconciliationIdentityKeycloakNetworkingKube-OVN · MultusEnvoy GatewayComputeKubeVirt · KamajiCluster APIStorageCSIRook CephSecurityOpenBaoExternal Secretscert-managerObservabilityGrafana · MimirLokiFleet repodesired stateFluxinstalls +configures
The installation loop and runtime reconciliation loop are separate: Fleet and Flux install and configure the management cluster; Kube-DC controllers reconcile product resources through the management APIs.

Flux continuously reconciles installation configuration from the Fleet repository. Kube-DC controllers continuously reconcile product resources such as Organizations, Projects, External IP (EIp) resources, and Managed Clusters. These are different control loops: Flux installs and configures the platform, while the controllers operate Organization and Project resources.

This layered view connects the access surface, Organization and Project governance, workload capabilities, management-cluster foundation, and underlying infrastructure. Managed Clusters retain their own API, authorization, and CNI boundaries.

Kube-DC architectural layersUsers access the console, admin console, and CLI, which call Kubernetes and backend APIs. Kube-DC controllers reconcile Organization and Project governance, platform integrations, networking, compute, data services, Project workloads, and Managed Clusters. These capabilities run on the Kubernetes management cluster and physical or cloud infrastructure. Fleet and Flux separately install and configure the management cluster.ACCESS AND MANAGEMENTPLATFORM CONTROL · GOVERNANCE AND INTEGRATIONSWORKLOAD AND DATA CAPABILITIESFOUNDATIONUsersoperatorsAccess surfacesconsole · admin · CLIPlatform APIsKubernetesbackend APIsKube-DC controllersreconciliationGovernanceOrganizationsProjects · RBAC · VPCIdentityKeycloak · RBACSecurityOpenBaocertificatesObservabilityGrafana · MimirLokiNetworkingKube-OVN · MultusEnvoy GatewayComputeKubeVirt · CDIData servicesCSI · Rook Cephmanaged databasesProject workloadsbacking namespaceOrganization + ProjectManaged Clustersseparate APIauthorization · CNIFleet + Fluxdesired stateinstallationManagement clusterplatform execution planeInfrastructurephysical or cloudcompute · networks · storage
Kube-DC architectural layers. Organizations and Projects govern resources in the management cluster; Managed Clusters retain separate API, authorization, and CNI boundaries.

Main subsystems​

AreaResponsibilityPrincipal components
Identity and accessLogin, Organization membership, Project permissionsKeycloak, OIDC, Kubernetes RBAC
Tenancy and quotaOrganization and Project lifecycle, plan limits, usage statusKube-DC controllers, HNC, ResourceQuota
NetworkingProject VPCs, egress, external addresses, Services, ingressKube-OVN, Multus, MetalLB, Envoy Gateway
VirtualizationVM lifecycle, images, console access, live-migration-capable storage pathsKubeVirt, CDI, CSI
Managed ClustersControl-plane and worker lifecycleKamaji, Cluster API, provider controllers
Data servicesManaged databases, block volumes, and S3-compatible bucketsCloudNativePG, MariaDB operator, CSI, Rook Ceph
Security servicesManaged secrets, certificates, and encryption keysOpenBao, External Secrets, cert-manager
ObservabilityOrganization- and Project-scoped metrics, logs, alerts, and dashboardsGrafana, Mimir, Loki, Prometheus Operator

Not every subsystem is required on every installation. Storage, external networking, public certificate, GPU, and bare-metal capabilities depend on the cluster topology and enabled Fleet components.

Management cluster and Managed Clusters​

The management cluster runs the Kube-DC platform and stores its custom resources. A Managed Cluster has its own Kubernetes API and authorization boundary, even when its control-plane pods or workers run on infrastructure owned by the management cluster.

Use the management-cluster kubeconfig for platform operations. Use a Managed Cluster kubeconfig for workloads and cluster-scoped operations inside that Managed Cluster. A Project role does not grant cluster-admin access inside a Managed Cluster.

Isolation model​

Kube-DC combines several controls rather than relying on a single boundary:

  • namespace-scoped RBAC for Project resources;
  • Organization-level hierarchical quota across Project backing namespaces;
  • one Kube-OVN VPC and workload subnet per Project;
  • ingress and egress router policies for shared external networks;
  • admission policies for protected platform resources;
  • per-Organization identity, observability, and security-service mappings.

Platform administrators and management-cluster components remain inside the trusted platform boundary. See the security documentation for assumptions and residual risks.