Skip to content

Installation and Configuration

Old documentation for Hub v1

How to install and configure the Traefik Hub Agent.


The easiest way to install the agent is to follow the instructions provided in the Traefik Hub UI. The Traefik Hub Agent default installation uses a dedicated Traefik Proxy instance deployed during the installation process.

This dedicated Traefik Proxy instance is a preconfigured instance. You may also use an existing Traefik Proxy instance.

If you want to modify an existing installation or customize the agent installation, you have to perform the operations listed below.

Using an Existing Traefik Proxy

To use an existing Traefik Proxy instance, you may need to configure both Traefik Proxy and the Traefik Hub Agent.

Make sure you are using Traefik Proxy v2.10 or later and follow these steps:

  • Activate the Traefik Hub Provider and customize the configuration according to your needs
  • Restart Traefik Proxy to apply the modifications
  • Update the Traefik Hub Agent accordingly

Traefik Hub Agents

There is a specific Traefik Hub Agent for Kubernetes, and non-Kubernetes Agent. The Kubernetes Agent can be installed via a Helm Chart.

Traefik Hub Agent Install With Helm Chart

The Traefik Hub Agent needs to reach Traefik Proxy using the following arguments:


  • controllerDeployment.traefik.metricsURL Defines the URL of the Traefik Proxy entry point that exposes metrics: This allows the Traefik Hub Agent to fetch services metrics. Those metrics will be available in your Traefik Hub Dashboard.
  • controllerDeployment.args This specifies custom arguments to the Hub Agent Kubernetes Controller command. It is useful to defines a specific IngressClass: --set controllerDeployment.args="{--ingress-class-name=my-ingress-class}"


  • tunnelDeployment.traefik.tunnelHost This host is used by Traefik Hub Agent to create tunnels between your Traefik Proxy and the Traefik Hub Platform. Those tunnels allow you to expose securely services.
  • tunnelDeployment.traefik.tunnelPort The port of the Traefik Proxy traefikhub-tunl entry point dedicated to the Hub tunnel is, by default, 9901 (see more in Traefik Proxy Docs).
export INGRESS_CLASS_NAME=my-ingress-class
export TUNNEL_PORT=9901

helm upgrade --install hub-agent traefik/hub-agent --namespace hub-agent --create-namespace \
  --set token="${HUB_TOKEN}" \
  --set controllerDeployment.traefik.metricsURL="${METRICS_URL}" \
  --set controllerDeployment.args="{--ingress-class-name=${INGRESS_CLASS_NAME}}" \
  --set tunnelDeployment.traefik.tunnelHost=${TUNNEL_HOST} \
  --set tunnelDeployment.traefik.tunnelPort=${TUNNEL_PORT}
--entrypoints.metrics.address=:9100/tcp \
--metrics.prometheus.entrypoint=metrics \
--metrics.prometheus.addRoutersLabels=true \
--providers.kubernetesingress.ingressclass=my-ingress-class \
--experimental.hub \

Traefik Hub Agent GitOps install

Since v1.2.2, you may use the Helm chart to generate YAML for your Git repository managed with FluxCD, ArgoCD or other GitOps tools.

First, you can put your Traefik Hub token into a Secret.

See the following example, made to work with a Traefik Proxy already deployed in traefik namespace:

apiVersion: v1
kind: Secret
type: Opaque
  name: hub-agent
  namespace: traefik
  token: myTokenString

Second, you will need an internal service to expose Traefik Proxy API to the Hub Agent.

apiVersion: v1
kind: Service
  name: traefik-hub
  namespace: traefik
    app: traefik traefik
  type: ClusterIP
  selector: traefik
  - port: 9100
    name: "metrics"
    targetPort: metrics
    protocol: TCP
  - port: 9901
    name: "traefikhub-tunl"
    targetPort: traefikhub-tunl
    protocol: TCP

Now, you may generate the YAML for Traefik Hub, using this Service name:

export METRICS_URL=http://traefik-hub.traefik.svc.cluster.local:9100/metrics
export TUNNEL_HOST=traefik-hub.traefik.svc.cluster.local
export TUNNEL_PORT=9901
export INGRESS_CLASS_NAME=traefik
helm template hub-agent-on-my-cluster --namespace traefik \
  --set --set tokenSecretRef.key=token \
  --set controllerDeployment.traefik.metricsURL="${METRICS_URL}" \
  --set controllerDeployment.args="{--ingress-class-name=${INGRESS_CLASS_NAME}}" \
  --set tunnelDeployment.traefik.tunnelHost=${TUNNEL_HOST} \
  --set tunnelDeployment.traefik.tunnelPort=${TUNNEL_PORT} \
  --set withoutHelmLabels=true --include-crds traefik/hub-agent
   address: ":9100/tcp"
    entryPoint: metrics
    addRoutersLabels: true
    ingressClass: traefik
  hub: true
hub: {}

All available options are described in the values file of the Helm Chart.

Securing non Kubernetes Traefik Hub Agent using mTLS

The most effortless way to start the Traefik Hub Agent is to use the --traefik.tls.insecure=true option.

This configuration means that the TLS client accepts any certificate presented by the server and any hostname in that certificate. Moreover, in insecure mode, the Hub Agent generates self-signed certificates to answer Traefik Proxy HTTPS requests.

The connection itself is secure, but neither the identity of the server nor the identity of the client is verified.

Indeed, Traefik Proxy exposes an entry point for the Traefik Hub Agent; therefore, you may want to secure it more strictly. To do so, you need to configure a mutual TLS connection using:

  • A Certificate Authority
  • A public certificate
  • A private key on both Traefik Proxy and the Traefik Hub Agent

Mutual TLS (mTLS) Certificates Management

Traefik hub does not generate any of the certificates used in mTLS, they have to be created beforehand.

On the Traefik Proxy side, please follow the instructions provided in the documentation.

On the Traefik Hub Agent side, set, traefik.tls.cert, and traefik.tls.key.

Certificate Domain

The certificate must be valid for the agent.traefik domain.

version: "3.9"

  # Start the agent with the latest version
    pull_policy: always
    container_name: hub-agent
    restart: "on-failure"
      - run
      - --hub.token=XXX
      - --auth-server.advertise-url=http://hub-agent
      # Path to the certificate authority which signed TLS credentials.
      # Path to the certificate (must have agent.traefik domain name) used to communicate with Traefik Proxy.
      - --traefik.tls.cert=/certs/agent.traefik-client.pem
      # Path to the key used to communicate with Traefik Proxy.
      - --traefik.tls.key=/certs/agent.traefik-client-key.pem
      - /var/run/docker.sock:/var/run/docker.sock
      - ./certs:/certs
      - traefik

  # Start Traefik with the latest version
    image: traefik:v2.9
    container_name: traefik
      - --providers.docker
      # Enable Hub communication (open the port 9900 and 9901 by default)
      - --experimental.hub=true
      - --metrics.prometheus.addrouterslabels=true
      # Path to the certificate authority which signed TLS credentials.
      # Path to the certificate (must have proxy.traefik domain name) used to communicate with Traefik Hub Agent.
      - --traefik.tls.cert=/certs/proxy.traefik-client.pem
      # Path to the key used to communicate with Traefik Hub Agent.
      - --traefik.tls.key=/certs/proxy.traefik-client-key.pem
      - /var/run/docker.sock:/var/run/docker.sock
      - ./certs:/certs