Deploy Traefik Hub API Management on Azure Arc

Introduction

Traefik Labs and Microsoft have partnered to deliver a Kubernetes-native platform that unifies API management across hybrid and multi-cloud environments. This integration combines Traefik's cloud-native API Gateway & API Management with Azure Arc and Azure Kubernetes Service (AKS), enabling consistent traffic management and governance across all environments.

The Azure Marketplace deployment provides a streamlined experience for setting up Traefik Hub API Management on Azure Arc-enabled Kubernetes clusters. This guide walks you through deploying Traefik Hub API Management from the Azure Marketplace, deploying a sample API, configuring API routing and enabling an API Portal in your Azure Arc environment.

Prerequisites

An Azure subscription
A Traefik Hub License token
Access to an existing Azure Arc-enabled Kubernetes cluster. Follow the official documentation to connect your Kubernetes cluster to Azure Arc.

Deploy Traefik Hub API Management on Azure Arc from Azure Marketplace

Go to the Azure Marketplace and click on the Get It Now button

Get It Now

You will be asked to sign in to Azure, once you are signed in, a dialog will be displayed to Create this app in Azure, select Continue

Select Cluster

On the next page, select the Subscription, Resource Group, and your Arc-enabled Kubernetes cluster for your deployment.

Deploy

On the next page, you will be asked to provide a cluster name, a product (please select Traefik Hub API Management), a license token and a number of replicas.

License Token

if you do not have a license token, visit Create New Gateway to create your new gateway.
- Enter your gateway name
- Set the platform to "Kubernetes"
- Copy the provided gateway token

tip

If you don't yet have a Traefik Hub account, please reach out to our sales team.

Return to the Azure marketplace portal. Paste your Traefik Hub license token into the designated field. Click Next to review your deployment configuration. After verifying your configuration, click Create to begin the deployment process.
The deployment will start and you will be able to see the progress in the Azure portal.
Once the deployment is complete, you can head over to the Traefik Hub Online Dashboard to see your new API Management Gateway marked as Online.

Deployment Complete

Online

Deploy and Test an API

Enable CrossNamespace references

We need to upgrade the Traefik deployment to allow CrossNamespace references because we will have our API in the apps namespace and our traefik deployment will live in the traefik namespace.

To do this, we can use the Azure CLI & k8s-extension.

First, install the k8s-extension.

az extension add --name k8s-extension

Then, update the Traefik deployment to allow CrossNamespace references.

az k8s-extension update -n traefik -c <cluster-name> -t connectedClusters -g <resource-group> --config providers.kubernetesCRD.allowCrossNamespace=true

You can verify the change by running the following command:

kubectl describe deployment traefik -n traefik | grep allowCrossNamespace

If the output contains the following line, the change has been applied successfully:

--providers.kubernetescrd.allowCrossNamespace=true

Now, lets deploy the sample weather API and enable the Traefik Hub API Management features.

Step 1: Create Namespace and Deploy Sample API

First, create a namespace for your API and deploy the sample weather API:

kubectl create namespace apps
kubectl apply -f https://raw.githubusercontent.com/traefik/hub/main/src/manifests/weather-app.yaml

The following response will be displayed after running the above command:

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-openappispec created

Step 2: Create API Resource

Before proceeding with creating the API resource, we need to obtain the external IP address of your Traefik load balancer. This IP will be used to configure the IngressRoutes for both the API and the API Portal.

Run the following command to get your load balancer IP:

export EXTERNAL_IP=$(kubectl get svc -n traefik traefik \
  -o jsonpath='{.status.loadBalancer.ingress[0].ip}')
echo "Use EXTERNAL_IP=${EXTERNAL_IP}"

Next, create a new API resource with a Traefik IngressRoute to expose it by running the command below:

cat <<EOF | kubectl apply -f -
---
apiVersion: hub.traefik.io/v1alpha1
kind: API
metadata:
  name: weather-api
  namespace: apps
spec:
  openApiSpec:
    path: /openapi.yaml
    override:
      servers:
        - url: "https://$EXTERNAL_IP/weather"  # Replace $EXTERNAL_IP with your load balancer IP
---
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: api-ingressroute
  namespace: apps
  annotations:
    hub.traefik.io/api: weather-api@apps
