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:

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 image.registry=ghcr.io \
  --set image.repository=traefik/traefik-hub \
  --set ingressRoute.dashboard.enabled=false \
  --set image.tag=v3 \
   traefik/traefik
Turned off options

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, please refer to the dedicated documentation.

Specific version

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.

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 using a FIPS 140-2 Compliant Image​

FIPS 140-2 is a U.S. Federal Government security standard used to approve cryptographic modules. This section explains how to install a version of Traefik Hub API Gateway that meets FIPS compliance.

Traefik Hub supports FIPS 140-2 compliance for Linux binaries by building its images with a Go toolchain linked to BoringCrypto. In Go, BoringCrypto is a general-purpose cryptographic module that complies with FIPS 140-2.

For each version of Traefik Hub API Gateway, a specific Docker image is built using the Go option GOEXPERIMENT=boringcrypto.

FIPS compliant Windows image is available since v3.14.0. This image is built with Microsoft Go version and requires a FIPS enabled environment.

For more information on our FIPS compliance, see the FIPS Compliance Reference.

Deploy Hub API Gateway​

In the Step 2 described above, replace the Traefik Hub Gateway image with the FIPS one. To do so, set the major version as a prefix in the image tag. For example, to download the FIPS compliant Traefik Hub API Gateway image in version v3:

Install Traefik Hub API Gateway FIPS-140.2 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 image.registry=ghcr.io \
  --set image.repository=traefik/traefik-hub \
  --set ingressRoute.dashboard.enabled=false \
  --set image.tag=v3-fips \
   traefik/traefik
Turned off options

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, please refer to the dedicated documentation.

Specific version

If you want to download a specific version, you have to set the version as a prefix in the image tag. For example, to use the FIPS compliant Traefik Hub API Gateway image in version v3.1.1, use the tag v3.1.1-fips.

Installation on Windows nodes

If you want to install Trafik Hub API Gateway on Windows-powered Kubernetes nodes you'll need few additional Helm parameters. Windows requires:

  • Using the correct Windows image (Windows FIPS images are available starting from v3.14.0).
  • Adding a node selector to target Windows nodes.
  • Providing Windows-specific securityContext settings.

Below is an Helm install command that meets the above requirements:

Install Traefik Hub API Gateway FIPS-140.2 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 image.registry=ghcr.io \
  --set image.repository=traefik/traefik-hub \
  --set ingressRoute.dashboard.enabled=false \
  --set image.tag=v3-windowsservercore-ltsc2022-fips \
  --set-json 'nodeSelector={"kubernetes.io/os": "windows"}' \
  --set-json 'podSecurityContext={"runAsNonRoot":true,"runAsGroup":null,"runAsUser":null,"windowsOptions":{"runAsUserName":"ContainerUser"}}' \
   traefik/traefik

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 or AIServices for the AI Gateway) 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​