Skip to main content
The Tenant resource defines tenant-specific configuration for load balancing, ingress, Gateway API, DNS, and certificate management. It provides multi-tenant isolation at the cluster scope.

​
API Version

kubelb.k8c.io/v1alpha1

​
Resource Scope

Cluster-scoped

​
Spec Fields

​
Annotation Settings

​
propagatedAnnotations
map[string]string
Defines the list of annotations (key-value pairs) that will be propagated to the LoadBalancer service. Keep the value field empty in the key-value pair to allow any value.Tenant configuration has higher precedence than the annotations specified at the Config level.
​
propagateAllAnnotations
boolean
Defines whether all annotations will be propagated to the LoadBalancer service. If set to true, propagatedAnnotations will be ignored.Tenant configuration has higher precedence than the value specified at the Config level.
​
defaultAnnotations
map[AnnotatedResource]Annotations
Defines the list of annotations (key-value pairs) that will be set on the load balancing resources if not already present. A special key all can be used to apply the same set of annotations to all resources.Tenant configuration has higher precedence than the annotations specified at the Config level.Valid resource types: all, service, ingress, gateway, httproute, grpcroute, tcproute, udproute, tlsroute

​
LoadBalancer Settings

​
loadBalancer.class
string
Class of the load balancer to use. This has higher precedence than the value specified in the Config.
​
loadBalancer.disable
boolean
default:"false"
Flag that can be used to disable L4 load balancing for a tenant.

​
Ingress Settings

​
ingress.class
string
Class of the ingress to use. This has higher precedence than the value specified in the Config.
​
ingress.disable
boolean
default:"false"
Flag that can be used to disable Ingress for a tenant.

​
Gateway API Settings

​
gatewayAPI.class
string
Class of the gateway API to use. This can be used to specify a specific gateway API implementation. This has higher precedence than the value specified in the Config.
​
gatewayAPI.defaultGateway
ObjectReference
Default gateway reference to use for the tenant. This is only used for load balancer hostname.
​
gatewayAPI.defaultGateway.name
string
Name of the gateway.
​
gatewayAPI.defaultGateway.namespace
string
Namespace of the gateway.
​
gatewayAPI.disable
boolean
default:"false"
Flag that can be used to disable Gateway API for a tenant.

​
DNS Settings

​
dns.wildcardDomain
string
Domain that will be used as the base domain to create wildcard DNS records for DNS resources. This is only used for determining the hostname for LoadBalancer resources at LoadBalancer.Spec.Hostname.
​
dns.allowExplicitHostnames
boolean
Flag that can be used to allow explicit hostnames to be used for DNS resources. This is only used when LoadBalancer.Spec.Hostname is set.
​
dns.useDNSAnnotations
boolean
Flag that can be used to add DNS annotations to DNS resources. This is only used when LoadBalancer.Spec.Hostname is set.
​
dns.useCertificateAnnotations
boolean
Flag that can be used to add Certificate annotations to Certificate resources. This is only used when LoadBalancer.Spec.Hostname is set.

​
Certificate Settings

​
certificates.defaultClusterIssuer
string
The Cluster Issuer to use for the certificates by default. This is only used for load balancer hostname.

​
Status Fields

The Tenant resource currently does not have any status fields.

​
Example

​
Basic Tenant Configuration

apiVersion: kubelb.k8c.io/v1alpha1
kind: Tenant
metadata:
  name: tenant-example
spec:
  propagateAllAnnotations: false
  propagatedAnnotations:
    custom.io/annotation: "allowed-value"
    another.io/annotation: ""
  defaultAnnotations:
    all:
      default.io/annotation: "default-value"
    service:
      service.io/annotation: "service-specific"
  loadBalancer:
    class: metallb
    disable: false
  ingress:
    class: nginx
    disable: false
  gatewayAPI:
    class: envoy
    disable: false
  dns:
    wildcardDomain: "*.tenant1.example.com"
    allowExplicitHostnames: true
    useDNSAnnotations: true
    useCertificateAnnotations: true
  certificates:
    defaultClusterIssuer: letsencrypt-prod

​
Tenant with LoadBalancer Disabled

apiVersion: kubelb.k8c.io/v1alpha1
kind: Tenant
metadata:
  name: tenant-no-l4
spec:
  loadBalancer:
    disable: true
  ingress:
    class: nginx
  gatewayAPI:
    class: envoy
    defaultGateway:
      name: shared-gateway
      namespace: gateway-system
  dns:
    wildcardDomain: "*.apps.example.com"

​
Tenant with Custom Gateway

apiVersion: kubelb.k8c.io/v1alpha1
kind: Tenant
metadata:
  name: tenant-custom-gateway
spec:
  propagateAllAnnotations: true
  gatewayAPI:
    class: istio
    defaultGateway:
      name: istio-gateway
      namespace: istio-system
    disable: false
  dns:
    wildcardDomain: "*.tenant-custom.example.com"
    allowExplicitHostnames: false
  certificates:
    defaultClusterIssuer: cert-manager-issuer

​
Tenant with Specific Annotations

apiVersion: kubelb.k8c.io/v1alpha1
kind: Tenant
metadata:
  name: tenant-annotations
spec:
  propagatedAnnotations:
    cloud.provider.io/load-balancer-type: "nlb"
    monitoring.io/scrape: "true"
  defaultAnnotations:
    httproute:
      route.io/timeout: "30s"
      route.io/retry: "3"
    gateway:
      gateway.io/class: "premium"
  loadBalancer:
    class: cloud-lb
  dns:
    wildcardDomain: "*.prod.example.com"
    useDNSAnnotations: true
    useCertificateAnnotations: true
  certificates:
    defaultClusterIssuer: letsencrypt-prod

​
Notes

  • Tenant configuration always takes precedence over Config-level settings
  • Use the disable flags to selectively disable L4 load balancing, Ingress, or Gateway API functionality per tenant
  • The wildcardDomain setting is used to automatically generate hostnames for LoadBalancer resources
  • Annotation settings allow fine-grained control over which annotations are propagated or set by default on load balancing resources

Build docs developers (and LLMs) love

Get started for freeTalk to us