spec:
  entryPoints:
    - websecure
  routes:
    - match: Host(\`$EXTERNAL_IP\`) && PathPrefix(\`/weather\`)  # Replace $EXTERNAL_IP with your load balancer IP
      kind: Rule
      services:
        - name: weather-app
          port: 3000
      middlewares:
        - name: stripprefix-weather
EOF

info

Since we're using an IP address over HTTPS, you'll see a browser warning about an invalid certificate (Traefik serves a self-signed cert by default). This is expected in a demo. For production, enable an ACME resolver to get real certificates (see Let's Encrypt TLS docs), or use a free domain like https://traefik.me for valid certs.

If you head over to the traefik online dashboard, you should see this API:

Verify API creation via Hub Online Dashboard

You can also verify this within your cluster by running the following command:

kubectl get apis -n apps

Step 3: Create API Portal Resource

Create the API Portal that will serve as the interface for managing your APIs:

cat <<EOF | kubectl apply -f -
apiVersion: hub.traefik.io/v1alpha1
kind: APIPortal
metadata:
  name: weather-portal
  namespace: apps
spec:
  title: "Weather API Portal"
  description: "Developer Portal for Weather APIs"
  trustedUrls:
    - https://$EXTERNAL_IP/portal # Replace EXTERNAL_IP with your load balancer IP
EOF

info

Replace EXTERNAL_IP with your actual load balancer IP address.

The following response will be displayed after running the above command:

apiportal.hub.traefik.io/weather-portal created

Step 4: Expose the API Portal

Configure an IngressRoute to expose the API Portal:

cat <<EOF | kubectl apply -f -
---
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: weather-portal
  namespace: apps
  annotations:
    # Link this IngressRoute to your API Portal (format: <portalName>@<portalNamespace>)
    hub.traefik.io/api-portal: weather-portal@apps
spec:
  entryPoints:
    - websecure
  routes:
    - match: Host(\`$EXTERNAL_IP\`) && PathPrefix(\`/portal\`)
      kind: Rule
      middlewares:
      - name: stripprefix-weather
        namespace: apps
      services:
        - name: apiportal
          namespace: traefik
          port: 9903
EOF

The following response will be displayed after running the above command:

ingressroute.traefik.io/weather-portal configured

To access the API Portal, you need to create users and groups in the Traefik Hub Dashboard:

Log in to the Traefik Hub Dashboard
Navigate to the Groups section
Create a new group called "developers":
- Select "Add group"
- Enter "developers" as the group name
- Select "Create"
Create a new user:
- Navigate to the Users section
- Fill in the required fields (First name, Last name, Email, Company)
- Select the "developers" group
- Select "Save"
- After creating a new user, you'll be prompted to set a password. Select the link displayed and paste it in your browser to set a new password. Remember these credentials as they will be used to access the API Portal.

Before we can route requests correctly to our application and API portal, we must remove the /portal prefix (and any other API prefixes) from incoming URLs. The stripPrefix middleware handles this by stripping these path segments so the backend service sees clean routes.

To apply this change, run:

cat <<EOF | kubectl apply -f -
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: stripprefix-weather
  namespace: apps
spec:
  stripPrefix:
    prefixes:
      - /portal
      - /weather
      - /api-key
      - /simple
      - /complex
      - /weather-v1-wrr
      - /weather-v1
      - /weather-multi-versions
      - /no-auth
      - /basic-auth
      - /api-key
      - /forecast
EOF

Step 5: Create API Plan

For the APIPlan feature to work, you need to deploy and configure Redis in your cluster and Traefik deployment. You can do this by following these steps:

info

These commands install Redis for demo purposes. For production deployments, refer to the Redis production installation guide: https://doc.traefik.io/traefik-hub/api-gateway/expose/middleware/distributed-rate-limit

Install the Redis via the Helm chart

helm install redis oci://registry-1.docker.io/bitnamicharts/redis -n traefik --wait

info

The installation process can take a few seconds.

Export your Redis instance password:

export REDIS_PASSWORD=$(kubectl get secret --namespace traefik redis -o jsonpath="{.data.redis-password}" | base64 -d)

Finally, upgrade your Traefik deployment to include Redis:

az k8s-extension update -y -n traefik -c <cluster-name> -t connectedClusters -g <resource-group> --config hub.redis.endpoints=redis-master.traefik.svc.cluster.local:6379 --config hub.redis.password=${REDIS_PASSWORD}

You can verify the change by running the following command:

kubectl describe deployment traefik -n traefik | grep redis

If the output contains the following lines, the change has been applied successfully:

--hub.redis.endpoints=redis-master.traefik.svc.cluster.local:6379
--hub.redis.password=<YOUR_REDIS_PASSWORD>

Next, create an API plan for the weather API:

cat <<EOF | kubectl apply -f -
apiVersion: hub.traefik.io/v1alpha1
kind: APIPlan
metadata:
  name: weather-api-plans
  namespace: apps
spec:
  title: "Weather API Plans"
  description: "Plans for accessing the Weather API"
  rateLimit:
    limit: 10
    period: 1s
  quota:
    limit: 1000
    period: 720h  # 30 days
EOF

The following response will be displayed after running the above command:

apiplan.hub.traefik.io/weather-api-plans created

Step 6: Create API Catalog Item

Create an APICatalogItem to make the API visible in the portal:

cat <<EOF | kubectl apply -f -
apiVersion: hub.traefik.io/v1alpha1
kind: APICatalogItem
metadata:
  name: weather-api-catalog
  namespace: apps
spec:
  groups:
    - developers
  apis:
    - name: weather-api # the name of the API deployed earlier
  apiPlan:
    name: weather-api-plans # name of the API plan deployed earlier
EOF

The following response will be displayed after running the above command:

apicatalogitem.hub.traefik.io/weather-api-catalog created

With this APICatalogItem, the weather API will only be visible to users in the developers group in the API portal.

Step 7: Create an Application in API Portal

Access the API Portal at http://$EXTERNAL_IP/portal/
Log in with the credentials created in the previous section

info
Your browser will warn about an untrusted certificate—but that's expected, and you can safely "proceed anyway" to your dashboard.
Navigate to the Applications section
Create a new application named "weather-app"
generate an application ID by clicking on "Generate" beside the application ID field
Note down the generated appId (you'll need this for a managed subscription)

Step 8: Create Managed Subscription

cat <<EOF | kubectl apply -f -
apiVersion: hub.traefik.io/v1alpha1
kind: ManagedSubscription
metadata:
  name: weather-api-subscription
  namespace: apps
spec:
  applications:
    - appId: "REPLACE-WITH-YOUR-APP-ID"  # Use the appId generated in the API portal
  apis:
    - name: weather-api
  apiPlan:
    name: weather-api-plans
EOF

The following response will be displayed after running the above command:

managedsubscription.hub.traefik.io/weather-api-subscription created

Verify API Management Features

Step 1: Access the API Portal

Open http://$EXTERNAL_IP/portal in your browser
Log in with the credentials created earlier
In the API Catalog section you can view the OpenAPI specification of your API. You can also explore API plans, managed subscription, endpoints, request/response schemas, and examples

API Portal

Step 2: View API Documentation

In the API Catalog section you can view the OpenAPI specification of your API. You can also explore API plans, managed subscription, endpoints, request/response schemas, and examples

Step 3: Test the API

Use the built-in UI to test the API endpoints
Generate an API key for your application from the API Portal
Use the API key in your requests:

Test The API in the APIPortal

Step 4: Verify API Plans and Subscriptions

You can also verify your API plans and subscription from the Traefik Hub Online Dashboard.

Verify From Traefik Hub Online Dashboard

That's it! You've successfully deployed Traefik Hub API Management in your Azure Arc-enabled Kubernetes cluster and verified its functionality with a sample API.

Next Steps

For production-ready Redis deployment and advanced options, see the Distribute Rate Limit docs.
To obtain valid TLS certificates, configure an ACME resolver with Let's Encrypt: see Let's Encrypt TLS docs.
Explore additional features and configuration patterns in the Traefik Hub documentation.

Introduction​

Prerequisites​

Deploy Traefik Hub API Management on Azure Arc from Azure Marketplace​

Deploy and Test an API​

Enable CrossNamespace references​

Step 1: Create Namespace and Deploy Sample API​

Step 2: Create API Resource​

Step 3: Create API Portal Resource​

Step 4: Expose the API Portal​

Step 5: Create API Plan​

Step 6: Create API Catalog Item​

Step 7: Create an Application in API Portal​

Step 8: Create Managed Subscription​

Verify API Management Features​

Step 1: Access the API Portal​

Step 2: View API Documentation​

Step 3: Test the API​

Step 4: Verify API Plans and Subscriptions​

Next Steps​

Introduction

Prerequisites

Deploy Traefik Hub API Management on Azure Arc from Azure Marketplace

Deploy and Test an API

Enable CrossNamespace references

Step 1: Create Namespace and Deploy Sample API

Step 2: Create API Resource

Step 3: Create API Portal Resource

Step 4: Expose the API Portal

Step 5: Create API Plan

Step 6: Create API Catalog Item

Step 7: Create an Application in API Portal

Step 8: Create Managed Subscription

Verify API Management Features

Step 1: Access the API Portal

Step 2: View API Documentation

Step 3: Test the API

Step 4: Verify API Plans and Subscriptions

Next Steps