Multi-Tenancy in Kubernetes¶
In a multi-tenant Kubernetes cluster, several teams or tenants share the same cluster. How well Traefik Proxy isolates tenants from each other depends on how you deploy it:
| Deployment | Routing Configuration | Address | Multi-Tenancy |
|---|---|---|---|
| Traefik Operator with Kubernetes Gateway API | One per Gateway | One per Gateway | Recommended |
One Traefik instance per Gateway, scoped with providers.kubernetesGateway.gateways |
One per Gateway | One per Gateway | Alternative to the Traefik Operator |
| Single Traefik instance with Kubernetes Gateway API | Shared by all Gateways | Shared by all Gateways | Not recommended |
One Traefik instance per tenant with Ingress or IngressRoute, scoped with namespaces |
One per tenant | One per tenant | Recommended for Ingress and IngressRoute |
| Single Traefik instance with Ingress or IngressRoute | Shared by all namespaces | Shared by all namespaces | Not recommended |
For multi-tenant clusters, use Kubernetes Gateway API with the Traefik Operator, or with one Traefik instance per Gateway scoped with providers.kubernetesGateway.gateways, and create one Gateway per tenant.
Gateway API¶
Kubernetes Gateway API treats each Gateway as an independent entry point to the cluster, with its own listeners, routes, and addresses.
A single Traefik instance doesn't keep Gateways separate.
To give each Gateway its own Traefik data plane, use the Traefik Operator, or deploy one Traefik instance per Gateway scoped with providers.kubernetesGateway.gateways.
Single Traefik Instance¶
When you run one Traefik instance with the Kubernetes Gateway API provider, that instance serves every Gateway it watches from one shared routing configuration:
- Routes are not isolated per Gateway. Routers built from routes attached to different Gateways share the same entry points, so a route attached to one tenant's Gateway can match requests intended for another tenant's Gateway.
- Gateways share one address. Every Gateway reports the address of the same Traefik instance in its
status.addresses. - Gateways share one instance. Heavy traffic or a misconfiguration on one Gateway affects every other Gateway served by that instance.
Use a single Traefik instance only when every Gateway it serves belongs to the same tenant. To isolate Gateways without the Traefik Operator, see One Traefik Instance Per Gateway.
Traefik Operator¶
The Traefik Operator watches Gateways and provisions a dedicated Traefik data plane for each one, in the Gateway's own namespace.
Each data plane is a separate Traefik instance, with its own Deployment, Service, and ServiceAccount, and it serves only the Gateway it was provisioned for:
- Each Gateway has its own routing configuration. A route attached to one tenant's Gateway can't match requests sent to another tenant's Gateway.
- Each Gateway reports its own address. The data plane reports the address of its own
Servicein the Gatewaystatus.addresses, and honors the addresses requested inspec.addresses. - Each Gateway carries its own infrastructure metadata. The labels and annotations set in the Gateway
spec.infrastructureare added to the resources generated for its data plane. - Each data plane runs in the tenant's namespace. Kubernetes deletes the data plane with its Gateway, and the data plane counts against the tenant's namespace quotas.
To get the same isolation without the Traefik Operator, see One Traefik Instance Per Gateway.
The Traefik Operator requires Traefik v3.8 or later as the data plane. To install it, follow the Traefik Operator Getting Started guide. The Traefik Operator is validated against the Gateway API conformance suite. See the Traefik Operator conformance report for the results.
Isolation applies per Gateway, so tenants that share a Gateway also share its data plane. Create one Gateway per tenant, in the tenant's namespace.
Listeners add control inside each Gateway.
A cluster operator can use the listener hostname to limit the domain names a Gateway serves, and allowedRoutes to limit which namespaces can attach routes to it.
See Gateway API routing configuration for the listener options Traefik supports.
One Traefik Instance Per Gateway¶
Without the Traefik Operator, you can get the same isolation by deploying one Traefik instance per Gateway yourself.
Set providers.kubernetesGateway.gateways on each instance to the Gateway it serves.
An instance reconciles only the Gateways listed in gateways, and ignores every other Gateway and the routes attached to it.
Give each instance its own Service, and set providers.kubernetesGateway.statusAddress.service to that Service, so each Gateway reports the address of its own instance.
List each Gateway in the gateways option of one instance only.
Using the tenant-a Gateway in the tenant-a namespace as the example:
providers:
kubernetesGateway:
# Reconcile only the tenant-a Gateway.
gateways:
- name: tenant-a
namespace: tenant-a
# Report the address of this instance's Service in the Gateway status.
statusAddress:
service:
name: traefik-tenant-a
namespace: tenant-a[providers.kubernetesGateway]
# Reconcile only the tenant-a Gateway.
[[providers.kubernetesGateway.gateways]]
name = "tenant-a"
namespace = "tenant-a"
# Report the address of this instance's Service in the Gateway status.
[providers.kubernetesGateway.statusAddress.service]
name = "traefik-tenant-a"
namespace = "tenant-a"--providers.kubernetesgateway.gateways[0].name=tenant-a
--providers.kubernetesgateway.gateways[0].namespace=tenant-a
--providers.kubernetesgateway.statusaddress.service.name=traefik-tenant-a
--providers.kubernetesgateway.statusaddress.service.namespace=tenant-aproviders:
kubernetesGateway:
enabled: true
# Reconcile only the tenant-a Gateway.
gateways:
- name: tenant-a
namespace: tenant-a
# The chart reports the address of its own Service in the Gateway status by default.
statusAddress:
service:
enabled: trueUnlike the Traefik Operator, this setup leaves you to create, update, and delete each instance and its Service when tenants add or remove Gateways.
Ingress and IngressRoute¶
The Kubernetes Ingress and IngressRoute providers build one routing configuration for every namespace a Traefik instance watches, so tenants share the limits described in Limits of a Shared Traefik Instance.
With Ingress or IngressRoute, the recommended approach for multi-tenant Kubernetes clusters is to deploy one dedicated Traefik instance per tenant, scoped to that tenant's namespace(s). This ensures strict boundaries between tenants and prevents cross-tenant configuration leakage.
Each Traefik instance should be:
- Deployed in the tenant's namespace with a dedicated
ServiceAccount - Configured with
providers.kubernetesCRD.namespacesand/orproviders.kubernetesIngress.namespacesto restrict resource watch to that tenant's namespaces only - Subject to Kubernetes RBAC that limits its access to only the resources it needs
This namespace-per-tenant topology, combined with Kubernetes NetworkPolicy resources, provides the strongest available isolation when using Ingress or IngressRoute on a shared cluster.
Dedicate one Traefik instance per tenant using the Helm Chart
providers:
kubernetesCRD:
namespaces:
- tenant
kubernetesIngress:
namespaces:
- tenant
Limits of a Shared Traefik Instance¶
A single Traefik instance shared by several tenants has these limits, whatever the provider:
- Resource visibility and isolation: Traefik requires cluster-level permissions and watches resources across namespaces. A misconfiguration in one tenant's resources can affect other tenants.
- Traffic and availability: Routing rules, middlewares, or heavy traffic from one tenant can affect the reliability and performance of other tenants.
- Observability and privacy: Logs, metrics, and traces are shared by default, which can expose sensitive information across tenants.
TLS Store¶
Traefik holds all its TLS certificates in a TLS store that is global to the instance. The TLS store is shared across all namespaces, so any Ingress, IngressRoute, or Gateway served by the instance can use or affect TLS configuration intended for another tenant. This lack of isolation is a risk when tenants require strict boundaries around TLS certificates.