Skip to main content

Install Traefik Hub Gateway on Kubernetes

Before You Begin​

Before you begin the installation process, it is recommended that you have a basic understanding of Kubernetes. You should have access to a working Kubernetes cluster, either on a cloud provider or on your own infrastructure.

Please make sure that you have the following:

  • Kubectl
  • Helm v3
  • Kubernetes version 1.23 or greater.
  • Allow outgoing requests to api.traefik.io on HTTPS ports (TCP/443).
  • Networking requirements to make sure that the Traefik Hub API Gateway can communicate with Traefik Hub to validate the token.

You can use alternatives such as kind, k3d, k3s, cloud providers, and others.

warning

You must disable the built-in Traefik ingress for k3d and k3s clusters to avoid possible conflicts. Refer to their documentation to see how to disable it.

Install with the Helm Chart​

Log in to the Traefik Hub Online Dashboard, and open the page which allows you to create a new Hub Gateway.

⚠️ Copy only the token.

Step 1: Store the token in a secret​

Open a terminal and run the following commands to create the required secret:

# Create an environment variable which contains the token
# Set the token provided in the Dashboard here
export TRAEFIK_HUB_TOKEN=
# Initilaze the namespace and the secret that contains the token
kubectl create namespace traefik
kubectl create secret generic license --namespace traefik --from-literal=token=$TRAEFIK_HUB_TOKEN

Step 2: Deploy Hub API Gateway​

Run the helm commands to install Hub API Gateway:

Install Traefik Hub API Gateway using Helm
# Add the Helm repository
helm repo add --force-update traefik https://traefik.github.io/charts
# Install the Helm chart
helm install traefik -n traefik --wait \
  --set hub.token=license \
  --set ingressRoute.dashboard.enabled=false \
   traefik/traefik
Proxy Mode

You can install Traefik Hub without a license by enabling Proxy Mode. This requires Traefik Hub >= v3.21.0-ea, which is above the version this chart defaults to. Also set image.tag:

Install Traefik Hub in Proxy Mode using Helm
helm install traefik -n traefik --wait \
  --set hub.enabled=true \
  --set image.tag=v3.21.0-ea.1 \
  --set ingressRoute.dashboard.enabled=false \
   traefik/traefik

In this mode, Traefik Hub behaves as Traefik Proxy. When you're ready to add a license to use commercial features, run helm upgrade with --set hub.token=<secret-name> added to the same values. See Proxy Mode for details.

If you want to download a specific version, you have to set the version with the following format: vMAJOR.MINOR.PATCH; for example v3.1.1.

In this installation guide, a few options that are set by default in Traefik Hub API Gateway Helm Chart are turned off. It allows you to set up an instance of Hub API Gateway with a minimal set of features. For example, this installation does not deploy the Traefik Hub API Gateway local dashboard. A dedicated section describes how to deploy a secured dashboard. To customize the installation using the Helm Chart, refer to the dedicated documentation.

Offline Mode

Working in an air-gapped environment? Want to install Traefik Hub API Gateway in an offline mode?

Check out the Offline Mode documentation.

Using the commands described above, the following objects are installed in the namespace traefik:

# kubectl -n traefik describe deployments.apps traefik
Name:                   traefik
Namespace:              traefik
...
  Containers:
   traefik:
    Ports:       9100/TCP, 9000/TCP, 8000/TCP, 8443/TCP, 9943/TCP
    Host Ports:  0/TCP, 0/TCP, 0/TCP, 0/TCP, 0/TCP
    Args:
      --global.checknewversion
      --global.sendanonymoususage
      --log.level=INFO
      --hub.token=$(HUB_TOKEN)
      # Entrypoints (Link concepts entrypoints)
      --entryPoints.metrics.address=:9100/tcp
      --entryPoints.traefik.address=:9000/tcp
      --entryPoints.web.address=:8000/tcp
      --entryPoints.websecure.address=:8443/tcp
      # Set TLS per default on the Entrypoint websecure
      --entryPoints.websecure.http.tls=true
      # Enable to check the Health of Traefik Hub API Gateway on the path /ping
      --ping=true
      # Enable Kubernetes providers (Link concepts providers)
      --providers.kubernetescrd
      --providers.kubernetesingress
    Liveness:   http-get http://:9000/ping delay=2s timeout=2s period=10s #success=1 #failure=3
    Readiness:  http-get http://:9000/ping delay=2s timeout=2s period=10s #success=1 #failure=1
    Environment:
      HUB_TOKEN:      <set to the key 'token' in secret 'traefik-hub-license'>  Optional: false
      POD_NAME:        (v1:metadata.name)
      POD_NAMESPACE:   (v1:metadata.namespace)

Install Multiple API Gateway Instances​

You can deploy multiple, isolated Traefik Hub API gateway instances on a Kubernetes cluster. This is useful for multi-tenant environments where different teams or applications require separate gateway instances.

Isolation is achieved by configuring each gateway instance to watch only specific namespaces using Helm chart values. This ensures that an instance only interacts with resources (like Kubernetes Secrets for Let's Encrypt) within its designated namespaces.

To configure a namespaced gateway instance, you must set the following Helm values together:

  • hub.namespaces: Define the list of namespaces this gateway instance should monitor for specific Hub-related resources (Secrets, AIServices).
  • rbac.namespaced=true: Restrict the gateway's permissions to only the namespaces listed in hub.namespaces.
  • ingressClass.enabled=false: Required when using namespaced RBAC to prevent conflicts with IngressClass resource handling.
  • providers.kubernetesCRD.namespaces (or providers.kubernetesIngress.namespaces): Align the namespaces watched by the underlying Traefik Proxy for standard resources (Middleware, TLSOption, etc.) with hub.namespaces.

Example Configuration:

Deploying an instance named traefik in the traefik namespace, watching the apps:

helm upgrade --install --namespace traefik traefik traefik/traefik \
  --create-namespace \
  --set hub.token=YOUR_TRAEFIK_HUB_LICENSE \
  --set 'hub.namespaces={apps}' \
  --set rbac.namespaced=true \
  --set ingressClass.enabled=false \
  --set providers.kubernetesCRD.namespaces={traefik,apps}
info

Repeat this process with different installation namespaces (--namespace), release names, and hub.namespaces / providers.kubernetesCRD.namespaces lists for each isolated gateway instance.

Scaling the Traefik Hub Gateway​

Traefik Hub API Gateway is built to seamlessly handle increased traffic by scaling out your deployment. You have two options to scale the Gateway: manual scaling and automatic scaling.

Manual Scaling​

You can manually control the number of Gateway pods by setting the deployment.replicas value in the Helm chart. By default, this value is set to 1. To increase the number of replicas, adjust this value during installation.

For example, to install the Gateway with three replicas, run:

helm install traefik-hub -n traefik --set deployment.replicas=3 traefik/traefik-hub

Or, if you need to update an existing deployment:

helm upgrade traefik-hub -n traefik --reuse-values --set deployment.replicas=3 traefik/traefik-hub

Automatic Scaling​

For dynamic scaling, you can use Kubernetes Horizontal Pod Autoscalers (HPA) to automatically adjust the number of replicas based on CPU usage or other metrics. Since the Gateway is typically CPU-bound, using HPA can help ensure optimal performance during traffic spikes.

For more details on configuring automatic scaling, please refer to the Autoscaling page.

Related Content​