Skip to main content

Install vs Routing Configuration

Terminology Update

In Traefik Hub documentation, we now refer to Static Configuration as Install Configuration and Dynamic Configuration as Routing Configuration. This change better reflects the purpose of each configuration type.

Traefik Hub's configuration is the cornerstone of how it operates and routes traffic. Traefik (the proxy at the heart of Traefik Hub) uses a declarative configuration model with two distinct types of configurations: Install and Routing. Understanding the difference between Install Configuration and Routing Configuration is key. In short, the Install Configuration defines Traefik's core settings that rarely change (how Traefik itself runs). In contrast, the Routing Configuration defines the routing rules and behaviors for your services that can change frequently. This separation allows Traefik to adjust routing on the fly without restarting, which is crucial for reliability and high availability

Install Configuration​

Install Configuration controls Traefik Hub's fundamental parameters that are only read at startup (or during restarts). These settings include:

  • EntryPoints: The network endpoints (ports/protocols) that Traefik will listen on for incoming requests. For example, you might define entrypoints for HTTP (port 80) and HTTPS (port 443).
  • Providers: How Traefik discovers Routing Configuration. This could be Docker, Kubernetes, file, etc Enabling a provider in install configuration tells Traefik where to load routes from.
  • API/Dashboard: Handles whether the Traefik Hub API or web dashboard is enabled, and on which entrypoint (these are configured at startup).
  • Logging and Metrics: Global log level, access log settings, tracing, metrics, and other global observability settings.
  • TLS certificates and resolvers: Configuration for obtaining or providing certificates (For example, Let's Encrypt (ACME) resolvers) is part of install configuration. For instance, defining an ACME certificate resolver with email, storage file, and challenge type must be done in install configuration. (The certificates obtained at runtime are part of Routing Configuration, but the setup is install configuration.)
  • Other global settings: Such as default TLS options, or any flags that influence the behavior of the Traefik Hub process.

How to Define Install Configuration​

  1. File (YAML or TOML): Typically a traefik.yml/traefik.toml file or a Kubernetes ConfigMap. This file contains the configuration keys (entryPoints, providers, etc.). Traefik reads it on startup. For example, a YAML file might specify entrypoints and providers as below:
entryPoints:
  web:
    address: ":80"
  websecure:
    address: ":443"
api:
  dashboard: true       # Enable Traefik's dashboard
log:
  level: INFO           # Log level set to INFO
certificatesResolvers:
  letsencrypt:
    acme:
      email: "[email protected]"
      storage: acme.json
      httpChallenge:
        entryPoint: web

In the example above, we defined two entrypoints (web and websecure), enabeled the dashboard, set logging, and configure a LetsEncrypt resolver. These settings take effect only on startup (changes would require a restart).

  1. CLI Arguments: You can pass Install Configuration as command-line flags when launching Traefik. This is common in Docker Compose or Nomad. For example, the above file's settings could be passed via CLI:
traefik \
  --entryPoints.web.address=:80 \
  --entryPoints.websecure.address=:443 \
  --providers.docker=true \
  --api.dashboard=true \
  --log.level=INFO \
  --certificatesresolvers.letsencrypt.acme.email="[email protected]" \
  --certificatesresolvers.letsencrypt.acme.storage="acme.json" \
  --certificatesresolvers.letsencrypt.acme.httpChallenge.entryPoint=web

In the example above, Each --flag corresponds to an Install Configuration option. For instance, --entryPoints.web.address=:80 defines the same entrypoint as the YAML above.

  1. Helm Chart Values: When installing Traefik Hub via Helm, most Install Configuration is supplied in the values.yaml. The Helm chart translates these values into Traefik's Install Configuration. For example, in a Helm values file you might add:
helm upgrade traefik -n traefik \
  --version v34.4.0 \
  --set hub.token=traefik-hub-license \
  --set image.registry=ghcr.io \
  --set image.repository=traefik/traefik-hub \
  --set image.tag=v3.14.1 \
  --set ingressClass.enabled=false \
  --set ingressRoute.dashboard.enabled=true \
  --set ingressRoute.dashboard.matchRule='Host(`dashboard.docker.localhost`)' \
  --set ingressRoute.dashboard.entryPoints={web} \
  --set logs.general.level=INFO \
  --set ports.web.expose.default=true \
  --set ports.websecure.expose.default=true \
  --set providers.kubernetesCRD.enabled=true \
  --set metrics.otlp.http.enabled=true \
  --set="additionalArguments={--experimental.otlpLogs=true}" \
  traefik/traefik

These passes the desired settings to Traefik Hub. Helm also provides structured fields for common settings; for instance, enabling the dashboard or specific providers can often be done with specific values keys in the official chart.

info

Install Configuration is processed once at startup. If you need to change an Install Configuration parameter (like opening a new entrypoint or altering an ACME email), you must restart Traefik Hub for it to take effect. In practice, Install Configuration settings are infrequently changed after initial deployment, precisely to avoid unnecessary restarts.

Routing Configuration​

Routing Configuration controls everything about how Traefik Hub routes requests to your services. Unlike Install Configuration, Routing Configuration can change at runtime, and Traefik Hub will apply those changes without a restart. This is where you define the routes, middleware, services, and TLS certificates that actually handle traffic. Key elements managed via Routing Configuration include:

  • Routers: These define rules for matching incoming requests (e.g., hostnames, paths) and tie the request to a service.
  • Services: These define how to reach your backend applications (e.g., load balancer settings, server endpoints). A service can be a load balancer with one or many servers (container IPs, URLs, etc.).
  • Middlewares: These are optional request modifiers or filters (like authentication, rewriting, rate-limiting) that can be applied to routers. Routing Configuration lets you attach middleware to routers. Middlewares are available for both HTTP & TCP trraffic.
  • TLS certificates (dynamic): While the mechanism to obtain certs (ACME resolver) is Install Configuration, the certificates themselves and which domains they apply to are part of Routing Configuration. For instance, certificates fetched via Let's Encrypt or provided via a Certificate Kubernetes resource are loaded dynamically. You can add, remove, or renew certificates without restarting Traefik Hub.
info

If you use Traefik Hub for API Management, all the APIM CRDs are also part of the Routing Configuration.

How to Define Routing Configuration​

Routing Configuration is provided by providers at runtime. Traefik Hub can watch various sources (providers) for configuration changes. The Common methods include:

  1. File Provider (YAML/TOML): You can supply a separate Routing Configuration file. In Install Configuration, you'd enable the file provider (e.g. providers.file.filename=dynamic.yml or a directory). Traefik will load routes from that file and watch for changes. For example, a Routing Configuration YAML file might look like:
http:
  routers:
    my-router:
      rule: "Host(`example.com`)"
      entryPoints: ["web", "websecure"]
      service: my-service
      middlewares: ["https-redirect"]
  services:
    my-service:
      loadBalancer:
        servers:
          - url: "http://10.0.10.5:8080"
          - url: "http://10.0.10.6:8080"
  middlewares:
    https-redirect:
      redirectScheme:
        scheme: https
  1. Docker Labels (including Swarm mode): When using Docker or Docker Swarm, Traefik can use container labels as Routing Configuration. The Docker provider (enabled in Install Configuration) watches for containers with Traefik labels. For example, you might start a Docker container with:
labels:
  - "traefik.http.routers.app.rule=Host(`app.example.com`)"
  - "traefik.http.routers.app.entrypoints=websecure"
  - "traefik.http.routers.app.tls.certresolver=letsencrypt"
  - "traefik.http.services.app.loadbalancer.server.port=80"

These labels declare a router rule for app.example.com on the websecure entrypoint (HTTPS), using the letsencrypt cert resolver, and define a service that forwards to the container’s port 80. Traefik Hub will automatically create a router and service from these labels. In Docker Swarm, you attach similar labels to services in the stack file. As containers start/stop or labels change, Traefik Hub updates the configuration live.

  1. Kubernetes CRDs and Ingresses: In a Kubernetes environment, Traefik Hub uses Kubernetes as a provider. You can use Traefik's Custom Resource Definitions (CRDs) or standard Ingress resources to define Routing Configuration. For instance, using CRDs, an IngressRoute resource can define routes and services. Example using Traefik Kubernetes IngressRoute CRD:
apiVersion: traefik.containo.us/v1alpha1
kind: IngressRoute
metadata:
  name: my-app-route
  namespace: default
spec:
  entryPoints:
    - websecure
  routes:
    - match: Host(`app.example.com`) && PathPrefix(`/api`)
      kind: Rule
      services:
        - name: my-app-service
          port: 80
  tls:
    certResolver: letsencrypt

Here the CRD defines that requests to app.example.com/api on the websecure entrypoint should go to the Kubernetes service my-app-service:80, with TLS handled by "letsencrypt" resolver. Traefik Hub continuously watches these CRDs (and Kubernetes Ingresses if using those) and will update routing as they are added, modified, or removed. All of this happens without restarting Traefik, since the Kubernetes API serves as a Routing Configuration provider. You can find a list of all the available Kubernetes CRD resources here.

  1. Tags (Nomad, Consul Catalog): In certain providers like Nomad & Consul, Routing Configuration is provided via metadata tags. For example, in a Nomad job file you might have a service registration like:
service {
  name = "whoami-demo"
  provider = "nomad"
  port = "http"
  tags = [
    "traefik.http.routers.whoami.rule=Host(`whoami.nomad.localhost`)",
    "traefik.http.routers.whoami.service=whoami-demo",
    "traefik.http.services.whoami-demo.loadbalancer.server.port=8080"
  ]
}

These tags function like Docker labels: traefik.http.routers.whoami.rule=Host(`whoami.nomad.localhost`) defines a router rule and link it to a service with port 8080. When the Nomad job runs, Traefik (with Nomad provider enabled) will detect this and configure the route automatically. Changes in Nomad service tags or new deployments are picked up dynamically by Traefik.

  1. KV Stores: You can also use a Key-Value (KV) store—such as Consul, Etcd, or Redis—to provide Routing Configuration for Traefik Hub. When you enable a KV provider in the Install Configuration, Traefik automatically watches the specified KV store for changes. This approach can be especially useful in environments where sharing or updating configurations across multiple instances is important. As with any Routing Configuration source, Traefik applies KV updates in real time—no restarts required.

Below is a sample of how you might arrange a router, service, and middleware within a KV store. The exact key structure may vary slightly by provider, but it typically follows the same logical hierarchy you'd see in a file-based configuration:

KeyValue
traefik/http/routers/my-router/rule"Host(kv.example.com)"
traefik/http/routers/my-router/entryPoints/0"web"
traefik/http/routers/my-router/entryPoints/1"websecure"
traefik/http/routers/my-router/service"my-service"
traefik/http/services/my-service/loadBalancer/servers/0/url"http://10.0.10.5:8080"
traefik/http/services/my-service/loadBalancer/servers/1/url"http://10.0.10.6:8080"
traefik/http/middlewares/https-redirect/redirectScheme/scheme"https"

Conclusion​

Install vs Routing Configuration separation means you can keep Traefik Hub's core running stable (Install Configuration) while flexibly adapting the routing layer (Routing Configuration) in real time. This leads to a highly available setup: your setup is never down, even during reconfiguration or upgrades.

Related Content​