Skip to main content

Getting Started

Traefik Hub API Gateway is cloud-native and multi-platform.

We can start:

  1. on Kubernetes
  2. on Linux

Pre-requisites​

  • A Traefik Hub account and license.
  • Helm installed.
  • Allow outgoing requests to api.traefik.io on HTTPS ports (TCP/443).

On Kubernetes​

For this tutorial, we deploy Traefik Hub API Gateway on a Kubernetes cluster using k3s. It's possible to use alternatives such as kind, k3d, k3s cloud providers, and others.

warning

It's important to 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.

First, clone the GitHub repository dedicated to tutorials:

git clone https://github.com/traefik/hub.git
cd hub

Create a Kubernetes Cluster Using k3s​

Before you begin, ensure that any existing Kubernetes cluster is fully uninstalled to prevent potential conflicts during the K3s installation.

curl -sfL https://get.k3s.io | K3S_KUBECONFIG_MODE="644" INSTALL_K3S_EXEC="--disable traefik" sh -
info

In the command above, we deploy K3s using its official installation script and pass configuration options through environment variables, which are applied to the K3s service configuration:

  • Additional utilities will be installed, including kubectl, crictl, ctr, k3s-killall.sh, and k3s-uninstall.sh.
  • K3S_KUBECONFIG_MODE="644" lets non-root users run kubectl. The kubeconfig file will be written in /etc/rancher/k3s/k3s.yaml. The installed kubectl will automatically use it.
  • INSTALL_K3S_EXEC="--disable traefik" disables the built-in Traefik to avoid conflicts.

Note: This configuration is intended for demonstration purposes only. It is not recommended for production environments. For more advanced configuration options, refer to the official K3s documentation: K3s Configuration

Alternative option: Create a Kubernetes Cluster Using kind​

kind requires some configuration to use an IngressController on localhost. See the following example:

Create the cluster

Ports need to be mapped for HTTP and HTTPS for kind with this config:

kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
name: traefik-hub
nodes:
- role: control-plane
  extraPortMappings:
  - containerPort: 30000
    hostPort: 80
    protocol: TCP
  - containerPort: 30001
    hostPort: 443
    protocol: TCP
kind create cluster --config=src/kind/config.yaml
kubectl cluster-info
kubectl wait --for=condition=ready nodes traefik-hub-control-plane

Step 1: Install Traefik Hub API Gateway​

Log in to the Traefik Hub Online Dashboard, navigate to the Gateways page to create a new gateway.

Click on Quick getting started instruction and select Kubernetes option.

Copy the content of 'Configuration' box.

Open a terminal and run the copied commands to install Traefik Hub using Helm.

For example:

# Add the Helm repository
helm repo add --force-update traefik https://traefik.github.io/charts

# Install the Ingress Controller
kubectl create namespace traefik
kubectl create secret generic traefik-hub-license --namespace traefik --from-literal=token=<traefik-hub-license>
helm upgrade --install --namespace traefik traefik traefik/traefik \
  --set hub.token=traefik-hub-license \
  --set image.registry=ghcr.io \
  --set image.repository=traefik/traefik-hub \
  --set image.tag=latest-v3

The following will be displayed in your terminal after running the commands:

"traefik" has been added to your repositories
namespace/traefik created
secret/traefik-hub-license created
Release "traefik" does not exist. Installing it now.
NAME: traefik
LAST DEPLOYED: Mon Aug 12 20:00:00 2024
NAMESPACE: traefik
STATUS: deployed
REVISION: 1
TEST SUITE: None
NOTES:
traefik with ghcr.io/traefik/traefik-hub:v3.17.3 has been deployed successfully on traefik namespace !

If Traefik Hub API Gateway is already installed, copy the new token generated from the gateway creation page and use it to generate the traefik-hub-license secret :

export TRAEFIK_HUB_TOKEN= <paste-token-here>
kubectl create secret generic traefik-hub-license --namespace traefik --from-literal=token=$TRAEFIK_HUB_TOKEN

Next, upgrade Traefik helm chart:

# Upgrade CRDs
kubectl apply --server-side --force-conflicts -k https://github.com/traefik/traefik-helm-chart/traefik/crds/
# Update the Helm repository
helm repo update
#Create the traefik-hub-license secret
kubectl create secret generic traefik-hub-license --namespace traefik --from-literal=token=$TRAEFIK_HUB_TOKEN
# Upgrade the Helm chart
helm upgrade traefik -n traefik --wait traefik/traefik \
  --set hub.token=traefik-hub-license \
  --set image.registry=ghcr.io \
  --set image.repository=traefik/traefik-hub \
  --set image.tag=latest-v3 \

