Skip to content

Installation and Configuration


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 just a regular preconfigured instance. You may also use an existing Traefik Proxy instance.

If you want to modify an existing installation and/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.9 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 HelmChart

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


  • controllerDeployment.traefik.metricsURL Defines the URL of the Traefik Proxy entrypoint 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 EntryPoint 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/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 \

Securing non Kubernetes Traefik Hub Agent using mTLS

The easiest 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 host name in that certificate. Moreover, in insecure mode, the Hub Agent generates self-sign certificate to answer Traefik Proxy HTTPS requests. In short, 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 EntryPoint 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

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