Skip to main content

​
Prerequisites

Before installing KubeLB, ensure you have:

Management Cluster

A Kubernetes cluster with LoadBalancer service support (cloud provider or MetalLB)

Tenant Cluster

One or more Kubernetes clusters that need load balancing services

Network Connectivity

Network access from management cluster to tenant cluster nodes (NodePort range: 30000-32767)

Helm 3.x

Helm CLI installed for deploying charts

​
Installation Overview

KubeLB installation consists of two main steps:
  1. Deploy KubeLB Manager to the management cluster
  2. Deploy KubeLB CCM to each tenant cluster

​
Step 1: Deploy KubeLB Manager

The KubeLB Manager runs in your management cluster and provides the central control plane.
1

Create Namespace

Create a namespace for the KubeLB Manager:
kubectl create namespace kubelb
2

Pull Helm Chart

Pull the KubeLB Manager Helm chart:
helm pull oci://quay.io/kubermatic/helm-charts/kubelb-manager --version=v1.3.1 --untardir "." --untar
3

Apply CRDs

Apply the Custom Resource Definitions:
kubectl apply -f kubelb-manager/crds/
4

Create Values File

Create a values.yaml file for your configuration:
values.yaml
kubelb:
  # Enable debug logging
  debug: false
  logLevel: info
  
  # Enable leader election for HA
  enableLeaderElection: true
  
  # Envoy proxy configuration
  envoyProxy:
    topology: shared  # Options: shared, global
    replicas: 2
    useDaemonset: false
    singlePodPerNode: true
    resources:
      requests:
        cpu: 100m
        memory: 128Mi
      limits:
        cpu: 500m
        memory: 512Mi

# Manager resource limits
resources:
  requests:
    cpu: 100m
    memory: 128Mi
  limits:
    cpu: 500m
    memory: 512Mi
For Gateway API support, add enableGatewayAPI: true to the kubelb section.
5

Install Helm Chart

Install the KubeLB Manager:
helm install kubelb-manager kubelb-manager/ \
  --namespace kubelb \
  -f values.yaml
6

Verify Installation

Verify the manager is running:
kubectl -n kubelb get pods
Expected output:
NAME                              READY   STATUS    RESTARTS   AGE
kubelb-manager-xxxxxxxxxx-xxxxx   2/2     Running   0          30s

​
Step 2: Deploy KubeLB CCM

The KubeLB CCM must be installed in each tenant cluster that needs load balancing services.
1

Create Kubeconfig Secret

Switch to your tenant cluster context and create a kubeconfig for accessing the management cluster.First, create a ServiceAccount in the management cluster for the tenant:
# On management cluster
kubectl -n kubelb create serviceaccount tenant-production

# Create RBAC (this is automatically handled during tenant setup)
# Get the token
kubectl -n kubelb create token tenant-production
Create a kubeconfig file and then create a secret in the tenant cluster:
# On tenant cluster
kubectl create namespace kubelb
kubectl -n kubelb create secret generic kubelb-cluster \
  --from-file=kubelb=path/to/management-kubeconfig.yaml
2

Pull CCM Helm Chart

Pull the KubeLB CCM Helm chart:
helm pull oci://quay.io/kubermatic/helm-charts/kubelb-ccm --version=v1.3.1 --untardir "." --untar
3

Apply CRDs

Apply the CCM Custom Resource Definitions:
kubectl apply -f kubelb-ccm/crds/
4

Create CCM Values File

Create a values-ccm.yaml file:
values-ccm.yaml
kubelb:
  # Name of the secret containing management cluster kubeconfig
  clusterSecretName: kubelb-cluster
  
  # Unique identifier for this tenant (required)
  tenantName: production
  
  # Node address type for routing
  nodeAddressType: ExternalIP  # Options: ExternalIP, InternalIP
  
  # Enable leader election
  enableLeaderElection: true
  
  # Class-based filtering
  useLoadBalancerClass: false  # Set to true to only manage services with class "kubelb"
  useIngressClass: true        # Only manage Ingress with class "kubelb"
  useGatewayClass: true        # Only manage Gateway with class "kubelb"
  
  # Controller toggles
  disableIngressController: false
  disableGatewayController: false  # Set to true if not using Gateway API
  disableHTTPRouteController: false
  disableGRPCRouteController: false

