Skip to main content
The KubeLB Manager is deployed in the management cluster and is responsible for:
  • Hosting the Envoy xDS control plane
  • Receiving load balancer configurations from tenant clusters
  • Deploying and configuring Envoy proxy instances
  • Managing LoadBalancer and Route resources

​
Prerequisites

Before installing the Manager, ensure you have:
  • A Kubernetes cluster meeting the management cluster requirements
  • kubectl configured to access the management cluster
  • Helm 3.x installed
  • The kubelb namespace created

​
Installation Steps

1

Create the namespace

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

Pull the Helm chart

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

Apply CRDs

Install the Custom Resource Definitions (CRDs) before installing the chart:
kubectl apply -f kubelb-manager/crds/
CRDs must be installed separately as they are not managed by Helm to prevent accidental deletion.
4

Create values file

Create a values.yaml file with your configuration. Here’s a minimal example:
values.yaml
kubelb:
  # Enable debug logging (set to false in production)
  debug: true
  logLevel: info
  
  # Envoy proxy configuration
  envoyProxy:
    topology: shared
    replicas: 2
    singlePodPerNode: true

# Resource limits
resources:
  limits:
    cpu: 500m
    memory: 512Mi
  requests:
    cpu: 100m
    memory: 128Mi
The shared topology deploys one Envoy proxy per tenant cluster, which is the recommended configuration.
5

Install the Helm chart

Install KubeLB Manager using Helm:
helm install kubelb-manager kubelb-manager/ \
  --namespace kubelb \
  -f values.yaml \
  --create-namespace

​
Configuration Options

​
Envoy Proxy Topology

KubeLB supports different Envoy proxy deployment topologies: 
kubelb:
  envoyProxy:
    topology: shared
    replicas: 2
    singlePodPerNode: true

​
Gateway API Support

To enable Gateway API controllers: 
kubelb:
  enableGatewayAPI: true
Gateway API CRDs must be installed before enabling this feature, otherwise the controller will fail to start.

​
Annotation Propagation

Control which annotations are propagated from LoadBalancer resources to services: 
kubelb:
  propagatedAnnotations:
    metallb.universe.tf/loadBalancerIPs: "true"
    external-dns.alpha.kubernetes.io/hostname: "true"

​
Resource Configuration

Configure resources for both the Manager and Envoy proxy: 
# Manager resources
resources:
  limits:
    cpu: 1000m
    memory: 1Gi
  requests:
    cpu: 200m
    memory: 256Mi

# Envoy proxy resources
kubelb:
  envoyProxy:
    resources:
      limits:
        cpu: 2000m
        memory: 2Gi
      requests:
        cpu: 500m
        memory: 512Mi

​
Monitoring

Enable Prometheus ServiceMonitor: 
serviceMonitor:
  enabled: true

metrics:
  port: 9443
Enable Grafana dashboards: 
grafana:
  dashboards:
    enabled: true
    annotations:
      grafana_folder: "KubeLB"
Requires Grafana to be deployed with sidecar.dashboards.enabled=true.

​
Security

​
Chart Signature Verification

All KubeLB Helm charts are cryptographically signed using Sigstore Cosign. Verify the chart before installation: 
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

​
Image Signature Verification

Verify the Manager container image: 
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

​
Security Context

The Manager runs with restrictive security settings by default: 
podSecurityContext:
  runAsNonRoot: true
  seccompProfile:
    type: RuntimeDefault

securityContext:
  allowPrivilegeEscalation: false
  capabilities:
    drop:
      - ALL
  runAsUser: 65532

​
Advanced Configuration

​
KKP Integration

For Kubermatic Kubernetes Platform integration: 
kkpintegration:
  rbac: true

​
Leader Election

Configure leader election for high availability: 
kubelb:
  enableLeaderElection: true

replicaCount: 2

​
Skip Config Generation

To manage the Config CR manually: 
kubelb:
  skipConfigGeneration: true

​
Upgrading

To upgrade KubeLB Manager to a new version:
1

Update CRDs

kubectl apply -f kubelb-manager/crds/
2

Upgrade Helm release

helm upgrade kubelb-manager oci://quay.io/kubermatic/helm-charts/kubelb-manager \
  --version=v1.3.1 \
  --namespace kubelb \
  -f values.yaml

​
Troubleshooting

​
Check Manager Status

kubectl get pods -n kubelb -l app.kubernetes.io/name=kubelb-manager

​
View Manager Logs

kubectl logs -n kubelb -l app.kubernetes.io/name=kubelb-manager -f

​
Check Envoy Proxy Status

kubectl get pods -n kubelb -l app=envoy-proxy

​
Common Issues

If the Manager fails to start with Gateway API errors, ensure Gateway API CRDs are installed or disable Gateway API support by setting kubelb.enableGatewayAPI: false.

​
Next Steps

After installing the Manager:
  1. Install KubeLB CCM in your tenant clusters
  2. Verify the installation to ensure components are working correctly

Build docs developers (and LLMs) love

Get started for freeTalk to us