Skip to main content

Install the Administration UI

This guide deploys the Administration UI for a Traefik Hub gateway on Kubernetes. Once deployed, you can view your gateway's routes, middlewares, services, and certificates in your browser.

Prerequisites​

  • A Traefik Hub gateway v3.21.0 or later, installed with the traefik/traefik Helm chart as the release traefik in the namespace traefik. If your release or namespace differs, adjust the manifest.
  • A gateway token that includes the ai-dashboard feature, stored in the secret traefik-hub-license under the key token. The gateway already uses this secret when you install it with the Helm value hub.token.
  • kubectl access to the cluster.

Run the following command to check that your token includes the ai-dashboard feature:

kubectl -n traefik get secret traefik-hub-license -o jsonpath='{.data.token}' \
  | base64 -d | cut -d. -f2 | base64 -d 2>/dev/null | grep -o ai-dashboard

The command prints ai-dashboard when your token includes the feature. If it prints nothing, contact the Traefik Labs team to enable the feature for your workspace. Without it, the Administration UI exits at startup with the error the dashboard requires the "ai-dashboard" feature in your license.

Step 1: Enable the gateway API​

The Administration UI reads your gateway's runtime configuration from the gateway API.

  1. Save the following as values.yaml:

    values.yaml
    api:
      insecure: true

  2. Upgrade the Helm release. The --reuse-values flag keeps your current values and applies only values.yaml:

    helm upgrade traefik traefik/traefik --namespace traefik --reuse-values --values values.yaml

The gateway now serves its API on port 8080, and the Helm chart doesn't publish that port outside the cluster. Any workload in the cluster that can reach that port can read your gateway's configuration, because the API has no authentication. The next step protects access to the API through the Administration UI.

Step 2: Protect the Administration UI​

Attach an authentication middleware to the Administration UI route before you expose it beyond a test environment. The following example uses BasicAuth. For production, use a middleware that matches your identity provider, such as OIDC.

  1. Generate a user entry and store it in a secret named admin-ui-basic-auth:

    kubectl -n traefik create secret generic admin-ui-basic-auth \
      --from-literal=users="$(htpasswd -nB admin)"

  2. Save the following middleware as admin-ui-auth.yaml:

    admin-ui-auth.yaml
    apiVersion: traefik.io/v1alpha1
    kind: Middleware
    metadata:
      name: admin-ui-auth
      namespace: traefik
    spec:
      basicAuth:
        secret: admin-ui-basic-auth
        removeHeader: true # Removes the credentials before the request reaches the Administration UI.

  3. Apply it:

    kubectl apply -f admin-ui-auth.yaml