# CCM resource limits
resources:
  requests:
    cpu: 100m
    memory: 128Mi
  limits:
    cpu: 500m
    memory: 512Mi
The tenantName must be unique across all tenant clusters and follow RFC 1123 lowercase naming conventions.
5

Install CCM Helm Chart

Install the KubeLB CCM:
helm install kubelb-ccm kubelb-ccm/ \
  --namespace kubelb \
  -f values-ccm.yaml
6

Verify CCM Installation

Verify the CCM is running:
kubectl -n kubelb get pods
Expected output:
NAME                          READY   STATUS    RESTARTS   AGE
kubelb-ccm-xxxxxxxxxx-xxxxx   2/2     Running   0          30s

​
Test Your Installation

Let’s verify that KubeLB is working by creating a test service.
1

Create Test Application

In your tenant cluster, create a simple nginx deployment:
test-app.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-test
spec:
  replicas: 2
  selector:
    matchLabels:
      app: nginx-test
  template:
    metadata:
      labels:
        app: nginx-test
    spec:
      containers:
      - name: nginx
        image: nginx:latest
        ports:
        - containerPort: 80
---
apiVersion: v1
kind: Service
metadata:
  name: nginx-test
spec:
  type: LoadBalancer
  selector:
    app: nginx-test
  ports:
  - port: 80
    targetPort: 80
    protocol: TCP
Apply the manifest:
kubectl apply -f test-app.yaml
2

Check Service Status

Wait for the LoadBalancer IP to be assigned:
kubectl get service nginx-test -w
After a few moments, you should see an EXTERNAL-IP assigned:
NAME         TYPE           CLUSTER-IP      EXTERNAL-IP      PORT(S)        AGE
nginx-test   LoadBalancer   10.96.100.123   192.168.1.100    80:31234/TCP   1m
3

Verify Load Balancer in Management Cluster

Switch to the management cluster and check that the LoadBalancer CRD was created:
kubectl -n tenant-production get loadbalancers
You should see:
NAME         AGE
nginx-test   1m
4

Test Connectivity

Test accessing the service through the load balancer:
curl http://192.168.1.100
You should receive the nginx welcome page.

​
Next Steps

Configure Gateway API

Set up Layer 7 routing with Gateway API

Use Ingress Resources

Configure HTTP/HTTPS routing with Ingress

Multi-Tenant Setup

Learn about managing multiple tenant clusters

Monitoring & Observability

Set up metrics and monitoring for KubeLB

​
Security

​
Verify Chart Signature

All KubeLB Helm charts are cryptographically signed using Sigstore Cosign: 
cosign verify quay.io/kubermatic/helm-charts/kubelb-manager:v1.3.1 \
  --certificate-identity-regexp="^https://github.com/kubermatic/kubelb/.github/workflows/release.yml@refs/tags/v.*" \
  --certificate-oidc-issuer=https://token.actions.githubusercontent.com

​
Verify Image Signature

cosign verify quay.io/kubermatic/kubelb-manager:v1.3.1 \
  --certificate-identity-regexp="^https://github.com/kubermatic/kubelb/.github/workflows/release.yml@refs/tags/v.*" \
  --certificate-oidc-issuer=https://token.actions.githubusercontent.com

​
Troubleshooting

​
CCM Cannot Connect to Management Cluster

If the CCM cannot connect to the management cluster:
  1. Verify the kubeconfig secret exists and is correctly formatted
  2. Check network connectivity from tenant to management cluster
  3. Verify RBAC permissions for the tenant ServiceAccount
kubectl -n kubelb logs deployment/kubelb-ccm

​
LoadBalancer IP Not Assigned

If services don’t receive an external IP:
  1. Check that the management cluster has a working LoadBalancer implementation
  2. Verify the manager pods are running in the management cluster
  3. Check manager logs for errors
kubectl -n kubelb logs deployment/kubelb-manager

​
Traffic Not Reaching Pods

If traffic doesn’t reach your pods:
  1. Verify network connectivity from management cluster to tenant nodes
  2. Check that NodePort services are accessible
  3. Verify Envoy proxy is running and configured
kubectl -n kubelb get pods -l app.kubernetes.io/name=envoy

Build docs developers (and LLMs) love

Get started for freeTalk to us