Skip to main content

Running Multiple Traefik Hub Gateways on the Same Cluster

Traefik Hub enables the deployment of multiple isolated API Management-enabled gateway instances on a single Kubernetes cluster. Each instance is scoped to specific namespaces, ensuring only the resources within those designated namespaces are managed and displayed by that instance.

Key benefits include:

  • Resource Isolation: Each gateway instance processes only the resources within its defined namespaces, preventing interference between multiple deployments.
  • Simplified Deployment: When deploying Traefik Hub, you can specify the namespaces to watch, ensuring that the deployment aligns with your organizational or team structure.
  • Consistent Management: Your API management operations remain consistent and controlled, even when multiple gateway instances are running within the same cluster.

TL;DR Setup​

When installing multiple parallel Traefik Hub gateways for multi-tenancy, you must configure each instance to watch specific namespaces and restrict RBAC to those namespaces. This configuration must be applied for each separate gateway instance you install.

export TRAEFIK_HUB_TOKEN=
export TARGET_NAMESPACE=
kubectl create namespace $TARGET_NAMESPACE
kubectl create secret generic traefik-hub-license --namespace $TARGET_NAMESPACE --from-literal=token=$TRAEFIK_HUB_TOKEN
helm upgrade --install --namespace $TARGET_NAMESPACE traefik \
  --set hub.token=traefik-hub-license \
  --set hub.apimanagement.enabled=true \
  --set image.registry=ghcr.io \
  --set image.repository=traefik/traefik-hub \
  --set image.tag=v3.16.0 \
  --set ingressClass.enabled=false \
  --set ingressRoute.dashboard.enabled=true \
  --set rbac.namespaced=true \
  --set "hub.namespaces={$TARGET_NAMESPACE}" \
  --set "providers.kubernetesIngress.namespaces={$TARGET_NAMESPACE}" \
  --set "providers.kubernetesCRD.namespaces={$TARGET_NAMESPACE}" \
    traefik/traefik

This configuration ensures that:

  • The Traefik Hub instance only watches the specified namespaces. See the Configuring Namespace Isolation section for more details.
  • RBAC is enforced within those namespaces. See the Enabling Namespaced RBAC section for more details.
  • The Traefik Hub discovers only the resources within the selected namespaces.
  • Automatic IngressClass creation is turned off to avoid conflicts. See the Handling Ingress Class Management section for more details.

Configuring Namespace Isolation​

When deploying the Traefik Hub gateway using the official Helm chart, specific values control the namespace isolation behavior. Setting these values correctly ensures that each gateway instance operates only within its designated boundaries.

The primary parameter for namespace scoping is hub.namespaces. This value accepts a list of Kubernetes namespaces that this specific Traefik Hub gateway instance will monitor. Its effect depends on the features enabled:

  • For API Management: It limits the namespaces watched for API Management CRDs, such as APIs, APICatalogItems, and APIPortals.
  • For API Gateway: It limits the namespaces watched for Kubernetes Secrets used by features like distributed Let's Encrypt and the AI Gateway, and for AIServices resources when the AI Gateway is active.

The gateway instance will remain unaware of and will not process these specific resources if they are created in other, unwatched namespaces.

hub:
  namespaces:
    - "apps"
    # - "another-relevant-namespace" # Add more namespaces if needed for this instance
note

Discovery of standard Traefik CRDs like Middleware and TLSOption is controlled by the providers.kubernetesCRD.namespaces (or providers.kubernetesIngress.namespaces) setting, not hub.namespaces. Ensure these provider settings are configured to watch the necessary namespaces for these resource types. See the Aligning with Kubernetes Provider Namespaces section for details.

In the example above, the gateway instance configured with these values will only watch for Traefik Hub CRDs within the apps namespace. If resources are created in a team-b-apps namespace, this instance will ignore them.

info

It's crucial that the namespace where the gateway itself is deployed is included in this list if you intend to manage resources within that namespace using this gateway.

