Skip to main content
KubeLB implements a hub-and-spoke architecture to centrally manage load balancers across multiple Kubernetes clusters in multi-cloud and on-premise environments.

​
Architecture Overview

The hub-and-spoke model consists of three main components:

Management Cluster

The central hub that hosts the KubeLB Manager and coordinates load balancing

Tenant Clusters

Consumer clusters that run the KubeLB CCM and workloads requiring load balancers

​
Components

​
KubeLB Manager (Hub)

The KubeLB Manager runs in the management cluster and serves as the central control plane. It is responsible for:
  • Hosting the Envoy xDS (Extensible Discovery Service) control plane server
  • Receiving load balancer configurations from tenant clusters via the LoadBalancer and Route CRDs
  • Deploying and configuring Envoy proxy instances based on the selected topology
  • Managing tenant registrations and multi-tenancy isolation
  • Configuring load balancer services and routing rules
The manager implements the envoy-control-plane APIs to dynamically configure Envoy proxies using the xDS protocol.
The manager runs in its own dedicated Kubernetes cluster, separate from your workload clusters. This ensures isolation and centralized management.

​
KubeLB CCM (Spoke)

The KubeLB CCM (Cloud Controller Manager) is deployed in each tenant cluster that requires load balancer services. It acts as a bridge between the tenant cluster and the management cluster. Key responsibilities:
  • Watches for Kubernetes Service resources of type LoadBalancer
  • Watches for Ingress resources
  • Watches for Gateway API resources (Gateway, HTTPRoute, GRPCRoute)
  • Watches for node changes to track available endpoints
  • Propagates load balancer configurations to the manager as LoadBalancer and Route CRDs
  • Updates service status with assigned load balancer IPs
The CCM is installed via Helm chart and requires API access to the management cluster.

​
Cluster Relationships

​
Management Cluster

The management cluster is the central hub that:
  • Hosts the KubeLB Manager controller
  • Runs the Envoy xDS control plane server
  • Deploys Envoy proxy instances (based on topology)
  • Stores tenant configurations and load balancer state
  • Must have a LoadBalancer implementation (cloud provider or MetalLB)
Requirements:
  • Service type LoadBalancer support (cloud provider or self-managed like MetalLB)
  • Network access to tenant cluster nodes on NodePort range (default: 30000-32767)

​
Tenant Clusters

Tenant clusters are the consumer clusters where:
  • Application workloads run
  • Services require external load balancers
  • KubeLB CCM is deployed
  • Each cluster is registered as a Tenant resource in the management cluster
Requirements:
  • Registered as a Tenant in the management cluster
  • Network connectivity to the management cluster API server
  • NodePort range accessible from the management cluster

​
Communication Flow

​
Layer 4 Load Balancing (Services)

​
Layer 7 Load Balancing (Ingress/Gateway API)

​
Data Plane Architecture

KubeLB uses Envoy proxy as the data plane for load balancing:
  1. Configuration Propagation: CCM sends load balancer specs to the manager
  2. xDS Server: Manager runs an xDS control plane that configures Envoy
  3. Dynamic Updates: Envoy proxies receive configuration updates via xDS protocol
  4. Traffic Routing: Envoy forwards traffic to tenant cluster NodePorts
apiVersion: kubelb.k8c.io/v1alpha1
kind: LoadBalancer
metadata:
  name: my-service
  namespace: tenant-ns
spec:
  type: LoadBalancer
  endpoints:
    - name: default
      addresses:
        - ip: "192.168.1.10"
        - ip: "192.168.1.11"
      ports:
        - name: http
          port: 30080
          protocol: TCP
  ports:
    - name: http
      port: 80
      protocol: TCP

​
Benefits of Hub-and-Spoke Model

All load balancer configurations are managed from a single control plane, simplifying operations and reducing overhead.
Tenant clusters can run in different cloud providers or on-premise, while the management cluster handles load balancing.
Reduces the number of cloud load balancers needed by consolidating load balancing in the management cluster.
Uniform load balancer behavior across all tenant clusters, regardless of underlying infrastructure.

​
Network Requirements

Network connectivity is critical for the hub-and-spoke model to function properly.
Required network paths:
SourceDestinationPortPurpose
Tenant Cluster (CCM)Management Cluster API6443API access to create CRDs
Management Cluster (Envoy)Tenant Cluster Nodes30000-32767NodePort access for traffic routing
Envoy ProxyEnvoy xDS Server18000xDS configuration updates
ClientsManagement Cluster (LoadBalancer)80/443Application traffic

​
Next Steps

Multi-Tenancy

Learn about tenant isolation and namespace mapping

Load Balancing

Understand Layer 4 and Layer 7 load balancing

Envoy Topology

Explore different Envoy deployment topologies

Installation

Install KubeLB in your environment

Build docs developers (and LLMs) love

Get started for freeTalk to us