Step 2: Deploy an API as an Ingress​

Without Traefik Hub API Gateway, an API can be deployed as an Ingress, an IngressRoute or an HTTPRoute.

In this tutorial, APIs are implemented using a JSON server in Go; the source code is here.

Let's deploy a weather app exposing an API.

kubectl apply -f src/manifests/weather-app.yaml

It should create the public app

namespace/apps created
configmap/weather-data created
middleware.traefik.io/stripprefix-weather created
deployment.apps/weather-app created
service/weather-app created
configmap/weather-app-openapispec created

It can be exposed with an IngressRoute:

---
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: getting-started-apigateway
  namespace: apps
spec:
  entryPoints:
    - web
  routes:
  - match: Host(`localhost`) && PathPrefix(`/weather`)
    kind: Rule
    services:
    - name: weather-app
      port: 3000
    middlewares:
      - name: stripprefix-weather
kubectl apply -f api-gateway/1-getting-started/manifests/weather-app-ingressroute.yaml

After applying the resources, it creates the IngressRoute resource:

ingressroute.traefik.io/getting-started-apigateway created

This API can be accessed using curl:

curl http://localhost/weather | jq
[
  {"city":"GopherCity","id":"0","weather":"Moderate rain"},
  {"city":"City of Gophers","id":"1","weather":"Sunny"},
  {"city":"GopherRocks","id":"2","weather":"Cloudy"}
]

Step 3: Secure authentication on this API with Traefik Hub​

Let's secure the weather API with an API Key.

First, we need to generate a password hash before proceeding. This can be done with htpasswd. It's usually contained in the apache2-utils package on various systems (e.g., Ubuntu, Debian) if you don't have it already.

htpasswd -nbs "" "Let's use API Key with Traefik Hub" | cut -c 2-

It should output a hash similar to this:

{SHA}dhiZGvSW60OMQ+J6hPEyJ+jfUoU=

Next, store this hash in a Secret for the API Key Middleware and create a new IngressRoute:

cat <<'EOF' | kubectl apply -f -
---
apiVersion: v1
kind: Secret
metadata:
  name: getting-started-apigateway-apikey-auth
  namespace: apps
stringData:
  secretKey: "{SHA}dhiZGvSW60OMQ+J6hPEyJ+jfUoU=" # Generated API secretKey

---
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: getting-started-apigateway-apikey-auth
  namespace: apps
spec:
  plugin:
    apiKey:
      keySource:
        header: Authorization
        headerAuthScheme: Bearer
      secretValues:
        - urn:k8s:secret:getting-started-apigateway-apikey-auth:secretKey

---
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: getting-started-apigateway-api-key
  namespace: apps
spec:
  entryPoints:
    - web
  routes:
  - match: Host(`localhost`) && PathPrefix(`/api-key`)
    kind: Rule
    services:
    - name: weather-app
      port: 3000
    middlewares:
    - name: stripprefix-weather
    - name: getting-started-apigateway-apikey-auth
EOF

After applying the resources, it creates the Secret, Middleware, and IngressRoute resources:

secret/getting-started-apigateway-apikey-auth created
middleware.traefik.io/getting-started-apigateway-apikey-auth created
ingressroute.traefik.io/getting-started-apigateway-api-key created

And test it:

# This call is not authorized => 401
curl -i http://localhost/api-key/weather
# Let's set the API key
export API_KEY=$(echo -n "Let's use API Key with Traefik Hub" | base64)
# This call with the token is allowed => 200
curl -i -H "Authorization: Bearer $API_KEY" http://localhost/api-key/weather

The API is now secured.

On Linux​

This tutorial will show how to use Traefik Hub API Gateway on Linux using a shell command (for simplicity). In production, we recommend using Infra-as-Code or even GitOps.

info

We will use a Debian Linux in this tutorial.

First, clone the GitHub repository dedicated to tutorials:

git clone https://github.com/traefik/hub.git
cd hub

Step 1: Install Traefik Hub API Gateway​

Get the Traefik Hub API Gateway binary:

