Installation and Configuration

How to install and configure the Traefik Hub Agent.

Stand-Alone¶

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 Agent Install With Helm Chart¶

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

Controller¶

• 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}"

Tunnel¶

• 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 HUB_TOKEN=XXXXX
export INGRESS_CLASS_NAME=my-ingress-class
export METRICS_URL=http://my-traefik-host.my-traefik-ns.svc.cluster.local:9100/metrics
export TUNNEL_HOST=my-traefik-host.my-traefik-ns.svc.cluster.local
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 \
--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
metadata:
  name: hub-agent
  namespace: traefik
stringData:
  token: myTokenString

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

---
apiVersion: v1
kind: Service
metadata:
  name: traefik-hub
  namespace: traefik
  labels:
    app: traefik
    app.kubernetes.io/name: traefik
spec:
  type: ClusterIP
  selector:
    app.kubernetes.io/name: traefik
  ports:
  - 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 tokenSecretRef.name=hub-agent --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

entryPoints:
  metrics:
   address: ":9100/tcp"
metrics:
  prometheus:
    entryPoint: metrics
    addRoutersLabels: true
providers:
  kubernetesIngress:
    ingressClass: traefik
experimental:
  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

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

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

version: "3.9"

services:
  # Start the agent with the latest version
  hub-agent:
    image: ghcr.io/traefik/hub-agent-traefik:experimental
    pull_policy: always
    container_name: hub-agent
    restart: "on-failure"
    command:
      - run
      - --hub.token=XXX
      - --auth-server.advertise-url=http://hub-agent
      - --traefik.host=traefik
      # Path to the certificate authority which signed TLS credentials.
      - --traefik.tls.ca=/certs/ca.pem
      # 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
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./certs:/certs
    depends_on:
      - traefik

  # Start Traefik with the latest version
  traefik:
    image: traefik:v2.9
    container_name: traefik
    command:
      - --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.
      - --traefik.tls.ca=/certs/ca.pem
      # 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
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./certs:/certs