Skip to main content

Controller Architecture

This page shows how Kube-DC controllers turn platform custom resources into Kubernetes, network, identity, storage, and security state. It is an operator view: resource names and component responsibilities are shown, but source-code paths and implementation details are intentionally omitted.

High-Level Topology​

Kube-DC controller topologyThe kube-dc CLI updates the Fleet repository, Flux reconciles it through the Kubernetes API, and Kubernetes resources are watched by Organization and Project, network, security, and platform endpoint controllers. Product controllers integrate with Keycloak, Kube-OVN, KubeVirt, storage, and observability. Network controllers integrate with Kube-OVN. Security controllers integrate with OpenBao, Envoy Gateway, cert-manager, and observability. Endpoint controllers maintain core Kubernetes resources.kube-dc CLIinstallationcommandFleet repositorydesired stateFluxGitOpsreconciliationKubernetes APIresource APIKUBERNETES RESOURCESKUBE-DC MANAGERPLATFORM SYSTEMSProduct CRDsOrganization · ProjectOrganizationGroupNetwork CRDsEIp · FIpSecurity CRDsManagedSecret · KMSKeycertificate · DB policyCore resourcesService · SecretConfigMap · NamespaceProduct controllersOrganization +ProjectNetwork controllersexternal IPlifecycleSecurity controllerssecrets +certificatesEndpoint controllersselectorlessendpointsKeycloakidentityOpenBaosecret backendKube-OVNnetwork + MultusKubeVirtCDI + storageGateway servicesEnvoy + cert-managerObservabilityGrafana · metricslogs
Fleet and Flux deliver desired state to the Kubernetes API; resource-specific Kube-DC controllers then reconcile identity, networking, virtualization, security, endpoints, and observability integrations.

Controller Groups​

Controller groupWatchesMain responsibility
Organization and Project controllersOrganizations, Projects, OrganizationGroupsCreate backing namespaces, identity mappings, RBAC, default Project networking, quotas, and Project lifecycle state.
Network controllersEIp and FIp resources, LoadBalancer ServicesAllocate and bind external addresses, program Kube-OVN objects, and keep service load balancers attached to the right routers and switches.
Platform endpoint controllersAnnotated selectorless platform Services and NodesProbe eligible node backends and maintain companion EndpointSlices; charts and Fleet own the VIP, Gateway, routes, and certificates.
Security controllersManagedSecrets, ManagedCertificates, KMSKeys, DatabaseCredentialPoliciesBridge project security resources to OpenBao, cert-manager, projected Kubernetes Secrets, and status rollups.
Status aggregationProject security and platform stateRoll child-resource readiness into higher-level Project and Organization status so operators and UI users see one clear state.

Project Lifecycle​

Project lifecycle reconciliationA platform administrator creates an Organization through the Kubernetes API. Product controllers reconcile its Keycloak realm and groups and publish Organization status. An Organization administrator then creates a Project. Product controllers create its backing namespace, hierarchy, RBAC, trust resources, VPC, subnet, network attachment, SNAT, router policies, optional backup and image resources, observability scope, and Project status. Finally, an OrganizationGroup is reconciled into a Keycloak membership target and Project RoleBindings.create Organizationreconcilerealm + groupspublish statuscreate Projectreconcilenamespace · RBAC · trustVPC · subnet · policiesbackup + imagesdatasource scopepublish statuscreate OrgGroupreconcilesync identity targetcreate RoleBindings1 · ORGANIZATION SETUPPlatform adminactorKubernetes APIOrganization APIProduct controllersOrganizationreconcileKeycloakrealm + groups2 · PROJECT SETUPOrg adminactorKubernetes APIProject APIProduct controllersProjectreconcileAPI resourcesnamespace +accessNetworkingKube-OVN +MultusVirtualizationKubeVirt +storageObservabilitydatasourcescopeProject statusProjectconditions3 · ACCESS MAPPINGOrg adminactorKubernetes APIOrganizationGroupAPIProduct controllersaccessreconcileKeycloakmembershiptargetRoleBindingsper Project
Reconciliation proceeds in three operator-visible phases: establish the Organization and identity state, create all Project boundaries and integrations, then materialize group-based Project RoleBindings.

Network Flow​