Step 3: Deploy the Administration UI​

  1. Save the following manifest as admin-ui.yaml:

    admin-ui.yaml
    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: traefik-hub-admin-ui
      namespace: traefik # Replace with the namespace of your gateway. Change every namespace in this file.
    spec:
      replicas: 1
      selector:
        matchLabels:
          app.kubernetes.io/name: traefik-hub-admin-ui
      template:
        metadata:
          labels:
            app.kubernetes.io/name: traefik-hub-admin-ui
        spec:
          automountServiceAccountToken: false
          containers:
            - name: admin-ui
              image: ghcr.io/traefik/traefik-hub-dashboard:v3.21.2
              args:
                - serve
              env:
                - name: TRAEFIK_HUB_DASHBOARD_TOKEN
                  valueFrom:
                    secretKeyRef:
                      name: traefik-hub-license
                      key: token
                - name: TRAEFIK_HUB_DASHBOARD_API_URL
                  value: http://traefik-hub-api.traefik.svc:8080/api
                - name: HOME # The GitOps feature runs git, which writes its configuration and clone under $HOME.
                  value: /tmp
              ports:
                - name: http
                  containerPort: 8080
              readinessProbe:
                httpGet:
                  path: /readyz
                  port: http
                periodSeconds: 10
              livenessProbe:
                httpGet:
                  path: /healthz
                  port: http
                periodSeconds: 30
              securityContext:
                runAsNonRoot: true
                runAsUser: 65532
                readOnlyRootFilesystem: true
                allowPrivilegeEscalation: false
                capabilities:
                  drop: ["ALL"]
              resources:
                requests:
                  cpu: 20m
                  memory: 64Mi
                limits:
                  memory: 512Mi
              volumeMounts:
                - name: tmp
                  mountPath: /tmp
          volumes:
            - name: tmp
              emptyDir: {}
    ---
    apiVersion: v1
    kind: Service
    metadata:
      name: traefik-hub-admin-ui
      namespace: traefik
    spec:
      selector:
        app.kubernetes.io/name: traefik-hub-admin-ui
      ports:
        - name: http
          port: 80
          targetPort: http
    ---
    apiVersion: v1
    kind: Service
    metadata:
      name: traefik-hub-api # The gateway API on the traefik entrypoint, reachable only inside the cluster.
      namespace: traefik
    spec:
      selector:
        app.kubernetes.io/name: traefik
        app.kubernetes.io/instance: traefik-traefik # Replace with <release>-<namespace> of your Helm release.
      ports:
        - name: traefik
          port: 8080
          targetPort: traefik
    ---
    apiVersion: traefik.io/v1alpha1
    kind: IngressRoute
    metadata:
      name: traefik-hub-admin-ui
      namespace: traefik
    spec:
      entryPoints:
        - websecure
      routes:
        - kind: Rule
          match: Host(`admin.example.com`) # Replace with the hostname of the Administration UI.
          middlewares:
            - name: admin-ui-auth # Replace with the name of your authentication middleware.
          services:
            - name: traefik-hub-admin-ui
              port: 80

  2. Replace admin.example.com with the hostname for the Administration UI.

  3. Replace admin-ui-auth with the name of your authentication middleware if you didn't use the one from step 2.

  4. If your gateway runs in another namespace or your Helm release has another name, change every namespace: traefik and the app.kubernetes.io/instance label of the traefik-hub-api service. The label value is <release>-<namespace>.

  5. Apply the manifest and wait for the traefik-hub-admin-ui deployment:

    kubectl apply -f admin-ui.yaml
    kubectl -n traefik rollout status deploy/traefik-hub-admin-ui

The manifest sets only the required settings. For every other setting, see the Administration UI configuration reference.

Step 4: Open the Administration UI​

Open https://<your Administration UI hostname>, and sign in if your authentication middleware asks you to.

The Administration UI is now deployed. The Overview page displays the routers, entrypoints, and providers that your gateway has loaded.

Troubleshooting​

The pod exits with a token error

Error: The pod restarts, and its log contains the dashboard requires the "ai-dashboard" feature in your license.

Cause: The token in the traefik-hub-license secret doesn't include the ai-dashboard feature.

Solution: Run the command in Prerequisites. If it prints nothing, contact the Traefik Labs team to enable the feature, update the token in the secret, and restart the traefik-hub-admin-ui deployment.

The pages show 404 errors

Error: Requests to /api/overview return 404 with the message Traefik Hub API responded with status 404.

Cause: The gateway answers on port 8080, but the gateway API isn't enabled.

Solution: Add api.insecure: true to the Helm values of your gateway, and run the helm upgrade command from step 1.

The pages show 502 errors

Error: Requests to /api/overview return 502 with the message Unable to reach the Traefik Hub API.

Cause: The Administration UI can't reach the gateway API. Without GitOps, Kubernetes still marks the pod as ready, so the deployment looks healthy. With GitOps, the pod doesn't become ready, because the Administration UI calls the gateway API while it loads your repository at startup.

Solution: Run kubectl -n traefik get endpointslices -l kubernetes.io/service-name=traefik-hub-api. If the ENDPOINTS column doesn't list a pod address, the traefik-hub-api service selects no pods. Correct its app.kubernetes.io/instance label as described in step 3.

Next steps​