Skip to main content

Install vs Routing Configuration

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: static (install) and dynamic (routing). Understanding the difference between static and dynamic configuration is key. In short, the static configuration defines Traefik’s core settings that rarely change (how Traefik itself runs). In contrast, the dynamic 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

Static Configuration (Install)​

Static 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 dynamic configuration. This could be Docker, Kubernetes, file, etc. Enabling a provider in static config 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 static because you configure them on 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 static. For instance, defining an ACME certificate resolver with email, storage file, and challenge type must be done in static config. (The certificates obtained at runtime are part of dynamic config, but the setup is static.)
  • Other global settings: Such as default TLS options, or any flags that influence the behavior of the Traefik Hub process.

How to Define Static Configuration​

  1. File (YAML or TOML): Typically a traefik.yml/traefik.toml file or a Kubernetes ConfigMap. This file contains the static keys (entryPoints, providers, etc.). Traefik reads it on startup. For example, a YAML static 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 static config 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 a static 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 static configuration is supplied in the values.yaml. The Helm chart translates these values into Traefik’s static config. 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 static 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

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

Dynamic Configuration (Routing)​

Dynamic configuration controls everything about how Traefik Hub routes requests to your services. Unlike static config, dynamic config 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 dynamic config 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. Dynamic config 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 static, the certificates themselves and which domains they apply to are part of dynamic 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 dynamic configuration.

How to Define Dynamic Configuration​

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

  1. File Provider (YAML/TOML): You can supply a separate dynamic configuration file. In static config, 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 dynamic 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 dynamic config. The Docker provider (enabled in static config) 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 dynamic config. 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 dynamic 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, dynamic 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 dynamic configuration for Traefik Hub. When you enable a KV provider in the static 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 dynamic 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​

Static vs Dynamic separation means you can keep Traefik Hub’s core running stable (static part) while flexibly adapting the routing layer (dynamic part) in real time. This leads to a highly available setup: your setup is almost never down, even during reconfiguration or upgrades.

Related Content​