Skip to main content
KubeLB provides comprehensive configuration options through the Config CRD and command-line flags for both the Manager and CCM components.

​
Config CRD

The Config CRD is the primary way to configure KubeLB Manager behavior. It’s a cluster-scoped resource that defines global settings for load balancing, ingress, Gateway API, DNS, and certificates.

​
Configuration Structure

The Config resource is typically named default and created in the kubelb namespace: 
apiVersion: kubelb.k8c.io/v1alpha1
kind: Config
metadata:
  name: default
  namespace: kubelb
spec:
  envoyProxy:
    topology: shared
    replicas: 3
    useDaemonset: false
  loadBalancer: {}
  ingress: {}
  gatewayAPI: {}
  dns:
    wildcardDomain: "*.example.com"
  certificates: {}

​
Envoy Proxy Configuration

Configure the Envoy proxy deployment topology and resource settings: 
envoyProxy:
  topology: shared  # All tenants share the same Envoy deployment
  replicas: 3
  useDaemonset: false
  singlePodPerNode: true
The dedicated and global topology values are deprecated. Both now default to shared topology.

​
Envoy Proxy Options

FieldTypeDefaultDescription
topologystringsharedDeployment topology: shared (only supported value)
useDaemonsetboolfalseRun Envoy as DaemonSet instead of Deployment
replicasint323Number of replicas (ignored if useDaemonset is true)
singlePodPerNodeboolfalseSpread replicas across nodes using pod anti-affinity
nodeSelectormap[string]string-Node selector for Envoy pods
tolerations[]Toleration-Tolerations for Envoy pods
affinityAffinity-Custom affinity rules for Envoy pods
imagestring-Custom Envoy image (overrides default)

​
Graceful Shutdown Configuration

Configure graceful shutdown behavior for Envoy pods: 
envoyProxy:
  gracefulShutdown:
    disabled: false
    drainTimeout: "60s"
    minDrainDuration: "5s"
    terminationGracePeriodSeconds: 300
    shutdownManagerImage: "docker.io/envoyproxy/gateway:v1.3.0"
FieldTypeDefaultDescription
disabledboolfalseDisable graceful shutdown
drainTimeoutduration60sMaximum time to wait for connections to drain
minDrainDurationduration5sMinimum time before checking connection count
terminationGracePeriodSecondsint64300Pod termination grace period
shutdownManagerImagestringdocker.io/envoyproxy/gateway:v1.3.0Shutdown manager sidecar image

​
Overload Manager Configuration

Protect Envoy from resource exhaustion: 
envoyProxy:
  overloadManager:
    enabled: true
    maxActiveDownstreamConnections: 50000
    maxHeapSizeBytes: 2147483648  # 2GB
FieldTypeDescription
enabledboolEnable overload manager
maxActiveDownstreamConnectionsuint64Maximum active downstream connections
maxHeapSizeBytesuint64Maximum heap size before rejecting connections

​
DNS Configuration

Configure DNS management and automation: 
dns:
  wildcardDomain: "*.apps.example.com"
  allowExplicitHostnames: true
  useDNSAnnotations: true
  useCertificateAnnotations: true
FieldTypeDescription
wildcardDomainstringBase domain for wildcard DNS records
allowExplicitHostnamesboolAllow explicit hostnames in LoadBalancer.Spec.Hostname
useDNSAnnotationsboolAdd DNS annotations to DNS resources
useCertificateAnnotationsboolAdd certificate annotations to certificate resources

​
Annotation Settings

Control which annotations are propagated from tenant resources: 
propagatedAnnotations:
  "cert-manager.io/cluster-issuer": "letsencrypt-prod"
  "external-dns.alpha.kubernetes.io/hostname": ""
propagateAllAnnotations: false
defaultAnnotations:
  service:
    "kubelb.k8c.io/default-annotation": "value"
  ingress:
    "nginx.ingress.kubernetes.io/ssl-redirect": "true"
FieldTypeDescription
propagatedAnnotationsmap[string]stringAnnotations to propagate (empty value allows any)
propagateAllAnnotationsboolPropagate all annotations (ignores propagatedAnnotations)
defaultAnnotationsmap[AnnotatedResource]AnnotationsDefault annotations per resource type
Supported AnnotatedResource values: all, service, ingress, gateway, httproute, grpcroute, tcproute, udproute, tlsroute

​
Manager Command-Line Flags

The KubeLB Manager (kubelb) supports the following flags:

​
Basic Options

kubelb \
  --namespace=kubelb \
  --metrics-addr=:9443 \
  --health-probe-bind-address=:8081 \
  --enable-leader-election=true
FlagDefaultDescription
--namespacekubelbNamespace where the controller runs
--metrics-addr:9443Metrics endpoint bind address
--health-probe-bind-address:8081Health probe endpoint bind address
--enable-leader-electiontrueEnable leader election for HA deployments
--kubeconfig-Path to kubeconfig (only for out-of-cluster)

​
Envoy Control Plane Options