Project workload network flowProject virtual machines and Pods connect to the Project VPC and subnet, which uses outbound SNAT to the public or cloud external subnet. A LoadBalancer Service is synchronized by the service load-balancer controller through an EIp allocation and OVN load balancer. A FIp resource is synchronized through an EIp allocation and OVN floating-IP rules. External clients reach the external subnet, which forwards through the appropriate OVN rule to the Service or workload.PROJECTNETWORK CONTROLLERSKUBE-OVNEXTERNALWorkloadsVMs + PodsProject networkVPC + subnetOutbound SNATdefault egressExternal subnetcloud / publicServicetype LoadBalancerLB controllerService syncEIpallocationLoad-balancer ruleOVN load balancerFIp resourceone-to-one NATFIp controllerFloating IP syncFloating-IP rulesDNAT + SNATClientsingress source
Three paths share the Project VPC but remain distinct: default outbound SNAT, Service LoadBalancer publication, and one-to-one Floating IP translation.

Kube-DC has two address concepts:

  • EIp is the allocated external address object. It can back a Project gateway, a service load balancer, or another higher-level resource.
  • FIp creates a 1:1 NAT mapping from an EIp to either a selected VM interface (vmTarget) or an explicit internal workload address (ipAddress). The guest or Pod keeps its internal address.

The controller keeps ownership and status on the Kube-DC resources while Kube-OVN owns the low-level routing, NAT, and load-balancer programming.

Security Flow​

Project secret and certificate flowManagedSecret, ManagedCertificate, KMSKey, and DatabaseCredentialPolicy resources in a Project backing namespace are handled by dedicated security controllers. Secret sync uses OpenBao and writes a projected Kubernetes Secret. Certificate sync uses OpenBao and cert-manager to create a Certificate. KMS key sync uses OpenBao. Database credential policy sync uses OpenBao and the database manager and writes a projected Secret. All four controllers report to Project status aggregation.PROJECT BACKING NAMESPACESECURITY CONTROLLERSPLATFORM BACKENDSManagedSecretsource resourceManagedCertificatesource resourceKMSKeysource resourceDatabaseCredentialPolicysource resourceProjected SecretManagedSecret + DB policyCertificatecert-manager outputSecret syncsecret reconciliationCertificate synccertificatereconciliationKMS key synckey reconciliationDB policy synccredentialreconciliationOpenBaosecret + key backendcert-managercertificate issuerDatabase managercredential sourceProject statuscontroller conditions
Each Project-scoped security resource has a dedicated controller and backend path; controller conditions converge separately in Project status without exposing platform credentials.

Security controllers validate and reconcile Project-scoped requests while keeping backend credentials and privileged operations in platform service accounts. Ready conditions on child resources are aggregated so the Project status can show whether its security dependencies are usable.

Platform Endpoint Flow​

Platform endpoint reconciliationThe chart and Fleet desired state defines the MetalLB IPAddressPool and advertisement, annotated selectorless LoadBalancer Service, and Envoy or Kubernetes API listener. The Service triggers PlatformEndpointReconciler, which watches the Service and Nodes, probes each eligible node backend, and maintains a companion EndpointSlice attached to the Service. A Managed Cluster or Project workload resolves a vpc-dns hostname rewrite to a stable internal VIP and reaches the same Service.FLEET DESIRED STATEPLATFORM ENDPOINT RECONCILERPROJECT VPC PATHMetalLB addressespool + advertisementAnnotated ServiceselectorlessLoadBalancerGateway listenerEnvoy orKubernetes APIWatchService + NodesProbeeligible node backendsEndpointSlicecompanion resourceProject clientManaged Cluster / workloadvpc-dnshostname rewriteInternal VIPstable internal address
Fleet owns the address pool, listener, and selectorless Service; the endpoint controller probes eligible nodes and maintains its EndpointSlice, while Project clients resolve a stable internal VIP.

The chart and Fleet configuration own the MetalLB pool, advertisement, LoadBalancer Service, Gateway resources, routes, and certificates. The PlatformEndpointReconciler does not create those objects. It watches an explicitly annotated selectorless Service, health-probes the eligible node backends, and maintains the Service's companion EndpointSlice.

For topologies that cannot hairpin through the public address, vpc-dns rewrites platform hostnames to the internal VIP. This keeps the hostname and TLS identity unchanged while selecting a reachable path. See Internal platform endpoints.

Reading The Diagram​

  • The CLI and Fleet repository define desired state.
  • Flux applies that state to the management cluster.
  • Kube-DC controllers reconcile custom resources and selected Kubernetes resources into real platform state.
  • External platform systems such as Keycloak, OpenBao, Kube-OVN, KubeVirt, cert-manager, Envoy Gateway, and observability components do the specialized work.
  • Status flows back to Kube-DC resources so the UI, CLI, and operators can read the platform state from Kubernetes.