Enabling Namespaced RBAC​

Deploying a gateway instance scoped to specific namespaces requires adjusting the Role-Based Access Control (RBAC) permissions. Instead of granting cluster-wide permissions (ClusterRoles), the gateway needs permissions restricted to the namespaces it watches (Roles). This is controlled by the rbac.namespaced parameter in the Helm chart.

Setting rbac.namespaced=true instructs the Helm chart to generate Kubernetes Roles and RoleBindings confined to the namespaces listed in hub.namespaces, rather than ClusterRoles and ClusterRoleBindings. This enforces the isolation at the permission level, ensuring the gateway cannot access or modify resources outside its designated namespaces.

hub:
  namespaces:
    - "apps"

rbac:
  namespaced: true

Aligning with Kubernetes Provider Namespaces​

Traefik Hub relies on an embedded Traefik Proxy instance configured via the same Helm chart to handle routing. This Traefik Proxy instance also needs to be aware of the namespaces where relevant resources (like Ingresses or Services) reside. The configuration for this is typically found under the providers.kubernetesCRD.namespaces or providers.kubernetesIngress.namespaces keys within the Helm chart values, depending on which Kubernetes provider you use.

For consistent behavior, the namespaces watched by the Traefik Hub gateway (hub.namespaces) should align with the namespaces watched by the Kubernetes provider. If the Hub gateway watches apps for API CRDs, the Traefik provider should also watch apps to discover the associated Ingresses or Services. The Helm chart may issue a warning if these namespace lists diverge, as it often indicates a potential misconfiguration.

# Example values.yaml snippet showing aligned namespaces
hub:
  namespaces:
    - "apps"

rbac:
  namespaced: true

providers:
  kubernetesCRD:
    namespaces:
    - "apps"
  # or kubernetesIngress, depending on your setup

Handling Ingress Class Management​

When configuring namespaced RBAC (rbac.namespaced=true), there is a current interaction that requires explicit management of IngressClass resources. You must set kubernetes.ingressClass.enabled=false within the Helm chart values.

hub:
  namespaces:
    - "apps"

rbac:
  namespaced: true

# Disable automatic IngressClass creation when using namespaced RBAC
kubernetes:
  ingressClass:
    enabled: false

providers:
  kubernetesCRD:
    namespaces:
    - "apps"

Setting kubernetes.ingressClass.enabled=false stops the Helm chart from creating an IngressClass resource. If an IngressClass resource existed or if Kubernetes injected a default ingressClassName into an Ingress, a namespaced Traefik Hub gateway might ignore that Ingress if its provider configuration isn't set to watch that specific class. Ensure this value is set for all namespaced gateway deployments.

Modifying Watched Namespaces​

If you modify the hub.namespaces list for an existing gateway installation (for example, by removing a namespace during a Helm upgrade), resources previously synchronized from the now-unwatched namespace will still remain visible within the Traefik Hub Online Dashboard.

However, the gateway instance no longer has RBAC permissions in the removed namespace, and the Hub Online Dashboard prevents modification of the resources in the namespace. You will not be able to edit or manage them via the UI associated with that gateway instance. This behavior is intentional; it prevents accidental data loss if the namespace removal was a mistake or part of a temporary configuration change (like a rollback). To remove these phantom resources permanently, you must manually delete them via the dashboard.

Additionally, resources in the unwatched namespaced are labelled with an orphan tag as show below:

Orphan Resource in Hub Dashboard

Traefik Hub Online Dashboard Resource Creation Scope​

When interacting with a specific gateway instance through the Traefik Hub Online Dashboard, the available namespaces for creating new resources will be limited. The dashboard will only present the namespaces actively watched by that particular gateway instance, as defined in its hub.namespaces configuration. This reinforces the namespacing isolation, ensuring users can only create resources within the namespaces their gateway instance is configured to manage.