kubelb \
  --listen-address=:8001 \
  --enable-gateway-api=false
FlagDefaultDescription
--listen-address:8001Address for Envoy xDS control plane
--enable-gateway-apifalseEnable Gateway API and controllers
--debugfalseEnable debug mode for verbose logging
Gateway API CRDs must be installed before enabling --enable-gateway-api. The controller will fail to start if CRDs are missing.

​
Deprecated Flags

FlagStatusNotes
--enable-tenant-migrationDeprecatedNOOP - controller has been removed

​
CCM Command-Line Flags

The KubeLB Cloud Controller Manager (kubelb-ccm) runs in tenant clusters and propagates resources to the management cluster.

​
Required Flags

kubelb-ccm \
  --cluster-name=production \
  --kubelb-kubeconfig=/etc/kubelb/kubeconfig
FlagRequiredDescription
--cluster-nameYesUnique cluster/tenant name (auto-prefixed with tenant- if not present)
--kubelb-kubeconfigYesPath to KubeLB management cluster kubeconfig

​
Service Controller Options

kubelb-ccm \
  --enable-cloud-provider=true \
  --use-loadbalancer-class=false \
  --node-address-type=ExternalIP
FlagDefaultDescription
--enable-cloud-providertrueEnable cloud controller behavior for LoadBalancer status
--use-loadbalancer-classfalseFilter services by LoadBalancerClass kubelb
--node-address-typeExternalIPAddress type for endpoints: ExternalIP, InternalIP, or Hostname

​
Ingress and Gateway API Options

kubelb-ccm \
  --use-ingress-class=true \
  --use-gateway-class=true \
  --enable-gateway-api=false \
  --disable-ingress-controller=false \
  --disable-gateway-controller=false \
  --disable-httproute-controller=false \
  --disable-grpcroute-controller=false
FlagDefaultDescription
--use-ingress-classtrueFilter Ingresses with ingressClassName: kubelb
--use-gateway-classtrueFilter Gateways with gatewayClassName: kubelb
--enable-gateway-apifalseEnable Gateway API support
--disable-ingress-controllerfalseDisable Ingress controller
--disable-gateway-controllerfalseDisable Gateway controller
--disable-httproute-controllerfalseDisable HTTPRoute controller
--disable-grpcroute-controllerfalseDisable GRPCRoute controller

​
Gateway API CRD Management

kubelb-ccm \
  --install-gateway-api-crds=false \
  --gateway-api-crds-channel=standard
FlagDefaultDescription
--install-gateway-api-crdsfalseAutomatically install Gateway API CRDs
--gateway-api-crds-channelstandardCRD channel: standard or experimental

​
Secret Synchronization

kubelb-ccm \
  --enable-secret-synchronizer=false
FlagDefaultDescription
--enable-secret-synchronizerfalseAuto-convert Secrets with label kubelb.k8c.io/managed-by: kubelb to SyncSecrets

​
High Availability Options

kubelb-ccm \
  --enable-leader-election=true \
  --leader-election-namespace=""
FlagDefaultDescription
--enable-leader-electiontrueEnable leader election
--leader-election-namespace-Namespace for leader election lease

​
Observability Options

kubelb-ccm \
  --metrics-addr=:9445 \
  --health-probe-bind-address=:8081
FlagDefaultDescription
--metrics-addr:9445Metrics endpoint bind address
--health-probe-bind-address:8081Health probe endpoint bind address
--kubeconfig-Path to tenant cluster kubeconfig

​
Configuration Best Practices

  • Use shared topology with at least 3 replicas for high availability
  • Enable singlePodPerNode to spread Envoy pods across nodes
  • Configure resource requests and limits based on expected traffic
  • Enable graceful shutdown with appropriate drain timeouts
  • Set up overload manager to prevent resource exhaustion
  • Use unique cluster-name for each tenant cluster
  • Configure propagatedAnnotations to control annotation propagation
  • Use use-loadbalancer-class and use-ingress-class for explicit opt-in
  • Enable secret synchronization for centralized certificate management
  • Install Gateway API CRDs before enabling Gateway API support
  • Use --gateway-api-crds-channel=standard for stable features
  • Enable Gateway API gradually (start with --enable-gateway-api=true)
  • Test with --use-gateway-class=true to filter specific gateways
  • Configure wildcardDomain for automatic hostname generation
  • Enable useDNSAnnotations for external-dns integration
  • Enable useCertificateAnnotations for cert-manager integration
  • Set allowExplicitHostnames when using custom domains

​
Environment Variables

Both Manager and CCM support standard Kubernetes environment variables:
VariableDescription
NAMESPACEAlternative to --namespace flag (Manager only)
KUBECONFIGAlternative to --kubeconfig flag
HOMEUsed to find default kubeconfig location

​
Next Steps

Monitoring

Set up Prometheus metrics and Grafana dashboards

Troubleshooting

Debug common issues and check logs

Build docs developers (and LLMs) love

Get started for freeTalk to us