# Download the binary
LATEST_VERSION=$(curl -s https://api.github.com/repos/traefik/hub/releases/latest | grep 'tag_name' | cut -d '"' -f 4)
curl -L "https://github.com/traefik/hub/releases/download/$LATEST_VERSION/traefik-hub_${LATEST_VERSION}_linux_amd64.tar.gz" -o /tmp/traefik-hub.tar.gz
tar xvzf /tmp/traefik-hub.tar.gz -C /tmp traefik-hub-linux-amd64
rm -f /tmp/traefik-hub.tar.gz
# Install the binary with the required rights
sudo mv /tmp/traefik-hub-linux-amd64 /usr/local/bin/traefik-hub
sudo chown root:root /usr/local/bin/traefik-hub
sudo chmod 755 /usr/local/bin/traefik-hub
# Give the Traefik Hub binary ability to bind privileged ports like 80 or 443 as non-root
sudo setcap 'cap_net_bind_service=+ep' /usr/local/bin/traefik-hub

Create the config resources:

# Create a user
sudo groupadd --system traefik-hub
sudo useradd \
  -g traefik-hub --no-user-group \
  --home-dir /var/www --no-create-home \
  --shell /usr/sbin/nologin \
  --system traefik-hub
# Create a config directory
sudo mkdir -p /etc/traefik-hub/dynamic
sudo chown root:root /etc/traefik-hub
sudo chown traefik-hub:traefik-hub /etc/traefik-hub/dynamic
# Create a log file
sudo touch /var/log/traefik-hub.log
sudo chown traefik-hub:traefik-hub /var/log/traefik-hub.log

Log in to the Traefik Hub Online Dashboard, open the page to generate a new gateway.

warning

Do not install the gateway, but copy the token.

Export your token:

export TRAEFIK_HUB_TOKEN=SET_YOUR_TOKEN_HERE

With this token, we can add a static configuration file for Traefik Hub API Gateway and a systemd service:

sudo cp api-gateway/1-getting-started/linux/traefik-hub.toml /etc/traefik-hub/traefik-hub.toml
sudo sed -i -e "s/PASTE_YOUR_TOKEN_HERE/$TRAEFIK_HUB_TOKEN/g" /etc/traefik-hub/traefik-hub.toml
sudo cp api-gateway/1-getting-started/linux/traefik-hub.service /etc/systemd/system/traefik-hub.service
sudo chown root:root /etc/systemd/system/traefik-hub.service
sudo chmod 644 /etc/systemd/system/traefik-hub.service
sudo systemctl daemon-reload
sudo systemctl enable --now traefik-hub.service

Ensure the service is working as expected using the dedicated command:

sudo systemctl status traefik-hub.service
● traefik-hub.service - Traefik Hub
     Loaded: loaded (/etc/systemd/system/traefik-hub.service; enabled; preset: enabled)
     Active: active (running) since [...]; 2s ago
   Main PID: 2516 (traefik-hub)
      Tasks: 7 (limit: 1141)
     Memory: 30.6M
        CPU: 401ms
     CGroup: /system.slice/traefik-hub.service
             └─2516 /usr/local/bin/traefik-hub --configfile=/etc/traefik-hub/traefik-hub.toml

[...] systemd[1]: Started traefik-hub.service - Traefik Hub.

Step 2: Expose an API​

info

On Linux, we can use all the providers supported by Traefik Proxy and Traefik Hub API Gateway.

In this example, we'll set a configuration using a YAML file. We will deploy a whoami application on systemd and reach it from Traefik Proxy.

# Install whoami
curl -L https://github.com/traefik/whoami/releases/download/v1.11.0/whoami_v1.11.0_linux_amd64.tar.gz -o /tmp/whoami.tar.gz
tar xvzf /tmp/whoami.tar.gz -C /tmp whoami
rm -f /tmp/whoami.tar.gz
sudo mv /tmp/whoami /usr/local/bin/whoami
sudo chown root:root /usr/local/bin/whoami
sudo chmod 755 /usr/local/bin/whoami
# Create a user for whoami
sudo groupadd --system whoami
sudo useradd \
  -g whoami --no-user-group \
  --home-dir /var/www --no-create-home \
  --shell /usr/sbin/nologin \
  --system whoami

Enable this app with a systemd unit file:

sudo cp api-gateway/1-getting-started/linux/whoami.service /etc/systemd/system/whoami.service
sudo chmod 644 /etc/systemd/system/whoami.service
sudo chown root:root /etc/systemd/system/whoami.service
sudo systemctl daemon-reload
sudo systemctl enable --now whoami
sudo systemctl status whoami

And check that it's working as expected:

curl http://localhost:3000
Hostname: ip-172-31-26-184
IP: 127.0.0.1
IP: ::1
IP: 172.31.26.184
IP: fe80::8ff:eeff:fed5:2389
IP: 172.17.0.1
IP: 172.18.0.1
IP: fe80::42:92ff:fe17:7a6d
IP: fe80::4418:56ff:fe7b:4a46
RemoteAddr: 127.0.0.1:52412
GET / HTTP/1.1
Host: localhost:3000
User-Agent: curl/7.88.1
Accept: */*

Now, add a dynamic configuration file to expose it through Traefik Hub API Gateway.

Let's apply this tutorial configuration and test it:

# Not configured => 404
curl -I http://whoami.localhost
sudo cp api-gateway/1-getting-started/linux/whoami.yaml /etc/traefik-hub/dynamic/whoami.yaml
sleep 5
# Configured => 200
curl http://whoami.localhost
Hostname: ip-172-31-26-184
IP: 127.0.0.1
IP: ::1
IP: 172.31.26.184
IP: fe80::8ff:eeff:fed5:2389
IP: 172.17.0.1
IP: 172.18.0.1
IP: fe80::42:92ff:fe17:7a6d
IP: fe80::4418:56ff:fe7b:4a46
RemoteAddr: [::1]:59954
GET / HTTP/1.1
Host: whoami.localhost
User-Agent: curl/7.88.1
Accept: */*
Accept-Encoding: gzip
X-Forwarded-For: 127.0.0.1
X-Forwarded-Host: whoami.localhost
X-Forwarded-Port: 80
X-Forwarded-Proto: http
X-Forwarded-Server: ip-172-31-26-184
X-Real-Ip: 127.0.0.1

Step 3: Secure The Access Using an API Key​

Let's secure the access with an API Key.

Next, we need to generate a password hash before proceeding. This can be done with htpasswd. It's usually contained in the apache2-utils package on various systems (e.g., Ubuntu, Debian) if you don't have it already. Example in Debian:

sudo apt update
sudo apt install apache2-utils -y
htpasswd -nbs "" "Let's use API Key with Traefik Hub" | cut -c 2-
{SHA}dhiZGvSW60OMQ+J6hPEyJ+jfUoU=
{SHA}dhiZGvSW60OMQ+J6hPEyJ+jfUoU=

Put this password in the API Key middleware:

http:
  routers:
    whoami:
      rule: Host(`whoami.localhost`)
      service: local
      middlewares:
      - apikey-auth

  middlewares:
    apikey-auth:
      plugin:
        apiKey:
          keySource:
            header: Authorization
            headerAuthScheme: Bearer
          secretValues: "{SHA}dhiZGvSW60OMQ+J6hPEyJ+jfUoU="

  services:
    local:
      loadBalancer:
        servers:
          - url: http://localhost:3000

Let's apply it:

sudo cp api-gateway/1-getting-started/linux/whoami-apikey.yaml /etc/traefik-hub/dynamic/whoami.yaml
sleep 5

And test it:

# This call is not authorized => 401
curl -I http://whoami.localhost
# Let's set the token
export API_KEY=$(echo -n "Let's use API Key with Traefik Hub" | base64)
# This call with the token is allowed => 200
curl -I -H "Authorization: Bearer $API_KEY" http://whoami.localhost

The API is now secured.

Docker Providers​

We can also use the docker provider. You may have noticed that we already enabled it in the static configuration.

Let's see how it works. First, let's install docker:

sudo apt-get update
sudo apt-get install -y docker.io docker-compose

And give the traefik-hub user access to docker resources:

sudo usermod -aG docker traefik-hub
sudo systemctl restart traefik-hub.service

Now we can test the service with a docker compose file:

sudo docker compose -f $(pwd)/api-gateway/1-getting-started/linux/docker-compose.yaml up -d

Since we already enabled the docker provider in Traefik Hub API Gateway configuration, we should now be able to curl it:

curl http://whoami.docker.localhost
Hostname: cfd52cc4b3a6
IP: 127.0.0.1
IP: 172.18.0.2
RemoteAddr: 172.18.0.1:35766
GET / HTTP/1.1
Host: whoami.docker.localhost
User-Agent: curl/7.88.1
Accept: */*
Accept-Encoding: gzip
X-Forwarded-For: 127.0.0.1
X-Forwarded-Host: whoami.docker.localhost
X-Forwarded-Port: 80
X-Forwarded-Proto: http
X-Forwarded-Server: ip-172-31-26-184
X-Real-Ip: 127.0.0.1

Related Content​