diff --git a/docs/content/contributing/documentation.md b/docs/content/contributing/documentation.md index a57e4c695..ba0c22f8e 100644 --- a/docs/content/contributing/documentation.md +++ b/docs/content/contributing/documentation.md @@ -15,7 +15,7 @@ Let's see how. ### General -This [documentation](../../ "Link to the official Traefik documentation") is built with [MkDocs](https://mkdocs.org/ "Link to the website of MkDocs"). +This [documentation](../index.md "Link to the official Traefik documentation") is built with [MkDocs](https://mkdocs.org/ "Link to the website of MkDocs"). ### Method 1: `Docker` and `make` diff --git a/docs/content/getting-started/faq.md b/docs/content/getting-started/faq.md index 83622b896..a64e04186 100644 --- a/docs/content/getting-started/faq.md +++ b/docs/content/getting-started/faq.md @@ -12,10 +12,10 @@ and while the documentation often demonstrates configuration options through fil the core feature of Traefik is its dynamic configurability, directly reacting to changes from providers over time. -Notably, a part of the configuration is [static](../configuration-overview/#the-static-configuration), +Notably, a part of the configuration is [static](./configuration-overview.md#the-static-configuration), and can be provided by a file on startup, whereas various providers, such as the file provider, -contribute dynamically all along the traefik instance lifetime to its [dynamic configuration](../configuration-overview/#the-dynamic-configuration) changes. +contribute dynamically all along the traefik instance lifetime to its [dynamic configuration](./configuration-overview.md#the-dynamic-configuration) changes. In addition, the configuration englobes concepts such as the EntryPoint which can be seen as a listener on the Transport Layer (TCP), as apposed to the Router which is more about the Presentation (TLS) and Application layers (HTTP). diff --git a/docs/content/https/acme.md b/docs/content/https/acme.md index 53c6b0864..45b0e8e00 100644 --- a/docs/content/https/acme.md +++ b/docs/content/https/acme.md @@ -314,7 +314,7 @@ Use the `DNS-01` challenge to generate and renew ACME certificates by provisioni !!! warning "`CNAME` support" `CNAME` are supported (and sometimes even [encouraged](https://letsencrypt.org/2019/10/09/onboarding-your-customers-with-lets-encrypt-and-acme.html#the-advantages-of-a-cname)), - but there are a few cases where they can be [problematic](../../getting-started/faq/#why-does-lets-encrypt-wildcard-certificate-renewalgeneration-with-dns-challenge-fail). + but there are a few cases where they can be [problematic](../getting-started/faq.md#why-does-lets-encrypt-wildcard-certificate-renewalgeneration-with-dns-challenge-fail). If needed, `CNAME` support can be disabled with the following environment variable: diff --git a/docs/content/https/tls.md b/docs/content/https/tls.md index d8e1a0add..6b48e8e46 100644 --- a/docs/content/https/tls.md +++ b/docs/content/https/tls.md @@ -234,7 +234,7 @@ The TLS options allow one to configure some parameters of the TLS connection. !!! important "TLSOption in Kubernetes" - When using the [TLSOption resource](../../routing/providers/kubernetes-crd/#kind-tlsoption) in Kubernetes, one might setup a default set of options that, + When using the [TLSOption resource](../routing/providers/kubernetes-crd.md#kind-tlsoption) in Kubernetes, one might setup a default set of options that, if not explicitly overwritten, should apply to all ingresses. To achieve that, you'll have to create a TLSOption resource with the name `default`. There may exist only one TLSOption with the name `default` (across all namespaces) - otherwise they will be dropped. @@ -503,7 +503,7 @@ Traefik supports mutual authentication, through the `clientAuth` section. For authentication policies that require verification of the client certificate, the certificate authority for the certificates should be set in `clientAuth.caFiles`. -In Kubernetes environment, CA certificate can be set in `clientAuth.secretNames`. See [TLSOption resource](../../routing/providers/kubernetes-crd/#kind-tlsoption) for more details. +In Kubernetes environment, CA certificate can be set in `clientAuth.secretNames`. See [TLSOption resource](../routing/providers/kubernetes-crd.md#kind-tlsoption) for more details. The `clientAuth.clientAuthType` option governs the behaviour as follows: diff --git a/docs/content/migrate/v1-to-v2.md b/docs/content/migrate/v1-to-v2.md index 47d89b250..130d730e7 100644 --- a/docs/content/migrate/v1-to-v2.md +++ b/docs/content/migrate/v1-to-v2.md @@ -8,10 +8,10 @@ description: "Migrate from Traefik Proxy v1 to v2 and update all the necessary c How to Migrate from Traefik v1 to Traefik v2. {: .subtitle } -The version 2 of Traefik introduces a number of breaking changes, +The version 2 of Traefik introduced a number of breaking changes, which require one to update their configuration when they migrate from v1 to v2. -The goal of this page is to recapitulate all of these changes, and in particular to give examples, -feature by feature, of how the configuration looked like in v1, and how it now looks like in v2. + +For more information about the changes in Traefik v2, please refer to the [v2 documentation](https://doc.traefik.io/traefik/v2.11/migration/v1-to-v2/). !!! info "Migration Helper" @@ -22,1132 +22,3 @@ feature by feature, of how the configuration looked like in v1, and how it now l - convert `Ingress` to Traefik `IngressRoute` resources. - convert `acme.json` file from v1 to v2 format. - migrate the static configuration contained in the file `traefik.toml` to a Traefik v2 file. - -## Frontends and Backends Are Dead, Long Live Routers, Middlewares, and Services - -During the transition from v1 to v2, a number of internal pieces and components of Traefik were rewritten and reorganized. -As such, the combination of core notions such as frontends and backends has been replaced with the combination of [routers](../routing/routers/index.md), [services](../routing/services/index.md), and [middlewares](../middlewares/overview.md). - -Typically, a router replaces a frontend, and a service assumes the role of a backend, with each router referring to a service. -However, even though a backend was in charge of applying any desired modification on the fly to the incoming request, -the router defers that responsibility to another component. -Instead, a dedicated middleware is now defined for each kind of such modification. -Then any router can refer to an instance of the wanted middleware. - -!!! example "One frontend with basic auth and one backend, become one router, one service, and one basic auth middleware." - - !!! info "v1" - - ```yaml tab="Docker & Swarm" - labels: - - "traefik.frontend.rule=Host:test.localhost;PathPrefix:/test" - - "traefik.frontend.auth.basic.users=test:$$apr1$$H6uskkkW$$IgXLP6ewTrSuBkTrqE8wj/,test2:$$apr1$$d9hr9HBB$$4HxwgUir3HP4EsggP/QNo0" - ``` - - ```yaml tab="Ingress" - apiVersion: networking.k8s.io/v1beta1 - kind: Ingress - metadata: - name: traefik - namespace: kube-system - annotations: - kubernetes.io/ingress.class: traefik - traefik.ingress.kubernetes.io/rule-type: PathPrefix - spec: - rules: - - host: test.localhost - http: - paths: - - path: /test - backend: - serviceName: server0 - servicePort: 80 - - path: /test - backend: - serviceName: server1 - servicePort: 80 - ``` - - ```toml tab="File (TOML)" - [frontends] - [frontends.frontend1] - entryPoints = ["http"] - backend = "backend1" - - [frontends.frontend1.routes] - [frontends.frontend1.routes.route0] - rule = "Host:test.localhost" - [frontends.frontend1.routes.route0] - rule = "PathPrefix:/test" - - [frontends.frontend1.auth] - [frontends.frontend1.auth.basic] - users = [ - "test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/", - "test2:$apr1$d9hr9HBB$4HxwgUir3HP4EsggP/QNo0", - ] - - [backends] - [backends.backend1] - [backends.backend1.servers.server0] - url = "http://10.10.10.1:80" - [backends.backend1.servers.server1] - url = "http://10.10.10.2:80" - - [backends.backend1.loadBalancer] - method = "wrr" - ``` - - !!! info "v2" - - ```yaml tab="Docker & Swarm" - labels: - - "traefik.http.routers.router0.rule=Host(`test.localhost`) && PathPrefix(`/test`)" - - "traefik.http.routers.router0.middlewares=auth" - - "traefik.http.middlewares.auth.basicauth.users=test:$$apr1$$H6uskkkW$$IgXLP6ewTrSuBkTrqE8wj/,test2:$$apr1$$d9hr9HBB$$4HxwgUir3HP4EsggP/QNo0" - ``` - - ```yaml tab="IngressRoute" - # The definitions below require the definitions for the Middleware and IngressRoute kinds. - # https://doc.traefik.io/traefik/reference/dynamic-configuration/kubernetes-crd/#definitions - apiVersion: traefik.io/v1alpha1 - kind: Middleware - metadata: - name: basicauth - namespace: foo - - spec: - basicAuth: - users: - - test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/ - - test2:$apr1$d9hr9HBB$4HxwgUir3HP4EsggP/QNo0 - - --- - apiVersion: traefik.io/v1alpha1 - kind: IngressRoute - metadata: - name: ingressroutebar - - spec: - entryPoints: - - http - routes: - - match: Host(`test.localhost`) && PathPrefix(`/test`) - kind: Rule - services: - - name: server0 - port: 80 - - name: server1 - port: 80 - middlewares: - - name: basicauth - namespace: foo - ``` - - ```yaml tab="File (YAML)" - http: - routers: - router0: - rule: "Host(`test.localhost`) && PathPrefix(`/test`)" - service: my-service - middlewares: - - auth - - services: - my-service: - loadBalancer: - servers: - - url: http://10.10.10.1:80 - - url: http://10.10.10.2:80 - - middlewares: - auth: - basicAuth: - users: - - "test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/" - - "test2:$apr1$d9hr9HBB$4HxwgUir3HP4EsggP/QNo0" - ``` - - ```toml tab="File (TOML)" - [http.routers] - [http.routers.router0] - rule = "Host(`test.localhost`) && PathPrefix(`/test`)" - middlewares = ["auth"] - service = "my-service" - - [http.services] - [[http.services.my-service.loadBalancer.servers]] - url = "http://10.10.10.1:80" - [[http.services.my-service.loadBalancer.servers]] - url = "http://10.10.10.2:80" - - [http.middlewares] - [http.middlewares.auth.basicAuth] - users = [ - "test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/", - "test2:$apr1$d9hr9HBB$4HxwgUir3HP4EsggP/QNo0", - ] - ``` - -## TLS Configuration is Now Dynamic, per Router. - -TLS parameters used to be specified in the static configuration, as an entryPoint field. -With Traefik v2, a new dynamic TLS section at the root contains all the desired TLS configurations. -Then, a [router's TLS field](../routing/routers/index.md#tls) can refer to one of the [TLS configurations](../https/tls.md) defined at the root, hence defining the [TLS configuration](../https/tls.md) for that router. - -!!! example "TLS on websecure entryPoint becomes TLS option on Router-1" - - !!! info "v1" - - ```toml tab="File (TOML)" - # static configuration - [entryPoints] - [entryPoints.websecure] - address = ":443" - - [entryPoints.websecure.tls] - minVersion = "VersionTLS12" - cipherSuites = [ - "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256", - "TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384", - "TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256", - "TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256", - "TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256", - "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256", - ] - [[entryPoints.websecure.tls.certificates]] - certFile = "path/to/my.cert" - keyFile = "path/to/my.key" - ``` - - ```bash tab="CLI" - --entryPoints='Name:websecure Address::443 TLS:path/to/my.cert,path/to/my.key TLS.MinVersion:VersionTLS12 TLS.CipherSuites:TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256' - ``` - - !!! info "v2" - - ```yaml tab="File (YAML)" - http: - routers: - Router-1: - rule: "Host(`example.com`)" - service: service-id - # will terminate the TLS request - tls: - options: myTLSOptions - - tls: - certificates: - - certFile: /path/to/domain.cert - keyFile: /path/to/domain.key - options: - myTLSOptions: - minVersion: VersionTLS12 - cipherSuites: - - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 - - TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256 - - TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256 - - TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 - - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 - ``` - - ```toml tab="File (TOML)" - # dynamic configuration - [http.routers] - [http.routers.Router-1] - rule = "Host(`example.com`)" - service = "service-id" - # will terminate the TLS request - [http.routers.Router-1.tls] - options = "myTLSOptions" - - [[tls.certificates]] - certFile = "/path/to/domain.cert" - keyFile = "/path/to/domain.key" - - [tls.options] - [tls.options.myTLSOptions] - minVersion = "VersionTLS12" - cipherSuites = [ - "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256", - "TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384", - "TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256", - "TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256", - "TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256", - "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256", - ] - ``` - - ```yaml tab="IngressRoute" - # The definitions below require the definitions for the TLSOption and IngressRoute kinds. - # https://doc.traefik.io/traefik/reference/dynamic-configuration/kubernetes-crd/#definitions - apiVersion: traefik.io/v1alpha1 - kind: TLSOption - metadata: - name: mytlsoption - namespace: default - - spec: - minVersion: VersionTLS12 - cipherSuites: - - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 - - TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256 - - TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256 - - TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 - - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 - - --- - apiVersion: traefik.io/v1alpha1 - kind: IngressRoute - metadata: - name: ingressroutebar - - spec: - entryPoints: - - web - routes: - - match: Host(`example.com`) - kind: Rule - services: - - name: whoami - port: 80 - tls: - options: - name: mytlsoption - namespace: default - ``` - - ```yaml tab="Docker & Swarm" - labels: - # myTLSOptions must be defined by another provider, in this instance in the File Provider. - # see the cross provider section - - "traefik.http.routers.router0.tls.options=myTLSOptions@file" - ``` - -## HTTP to HTTPS Redirection is Now Configured on Routers - -Previously on Traefik v1, the redirection was applied on an entry point or on a frontend. -With Traefik v2 it is applied on an entry point or a [Router](../routing/routers/index.md). - -To apply a redirection: - -- on an entry point, the [HTTP redirection](../routing/entrypoints.md#redirection) has to be configured. -- on a router, one of the redirect middlewares, [RedirectRegex](../middlewares/http/redirectregex.md) or [RedirectScheme](../middlewares/http/redirectscheme.md), has to be configured and added to the router middlewares list. - -!!! example "Global HTTP to HTTPS redirection" - - !!! info "v1" - - ```toml tab="File (TOML)" - # static configuration - defaultEntryPoints = ["web", "websecure"] - - [entryPoints] - [entryPoints.web] - address = ":80" - [entryPoints.web.redirect] - entryPoint = "websecure" - - [entryPoints.websecure] - address = ":443" - [entryPoints.websecure.tls] - ``` - - ```bash tab="CLI" - --entryPoints=Name:web Address::80 Redirect.EntryPoint:websecure - --entryPoints='Name:websecure Address::443 TLS' - ``` - - !!! info "v2" - - ```yaml tab="File (YAML)" - # traefik.yml - ## static configuration - - entryPoints: - web: - address: ":80" - http: - redirections: - entrypoint: - to: websecure - scheme: https - - websecure: - address: ":443" - ``` - - ```toml tab="File (TOML)" - # traefik.toml - ## static configuration - - [entryPoints.web] - address = ":80" - [entryPoints.web.http.redirections.entryPoint] - to = "websecure" - scheme = "https" - - [entryPoints.websecure] - address = ":443" - ``` - - ```bash tab="CLI" - ## static configuration - - --entryPoints.web.address=:80 - --entryPoints.web.http.redirections.entrypoint.to=websecure - --entryPoints.web.http.redirections.entrypoint.scheme=https - --entryPoints.websecure.address=:443 - --providers.docker=true - ``` - -!!! example "HTTP to HTTPS redirection per domain" - - !!! info "v1" - - ```toml tab="File (TOML)" - [entryPoints] - [entryPoints.web] - address = ":80" - - [entryPoints.websecure] - address = ":443" - [entryPoints.websecure.tls] - - [file] - - [frontends] - [frontends.frontend1] - entryPoints = ["web", "websecure"] - [frontends.frontend1.routes] - [frontends.frontend1.routes.route0] - rule = "Host:example.net" - [frontends.frontend1.redirect] - entryPoint = "websecure" - ``` - - !!! info "v2" - - ```yaml tab="Docker & Swarm" - labels: - traefik.http.routers.app.rule: Host(`example.net`) - traefik.http.routers.app.entrypoints: web - traefik.http.routers.app.middlewares: https_redirect - - traefik.http.routers.appsecured.rule: Host(`example.net`) - traefik.http.routers.appsecured.entrypoints: websecure - traefik.http.routers.appsecured.tls: true - - traefik.http.middlewares.https_redirect.redirectscheme.scheme: https - traefik.http.middlewares.https_redirect.redirectscheme.permanent: true - ``` - - ```yaml tab="IngressRoute" - apiVersion: traefik.io/v1alpha1 - kind: IngressRoute - metadata: - name: http-redirect-ingressroute - - spec: - entryPoints: - - web - routes: - - match: Host(`example.net`) - kind: Rule - services: - - name: whoami - port: 80 - middlewares: - - name: https-redirect - - --- - apiVersion: traefik.io/v1alpha1 - kind: IngressRoute - metadata: - name: https-ingressroute - - spec: - entryPoints: - - websecure - routes: - - match: Host(`foo`) - kind: Rule - services: - - name: whoami - port: 80 - tls: {} - - --- - apiVersion: traefik.io/v1alpha1 - kind: Middleware - metadata: - name: https-redirect - spec: - redirectScheme: - scheme: https - permanent: true - ``` - - ```yaml tab="File (YAML)" - ## dynamic configuration - # dynamic-conf.yml - - http: - routers: - router0: - rule: "Host(`example.net`)" - entryPoints: - - web - middlewares: - - https_redirect - service: my-service - - router1: - rule: "Host(`example.net`)" - entryPoints: - - websecure - service: my-service - tls: {} - - middlewares: - https-redirect: - redirectScheme: - scheme: https - permanent: true - ``` - - ```toml tab="File (TOML)" - ## dynamic configuration - # dynamic-conf.toml - - [http.routers] - [http.routers.router0] - rule = "Host(`example.net`)" - service = "my-service" - entrypoints = ["web"] - middlewares = ["https_redirect"] - - [http.routers.router1] - rule = "Host(`example.net`)" - service = "my-service" - entrypoints = ["websecure"] - [http.routers.router1.tls] - - [http.middlewares] - [http.middlewares.https_redirect.redirectScheme] - scheme = "https" - permanent = true - ``` - -## Strip and Rewrite Path Prefixes - -With the new core notions of v2 (introduced earlier in the section -["Frontends and Backends Are Dead, Long Live Routers, Middlewares, and Services"](#frontends-and-backends-are-dead-long-live-routers-middlewares-and-services)), -transforming the URL path prefix of incoming requests is configured with [middlewares](../middlewares/overview.md), -after the routing step with [router rule `PathPrefix`](../routing/routers/index.md#rule). - -Use Case: Incoming requests to `http://example.org/admin` are forwarded to the webapplication "admin", -with the path `/admin` stripped, e.g. to `http://:/`. In this case, you must: - -- First, configure a router named `admin` with a rule matching at least the path prefix with the `PathPrefix` keyword, -- Then, define a middleware of type [`stripprefix`](../middlewares/http/stripprefix.md), which removes the prefix `/admin`, associated to the router `admin`. - -!!! example "Strip Path Prefix When Forwarding to Backend" - - !!! info "v1" - - ```yaml tab="Docker & Swarm" - labels: - - "traefik.frontend.rule=Host:example.org;PathPrefixStrip:/admin" - ``` - - ```yaml tab="Ingress" - apiVersion: networking.k8s.io/v1beta1 - kind: Ingress - metadata: - name: traefik - annotations: - kubernetes.io/ingress.class: traefik - traefik.ingress.kubernetes.io/rule-type: PathPrefixStrip - spec: - rules: - - host: example.org - http: - paths: - - path: /admin - backend: - serviceName: admin-svc - servicePort: admin - ``` - - ```toml tab="File (TOML)" - [frontends.admin] - [frontends.admin.routes.admin_1] - rule = "Host:example.org;PathPrefixStrip:/admin" - ``` - - !!! info "v2" - - ```yaml tab="Docker & Swarm" - labels: - - "traefik.http.routers.admin.rule=Host(`example.org`) && PathPrefix(`/admin`)" - - "traefik.http.routers.admin.middlewares=admin-stripprefix" - - "traefik.http.middlewares.admin-stripprefix.stripprefix.prefixes=/admin" - ``` - - ```yaml tab="IngressRoute" - --- - apiVersion: traefik.io/v1alpha1 - kind: IngressRoute - metadata: - name: http-redirect-ingressroute - namespace: admin-web - spec: - entryPoints: - - web - routes: - - match: Host(`example.org`) && PathPrefix(`/admin`) - kind: Rule - services: - - name: admin-svc - port: admin - middlewares: - - name: admin-stripprefix - --- - apiVersion: traefik.io/v1alpha1 - kind: Middleware - metadata: - name: admin-stripprefix - spec: - stripPrefix: - prefixes: - - /admin - ``` - - ```yaml tab="File (YAML)" - ## Dynamic Configuration - # dynamic-conf.yml - - # As YAML Configuration File - http: - routers: - admin: - service: admin-svc - middlewares: - - "admin-stripprefix" - rule: "Host(`example.org`) && PathPrefix(`/admin`)" - - middlewares: - admin-stripprefix: - stripPrefix: - prefixes: - - "/admin" - - # ... - ``` - - ```toml tab="File (TOML)" - ## Dynamic configuration - # dynamic-conf.toml - - [http.routers.router1] - rule = "Host(`example.org`) && PathPrefix(`/admin`)" - service = "admin-svc" - entrypoints = ["web"] - middlewares = ["admin-stripprefix"] - - [http.middlewares] - [http.middlewares.admin-stripprefix.stripPrefix] - prefixes = ["/admin"] - - # ... - ``` - -??? question "What About Other Path Transformations?" - - Instead of removing the path prefix with the [`stripprefix` middleware](../../middlewares/http/stripprefix/), you can also: - - - Add a path prefix with the [`addprefix` middleware](../../middlewares/http/addprefix/) - - Replace the complete path of the request with the [`replacepath` middleware](../../middlewares/http/replacepath/) - - ReplaceRewrite path using Regexp with the [`replacepathregex` middleware](../../middlewares/http/replacepathregex/) - - And a lot more on the [`HTTP middlewares` page](../../middlewares/http/overview/) - -## ACME (LetsEncrypt) - -[ACME](../https/acme.md) is now a certificate resolver (under a certificatesResolvers section) but remains in the static configuration. - -!!! example "ACME from provider to a specific Certificate Resolver" - - !!! info "v1" - - ```toml tab="File (TOML)" - # static configuration - defaultEntryPoints = ["websecure","web"] - - [entryPoints.web] - address = ":80" - [entryPoints.web.redirect] - entryPoint = "webs" - [entryPoints.websecure] - address = ":443" - [entryPoints.websecure.tls] - - [acme] - email = "your-email-here@example.com" - storage = "acme.json" - entryPoint = "websecure" - onHostRule = true - [acme.tlsChallenge] - ``` - - ```bash tab="CLI" - --defaultentrypoints=websecure,web - --entryPoints=Name:web Address::80 Redirect.EntryPoint:websecure - --entryPoints=Name:websecure Address::443 TLS - --acme.email=your-email-here@example.com - --acme.storage=acme.json - --acme.entryPoint=websecure - --acme.onHostRule=true - --acme.tlschallenge=true - ``` - - !!! info "v2" - - ```yaml tab="File (YAML)" - entryPoints: - web: - address: ":80" - - websecure: - address: ":443" - http: - tls: - certResolver: myresolver - - certificatesResolvers: - myresolver: - acme: - email: your-email@example.com - storage: acme.json - tlsChallenge: {} - ``` - - ```toml tab="File (TOML)" - # static configuration - [entryPoints] - [entryPoints.web] - address = ":80" - - [entryPoints.websecure] - address = ":443" - [entryPoints.websecure.http.tls] - certResolver = "myresolver" - - [certificatesResolvers.myresolver.acme] - email = "your-email@example.com" - storage = "acme.json" - [certificatesResolvers.myresolver.acme.tlsChallenge] - ``` - - ```bash tab="CLI" - --entryPoints.web.address=:80 - --entryPoints.websecure.address=:443 - --certificatesresolvers.myresolver.acme.email=your-email@example.com - --certificatesresolvers.myresolver.acme.storage=acme.json - --certificatesresolvers.myresolver.acme.tlschallenge=true - ``` - -## Traefik Logs - -In the v2, all the [log configuration](../observability/logs.md) remains in the static part but are unified under a `log` section. -There is no more log configuration at the root level. - -!!! example "Simple log configuration" - - !!! info "v1" - - ```toml tab="File (TOML)" - # static configuration - logLevel = "DEBUG" - - [traefikLog] - filePath = "/path/to/traefik.log" - format = "json" - ``` - - ```bash tab="CLI" - --logLevel=DEBUG - --traefikLog.filePath=/path/to/traefik.log - --traefikLog.format=json - ``` - - !!! info "v2" - - ```yaml tab="File (YAML)" - # static configuration - log: - level: DEBUG - filePath: /path/to/log-file.log - format: json - ``` - - ```toml tab="File (TOML)" - # static configuration - [log] - level = "DEBUG" - filePath = "/path/to/log-file.log" - format = "json" - ``` - - ```bash tab="CLI" - --log.level=DEBUG - --log.filePath=/path/to/traefik.log - --log.format=json - ``` - -## Access Logs - -Access Logs are configured in the same way as before. - -But all request headers are now filtered out by default in Traefik v2. -So during migration, you might want to consider enabling some needed fields (see [access log configuration](../observability/access-logs.md)). - -## Tracing - -Traefik v2 retains OpenTracing support. The `backend` root option from the v1 is gone, you just have to set your [tracing configuration](../observability/tracing/overview.md). - -!!! example "Simple Jaeger tracing configuration" - - !!! info "v1" - - ```toml tab="File (TOML)" - # static configuration - [tracing] - backend = "jaeger" - servicename = "tracing" - [tracing.jaeger] - samplingParam = 1.0 - samplingServerURL = "http://12.0.0.1:5778/sampling" - samplingType = "const" - localAgentHostPort = "12.0.0.1:6831" - ``` - - ```bash tab="CLI" - --tracing.backend=jaeger - --tracing.servicename=tracing - --tracing.jaeger.localagenthostport=12.0.0.1:6831 - --tracing.jaeger.samplingparam=1.0 - --tracing.jaeger.samplingserverurl=http://12.0.0.1:5778/sampling - --tracing.jaeger.samplingtype=const - ``` - - !!! info "v2" - - ```yaml tab="File (YAML)" - # static configuration - tracing: - servicename: tracing - jaeger: - samplingParam: 1 - samplingServerURL: 'http://12.0.0.1:5778/sampling' - samplingType: const - localAgentHostPort: '12.0.0.1:6831' - ``` - - ```toml tab="File (TOML)" - # static configuration - [tracing] - servicename = "tracing" - [tracing.jaeger] - samplingParam = 1.0 - samplingServerURL = "http://12.0.0.1:5778/sampling" - samplingType = "const" - localAgentHostPort = "12.0.0.1:6831" - ``` - - ```bash tab="CLI" - --tracing.servicename=tracing - --tracing.jaeger.localagenthostport=12.0.0.1:6831 - --tracing.jaeger.samplingparam=1.0 - --tracing.jaeger.samplingserverurl=http://12.0.0.1:5778/sampling - --tracing.jaeger.samplingtype=const - ``` - -## Metrics - -The v2 retains metrics tools and allows metrics to be configured for the entrypoints and/or services. -For a basic configuration, the [metrics configuration](../observability/metrics/overview.md) remains the same. - -!!! example "Simple Prometheus metrics configuration" - - !!! info "v1" - - ```toml tab="File (TOML)" - # static configuration - [metrics.prometheus] - buckets = [0.1,0.3,1.2,5.0] - entryPoint = "traefik" - ``` - - ```bash tab="CLI" - --metrics.prometheus.buckets=[0.1,0.3,1.2,5.0] - --metrics.prometheus.entrypoint=traefik - ``` - - !!! info "v2" - - ```yaml tab="File (YAML)" - # static configuration - metrics: - prometheus: - buckets: - - 0.1 - - 0.3 - - 1.2 - - 5 - entryPoint: metrics - ``` - - ```toml tab="File (TOML)" - # static configuration - [metrics.prometheus] - buckets = [0.1,0.3,1.2,5.0] - entryPoint = "metrics" - ``` - - ```bash tab="CLI" - --metrics.prometheus.buckets=[0.1,0.3,1.2,5.0] - --metrics.prometheus.entrypoint=metrics - ``` - -## No More Root Level Key/Values - -To avoid any source of confusion, there are no more configuration at the root level. -Each root item has been moved to a related section or removed. - -!!! example "From root to dedicated section" - - !!! info "v1" - - ```toml tab="File (TOML)" - # static configuration - checkNewVersion = false - sendAnonymousUsage = true - logLevel = "DEBUG" - insecureSkipVerify = true - rootCAs = [ "/mycert.cert" ] - maxIdleConnsPerHost = 200 - providersThrottleDuration = "2s" - AllowMinWeightZero = true - debug = true - defaultEntryPoints = ["web", "websecure"] - keepTrailingSlash = false - ``` - - ```bash tab="CLI" - --checknewversion=false - --sendanonymoususage=true - --loglevel=DEBUG - --insecureskipverify=true - --rootcas=/mycert.cert - --maxidleconnsperhost=200 - --providersthrottleduration=2s - --allowminweightzero=true - --debug=true - --defaultentrypoints=web,websecure - --keeptrailingslash=true - ``` - - !!! info "v2" - - ```yaml tab="File (YAML)" - # static configuration - global: - checkNewVersion: true - sendAnonymousUsage: true - - log: - level: DEBUG - - serversTransport: - insecureSkipVerify: true - rootCAs: - - /mycert.cert - maxIdleConnsPerHost: 42 - - providers: - providersThrottleDuration: 42 - ``` - - ```toml tab="File (TOML)" - # static configuration - [global] - checkNewVersion = true - sendAnonymousUsage = true - - [log] - level = "DEBUG" - - [serversTransport] - insecureSkipVerify = true - rootCAs = [ "/mycert.cert" ] - maxIdleConnsPerHost = 42 - - [providers] - providersThrottleDuration = 42 - ``` - - ```bash tab="CLI" - --global.checknewversion=true - --global.sendanonymoususage=true - --log.level=DEBUG - --serverstransport.insecureskipverify=true - --serverstransport.rootcas=/mycert.cert - --serverstransport.maxidleconnsperhost=42 - --providers.providersthrottleduration=42 - ``` - -## Dashboard - -You need to activate the API to access the [dashboard](../operations/dashboard.md). - -To activate the dashboard, you can either: - -- use the [secure mode](../operations/dashboard.md#secure-mode) with the `api@internal` service like in the following examples -- or use the [insecure mode](../operations/api.md#insecure) - -!!! example "Activate and access the dashboard" - - !!! info "v1" - - ```toml tab="File (TOML)" - ## static configuration - # traefik.toml - - [entryPoints.websecure] - address = ":443" - [entryPoints.websecure.tls] - [entryPoints.websecure.auth] - [entryPoints.websecure.auth.basic] - users = [ - "test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/" - ] - - [api] - entryPoint = "websecure" - ``` - - ```bash tab="CLI" - --entryPoints='Name:websecure Address::443 TLS Auth.Basic.Users:test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/' - --api - ``` - - !!! info "v2" - - ```yaml tab="Docker & Swarm" - # dynamic configuration - labels: - - "traefik.http.routers.api.rule=Host(`traefik.docker.localhost`)" - - "traefik.http.routers.api.entrypoints=websecure" - - "traefik.http.routers.api.service=api@internal" - - "traefik.http.routers.api.middlewares=myAuth" - - "traefik.http.routers.api.tls" - - "traefik.http.middlewares.myAuth.basicauth.users=test:$$apr1$$H6uskkkW$$IgXLP6ewTrSuBkTrqE8wj/" - ``` - - ```yaml tab="File (YAML)" - ## static configuration - # traefik.yml - - entryPoints: - websecure: - address: ':443' - - api: {} - - providers: - file: - directory: /path/to/dynamic/config - - ##---------------------## - - ## dynamic configuration - # /path/to/dynamic/config/dynamic-conf.yml - - http: - routers: - api: - rule: Host(`traefik.docker.localhost`) - entryPoints: - - websecure - service: api@internal - middlewares: - - myAuth - tls: {} - - middlewares: - myAuth: - basicAuth: - users: - - 'test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/' - ``` - - ```toml tab="File (TOML)" - ## static configuration - # traefik.toml - - [entryPoints.websecure] - address = ":443" - - [api] - - [providers.file] - directory = "/path/to/dynamic/config" - - ##---------------------## - - ## dynamic configuration - # /path/to/dynamic/config/dynamic-conf.toml - - [http.routers.api] - rule = "Host(`traefik.docker.localhost`)" - entrypoints = ["websecure"] - service = "api@internal" - middlewares = ["myAuth"] - [http.routers.api.tls] - - [http.middlewares.myAuth.basicAuth] - users = [ - "test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/" - ] - ``` - -## Providers - -Supported [providers](../providers/overview.md), for now: - -- [ ] Azure Service Fabric -- [x] Consul -- [x] Consul Catalog -- [x] Docker -- [ ] DynamoDB -- [ ] ECS -- [x] Etcd -- [ ] Eureka -- [x] File -- [x] Kubernetes Ingress -- [x] Kubernetes IngressRoute -- [x] Marathon -- [ ] Mesos -- [x] Rancher -- [x] Redis -- [x] Rest -- [x] Zookeeper - -## Some Tips You Should Know - -- Different sources of static configuration (file, CLI flags, ...) cannot be [mixed](../getting-started/configuration-overview.md#the-static-configuration). -- Now, configuration elements can be referenced between different providers by using the provider namespace notation: `@`. - For instance, a router named `myrouter` in a File Provider can refer to a service named `myservice` defined in Docker Provider with the following notation: `myservice@docker`. -- Middlewares are applied in the same order as their declaration in router. -- If you have any questions feel free to join our [community forum](https://community.traefik.io). diff --git a/docs/content/migrate/v2-to-v3-details.md b/docs/content/migrate/v2-to-v3-details.md index 03426c0ec..257ee0f5f 100644 --- a/docs/content/migrate/v2-to-v3-details.md +++ b/docs/content/migrate/v2-to-v3-details.md @@ -135,7 +135,7 @@ It is now unsupported and would prevent Traefik to start. ##### Remediation The `http3` option should be removed from the static configuration experimental section. -To configure `http3`, please checkout the [entrypoint configuration documentation](../routing/entrypoints.md#http3_1). +To configure `http3`, please checkout the [entrypoint configuration documentation](../reference/install-configuration/entrypoints.md#http3). ### Consul provider diff --git a/docs/content/migrate/v2-to-v3.md b/docs/content/migrate/v2-to-v3.md index 00fcfe8c2..175f36921 100644 --- a/docs/content/migrate/v2-to-v3.md +++ b/docs/content/migrate/v2-to-v3.md @@ -11,7 +11,7 @@ How to Migrate from Traefik v2 to Traefik v3. !!! success "Streamlined Migration Process" Traefik v3 introduces minimal breaking changes and maintains backward compatibility with v2 syntax in dynamic configuration, offering a gradual migration path. -With Traefik v3, we are introducing a streamlined transition process from v2. Minimal breaking changes have been made to specific options in the [static configuration](./v2-to-v3-details.md#static-configuration-changes "Link to static configuration changes"), and we are ensuring backward compatibility with v2 syntax in the [dynamic configuration](./v2-to-v3-details.md#dynamic-configuration-changes "Link to dynamic configuration changes"). This will offer a gradual path for adopting the v3 syntax, allowing users to progressively migrate their Kubernetes ingress resources, Docker labels, etc., to the new format. +With Traefik v3, we are introducing a streamlined transition process from v2. Minimal breaking changes have been made to specific options in the [static configuration](./v2-to-v3-details.md#install-configuration-changes "Link to install configuration changes"), and we are ensuring backward compatibility with v2 syntax in the [dynamic configuration](./v2-to-v3-details.md#routing-configuration-changes "Link to routing configuration changes"). This will offer a gradual path for adopting the v3 syntax, allowing users to progressively migrate their Kubernetes ingress resources, Docker labels, etc., to the new format. ## Migration Overview @@ -33,7 +33,7 @@ The migration process consists of three progressive steps designed to minimize r **Review and Update Static Configuration** -Check the changes in [static configurations](./v2-to-v3-details.md#static-configuration-changes "Link to static configuration changes") and [operations](./v2-to-v3-details.md#operations-changes "Link to operations changes") brought by Traefik v3. Modify your configurations accordingly. +Check the changes in [static configurations](./v2-to-v3-details.md#install-configuration-changes "Link to install configuration changes") and [operations](./v2-to-v3-details.md#operations-changes "Link to operations changes") brought by Traefik v3. Modify your configurations accordingly. **Enable v2 Compatibility Mode** @@ -110,13 +110,13 @@ We strongly advise you to follow a progressive migration strategy ([Kubernetes r ## Step 3: Progressively Migrate Dynamic Configuration !!! info "Optional Immediate Step" - This step can be done later in the process, as Traefik v3 is compatible with the v2 format for [dynamic configuration](./v2-to-v3-details.md#dynamic-configuration-changes "Link to dynamic configuration changes"). Enable Traefik logs to get some help if any deprecated option is in use. + This step can be done later in the process, as Traefik v3 is compatible with the v2 format for [dynamic configuration](./v2-to-v3-details.md#routing-configuration-changes "Link to routing configuration changes"). Enable Traefik logs to get some help if any deprecated option is in use. ### Migration Process **Review Dynamic Configuration Changes** -Check the changes in [dynamic configuration](./v2-to-v3-details.md#dynamic-configuration-changes "Link to dynamic configuration changes") to understand what updates are needed. +Check the changes in [dynamic configuration](./v2-to-v3-details.md#routing-configuration-changes "Link to routing configuration changes") to understand what updates are needed. **Progressive Router Migration** diff --git a/docs/content/migrate/v2.md b/docs/content/migrate/v2.md deleted file mode 100644 index b4e83e45e..000000000 --- a/docs/content/migrate/v2.md +++ /dev/null @@ -1,719 +0,0 @@ ---- -title: "Traefik Migration Documentation" -description: "Learn the steps needed to migrate to new Traefik Proxy v2 versions, i.e. v2.0 to v2.1 or v2.1 to v2.2. Read the technical documentation." ---- - -# Migration: Steps needed between the versions - -## v2.0 to v2.1 - -### Kubernetes CRD - -In v2.1, a new Kubernetes CRD called `TraefikService` was added. -While updating an installation to v2.1, -one should apply that CRD, and update the existing `ClusterRole` definition to allow Traefik to use that CRD. - -To add that CRD and enhance the permissions, the following definitions need to be applied to the cluster. - -```yaml tab="TraefikService" -apiVersion: apiextensions.k8s.io/v1beta1 -kind: CustomResourceDefinition -metadata: - name: traefikservices.traefik.containo.us - -spec: - group: traefik.containo.us - version: v1alpha1 - names: - kind: TraefikService - plural: traefikservices - singular: traefikservice - scope: Namespaced -``` - -```yaml tab="ClusterRole" -kind: ClusterRole -apiVersion: rbac.authorization.k8s.io/v1beta1 -metadata: - name: traefik-ingress-controller - -rules: - - apiGroups: - - "" - resources: - - services - - endpoints - - secrets - verbs: - - get - - list - - watch - - apiGroups: - - extensions - - networking.k8s.io - resources: - - ingresses - verbs: - - get - - list - - watch - - apiGroups: - - extensions - - networking.k8s.io - resources: - - ingresses/status - verbs: - - update - - apiGroups: - - traefik.io - - traefik.containo.us - resources: - - middlewares - - middlewaretcps - - ingressroutes - - traefikservices - - ingressroutetcps - - ingressrouteudps - - tlsoptions - - tlsstores - - serverstransports - - serverstransporttcps - verbs: - - get - - list - - watch -``` - -After having both resources applied, Traefik will work properly. - -## v2.1 to v2.2 - -### Headers middleware: accessControlAllowOrigin - -`accessControlAllowOrigin` is deprecated. -This field will be removed in future 2.x releases. -Please configure your allowed origins in `accessControlAllowOriginList` instead. - -### Kubernetes CRD - -In v2.2, new Kubernetes CRDs called `TLSStore` and `IngressRouteUDP` were added. -While updating an installation to v2.2, -one should apply that CRDs, and update the existing `ClusterRole` definition to allow Traefik to use that CRDs. - -To add that CRDs and enhance the permissions, the following definitions need to be applied to the cluster. - -```yaml tab="TLSStore" -apiVersion: apiextensions.k8s.io/v1beta1 -kind: CustomResourceDefinition -metadata: - name: tlsstores.traefik.containo.us - -spec: - group: traefik.containo.us - version: v1alpha1 - names: - kind: TLSStore - plural: tlsstores - singular: tlsstore - scope: Namespaced - -``` - -```yaml tab="IngressRouteUDP" -apiVersion: apiextensions.k8s.io/v1beta1 -kind: CustomResourceDefinition -metadata: - name: ingressrouteudps.traefik.containo.us - -spec: - group: traefik.containo.us - version: v1alpha1 - names: - kind: IngressRouteUDP - plural: ingressrouteudps - singular: ingressrouteudp - scope: Namespaced - -``` - -```yaml tab="ClusterRole" -kind: ClusterRole -apiVersion: rbac.authorization.k8s.io/v1beta1 -metadata: - name: traefik-ingress-controller - -rules: - - apiGroups: - - "" - resources: - - services - - endpoints - - secrets - verbs: - - get - - list - - watch - - apiGroups: - - extensions - - networking.k8s.io - resources: - - ingresses - verbs: - - get - - list - - watch - - apiGroups: - - extensions - - networking.k8s.io - resources: - - ingresses/status - verbs: - - update - - apiGroups: - - traefik.io - - traefik.containo.us - resources: - - middlewares - - middlewaretcps - - ingressroutes - - traefikservices - - ingressroutetcps - - ingressrouteudps - - tlsoptions - - tlsstores - - serverstransports - - serverstransporttcps - verbs: - - get - - list - - watch -``` - -After having both resources applied, Traefik will work properly. - -### Kubernetes Ingress - -To enable HTTPS, it is not sufficient anymore to only rely on a TLS section in the Ingress. - -#### Expose an Ingress on 80 and 443 - -Define the default TLS configuration on the HTTPS entry point. - -```yaml tab="Ingress" -kind: Ingress -apiVersion: networking.k8s.io/v1beta1 -metadata: - name: example - -spec: - tls: - - secretName: my-tls-secret - - rules: - - host: example.com - http: - paths: - - path: "/foo" - backend: - serviceName: example-com - servicePort: 80 -``` - -Entry points definition and enable Ingress provider: - -```yaml tab="File (YAML)" -# Static configuration - -entryPoints: - web: - address: :80 - websecure: - address: :443 - http: - tls: {} - -providers: - kubernetesIngress: {} -``` - -```toml tab="File (TOML)" -# Static configuration - -[entryPoints.web] - address = ":80" - -[entryPoints.websecure] - address = ":443" - [entryPoints.websecure.http] - [entryPoints.websecure.http.tls] - -[providers.kubernetesIngress] -``` - -```bash tab="CLI" -# Static configuration - ---entryPoints.web.address=:80 ---entryPoints.websecure.address=:443 ---entryPoints.websecure.http.tls=true ---providers.kubernetesIngress=true -``` - -#### Use TLS only on one Ingress - -Define the TLS restriction with annotations. - -```yaml tab="Ingress" -kind: Ingress -apiVersion: networking.k8s.io/v1beta1 -metadata: - name: example-tls - annotations: - traefik.ingress.kubernetes.io/router.entrypoints: websecure - traefik.ingress.kubernetes.io/router.tls: "true" - -spec: - tls: - - secretName: my-tls-secret - - rules: - - host: example.com - http: - paths: - - path: "" - backend: - serviceName: example-com - servicePort: 80 -``` - -Entry points definition and enable Ingress provider: - -```yaml tab="File (YAML)" -# Static configuration - -entryPoints: - web: - address: :80 - websecure: - address: :443 - -providers: - kubernetesIngress: {} -``` - -```toml tab="File (TOML)" -# Static configuration - -[entryPoints.web] - address = ":80" - -[entryPoints.websecure] - address = ":443" - -[providers.kubernetesIngress] -``` - -```bash tab="CLI" -# Static configuration - ---entryPoints.web.address=:80 ---entryPoints.websecure.address=:443 ---providers.kubernetesIngress=true -``` - -## v2.2.2 to v2.2.5 - -### InsecureSNI removal - -In `v2.2.2` we introduced a new flag (`insecureSNI`) which was available as a global option to disable domain fronting. -Since `v2.2.5` this global option has been removed, and you should not use it anymore. - -### HostSNI rule matcher removal - -In `v2.2.2` we introduced a new rule matcher (`HostSNI`) for HTTP routers which was allowing to match the Server Name Indication at the router level. -Since `v2.2.5` this rule has been removed for HTTP routers, and you should not use it anymore. - -## v2.2 to v2.3 - -### X.509 CommonName Deprecation - -The deprecated, legacy behavior of treating the CommonName field on X.509 certificates as a host name when no Subject Alternative Names are present, is now disabled by default. - -It means that if one is using https with your backend servers, and a certificate with only a CommonName, -Traefik will not try to match the server name indication with the CommonName anymore. - -It can be temporarily re-enabled by adding the value `x509ignoreCN=0` to the `GODEBUG` environment variable. - -More information: https://golang.org/doc/go1.15#commonname - -### File Provider - -The file parser has been changed, since v2.3 the unknown options/fields in a dynamic configuration file are treated as errors. - -### IngressClass - -In `v2.3`, the support of `IngressClass`, which is available since Kubernetes version `1.18`, has been introduced. -In order to be able to use this new resource the [Kubernetes RBAC](../reference/dynamic-configuration/kubernetes-crd.md#rbac) must be updated. - -## v2.3 to v2.4 - -### ServersTransport - -In `v2.4.0`, the support of `ServersTransport` has been introduced. -It is therefore necessary to update [RBAC](../reference/dynamic-configuration/kubernetes-crd.md#rbac) and [CRD](../reference/dynamic-configuration/kubernetes-crd.md) definitions. - -## v2.4.7 to v2.4.8 - -### Non-ASCII Domain Names - -In `v2.4.8`, we introduced a new check on domain names used in HTTP router rule `Host` and `HostRegexp` expressions, -and in TCP router rule `HostSNI` expression. -This check ensures that provided domain names don't contain non-ASCII characters. -If not, an error is raised, and the associated router will be shown as invalid in the dashboard. - -This new behavior is intended to show what was failing silently previously and to help troubleshooting configuration issues. -It doesn't change the support for non-ASCII domain names in routers rules, which is not part of the Traefik feature set so far. - -In order to use non-ASCII domain names in a router's rule, one should use the Punycode form of the domain name. -For more information, please read the [HTTP routers rule](../routing/routers/index.md#rule) part or [TCP router rules](../routing/routers/index.md#rule_1) part of the documentation. - -## v2.4.8 to v2.4.9 - -### Tracing Span - -In `v2.4.9`, we changed span error to log only server errors (>= 500). - -## v2.4.9 to v2.4.10 - -### K8S CrossNamespace - -In `v2.4.10`, the default value for `allowCrossNamespace` has been changed to `false`. - -### K8S ExternalName Service - -In `v2.4.10`, by default, it is no longer authorized to reference Kubernetes ExternalName services. -To allow it, the `allowExternalNameServices` option should be set to `true`. - -## v2.4 to v2.5 - -### Kubernetes CRD - -In `v2.5`, the [Traefik CRDs](../reference/dynamic-configuration/kubernetes-crd.md#definitions) have been updated to support the new API version `apiextensions.k8s.io/v1`. -As required by `apiextensions.k8s.io/v1`, we have included the OpenAPI validation schema. - -After deploying the new [Traefik CRDs](../reference/dynamic-configuration/kubernetes-crd.md#definitions), the resources will be validated only on creation or update. - -Please note that the unknown fields will not be pruned when migrating from `apiextensions.k8s.io/v1beta1` to `apiextensions.k8s.io/v1` CRDs. -For more details check out the official [documentation](https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/#specifying-a-structural-schema). - -### Kubernetes Ingress - -Traefik v2.5 moves forward for the Ingress provider to support Kubernetes v1.22. - -Traefik now supports only v1.14+ Kubernetes clusters, which means the support of `extensions/v1beta1` API Version ingresses has been dropped. - -The `extensions/v1beta1` API Version should now be replaced either by `networking.k8s.io/v1beta1` or by `networking.k8s.io/v1` (as of Kubernetes v1.19+). - -The support of the `networking.k8s.io/v1beta1` API Version will stop in Kubernetes v1.22. - -### Headers middleware: ssl redirect options - -`sslRedirect`, `sslTemporaryRedirect`, `sslHost` and `sslForceHost` are deprecated in Traefik v2.5. - -For simple HTTP to HTTPS redirection, you may use [EntryPoints redirections](../routing/entrypoints.md#redirection). - -For more advanced use cases, you can use either the [RedirectScheme middleware](../middlewares/http/redirectscheme.md) or the [RedirectRegex middleware](../middlewares/http/redirectregex.md). - -### Headers middleware: accessControlAllowOrigin - -`accessControlAllowOrigin` is no longer supported in Traefik v2.5. - -### X.509 CommonName Deprecation Bis - -Following up on the deprecation started [previously](#x509-commonname-deprecation), -as the `x509ignoreCN=0` value for the `GODEBUG` is [deprecated in Go 1.17](https://tip.golang.org/doc/go1.17#crypto/x509), -the legacy behavior related to the CommonName field cannot be enabled at all anymore. - -## v2.5.3 to v2.5.4 - -### Errors middleware - -In `v2.5.4`, when the errors service is configured with the [`PassHostHeader`](../routing/services/index.md#pass-host-header) option to `true` (default), -the forwarded Host header value is now set to the client request Host value and not `0.0.0.0`. -Check out the [Errors middleware](../middlewares/http/errorpages.md#service) documentation for more details. - -## v2.5 to v2.6 - -### HTTP/3 - -Traefik v2.6 introduces the `AdvertisedPort` option, -which allows advertising, in the `Alt-Svc` header, a UDP port different from the one on which Traefik is actually listening (the EntryPoint's port). -By doing so, it introduces a new configuration structure `http3`, which replaces the `enableHTTP3` option (which therefore doesn't exist anymore). -To enable HTTP/3 on an EntryPoint, please check out the [HTTP/3 configuration](../routing/entrypoints.md#http3) documentation. - -### Kubernetes Gateway API Provider - -In `v2.6`, the [Kubernetes Gateway API provider](../providers/kubernetes-gateway.md) now only supports the version [v1alpha2](https://gateway-api.sigs.k8s.io/v1alpha2/guides/) of the specification and -[route namespaces](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1beta1.RouteNamespaces) selectors, which requires Traefik to fetch and watch the cluster namespaces. -Therefore, the RBAC and CRD definitions must be updated. - -## v2.6.0 to v2.6.1 - -### Metrics - -In `v2.6.1`, the metrics system does not support any more custom HTTP method verbs to prevent potential metrics cardinality overhead. -In consequence, for metrics having the method label, -if the HTTP method verb of a request is not one defined in the set of common methods for [`HTTP/1.1`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods) -or the [`PRI`](https://datatracker.ietf.org/doc/html/rfc7540#section-11.6) verb (for `HTTP/2`), -the value for the method label becomes `EXTENSION_METHOD`, instead of the request's one. - -### Tracing - -In `v2.6.1`, the Datadog tags added to a span changed from `service.name` to `traefik.service.name` and from `router.name` to `traefik.router.name`. - -## v2.8 - -### TLS client authentication - -In `v2.8`, the `caOptional` option is deprecated as TLS client authentication is a server side option. -This option available in the ForwardAuth middleware, as well as in the HTTP, Consul, Etcd, Redis, ZooKeeper, Marathon, Consul Catalog, and Docker providers has no effect and must not be used anymore. - -### Consul Enterprise Namespaces - -In `v2.8`, the `namespace` option of Consul and Consul Catalog providers is deprecated, please use the `namespaces` options instead. - -### Traefik Pilot - -In `v2.8`, the `pilot.token` and `pilot.dashboard` options are deprecated. -Please check our Blog for migration instructions later this year. - -## v2.8.2 - -Since `v2.5.0`, the `PreferServerCipherSuites` is [deprecated and ignored](https://tip.golang.org/doc/go1.17#crypto/tls) by Go, -in `v2.8.2` the `preferServerCipherSuites` option is also deprecated and ignored in Traefik. - -In `v2.8.2`, Traefik now reject certificates signed with the SHA-1 hash function. ([details](https://tip.golang.org/doc/go1.18#sha1)) - -## v2.9 - -### Traefik Pilot - -In `v2.9`, Traefik Pilot support has been removed. - -## v2.10 - -### Nomad Namespace - -In `v2.10`, the `namespace` option of the Nomad provider is deprecated, please use the `namespaces` options instead. - -### Kubernetes CRDs - -In `v2.10`, the Kubernetes CRDs API Group `traefik.containo.us` is deprecated, and its support will end starting with Traefik v3. Please use the API Group `traefik.io` instead. - -As the Kubernetes CRD provider still works with both API Versions (`traefik.io/v1alpha1` and `traefik.containo.us/v1alpha1`), -it means that for the same kind, namespace and name, the provider will only keep the `traefik.io/v1alpha1` resource. - -In addition, the Kubernetes CRDs API Version `traefik.containo.us/v1alpha1` will not be supported in Traefik v3 itself. - -Please note that it is a requirement to update the CRDs and the RBAC in the cluster before upgrading Traefik. -To do so, please apply the required [CRDs](https://raw.githubusercontent.com/traefik/traefik/v2.10/docs/content/reference/dynamic-configuration/kubernetes-crd-definition-v1.yml) and [RBAC](https://raw.githubusercontent.com/traefik/traefik/v2.10/docs/content/reference/dynamic-configuration/kubernetes-crd-rbac.yml) manifests for v2.10: - -```bash -kubectl apply -f https://raw.githubusercontent.com/traefik/traefik/v2.10/docs/content/reference/dynamic-configuration/kubernetes-crd-rbac.yml -kubectl apply -f https://raw.githubusercontent.com/traefik/traefik/v2.10/docs/content/reference/dynamic-configuration/kubernetes-crd-definition-v1.yml -``` - -### Traefik Hub - -In `v2.10`, Traefik Hub configuration has been removed because Traefik Hub v2 doesn't require this configuration. - -## v2.11 - -### IPWhiteList (HTTP) - -In `v2.11`, the `IPWhiteList` middleware is deprecated, please use the [IPAllowList](../middlewares/http/ipallowlist.md) middleware instead. - -### IPWhiteList (TCP) - -In `v2.11`, the `IPWhiteList` middleware is deprecated, please use the [IPAllowList](../middlewares/tcp/ipallowlist.md) middleware instead. - -### TLS CipherSuites - -> By default, cipher suites without ECDHE support are no longer offered by either clients or servers during pre-TLS 1.3 handshakes. -> This change can be reverted with the `tlsrsakex=1 GODEBUG` setting. -> (https://go.dev/doc/go1.22#crypto/tls) - -The _RSA key exchange_ cipher suites are way less secure than the modern ECDHE cipher suites and exposes to potential vulnerabilities like [the Marvin Attack](https://people.redhat.com/~hkario/marvin). -Decision has been made to support ECDHE cipher suites only by default. - -The following ciphers have been removed from the default list: - -- `TLS_RSA_WITH_AES_128_CBC_SHA` -- `TLS_RSA_WITH_AES_256_CBC_SHA` -- `TLS_RSA_WITH_AES_128_GCM_SHA256` -- `TLS_RSA_WITH_AES_256_GCM_SHA384` - -To enable these ciphers, please set the option `CipherSuites` in your [TLS configuration](../https/tls.md#cipher-suites) or set the environment variable `GODEBUG=tlsrsakex=1`. - -### Minimum TLS Version - -> By default, the minimum version offered by `crypto/tls` servers is now TLS 1.2 if not specified with config.MinimumVersion, -> matching the behavior of crypto/tls clients. -> This change can be reverted with the `tls10server=1 GODEBUG` setting. -> (https://go.dev/doc/go1.22#crypto/tls) - -To enable TLS 1.0, please set the option `MinVersion` to `VersionTLS10` in your [TLS configuration](../https/tls.md#cipher-suites) or set the environment variable `GODEBUG=tls10server=1`. - -## v2.11.1 - -### Maximum Router Priority Value - -Before v2.11.1, the maximum user-defined router priority value is: - -- `MaxInt32` for 32-bit platforms, -- `MaxInt64` for 64-bit platforms. - -Please check out the [go documentation](https://pkg.go.dev/math#pkg-constants) for more information. - -In v2.11.1, Traefik reserves a range of priorities for its internal routers and now, -the maximum user-defined router priority value is: - -- `(MaxInt32 - 1000)` for 32-bit platforms, -- `(MaxInt64 - 1000)` for 64-bit platforms. - -### EntryPoint.Transport.RespondingTimeouts. - -Starting with `v2.11.1` the following timeout options are deprecated: - -- `.transport.respondingTimeouts.readTimeout` -- `.transport.respondingTimeouts.writeTimeout` -- `.transport.respondingTimeouts.idleTimeout` - -They have been replaced by: - -- `.transport.respondingTimeouts.http.readTimeout` -- `.transport.respondingTimeouts.http.writeTimeout` -- `.transport.respondingTimeouts.http.idleTimeout` - -### EntryPoint.Transport.RespondingTimeouts.TCP.LingeringTimeout - -Starting with `v2.11.1` a new `lingeringTimeout` entryPoints option has been introduced, with a default value of 2s. - -The lingering timeout defines the maximum duration between each TCP read operation on the connection. -As a layer 4 timeout, it applies during HTTP handling but respects the configured HTTP server `readTimeout`. - -This change avoids Traefik instances with the default configuration hanging while waiting for bytes to be read on the connection. - -We suggest to adapt this value accordingly to your situation. -The new default value is purposely narrowed and can close the connection too early. - -Increasing the `lingeringTimeout` value could be the solution notably if you are dealing with the following errors: - -- TCP: `Error while handling TCP connection: readfrom tcp X.X.X.X:X->X.X.X.X:X: read tcp X.X.X.X:X->X.X.X.X:X: i/o timeout` -- HTTP: `'499 Client Closed Request' caused by: context canceled` -- HTTP: `ReverseProxy read error during body copy: read tcp X.X.X.X:X->X.X.X.X:X: use of closed network connection` - -## v2.11.2 - -### LingeringTimeout - -Starting with `v2.11.2` the `.transport.respondingTimeouts.tcp.lingeringTimeout` introduced in `v2.11.1` has been removed. - -### RespondingTimeouts.TCP and RespondingTimeouts.HTTP - -Starting with `v2.11.2` the `respondingTimeouts.tcp` and `respondingTimeouts.http` sections introduced in `v2.11.1` have been removed. -To configure the responding timeouts, please use the [`respondingTimeouts`](../routing/entrypoints.md#respondingtimeouts) section. - -### EntryPoint.Transport.RespondingTimeouts.ReadTimeout - -Starting with `v2.11.2` the entryPoints [`readTimeout`](../routing/entrypoints.md#respondingtimeouts) option default value changed to 60 seconds. - -For HTTP, this option defines the maximum duration for reading the entire request, including the body. -For TCP, this option defines the maximum duration for the first bytes to be read on the connection. - -The default value was previously set to zero, which means no timeout. - -This change has been done to avoid Traefik instances with the default configuration to be hanging forever while waiting for bytes to be read on the connection. - -Increasing the `readTimeout` value could be the solution notably if you are dealing with the following errors: - -- TCP: `Error while handling TCP connection: readfrom tcp X.X.X.X:X->X.X.X.X:X: read tcp X.X.X.X:X->X.X.X.X:X: i/o timeout` -- HTTP: `'499 Client Closed Request' caused by: context canceled` -- HTTP: `ReverseProxy read error during body copy: read tcp X.X.X.X:X->X.X.X.X:X: use of closed network connection` - -## v2.11.3 - -### Connection headers - -In `v2.11.3`, the handling of the request Connection headers directives has changed to prevent any abuse. -Before, Traefik removed any header listed in the Connection header just before forwarding the request to the backends. -Now, Traefik removes the headers listed in the Connection header as soon as the request is handled. -As a consequence, middlewares do not have access to those Connection headers, -and a new option has been introduced to specify which ones could go through the middleware chain before being removed: `.forwardedHeaders.connection`. - -Please check out the [entrypoint forwarded headers connection option configuration](../routing/entrypoints.md#forwarded-headers) documentation. - -## v2.11.14 - -### `X-Forwarded-Prefix` - -In `v2.11.14`, the `X-Forwarded-Prefix` header is now handled like the other `X-Forwarded-*` headers: Traefik removes it when it's sent from an untrusted source. -Please refer to the Forwarded headers [documentation](../routing/entrypoints.md#forwarded-headers) for more details. - -## v2.11.24 - -### Request Path Sanitization - -Since `v2.11.24`, the incoming request path is now cleaned before being used to match the router rules and sent to the backends. -Any `/../`, `/./` or duplicate slash segments in the request path is interpreted and/or collapsed. - -If you want to disable this behavior, you can set the [`sanitizePath` option](../routing/entrypoints.md#sanitizepath) to `false` in the entryPoint HTTP configuration. -This can be useful when dealing with legacy clients that are not url-encoding data in the request path. -For example, as base64 uses the “/” character internally, -if it's not url encoded, -it can lead to unsafe routing when the `sanitizePath` option is set to `false`. - -!!! warning "Security" - - Setting the `sanitizePath` option to `false` is not safe. - Ensure every request is properly url encoded instead. - -## v2.11.25 - -### Request Path Normalization - -Since `v2.11.25`, the request path is now normalized by decoding unreserved characters in the request path, -and also uppercasing the percent-encoded characters. -This follows [RFC 3986 percent-encoding normalization](https://datatracker.ietf.org/doc/html/rfc3986#section-6.2.2.2), -and [RFC 3986 case normalization](https://datatracker.ietf.org/doc/html/rfc3986#section-6.2.2.1). - -The normalization happens before the request path is sanitized, -and cannot be disabled. -This notably helps with encoded dots characters (which are unreserved characters) to be sanitized properly. - -### Routing Path - -Since `v2.11.25`, the reserved characters [(as per RFC 3986)](https://datatracker.ietf.org/doc/html/rfc3986#section-2.2) are kept encoded in the request path when matching the router rules. -Those characters, when decoded, change the meaning of the request path for routing purposes, -and Traefik now keeps them encoded to avoid any ambiguity. - -### Request Path Matching Examples - -| Request Path | Router Rule | Traefik v2.11.24 | Traefik v2.11.25 | -|-------------------|------------------------|------------------|------------------| -| `/foo%2Fbar` | PathPrefix(`/foo/bar`) | Match | No match | -| `/foo/../bar` | PathPrefix(`/foo`) | No match | No match | -| `/foo/../bar` | PathPrefix(`/bar`) | Match | Match | -| `/foo/%2E%2E/bar` | PathPrefix(`/foo`) | Match | No match | -| `/foo/%2E%2E/bar` | PathPrefix(`/bar`) | No match | Match | - -## v2.11.28 - -### MultiPath TCP - -Since `v2.11.28`, the MultiPath TCP support introduced with `v2.11.26` has been removed. -It appears that enabling MPTCP on some platforms can cause Traefik to stop with the following error logs message: - -- `set tcp X.X.X.X:X->X.X.X.X:X: setsockopt: operation not supported` - -However, it can be re-enabled by setting the `multipathtcp` variable in the GODEBUG environment variable, see the related [go documentation](https://go.dev/doc/godebug#go-124). diff --git a/docs/content/migrate/v3.md b/docs/content/migrate/v3.md index 82f11f66e..657dac8d6 100644 --- a/docs/content/migrate/v3.md +++ b/docs/content/migrate/v3.md @@ -113,9 +113,9 @@ kubectl apply -f https://raw.githubusercontent.com/traefik/traefik/v3.3/docs/con **Updated Resources:** -- [TraefikService](../../routing/services/#mirroring-service) ([PR #11032](https://github.com/traefik/traefik/pull/11032)) -- [RateLimit](../../middlewares/http/ratelimit/) & [InFlightReq](../../middlewares/http/inflightreq/) middlewares ([PR #9747](https://github.com/traefik/traefik/pull/9747)) -- [Compress](../../middlewares/http/compress/) middleware ([PR #10943](https://github.com/traefik/traefik/pull/10943)) +- [TraefikService](../routing/services/index.md#mirroring-service) ([PR #11032](https://github.com/traefik/traefik/pull/11032)) +- [RateLimit](../middlewares/http/ratelimit.md) & [InFlightReq](../middlewares/http/inflightreq.md) middlewares ([PR #9747](https://github.com/traefik/traefik/pull/9747)) +- [Compress](../middlewares/http/compress.md) middleware ([PR #10943](https://github.com/traefik/traefik/pull/10943)) ### Kubernetes Gateway Provider Standard Channel @@ -326,7 +326,7 @@ kubectl apply -f https://raw.githubusercontent.com/traefik/traefik/v3.4/docs/con !!! warning "Deprecation" The `RoundRobin` strategy is deprecated but still supported (equivalent to `wrr`). It will be removed in the next major release. -Refer to the [HTTP Services Load Balancing documentation](../../routing/services/#load-balancing-strategy) for detailed information. +Refer to the [HTTP Services Load Balancing documentation](../routing/services/index.md#load-balancing-strategy) for detailed information. #### ServersTransport CA Certificate Configuration diff --git a/docs/content/observe/logs-and-access-logs.md b/docs/content/observe/logs-and-access-logs.md index 9affe13b0..51feeb557 100644 --- a/docs/content/observe/logs-and-access-logs.md +++ b/docs/content/observe/logs-and-access-logs.md @@ -173,7 +173,7 @@ The available filters are: When using the `json` format, you can customize which fields are included in your access logs. -- **Request Fields:** You can choose to `keep`, `drop`, or `redact` any of the standard request fields. A complete list of available fields like `ClientHost`, `RequestMethod`, and `Duration` can be found in the [reference documentation](../reference/install-configuration/observability/logs-and-accesslogs.md#available-fields). +- **Request Fields:** You can choose to `keep`, `drop`, or `redact` any of the standard request fields. A complete list of available fields like `ClientHost`, `RequestMethod`, and `Duration` can be found in the [reference documentation](../reference/install-configuration/observability/logs-and-accesslogs.md#json-format-fields). - **Request Headers:** You can also specify which request headers should be included in the logs, and whether their values should be `kept`, `dropped`, or `redacted`. !!! info diff --git a/docs/content/operations/api.md b/docs/content/operations/api.md index b2779ad74..8e867bdad 100644 --- a/docs/content/operations/api.md +++ b/docs/content/operations/api.md @@ -46,7 +46,7 @@ And then define a routing configuration on Traefik itself with the --8<-- "content/operations/include-api-examples.md" -??? warning "The router's [rule](../../routing/routers/#rule) must catch requests for the URI path `/api`" +??? warning "The router's [rule](../routing/routers/index.md#rule) must catch requests for the URI path `/api`" Using an "Host" rule is recommended, by catching all the incoming traffic on this host domain to the API. However, you can also use "path prefix" rule or any combination or rules. @@ -109,7 +109,7 @@ api: --api.dashboard=true ``` -!!! warning "With Dashboard enabled, the router [rule](../../routing/routers/#rule) must catch requests for both `/api` and `/dashboard`" +!!! warning "With Dashboard enabled, the router [rule](../routing/routers/index.md#rule) must catch requests for both `/api` and `/dashboard`" Please check the [Dashboard documentation](./dashboard.md#dashboard-router-rule) to learn more about this and to get examples. ### `debug` diff --git a/docs/content/operations/dashboard.md b/docs/content/operations/dashboard.md index b7df89025..c3776a369 100644 --- a/docs/content/operations/dashboard.md +++ b/docs/content/operations/dashboard.md @@ -11,7 +11,7 @@ See What's Going On The dashboard is the central place that shows you the current active routes handled by Traefik.
- Dashboard - Providers + Dashboard - Providers
The dashboard in action
diff --git a/docs/content/providers/consul-catalog.md b/docs/content/providers/consul-catalog.md index 5b3b97e65..34b81f0ed 100644 --- a/docs/content/providers/consul-catalog.md +++ b/docs/content/providers/consul-catalog.md @@ -477,7 +477,7 @@ _Optional, Default=true_ Expose Consul Catalog services by default in Traefik. If set to `false`, services that don't have a `traefik.enable=true` tag will be ignored from the resulting routing configuration. -For additional information, refer to [Restrict the Scope of Service Discovery](./overview.md#restrict-the-scope-of-service-discovery). +For additional information, refer to [Restrict the Scope of Service Discovery](./overview.md#exposedbydefault-and-traefikenable). ```yaml tab="File (YAML)" providers: @@ -672,7 +672,7 @@ providers: # ... ``` -For additional information, refer to [Restrict the Scope of Service Discovery](./overview.md#restrict-the-scope-of-service-discovery). +For additional information, refer to [Restrict the Scope of Service Discovery](./overview.md#exposedbydefault-and-traefikenable). ### `namespaces` diff --git a/docs/content/providers/docker.md b/docs/content/providers/docker.md index 525267b45..75840998d 100644 --- a/docs/content/providers/docker.md +++ b/docs/content/providers/docker.md @@ -380,7 +380,7 @@ _Optional, Default=true_ Expose containers by default through Traefik. If set to `false`, containers that do not have a `traefik.enable=true` label are ignored from the resulting routing configuration. -For additional information, refer to [Restrict the Scope of Service Discovery](./overview.md#restrict-the-scope-of-service-discovery). +For additional information, refer to [Restrict the Scope of Service Discovery](./overview.md#exposedbydefault-and-traefikenable). ```yaml tab="File (YAML)" providers: @@ -554,7 +554,7 @@ as well as the usual boolean logic, as shown in examples below. constraints = "LabelRegex(`a.label.name`, `a.+`)" ``` -For additional information, refer to [Restrict the Scope of Service Discovery](./overview.md#restrict-the-scope-of-service-discovery). +For additional information, refer to [Restrict the Scope of Service Discovery](./overview.md#exposedbydefault-and-traefikenable). ```yaml tab="File (YAML)" providers: diff --git a/docs/content/providers/ecs.md b/docs/content/providers/ecs.md index 2cf8cf1e9..420e8c695 100644 --- a/docs/content/providers/ecs.md +++ b/docs/content/providers/ecs.md @@ -214,7 +214,7 @@ as well as the usual boolean logic, as shown in examples below. constraints = "LabelRegex(`a.label.name`, `a.+`)" ``` -For additional information, refer to [Restrict the Scope of Service Discovery](./overview.md#restrict-the-scope-of-service-discovery). +For additional information, refer to [Restrict the Scope of Service Discovery](./overview.md#exposedbydefault-and-traefikenable). ```yaml tab="File (YAML)" providers: diff --git a/docs/content/providers/nomad.md b/docs/content/providers/nomad.md index ed55aa799..ef28d8c98 100644 --- a/docs/content/providers/nomad.md +++ b/docs/content/providers/nomad.md @@ -384,7 +384,7 @@ _Optional, Default=true_ Expose Nomad services by default in Traefik. If set to `false`, services that do not have a `traefik.enable=true` tag will be ignored from the resulting routing configuration. -For additional information, refer to [Restrict the Scope of Service Discovery](./overview.md#restrict-the-scope-of-service-discovery). +For additional information, refer to [Restrict the Scope of Service Discovery](./overview.md#exposedbydefault-and-traefikenable). ```yaml tab="File (YAML)" providers: @@ -504,7 +504,7 @@ providers: # ... ``` -For additional information, refer to [Restrict the Scope of Service Discovery](./overview.md#restrict-the-scope-of-service-discovery). +For additional information, refer to [Restrict the Scope of Service Discovery](./overview.md#exposedbydefault-and-traefikenable). ### `namespaces` diff --git a/docs/content/providers/swarm.md b/docs/content/providers/swarm.md index 1a9388174..e82e1d518 100644 --- a/docs/content/providers/swarm.md +++ b/docs/content/providers/swarm.md @@ -424,7 +424,7 @@ _Optional, Default=true_ Expose containers by default through Traefik. If set to `false`, containers that do not have a `traefik.enable=true` label are ignored from the resulting routing configuration. -For additional information, refer to [Restrict the Scope of Service Discovery](./overview.md#restrict-the-scope-of-service-discovery). +For additional information, refer to [Restrict the Scope of Service Discovery](./overview.md#exposedbydefault-and-traefikenable). ```yaml tab="File (YAML)" providers: @@ -621,7 +621,7 @@ as well as the usual boolean logic, as shown in examples below. constraints = "LabelRegex(`a.label.name`, `a.+`)" ``` -For additional information, refer to [Restrict the Scope of Service Discovery](./overview.md#restrict-the-scope-of-service-discovery). +For additional information, refer to [Restrict the Scope of Service Discovery](./overview.md#exposedbydefault-and-traefikenable). ```yaml tab="File (YAML)" providers: diff --git a/docs/content/reference/install-configuration/providers/docker.md b/docs/content/reference/install-configuration/providers/docker.md index 206cb92f6..eff2a9297 100644 --- a/docs/content/reference/install-configuration/providers/docker.md +++ b/docs/content/reference/install-configuration/providers/docker.md @@ -45,7 +45,7 @@ services: | `providers.docker.username` | Defines the username for Basic HTTP authentication. This should be used when the Docker daemon socket is exposed through an HTTP proxy that requires Basic HTTP authentication.| "" | No | | `providers.docker.password` | Defines the password for Basic HTTP authentication. This should be used when the Docker daemon socket is exposed through an HTTP proxy that requires Basic HTTP authentication.| "" | No | | `providers.docker.useBindPortIP` | Instructs Traefik to use the IP/Port attached to the container's binding instead of its inner network IP/Port. See [here](#usebindportip) for more information | false | No | -| `providers.docker.exposedByDefault` | Expose containers by default through Traefik. See [here](./overview.md#restrict-the-scope-of-service-discovery) for additional information | true | No | +| `providers.docker.exposedByDefault` | Expose containers by default through Traefik. See [here](./overview.md#exposedbydefault-and-traefikenable) for additional information | true | No | | `providers.docker.network` | Defines a default docker network to use for connections to all containers. This option can be overridden on a per-container basis with the `traefik.docker.network` label.| "" | No | | `providers.docker.defaultRule` | Defines what routing rule to apply to a container if no rule is defined by a label. See [here](#defaultrule) for more information. | ```"Host(`{{ normalize .Name }}`)"``` | No | | `providers.docker.httpClientTimeout` | Defines the client timeout (in seconds) for HTTP connections. If its value is 0, no timeout is set. | 0 | No | @@ -306,7 +306,7 @@ as well as the usual boolean logic, as shown in examples below. constraints = "LabelRegex(`a.label.name`, `a.+`)" ``` -For additional information, refer to [Restrict the Scope of Service Discovery](./overview.md#restrict-the-scope-of-service-discovery). +For additional information, refer to [Restrict the Scope of Service Discovery](./overview.md#exposedbydefault-and-traefikenable). ```yaml tab="File (YAML)" providers: diff --git a/docs/content/reference/install-configuration/providers/hashicorp/consul-catalog.md b/docs/content/reference/install-configuration/providers/hashicorp/consul-catalog.md index 7246dab05..e69717389 100644 --- a/docs/content/reference/install-configuration/providers/hashicorp/consul-catalog.md +++ b/docs/content/reference/install-configuration/providers/hashicorp/consul-catalog.md @@ -36,7 +36,7 @@ Attaching tags to services: | `providers.consulCatalog.refreshInterval` | Defines the polling interval.| 15s | No | | `providers.consulCatalog.prefix` | Defines the prefix for Consul Catalog tags defining Traefik labels.| traefik | yes | | `providers.consulCatalog.requireConsistent` | Forces the read to be fully consistent. See [here](#requireconsistent) for more information.| false | yes | -| `providers.consulCatalog.exposedByDefault` | Expose Consul Catalog services by default in Traefik. If set to `false`, services that do not have a `traefik.enable=true` tag will be ignored from the resulting routing configuration. See [here](../overview.md#restrict-the-scope-of-service-discovery). | true | no | +| `providers.consulCatalog.exposedByDefault` | Expose Consul Catalog services by default in Traefik. If set to `false`, services that do not have a `traefik.enable=true` tag will be ignored from the resulting routing configuration. See [here](../overview.md#exposedbydefault-and-traefikenable). | true | no | | `providers.consulCatalog.defaultRule` | The Default Host rule for all services. See [here](#defaultrule) for more information. | ```"Host(`{{ normalize .Name }}`)"``` | No | | `providers.consulCatalog.connectAware` | Enable Consul Connect support. If set to `true`, Traefik will be enabled to communicate with Connect services. | false | No | | `providers.consulCatalog.connectByDefault` | Consider every service as Connect capable by default. If set to true, Traefik will consider every Consul Catalog service to be Connect capable by default. The option can be overridden on an instance basis with the traefik.consulcatalog.connect tag. | false | No | @@ -166,7 +166,7 @@ providers: # ... ``` -For additional information, refer to [Restrict the Scope of Service Discovery](../overview.md#restrict-the-scope-of-service-discovery). +For additional information, refer to [Restrict the Scope of Service Discovery](../overview.md#exposedbydefault-and-traefikenable). ### `namespaces` diff --git a/docs/content/reference/install-configuration/providers/hashicorp/nomad.md b/docs/content/reference/install-configuration/providers/hashicorp/nomad.md index 45e6388d8..29ddc764e 100644 --- a/docs/content/reference/install-configuration/providers/hashicorp/nomad.md +++ b/docs/content/reference/install-configuration/providers/hashicorp/nomad.md @@ -46,7 +46,7 @@ service { | `providers.nomad.throttleDuration` | Defines how often the provider is allowed to handle service events from Nomad. This option is only compatible when the `watch` option is enabled | 0s | No | | `providers.nomad.defaultRule` | The Default Host rule for all services. See [here](#defaultrule) for more information | ```"Host(`{{ normalize .Name }}`)"``` | No | | `providers.nomad.constraints` | Defines an expression that Traefik matches against the container labels to determine whether to create any route for that container. See [here](#constraints) for more information. | "" | No | -| `providers.nomad.exposedByDefault` | Expose Nomad services by default in Traefik. If set to `false`, services that do not have a `traefik.enable=true` tag will be ignored from the resulting routing configuration. See [here](../overview.md#restrict-the-scope-of-service-discovery) for additional information | true | No | +| `providers.nomad.exposedByDefault` | Expose Nomad services by default in Traefik. If set to `false`, services that do not have a `traefik.enable=true` tag will be ignored from the resulting routing configuration. See [here](../overview.md#exposedbydefault-and-traefikenable) for additional information | true | No | | `providers.nomad.allowEmptyServices` | Instructs the provider to create any [servers load balancer](../../../../routing/services/index.md#servers-load-balancer) defined for Docker containers regardless of the [healthiness](https://docs.docker.com/engine/reference/builder/#healthcheck) of the corresponding containers. | false | No | | `providers.nomad.prefix` | Defines the prefix for Nomad service tags defining Traefik labels. | `traefik` | yes | | `providers.nomad.stale` | Instructs Traefik to use stale consistency for Nomad service API reads. See [here](#stale) for more information | false | No | @@ -245,7 +245,7 @@ providers: # ... ``` -For additional information, refer to [Restrict the Scope of Service Discovery](../overview.md#restrict-the-scope-of-service-discovery). +For additional information, refer to [Restrict the Scope of Service Discovery](../overview.md#exposedbydefault-and-traefikenable). ## Routing Configuration diff --git a/docs/content/reference/install-configuration/providers/kubernetes/kubernetes-crd.md b/docs/content/reference/install-configuration/providers/kubernetes/kubernetes-crd.md index 8d1527025..15ea9c9c0 100644 --- a/docs/content/reference/install-configuration/providers/kubernetes/kubernetes-crd.md +++ b/docs/content/reference/install-configuration/providers/kubernetes/kubernetes-crd.md @@ -108,18 +108,18 @@ See the dedicated section in [routing](../../../../routing/providers/kubernetes- -| Resource | Purpose | -|--------------------------------------------------|--------------------------------------------------------------------| -| [IngressRoute](../../../../routing/providers/kubernetes-crd.md#kind-ingressroute) | HTTP Routing | -| [Middleware](../../../../middlewares/http/overview.md) | Tweaks the HTTP requests before they are sent to your service | -| [TraefikService](../../../../routing/providers/kubernetes-crd.md#kind-traefikservice) | Abstraction for HTTP loadbalancing/mirroring | -| [TLSOptions](../../../../routing/providers/kubernetes-crd.md#kind-tlsoption) | Allows configuring some parameters of the TLS connection | -| [TLSStores](../../../../routing/providers/kubernetes-crd.md#kind-tlsstore) | Allows configuring the default TLS store | -| [ServersTransport](../../../../routing/providers/kubernetes-crd.md#kind-serverstransport) | Allows configuring the transport between Traefik and the backends | -| [IngressRouteTCP](../../../../routing/providers/kubernetes-crd.md#kind-ingressroutetcp) | TCP Routing | -| [MiddlewareTCP](../../../../routing/providers/kubernetes-crd.md#kind-middlewaretcp) | Tweaks the TCP requests before they are sent to your service | -| [ServersTransportTCP](../../../../routing/providers/kubernetes-crd.md#kind-serverstransporttc) | Allows configuring the transport between Traefik and the backends | -| [IngressRouteUDP](../../../../routing/providers/kubernetes-crd.md#kind-ingressrouteudp) | UDP Routing | +| Resource | Purpose | +|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------| +| [IngressRoute](../../../routing-configuration/kubernetes/crd/http/ingressroute.md) | HTTP Routing | +| [Middleware](../../../routing-configuration/kubernetes/crd/http/middleware.md) | Tweaks the HTTP requests before they are sent to your service | +| [TraefikService](../../../routing-configuration/kubernetes/crd/http/traefikservice.md) | Abstraction for HTTP loadbalancing/mirroring | +| [TLSOptions](../../../routing-configuration/kubernetes/crd/http/tlsoption.md) | Allows configuring some parameters of the TLS connection | +| [TLSStores](../../../routing-configuration/kubernetes/crd/http/tlsstore.md) | Allows configuring the default TLS store | +| [ServersTransport](../../../routing-configuration/kubernetes/crd/http/serverstransport.md) | Allows configuring the transport between Traefik and the backends | +| [IngressRouteTCP](../../../routing-configuration/kubernetes/crd/tcp/ingressroutetcp.md) | TCP Routing | +| [MiddlewareTCP](../../../routing-configuration/kubernetes/crd/tcp/middlewaretcp.md) | Tweaks the TCP requests before they are sent to your service | +| [ServersTransportTCP](../../../routing-configuration/kubernetes/crd/tcp/serverstransporttcp.md) | Allows configuring the transport between Traefik and the backends | +| [IngressRouteUDP](../../../routing-configuration/kubernetes/crd/udp/ingressrouteudp.md) | UDP Routing | ## Particularities diff --git a/docs/content/reference/install-configuration/providers/others/ecs.md b/docs/content/reference/install-configuration/providers/others/ecs.md index 9dc12d1f5..2cca65977 100644 --- a/docs/content/reference/install-configuration/providers/others/ecs.md +++ b/docs/content/reference/install-configuration/providers/others/ecs.md @@ -103,7 +103,7 @@ providers: # ... ``` -For additional information, refer to [Restrict the Scope of Service Discovery](../overview.md#restrict-the-scope-of-service-discovery). +For additional information, refer to [Restrict the Scope of Service Discovery](../overview.md#exposedbydefault-and-traefikenable). ### `defaultRule` diff --git a/docs/content/reference/install-configuration/providers/swarm.md b/docs/content/reference/install-configuration/providers/swarm.md index 9aa25ef0c..8f876dfd2 100644 --- a/docs/content/reference/install-configuration/providers/swarm.md +++ b/docs/content/reference/install-configuration/providers/swarm.md @@ -50,7 +50,7 @@ services: | `providers.swarm.username` | Defines the username for Basic HTTP authentication. This should be used when the Docker daemon socket is exposed through an HTTP proxy that requires Basic HTTP authentication. | "" | No | | `providers.swarm.password` | Defines the password for Basic HTTP authentication. This should be used when the Docker daemon socket is exposed through an HTTP proxy that requires Basic HTTP authentication. | "" | No | | `providers.swarm.useBindPortIP` | Instructs Traefik to use the IP/Port attached to the container's binding instead of its inner network IP/Port. See [here](#usebindportip) for more information | false | No | -| `providers.swarm.exposedByDefault` | Expose containers by default through Traefik. See [here](./overview.md#restrict-the-scope-of-service-discovery) for additional information | true | No | +| `providers.swarm.exposedByDefault` | Expose containers by default through Traefik. See [here](./overview.md#exposedbydefault-and-traefikenable) for additional information | true | No | | `providers.swarm.network` | Defines a default docker network to use for connections to all containers. This option can be overridden on a per-container basis with the `traefik.swarm.network` label. | "" | No | | `providers.swarm.defaultRule` | Defines what routing rule to apply to a container if no rule is defined by a label. See [here](#defaultrule) for more information | ```"Host(`{{ normalize .Name }}`)"``` | No | | `providers.swarm.refreshSeconds` | Defines the polling interval for Swarm Mode. | "15s" | No | @@ -312,7 +312,7 @@ as well as the usual boolean logic, as shown in examples below. constraints = "LabelRegex(`a.label.name`, `a.+`)" ``` -For additional information, refer to [Restrict the Scope of Service Discovery](./overview.md#restrict-the-scope-of-service-discovery). +For additional information, refer to [Restrict the Scope of Service Discovery](./overview.md#exposedbydefault-and-traefikenable). ```yaml tab="File (YAML)" providers: diff --git a/docs/content/reference/install-configuration/tls/spiffe.md b/docs/content/reference/install-configuration/tls/spiffe.md index d7067c8f0..ca4c10ddc 100644 --- a/docs/content/reference/install-configuration/tls/spiffe.md +++ b/docs/content/reference/install-configuration/tls/spiffe.md @@ -44,7 +44,7 @@ spiffe: ## ServersTransport Enabling SPIFFE does not imply that backend connections are going to use it automatically. -Each [ServersTransport](../../../routing/services/index.md#serverstransport_1) or [TCPServersTransport](../../../routing/services/index.md#serverstransport_2), that is meant to be secured with SPIFFE, must explicitly enable it (see [SPIFFE with ServersTransport](../../../routing/services/index.md#spiffe) or [SPIFFE with TCPServersTransport](../../../routing/services/index.md#spiffe_1)). +Each [ServersTransport](../../routing-configuration/http/load-balancing/serverstransport.md) or [TCPServersTransport](../../routing-configuration/tcp/serverstransport.md), that is meant to be secured with SPIFFE, must explicitly enable it (see [SPIFFE with ServersTransport](../../routing-configuration/http/load-balancing/serverstransport.md#opt-spiffe) or [SPIFFE with TCPServersTransport](../../routing-configuration/tcp/serverstransport.md#opt-serverstransport-spiffe)). ### Configuration Example diff --git a/docs/content/reference/routing-configuration/http/load-balancing/serverstransport.md b/docs/content/reference/routing-configuration/http/load-balancing/serverstransport.md index c27cb1502..5774e60df 100644 --- a/docs/content/reference/routing-configuration/http/load-balancing/serverstransport.md +++ b/docs/content/reference/routing-configuration/http/load-balancing/serverstransport.md @@ -94,19 +94,20 @@ labels: ## Configuration Options -| Field | Description | Default | Required | -|:------|:----------------------------------------------------------|:---------------------|:---------| -| `serverName` | Configures the server name that will be used as the SNI. | "" | No | -| `certificates` | Defines the list of certificates (as file paths, or data bytes) that will be set as client certificates for mTLS. | [] | No | -| `insecureSkipVerify` | Controls whether the server's certificate chain and host name is verified. | false | No | -| `rootcas` | Set of root certificate authorities to use when verifying server certificates. (for mTLS connections). | [] | No | -| `maxIdleConnsPerHost` | Maximum idle (keep-alive) connections to keep per-host. | 200 | No | -| `disableHTTP2` | Disables HTTP/2 for connections with servers. | false | No | -| `peerCertURI` | Defines the URI used to match against SAN URIs during the server's certificate verification. | "" | No | -| `forwardingTimeouts.dialTimeout` | Amount of time to wait until a connection to a server can be established.
0 = no timeout | 30s | No | -| `forwardingTimeouts.responseHeaderTimeout` | Amount of time to wait for a server's response headers after fully writing the request (including its body, if any).
0 = no timeout | 0s | No | -| `forwardingTimeouts.idleConnTimeout` | Maximum amount of time an idle (keep-alive) connection will remain idle before closing itself.
0 = no timeout | 90s | No | -| `forwardingTimeouts.readIdleTimeout` | Defines the timeout after which a health check using ping frame will be carried out if no frame is received on the HTTP/2 connection. | 0s | No | -| `forwardingTimeouts.pingTimeout` | Defines the timeout after which the HTTP/2 connection will be closed if a response to ping is not received. | 15s | No | -| `spiffe.ids` | Defines the allowed SPIFFE IDs.
This takes precedence over the SPIFFE TrustDomain. | [] | No | -| `spiffe.trustDomain` | Defines the SPIFFE trust domain. | "" | No | +| Field | Description | Default | Required | +|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------|:--------|:---------| +| `serverName` | Configures the server name that will be used as the SNI. | "" | No | +| `certificates` | Defines the list of certificates (as file paths, or data bytes) that will be set as client certificates for mTLS. | [] | No | +| `insecureSkipVerify` | Controls whether the server's certificate chain and host name is verified. | false | No | +| `rootcas` | Set of root certificate authorities to use when verifying server certificates. (for mTLS connections). | [] | No | +| `maxIdleConnsPerHost` | Maximum idle (keep-alive) connections to keep per-host. | 200 | No | +| `disableHTTP2` | Disables HTTP/2 for connections with servers. | false | No | +| `peerCertURI` | Defines the URI used to match against SAN URIs during the server's certificate verification. | "" | No | +| `forwardingTimeouts.dialTimeout` | Amount of time to wait until a connection to a server can be established.
0 = no timeout | 30s | No | +| `forwardingTimeouts.responseHeaderTimeout` | Amount of time to wait for a server's response headers after fully writing the request (including its body, if any).
0 = no timeout | 0s | No | +| `forwardingTimeouts.idleConnTimeout` | Maximum amount of time an idle (keep-alive) connection will remain idle before closing itself.
0 = no timeout | 90s | No | +| `forwardingTimeouts.readIdleTimeout` | Defines the timeout after which a health check using ping frame will be carried out if no frame is received on the HTTP/2 connection. | 0s | No | +| `forwardingTimeouts.pingTimeout` | Defines the timeout after which the HTTP/2 connection will be closed if a response to ping is not received. | 15s | No | +| `spiffe` | Defines the SPIFFE configuration. An empty `spiffe` section enables SPIFFE (that allows any SPIFFE ID). | | No | +| `spiffe.ids` | Defines the allowed SPIFFE IDs.
This takes precedence over the SPIFFE TrustDomain. | [] | No | +| `spiffe.trustDomain` | Defines the SPIFFE trust domain. | "" | No | diff --git a/docs/content/reference/routing-configuration/http/routing/router.md b/docs/content/reference/routing-configuration/http/routing/router.md index 62a9b6064..2e9a7eb56 100644 --- a/docs/content/reference/routing-configuration/http/routing/router.md +++ b/docs/content/reference/routing-configuration/http/routing/router.md @@ -23,6 +23,11 @@ http: - "ratelimit" tls: certResolver: "letsencrypt" + options: "modern" + domains: + - main: "example.com" + sans: + - "www.example.com" observability: metrics: true accessLogs: true @@ -41,6 +46,11 @@ http: [http.routers.my-router.tls] certResolver = "letsencrypt" + options = "modern" + + [[http.routers.my-router.tls.domains]] + main = "example.com" + sans = ["www.example.com"] [http.routers.my-router.observability] metrics = true @@ -56,6 +66,9 @@ labels: - "traefik.http.routers.my-router.middlewares=auth,ratelimit" - "traefik.http.routers.my-router.service=my-service" - "traefik.http.routers.my-router.tls.certresolver=letsencrypt" + - "traefik.http.routers.my-router.tls.options=modern" + - "traefik.http.routers.my-router.tls.domains[0].main=example.com" + - "traefik.http.routers.my-router.tls.domains[0].sans=www.example.com" - "traefik.http.routers.my-router.observability.metrics=true" - "traefik.http.routers.my-router.observability.accessLogs=true" - "traefik.http.routers.my-router.observability.tracing=true" @@ -70,6 +83,9 @@ labels: "traefik.http.routers.my-router.middlewares=auth,ratelimit", "traefik.http.routers.my-router.service=my-service", "traefik.http.routers.my-router.tls.certresolver=letsencrypt", + "traefik.http.routers.my-router.tls.options=modern", + "traefik.http.routers.my-router.tls.domains[0].main=example.com", + "traefik.http.routers.my-router.tls.domains[0].sans=www.example.com", "traefik.http.routers.my-router.observability.metrics=true", "traefik.http.routers.my-router.observability.accessLogs=true", "traefik.http.routers.my-router.observability.tracing=true" @@ -79,18 +95,22 @@ labels: ## Configuration Options -| Field | Description | Default | Required | -|------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------|----------| -| `entryPoints` | The list of entry points to which the router is attached. If not specified, HTTP routers are attached to all entry points. | All entry points | No | -| `rule` | Rules are a set of matchers configured with values, that determine if a particular request matches specific criteria. If the rule is verified, the router becomes active, calls middlewares, and then forwards the request to the service. See [Rules & Priority](./rules-and-priority.md) for details. | | Yes | -| `priority` | To avoid path overlap, routes are sorted, by default, in descending order using rules length. The priority is directly equal to the length of the rule, and so the longest length has the highest priority. A value of `0` for the priority is ignored. See [Rules & Priority](./rules-and-priority.md) for details. | Rule length | No | -| `middlewares` | The list of middlewares that are applied to the router. Middlewares are applied in the order they are declared. See [Middlewares overview](../middlewares/overview.md) for available middlewares. | | No | -| `tls` | TLS configuration for the router. When specified, the router will only handle HTTPS requests. See [TLS overview](../tls/overview.md) for detailed TLS configuration. | | No | -| `observability` | Observability configuration for the router. Allows fine-grained control over access logs, metrics, and tracing per router. See [Observability](./observability.md) for details. | Inherited from entry points | No | -| `service` | The name of the service that will handle the matched requests. Services can be load balancer services, weighted round robin, mirroring, or failover services. See [Service](../load-balancing/service.md) for details.| | Yes | - +| Field | Description | Default | Required | +|----------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------|----------| +| `entryPoints` | The list of entry points to which the router is attached. If not specified, HTTP routers are attached to all entry points. | All entry points | No | +| `rule` | Rules are a set of matchers configured with values, that determine if a particular request matches specific criteria. If the rule is verified, the router becomes active, calls middlewares, and then forwards the request to the service. See [Rules & Priority](./rules-and-priority.md) for details. | | Yes | +| `priority` | To avoid path overlap, routes are sorted, by default, in descending order using rules length. The priority is directly equal to the length of the rule, and so the longest length has the highest priority. A value of `0` for the priority is ignored. See [Rules & Priority](./rules-and-priority.md) for details. | Rule length | No | +| `middlewares` | The list of middlewares that are applied to the router. Middlewares are applied in the order they are declared. See [Middlewares overview](../middlewares/overview.md) for available middlewares. | | No | +| `tls` | TLS configuration for the router. When specified, the router will only handle HTTPS requests. | | No | +| `tls.certResolver` | The name of the certificate resolver to use for automatic certificate generation. See [Certificate Resolver](../tls/overview.md#certificate-resolver) for details. | | No | +| `tls.options` | The name of the TLS options to use for configuring TLS parameters (cipher suites, min/max TLS version, client authentication, etc.). See [TLS Options](../tls/tls-options.md) for detailed configuration. | `default` | No | +| `tls.domains` | List of domains and Subject Alternative Names (SANs) for explicit certificate domain specification. When using ACME certificate resolvers, domains are automatically extracted from router rules, making this option optional. | | No | +| `observability` | Observability configuration for the router. Allows fine-grained control over access logs, metrics, and tracing per router. See [Observability](./observability.md) for details. | Inherited from entry points | No | +| `service` | The name of the service that will handle the matched requests. Services can be load balancer services, weighted round robin, mirroring, or failover services. See [Service](../load-balancing/service.md) for details. | | Yes | ## Router Naming - The character `@` is not authorized in the router name - In provider-specific configurations (Docker, Kubernetes), router names are often auto-generated based on service names and rules + +{!traefik-for-business-applications.md!} diff --git a/docs/content/reference/routing-configuration/http/tls/overview.md b/docs/content/reference/routing-configuration/http/tls/overview.md index 3c9a3b712..c1e1a6892 100644 --- a/docs/content/reference/routing-configuration/http/tls/overview.md +++ b/docs/content/reference/routing-configuration/http/tls/overview.md @@ -1,10 +1,103 @@ --- -title: "Traefik TLS Documentation" -description: "Learn how to configure the transport layer security (TLS) connection in Traefik Proxy. Read the technical documentation." +title: "Traefik HTTP TLS Documentation" +description: "Learn how to configure the transport layer security (TLS) connection for HTTP services in Traefik Proxy. Read the technical documentation." --- -Traefik's TLS configuration defines how TLS negotiation is handled for incoming connections. +## General -The next section of this documentation explains how to configure TLS connections through a definition in the dynamic configuration and how to configure TLS options, and certificates stores. +When an HTTP router is configured to handle HTTPS traffic, include a `tls` field in its definition. +This field tells Traefik that the router should process only TLS requests and ignore non-TLS traffic. + +By default, an HTTP router with a TLS field will terminate the TLS connections, +meaning that it will send decrypted data to the services. +The TLS configuration provides several options for fine-tuning the TLS behavior, +including automatic certificate generation, custom TLS options, and explicit domain specification. + +## Configuration Example + +```yaml tab="Structured (YAML)" +http: + routers: + my-https-router: + rule: "Host(`example.com`) && Path(`/api`)" + service: "my-http-service" + tls: + certResolver: "letsencrypt" + options: "modern-tls" + domains: + - main: "example.com" + sans: + - "www.example.com" + - "api.example.com" +``` + +```toml tab="Structured (TOML)" +[http.routers.my-https-router] + rule = "Host(`example.com`) && Path(`/api`)" + service = "my-http-service" + + [http.routers.my-https-router.tls] + certResolver = "letsencrypt" + options = "modern-tls" + + [[http.routers.my-https-router.tls.domains]] + main = "example.com" + sans = ["www.example.com", "api.example.com"] +``` + +```yaml tab="Labels" +labels: + - "traefik.http.routers.my-https-router.rule=Host(`example.com`) && Path(`/api`)" + - "traefik.http.routers.my-https-router.service=my-http-service" + - "traefik.http.routers.my-https-router.tls=true" + - "traefik.http.routers.my-https-router.tls.certresolver=letsencrypt" + - "traefik.http.routers.my-https-router.tls.options=modern-tls" + - "traefik.http.routers.my-https-router.tls.domains[0].main=example.com" + - "traefik.http.routers.my-https-router.tls.domains[0].sans=www.example.com,api.example.com" +``` + +```json tab="Tags" +{ + "Tags": [ + "traefik.http.routers.my-https-router.rule=Host(`example.com`) && Path(`/api`)", + "traefik.http.routers.my-https-router.service=my-http-service", + "traefik.http.routers.my-https-router.tls=true", + "traefik.http.routers.my-https-router.tls.certresolver=letsencrypt", + "traefik.http.routers.my-https-router.tls.options=modern-tls", + "traefik.http.routers.my-https-router.tls.domains[0].main=example.com", + "traefik.http.routers.my-https-router.tls.domains[0].sans=www.example.com,api.example.com" + ] +} +``` + +## Configuration Options + +| Field | Description | Default | Required | +|:-----------------------------------------------------------------------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:----------|:---------| +| `options` | The name of the TLS options to use for configuring TLS parameters (cipher suites, min/max TLS version, client authentication, etc.). See [TLS Options](./tls-options.md) for detailed configuration. | `default` | No | +| `certResolver` | The name of the certificate resolver to use for automatic certificate generation via ACME providers (such as Let's Encrypt). See the [Certificate Resolver](./#certificate-resolver) section for more details. | "" | No | +| `domains` | List of domains and Subject Alternative Names (SANs) for explicit certificate domain specification. See the [Custom Domains](./#custom-domains) section for more details. | [] | No | + +## Certificate Resolver + +The `tls.certResolver` option allows you to specify a certificate resolver for automatic certificate generation via ACME providers (such as Let's Encrypt). + +When a certificate resolver is configured for a router, +Traefik will automatically obtain and manage TLS certificates for the domains specified in the router's rule (in the `Host` matcher) or in the `tls.domains` configuration (with `tls.domains` taking precedence). + +!!! important "Prerequisites" + + - Certificate resolvers must be defined in the [static configuration](../../../install-configuration/tls/certificate-resolvers/acme.md) + - The router must have `tls` enabled + - An ACME challenge type must be configured for the certificate resolver + +## Custom Domains + +When using ACME certificate resolvers, domains are automatically extracted from router rules, +but the `tls.domains` option allows you to explicitly specify the domains and Subject Alternative Names (SANs) for which certificates should be generated. + +This provides fine-grained control over certificate generation and takes precedence over domains automatically extracted from router rules. + +Every domain must have A/AAAA records pointing to Traefik. {!traefik-for-business-applications.md!} diff --git a/docs/content/reference/routing-configuration/kubernetes/crd/tcp/ingressroutetcp.md b/docs/content/reference/routing-configuration/kubernetes/crd/tcp/ingressroutetcp.md index 1b35ff485..90a64e771 100644 --- a/docs/content/reference/routing-configuration/kubernetes/crd/tcp/ingressroutetcp.md +++ b/docs/content/reference/routing-configuration/kubernetes/crd/tcp/ingressroutetcp.md @@ -3,7 +3,7 @@ title: "Kubernetes IngressRouteTCP" description: "An IngressRouteTCP is a Traefik CRD is in charge of connecting incoming TCP connections to the Services that can handle them." --- -`IngressRouteTCP` is the CRD implementation of a [Traefik TCP router](../../../tcp/router/rules-and-priority.md). +`IngressRouteTCP` is the CRD implementation of a [Traefik TCP router](../../../tcp/routing/rules-and-priority.md). Before creating `IngressRouteTCP` objects, you need to apply the [Traefik Kubernetes CRDs](https://doc.traefik.io/traefik/reference/dynamic-configuration/kubernetes-crd/#definitions) to your Kubernetes cluster. @@ -39,7 +39,6 @@ spec: serversTransport: transport nativeLB: true nodePortLB: true - tls: false tls: secretName: supersecret @@ -57,33 +56,33 @@ spec: ## Configuration Options -| Field | Description | Default | Required | -|-------------------------------------|-----------------------------|-------------------------------------------|-----------------------| -| `entryPoints` | List of entrypoints names. | | No | -| `routes` | List of routes. | | Yes | -| `routes[n].match` | Defines the [rule](../../../tcp/router/rules-and-priority.md#rules) of the underlying router. | | Yes | -| `routes[n].priority` | Defines the [priority](../../../tcp/router/rules-and-priority.md#priority) to disambiguate rules of the same length, for route matching. | | No | -| `routes[n].middlewares[n].name` | Defines the [MiddlewareTCP](./middlewaretcp.md) name. | | Yes | -| `routes[n].middlewares[n].namespace` | Defines the [MiddlewareTCP](./middlewaretcp.md) namespace. | ""| No| -| `routes[n].services` | List of [Kubernetes service](https://kubernetes.io/docs/concepts/services-networking/service/) definitions. | | No | -| `routes[n].services[n].name` | Defines the name of a [Kubernetes service](https://kubernetes.io/docs/concepts/services-networking/service/). | | Yes | -| `routes[n].services[n].port` | Defines the port of a [Kubernetes service](https://kubernetes.io/docs/concepts/services-networking/service/). This can be a reference to a named port.| | Yes | -| `routes[n].services[n].weight` | Defines the weight to apply to the server load balancing. | 1 | No | -| `routes[n].services[n].proxyProtocol` | Defines the [PROXY protocol](../../../../install-configuration/entrypoints.md#proxyprotocol-and-load-balancers) configuration. | | No | -| `routes[n].services[n].proxyProtocol.version` | Defines the [PROXY protocol](../../../../install-configuration/entrypoints.md#proxyprotocol-and-load-balancers) version. | | No | -| `routes[n].services[n].serversTransport` | Defines the [ServersTransportTCP](./serverstransporttcp.md).
The `ServersTransport` namespace is assumed to be the [Kubernetes service](https://kubernetes.io/docs/concepts/services-networking/service/) namespace. | | No | -| `routes[n].services[n].nativeLB` | Controls, when creating the load-balancer, whether the LB's children are directly the pods IPs or if the only child is the Kubernetes Service clusterIP. See [here](#nativelb) for more information. | false | No | +| Field | Description | Default | Required | +|-------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------|-----------------------| +| `entryPoints` | List of entrypoints names. | | No | +| `routes` | List of routes. | | Yes | +| `routes[n].match` | Defines the [rule](../../../tcp/routing/rules-and-priority.md#rules) of the underlying router. | | Yes | +| `routes[n].priority` | Defines the [priority](../../../tcp/routing/rules-and-priority.md#priority-calculation) to disambiguate rules of the same length, for route matching. | | No | +| `routes[n].middlewares[n].name` | Defines the [MiddlewareTCP](./middlewaretcp.md) name. | | Yes | +| `routes[n].middlewares[n].namespace` | Defines the [MiddlewareTCP](./middlewaretcp.md) namespace. | ""| No| +| `routes[n].services` | List of [Kubernetes service](https://kubernetes.io/docs/concepts/services-networking/service/) definitions. | | No | +| `routes[n].services[n].name` | Defines the name of a [Kubernetes service](https://kubernetes.io/docs/concepts/services-networking/service/). | | Yes | +| `routes[n].services[n].port` | Defines the port of a [Kubernetes service](https://kubernetes.io/docs/concepts/services-networking/service/). This can be a reference to a named port. | | Yes | +| `routes[n].services[n].weight` | Defines the weight to apply to the server load balancing. | 1 | No | +| `routes[n].services[n].proxyProtocol` | Defines the [PROXY protocol](../../../../install-configuration/entrypoints.md#proxyprotocol-and-load-balancers) configuration. | | No | +| `routes[n].services[n].proxyProtocol.version` | Defines the [PROXY protocol](../../../../install-configuration/entrypoints.md#proxyprotocol-and-load-balancers) version. | | No | +| `routes[n].services[n].serversTransport` | Defines the [ServersTransportTCP](./serverstransporttcp.md).
The `ServersTransport` namespace is assumed to be the [Kubernetes service](https://kubernetes.io/docs/concepts/services-networking/service/) namespace. | | No | +| `routes[n].services[n].nativeLB` | Controls, when creating the load-balancer, whether the LB's children are directly the pods IPs or if the only child is the Kubernetes Service clusterIP. See [here](#nativelb) for more information. | false | No | | `routes[n].services[n].nodePortLB` | Controls, when creating the load-balancer, whether the LB's children are directly the nodes internal IPs using the nodePort when the service type is `NodePort`. It allows services to be reachable when Traefik runs externally from the Kubernetes cluster but within the same network of the nodes. | false | No | -| `tls` | Defines [TLS](../../../../install-configuration/tls/certificate-resolvers/overview.md) certificate configuration. | | No | -| `tls.secretName` | Defines the [secret](https://kubernetes.io/docs/concepts/configuration/secret/) name used to store the certificate (in the `IngressRoute` namespace). | "" | No | -| `tls.options` | Defines the reference to a [TLSOption](../http/tlsoption.md). | "" | No | -| `tls.options.name` | Defines the [TLSOption](../http/tlsoption.md) name. | "" | No | -| `tls.options.namespace` | Defines the [TLSOption](../http/tlsoption.md) namespace. | "" | No | -| `tls.certResolver` | Defines the reference to a [CertResolver](../../../../install-configuration/tls/certificate-resolvers/overview.md). | "" | No | -| `tls.domains` | List of domains. | "" | No | -| `tls.domains[n].main` | Defines the main domain name. | "" | No | -| `tls.domains[n].sans` | List of SANs (alternative domains). | "" | No | -| `tls.passthrough` | If `true`, delegates the TLS termination to the backend. | false | No | +| `tls` | Defines [TLS](../../../../install-configuration/tls/certificate-resolvers/overview.md) certificate configuration. | | No | +| `tls.secretName` | Defines the [secret](https://kubernetes.io/docs/concepts/configuration/secret/) name used to store the certificate (in the `IngressRoute` namespace). | "" | No | +| `tls.options` | Defines the reference to a [TLSOption](tlsoption.md). | "" | No | +| `tls.options.name` | Defines the [TLSOption](tlsoption.md) name. | "" | No | +| `tls.options.namespace` | Defines the [TLSOption](tlsoption.md) namespace. | "" | No | +| `tls.certResolver` | Defines the reference to a [CertResolver](../../../../install-configuration/tls/certificate-resolvers/overview.md). | "" | No | +| `tls.domains` | List of domains. | "" | No | +| `tls.domains[n].main` | Defines the main domain name. | "" | No | +| `tls.domains[n].sans` | List of SANs (alternative domains). | "" | No | +| `tls.passthrough` | If `true`, delegates the TLS termination to the backend. | false | No | ### ExternalName Service diff --git a/docs/content/reference/routing-configuration/kubernetes/crd/udp/ingressrouteudp.md b/docs/content/reference/routing-configuration/kubernetes/crd/udp/ingressrouteudp.md index 9dd576470..eadfd1773 100644 --- a/docs/content/reference/routing-configuration/kubernetes/crd/udp/ingressrouteudp.md +++ b/docs/content/reference/routing-configuration/kubernetes/crd/udp/ingressrouteudp.md @@ -3,7 +3,7 @@ title: "IngressRouteUDP" description: "Understand the routing configuration for the Kubernetes IngressRouteUDP & Traefik CRD" --- -`IngressRouteUDP` is the CRD implementation of a [Traefik UDP router](../../../udp/router/rules-priority.md). +`IngressRouteUDP` is the CRD implementation of a [Traefik UDP router](../../../udp/routing/rules-priority.md). Before creating `IngressRouteUDP` objects, you need to apply the [Traefik Kubernetes CRDs](https://doc.traefik.io/traefik/reference/dynamic-configuration/kubernetes-crd/#definitions) to your Kubernetes cluster. diff --git a/docs/content/reference/routing-configuration/kubernetes/gateway-api.md b/docs/content/reference/routing-configuration/kubernetes/gateway-api.md index 19128303c..a25e147c4 100644 --- a/docs/content/reference/routing-configuration/kubernetes/gateway-api.md +++ b/docs/content/reference/routing-configuration/kubernetes/gateway-api.md @@ -748,7 +748,6 @@ By default, NativeLB is `false`. Note that it is possible to override the default value by using the option [`nativeLBByDefault`](../../install-configuration/providers/kubernetes/kubernetes-gateway.md) at the provider level. ```yaml ---- apiVersion: v1 kind: Service metadata: @@ -757,7 +756,10 @@ metadata: annotations: traefik.io/service.nativelb: "true" spec: -[...] + ports: + - name: web + port: 80 + ``` {!traefik-for-business-applications.md!} diff --git a/docs/content/reference/routing-configuration/other-providers/consul-catalog.md b/docs/content/reference/routing-configuration/other-providers/consul-catalog.md index dd33c91ac..7958a4c01 100644 --- a/docs/content/reference/routing-configuration/other-providers/consul-catalog.md +++ b/docs/content/reference/routing-configuration/other-providers/consul-catalog.md @@ -385,7 +385,7 @@ You can declare TCP Routers, Middlewares and/or Services using tags. ??? info "`traefik.tcp.routers..rule`" - See [rule](../tcp/router/rules-and-priority.md#rules) for more information. + See [rule](../tcp/routing/rules-and-priority.md#rules) for more information. ```yaml traefik.tcp.routers.mytcprouter.rule=HostSNI(`example.com`) @@ -405,7 +405,7 @@ You can declare TCP Routers, Middlewares and/or Services using tags. ``` ??? info "`traefik.tcp.routers..priority`" - See [priority](../tcp/router/rules-and-priority.md#priority) for more information. + See [priority](../tcp/routing/rules-and-priority.md#priority-calculation) for more information. ```yaml - "traefik.tcp.routers.mytcprouter.priority=42" ``` @@ -460,7 +460,7 @@ You can declare TCP Routers, Middlewares and/or Services using tags. ??? info "`traefik.tcp.routers..tls.passthrough`" - See [Passthrough](../tcp/tls.md#passthrough) for more information. + See [Passthrough](../tcp/tls.md#opt-passthrough) for more information. ```yaml traefik.tcp.routers.mytcprouter.tls.passthrough=true @@ -485,14 +485,6 @@ You can declare TCP Routers, Middlewares and/or Services using tags. traefik.tcp.services.mytcpservice.loadbalancer.server.tls=true ``` -??? info "`traefik.tcp.services..loadbalancer.proxyprotocol.version`" - - See [PROXY protocol](../tcp/service.md#proxy-protocol) for more information. - - ```yaml - traefik.tcp.services.mytcpservice.loadbalancer.proxyprotocol.version=1 - ``` - ??? info "`traefik.tcp.services..loadbalancer.serverstransport`" Allows to reference a ServersTransport resource that is defined either with the File provider or the Kubernetes CRD one. diff --git a/docs/content/reference/routing-configuration/other-providers/docker.md b/docs/content/reference/routing-configuration/other-providers/docker.md index 2d3de7ca7..a6773b190 100644 --- a/docs/content/reference/routing-configuration/other-providers/docker.md +++ b/docs/content/reference/routing-configuration/other-providers/docker.md @@ -498,7 +498,7 @@ You can declare TCP Routers and/or Services using labels. ??? info "`traefik.tcp.routers..rule`" - See [rule](../tcp/router/rules-and-priority.md#rules) for more information. + See [rule](../tcp/routing/rules-and-priority.md#rules) for more information. ```yaml "traefik.tcp.routers.mytcprouter.rule=HostSNI(`example.com`)" @@ -565,7 +565,7 @@ You can declare TCP Routers and/or Services using labels. ??? info "`traefik.tcp.routers..tls.passthrough`" - See [TLS](../tcp/tls.md#passthrough) for more information. + See [TLS](../tcp/tls.md#opt-passthrough) for more information. ```yaml "traefik.tcp.routers.mytcprouter.tls.passthrough=true" @@ -573,7 +573,7 @@ You can declare TCP Routers and/or Services using labels. ??? info "`traefik.tcp.routers..priority`" - See [priority](../tcp/router/rules-and-priority.md) for more information. + See [priority](../tcp/routing/rules-and-priority.md) for more information. ```yaml "traefik.tcp.routers.mytcprouter.priority=42" @@ -597,14 +597,6 @@ You can declare TCP Routers and/or Services using labels. "traefik.tcp.services.mytcpservice.loadbalancer.server.tls=true" ``` -??? info "`traefik.tcp.services..loadbalancer.proxyprotocol.version`" - - See [PROXY protocol](../tcp/service.md#proxy-protocol) for more information. - - ```yaml - "traefik.tcp.services.mytcpservice.loadbalancer.proxyprotocol.version=1" - ``` - ??? info "`traefik.tcp.services..loadbalancer.serverstransport`" Allows to reference a ServersTransport resource that is defined either with the File provider or the Kubernetes CRD one. diff --git a/docs/content/reference/routing-configuration/other-providers/ecs.md b/docs/content/reference/routing-configuration/other-providers/ecs.md index a62fb324f..03b4f4d45 100644 --- a/docs/content/reference/routing-configuration/other-providers/ecs.md +++ b/docs/content/reference/routing-configuration/other-providers/ecs.md @@ -454,7 +454,7 @@ You can declare TCP Routers and/or Services using labels. ??? info "`traefik.tcp.routers..tls.passthrough`" - See [Passthrough](../tcp/tls.md#passthrough) for more information. + See [Passthrough](../tcp/tls.md#opt-passthrough) for more information. ```yaml traefik.tcp.routers.mytcprouter.tls.passthrough=true @@ -462,7 +462,7 @@ You can declare TCP Routers and/or Services using labels. ??? info "`traefik.tcp.routers..priority`" - See [priority](../tcp/router/rules-and-priority.md#priority) for more information. + See [priority](../tcp/routing/rules-and-priority.md#priority-calculation) for more information. ```yaml traefik.tcp.routers.mytcprouter.priority=42 @@ -494,14 +494,6 @@ You can declare TCP Routers and/or Services using labels. traefik.http.services.myservice.loadbalancer.server.weight=42 ``` -??? info "`traefik.tcp.services..loadbalancer.proxyprotocol.version`" - - See [PROXY protocol](../tcp/service.md#proxy-protocol) for more information. - - ```yaml - traefik.tcp.services.mytcpservice.loadbalancer.proxyprotocol.version=1 - ``` - ??? info "`traefik.tcp.services..loadbalancer.serverstransport`" Allows to reference a ServersTransport resource that is defined either with the File provider or the Kubernetes CRD one. diff --git a/docs/content/reference/routing-configuration/other-providers/kv.md b/docs/content/reference/routing-configuration/other-providers/kv.md index dcc4cdef9..8f11d50ba 100644 --- a/docs/content/reference/routing-configuration/other-providers/kv.md +++ b/docs/content/reference/routing-configuration/other-providers/kv.md @@ -140,7 +140,7 @@ You can declare TCP Routers and/or Services using KV. | `traefik/tcp/routers/mytcprouter/tls/domains/0/sans/1` | See [TLS](../tcp/tls.md) for more information. | `dev.example.org` | | `traefik/tcp/routers/mytcprouter/tls/options` | See [TLS](../tcp/tls.md) for more information. | `foobar` | | `traefik/tcp/routers/mytcprouter/tls/passthrough` | See [TLS](../tcp/tls.md) for more information. | `true` | -| `traefik/tcp/routers/mytcprouter/priority` | See [priority](../tcp/router/rules-and-priority.md#priority) for more information. | `42` | +| `traefik/tcp/routers/mytcprouter/priority` | See [priority](../tcp/routing/rules-and-priority.md#priority-calculation) for more information. | `42` | #### Services @@ -148,10 +148,9 @@ You can declare TCP Routers and/or Services using KV. |--------------------------------------------------------------------|--------------------------------------------------------------------|------------------| | `traefik/tcp/services/mytcpservice/loadbalancer/servers/0/address` | See [servers](../tcp/service.md#servers-load-balancer) for more information. | `xx.xx.xx.xx:xx` | | `traefik/tcp/services/mytcpservice/loadbalancer/servers/0/tls` | See [servers](../tcp/service.md#servers-load-balancer) for more information. | `true` | -| `traefik/tcp/services/mytcpservice/loadbalancer/proxyprotocol/version` | See [PROXY protocol](../tcp/service.md#proxy-protocol) for more information. | `1` | | `traefik/tcp/services/myservice/loadbalancer/serverstransport` | Allows to reference a ServersTransport resource that is defined either with the File provider or the Kubernetes CRD one.
See [serverstransport](../tcp/serverstransport.md) for more information. | `foobar@file` | | `traefik/tcp/services//weighted/services/0/name` | See [Service](../tcp/service.md#weighted-round-robin) for more information. | `foobar` | -| `traefik/tcp/services//weighted/services/0/weight` | See [Service](../tcp/service.md#weighted-round-robin-wrr) for more information. | `42` | +| `traefik/tcp/services//weighted/services/0/weight` | See [Service](../tcp/service.md#weighted-round-robin) for more information. | `42` | #### Middleware @@ -205,8 +204,8 @@ You can declare UDP Routers and/or Services using KV. | Key (Path) | Description | Value | |------------------------------------------------------------------|------------------------------------------------------------------|-------| -| `traefik/udp/routers/myudprouter/entrypoints/0` | See [UDP Router](../udp/router/rules-priority.md#entrypoints) for more information. | `foobar` | -| `traefik/udp/routers/myudprouter/service` | See [UDP Router](../udp/router/rules-priority.md#configuration-example) for more information. | `foobar` | +| `traefik/udp/routers/myudprouter/entrypoints/0` | See [UDP Router](../udp/routing/rules-priority.md#entrypoints) for more information. | `foobar` | +| `traefik/udp/routers/myudprouter/service` | See [UDP Router](../udp/routing/rules-priority.md#configuration-example) for more information. | `foobar` | #### Services diff --git a/docs/content/reference/routing-configuration/other-providers/nomad.md b/docs/content/reference/routing-configuration/other-providers/nomad.md index a9ec538c0..18c962ed7 100644 --- a/docs/content/reference/routing-configuration/other-providers/nomad.md +++ b/docs/content/reference/routing-configuration/other-providers/nomad.md @@ -377,7 +377,7 @@ You can declare TCP Routers and/or Services using tags. ??? info "`traefik.tcp.routers..rule`" - See [rule](../tcp/router/rules-and-priority.md#rules) for more information. + See [rule](../tcp/routing/rules-and-priority.md#rules) for more information. ```yaml traefik.tcp.routers.mytcprouter.rule=HostSNI(`example.com`) @@ -398,7 +398,7 @@ You can declare TCP Routers and/or Services using tags. ??? info "`traefik.tcp.routers..priority`" - See [priority](../tcp/router/rules-and-priority.md#priority) for more information. + See [priority](../tcp/routing/rules-and-priority.md#priority-calculation) for more information. ```yaml traefik.tcp.routers.myrouter.priority=42 @@ -454,7 +454,7 @@ You can declare TCP Routers and/or Services using tags. ??? info "`traefik.tcp.routers..tls.passthrough`" - See [Passthrough](../tcp/tls.md#passthrough) for more information. + See [Passthrough](../tcp/tls.md#opt-passthrough) for more information. ```yaml traefik.tcp.routers.mytcprouter.tls.passthrough=true @@ -478,14 +478,6 @@ You can declare TCP Routers and/or Services using tags. traefik.tcp.services.mytcpservice.loadbalancer.server.tls=true ``` -??? info "`traefik.tcp.services..loadbalancer.proxyprotocol.version`" - - See [PROXY protocol](../tcp/service.md#proxy-protocol) for more information. - - ```yaml - traefik.tcp.services.mytcpservice.loadbalancer.proxyprotocol.version=1 - ``` - ??? info "`traefik.tcp.services..loadbalancer.serverstransport`" Allows to reference a ServersTransport resource that is defined either with the File provider or the Kubernetes CRD one. diff --git a/docs/content/reference/routing-configuration/other-providers/swarm.md b/docs/content/reference/routing-configuration/other-providers/swarm.md index ad0877351..427484d8d 100644 --- a/docs/content/reference/routing-configuration/other-providers/swarm.md +++ b/docs/content/reference/routing-configuration/other-providers/swarm.md @@ -520,7 +520,7 @@ You can declare TCP Routers and/or Services using labels. ??? info "`traefik.tcp.routers..rule`" - See [rule](../tcp/router/rules-and-priority.md#rules) for more information. + See [rule](../tcp/routing/rules-and-priority.md#rules) for more information. ```yaml - "traefik.tcp.routers.mytcprouter.rule=HostSNI(`example.com`)" @@ -589,7 +589,7 @@ You can declare TCP Routers and/or Services using labels. ??? info "`traefik.tcp.routers..tls.passthrough`" - See [Passthrough](../tcp/tls.md#passthrough) for more information. + See [Passthrough](../tcp/tls.md#opt-passthrough) for more information. ```yaml - "traefik.tcp.routers.mytcprouter.tls.passthrough=true" @@ -597,7 +597,7 @@ You can declare TCP Routers and/or Services using labels. ??? info "`traefik.tcp.routers..priority`" - See [priority](../tcp/router/rules-and-priority.md) for more information. + See [priority](../tcp/routing/rules-and-priority.md) for more information. ```yaml - "traefik.tcp.routers.myrouter.priority=42" @@ -621,14 +621,6 @@ You can declare TCP Routers and/or Services using labels. - "traefik.tcp.services.mytcpservice.loadbalancer.server.tls=true" ``` -??? info "`traefik.tcp.services..loadbalancer.proxyprotocol.version`" - - See [PROXY protocol](../tcp/service.md#proxy-protocol) for more information. - - ```yaml - - "traefik.tcp.services.mytcpservice.loadbalancer.proxyprotocol.version=1" - ``` - ??? info "`traefik.tcp.services..loadbalancer.serverstransport`" Allows to reference a ServersTransport resource that is defined either with the File provider or the Kubernetes CRD one. diff --git a/docs/content/reference/routing-configuration/tcp/routing/router.md b/docs/content/reference/routing-configuration/tcp/routing/router.md index 2c8a8efc4..4761ebf5c 100644 --- a/docs/content/reference/routing-configuration/tcp/routing/router.md +++ b/docs/content/reference/routing-configuration/tcp/routing/router.md @@ -26,6 +26,11 @@ tcp: tls: passthrough: false certResolver: "letsencrypt" + options: "modern-tls" + domains: + - main: "example.com" + sans: + - "www.example.com" service: my-tcp-service ``` @@ -41,6 +46,11 @@ tcp: [tcp.routers.my-tcp-router.tls] passthrough = false certResolver = "letsencrypt" + options = "modern-tls" + + [[tcp.routers.my-tcp-router.tls.domains]] + main = "example.com" + sans = ["www.example.com"] ``` ```yaml tab="Labels" @@ -51,6 +61,9 @@ labels: - "traefik.tcp.routers.my-tcp-router.middlewares=tcp-ipallowlist" - "traefik.tcp.routers.my-tcp-router.tls.certresolver=letsencrypt" - "traefik.tcp.routers.my-tcp-router.tls.passthrough=false" + - "traefik.tcp.routers.my-tcp-router.tls.options=modern-tls" + - "traefik.tcp.routers.my-tcp-router.tls.domains[0].main=example.com" + - "traefik.tcp.routers.my-tcp-router.tls.domains[0].sans=www.example.com" - "traefik.tcp.routers.my-tcp-router.service=my-tcp-service" ``` @@ -63,6 +76,9 @@ labels: "traefik.tcp.routers.my-tcp-router.middlewares=tcp-ipallowlist", "traefik.tcp.routers.my-tcp-router.tls.certresolver=letsencrypt", "traefik.tcp.routers.my-tcp-router.tls.passthrough=false", + "traefik.tcp.routers.my-tcp-router.tls.options=modern-tls", + "traefik.tcp.routers.my-tcp-router.tls.domains[0].main=example.com", + "traefik.tcp.routers.my-tcp-router.tls.domains[0].sans=www.example.com", "traefik.tcp.routers.my-tcp-router.service=my-tcp-service" ] } @@ -70,17 +86,19 @@ labels: ## Configuration Options -| Field | Description | Default | Required | -|------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------|----------| -| `entryPoints` | The list of entry points to which the router is attached. If not specified, TCP routers are attached to all TCP entry points. | All TCP entry points | No | -| `rule` | Rules are a set of matchers configured with values, that determine if a particular connection matches specific criteria. If the rule is verified, the router becomes active, calls middlewares, and then forwards the connection to the service. See [Rules & Priority](./rules-and-priority.md) for details. | | Yes | -| `priority` | To avoid rule overlap, routes are sorted, by default, in descending order using rules length. The priority is directly equal to the length of the rule, and so the longest length has the highest priority. A value of `0` for the priority is ignored. See [Rules & Priority](./rules-and-priority.md) for details. | Rule length | No | -| `middlewares` | The list of middlewares that are applied to the router. Middlewares are applied in the order they are declared. See [TCP Middlewares overview](../middlewares/overview.md) for available TCP middlewares. | | No | -| `tls` | TLS configuration for the router. When specified, the router will only handle TLS connections. See [TLS configuration](../tls.md) for detailed TLS options. | | No | -| `service` | The name of the service that will handle the matched connections. Services can be load balancer services or weighted round robin services. See [TCP Service](../service.md) for details. | | Yes | +| Field | Description | Default | Required | +|--------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------|----------| +| `entryPoints` | The list of entry points to which the router is attached. If not specified, TCP routers are attached to all TCP entry points. | All TCP entry points | No | +| `rule` | Rules are a set of matchers configured with values, that determine if a particular connection matches specific criteria. If the rule is verified, the router becomes active, calls middlewares, and then forwards the connection to the service. See [Rules & Priority](./rules-and-priority.md) for details. | | Yes | +| `priority` | To avoid rule overlap, routes are sorted, by default, in descending order using rules length. The priority is directly equal to the length of the rule, and so the longest length has the highest priority. A value of `0` for the priority is ignored. See [Rules & Priority](./rules-and-priority.md) for details. | Rule length | No | +| `middlewares` | The list of middlewares that are applied to the router. Middlewares are applied in the order they are declared. See [TCP Middlewares overview](../middlewares/overview.md) for available TCP middlewares. | | No | +| `tls` | TLS configuration for the router. When specified, the router will only handle TLS connections. See [TLS configuration](../tls.md) for detailed TLS options. | | No | +| `service` | The name of the service that will handle the matched connections. Services can be load balancer services or weighted round robin services. See [TCP Service](../service.md) for details. | | Yes | ## Router Naming - The character `@` is not authorized in the router name - Router names should be descriptive and follow your naming conventions - In provider-specific configurations (Docker, Kubernetes), router names are often auto-generated based on service names and rules + +{!traefik-for-business-applications.md!} diff --git a/docs/content/reference/routing-configuration/tcp/serverstransport.md b/docs/content/reference/routing-configuration/tcp/serverstransport.md index 663e60a77..b3a865f94 100644 --- a/docs/content/reference/routing-configuration/tcp/serverstransport.md +++ b/docs/content/reference/routing-configuration/tcp/serverstransport.md @@ -84,8 +84,8 @@ labels: ## Configuration Options -| Field | Description | Default | Required | -|:----------------------------------------------------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:--------|:---------| +| Field | Description | Default | Required | +|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:--------|:---------| | `serverstransport.`
`dialTimeout` | Defines the timeout when dialing the backend TCP service. If zero, no timeout exists. | 30s | No | | `serverstransport.`
`dialKeepAlive` | Defines the interval between keep-alive probes for an active network connection. | 15s | No | | `serverstransport.`
`terminationDelay` | Sets the time limit for the proxy to fully terminate connections on both sides after initiating the termination sequence, with a negative value indicating no deadline. More Information [here](#terminationdelay) | 100ms | No | @@ -97,6 +97,7 @@ labels: | `serverstransport.`
`tls`
`.insecureSkipVerify` | Controls whether the server's certificate chain and host name is verified. | false | No | | `serverstransport.`
`tls`
`.rootcas` | Defines the root certificate authorities to use when verifying server certificates. (for mTLS connections). | | No | | `serverstransport.`
`tls.`
`peerCertURI` | Defines the URI used to match against SAN URIs during the server's certificate verification. | false | No | +| `serverstransport.`
`spiffe` | Defines the SPIFFE configuration. An empty `spiffe` section enables SPIFFE (that allows any SPIFFE ID). | | No | | `serverstransport.`
`spiffe`
`.ids` | Allow SPIFFE IDs.
This takes precedence over the SPIFFE TrustDomain. | | No | | `serverstransport.`
`spiffe`
`.trustDomain` | Allow SPIFFE trust domain. | "" | No | diff --git a/docs/content/reference/routing-configuration/tcp/tls.md b/docs/content/reference/routing-configuration/tcp/tls.md index 9b8c9bd45..ccaf54dfb 100644 --- a/docs/content/reference/routing-configuration/tcp/tls.md +++ b/docs/content/reference/routing-configuration/tcp/tls.md @@ -5,7 +5,7 @@ description: "Learn how to configure the transport layer security (TLS) connecti ## General -When a router is configured to handle HTTPS traffic, include a `tls` field in its definition. This field tells Traefik that the router should process only TLS requests and ignore non-TLS traffic. +When a TCP router is configured to handle TLS traffic, include a `tls` field in its definition. This field tells Traefik that the router should process only TLS connections and ignore non-TLS traffic. By default, a router with a TLS field will terminate the TLS connections, meaning that it will send decrypted data to the services. @@ -94,11 +94,33 @@ labels: ## Configuration Options -| Field | Description | Default | Required | -|:------------------|:--------------------|:-----------------------------------------------|:---------| -| `passthrough` | Defines whether the requests should be forwarded "as is", keeping all data encrypted. | false | No | -| `options` | enables fine-grained control of the TLS parameters. It refers to a [TLS Options](../http/tls/tls-certificates.md#tls-options) and will be applied only if a `HostSNI` rule is defined. | "" | No | -| `domains` | Defines a set of SANs (alternative domains) for each main domain. Every domain must have A/AAAA records pointing to Traefik. Each domain & SAN will lead to a certificate request.| [] | No | -| `certResolver` | If defined, Traefik will try to generate certificates based on routers `Host` & `HostSNI` rules. | "" | No | +| Field | Description | Default | Required | +|:-----------------------------------------------------------------------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:--------|:---------| +| `passthrough` | Defines whether the requests should be forwarded "as is", keeping all data encrypted. | false | No | +| `options` | enables fine-grained control of the TLS parameters. It refers to a [TLS Options](../http/tls/tls-options.md) and will be applied only if a `HostSNI` rule is defined. | "" | No | +| `certResolver` | The name of the certificate resolver to use for automatic certificate generation via ACME providers (such as Let's Encrypt). See the [Certificate Resolver](./#certificate-resolver) section for more details. | "" | No | +| `domains` | List of domains and Subject Alternative Names (SANs) for explicit certificate domain specification. See the [Custom Domains](./#custom-domains) section for more details. | [] | No | + +## Certificate Resolver + +The `tls.certResolver` option allows you to specify a certificate resolver for automatic certificate generation via ACME providers (such as Let's Encrypt). + +When a certificate resolver is configured for a router, +Traefik will automatically obtain and manage TLS certificates for the domains specified in the router's rule (in the `HostSNI` matcher) or in the `tls.domains` configuration (with `tls.domains` taking precedence). + +!!! important "Prerequisites" + + - Certificate resolvers must be defined in the [static configuration](../../install-configuration/tls/certificate-resolvers/acme.md) + - The router must have `tls` enabled + - An ACME challenge type must be configured for the certificate resolver + +## Custom Domains + +When using ACME certificate resolvers, domains are automatically extracted from router rules, +but the `tls.domains` option allows you to explicitly specify the domains and Subject Alternative Names (SANs) for which certificates should be generated. + +This provides fine-grained control over certificate generation and takes precedence over domains automatically extracted from router rules. + +Every domain must have A/AAAA records pointing to Traefik. {!traefik-for-business-applications.md!} diff --git a/docs/content/reference/routing-configuration/udp/routing/router.md b/docs/content/reference/routing-configuration/udp/routing/router.md index 1061e25f6..5d4bd57e1 100644 --- a/docs/content/reference/routing-configuration/udp/routing/router.md +++ b/docs/content/reference/routing-configuration/udp/routing/router.md @@ -60,7 +60,7 @@ Even though UDP is connectionless, Traefik's UDP router implementation relies on Each session has an associated timeout that cleans up inactive sessions after a specified duration of inactivity. -Session timeout can be configured using the `entryPoints.name.udp.timeout` option in the static configuration. See [EntryPoints documentation](../../install-configuration/entrypoints.md) for details. +Session timeout can be configured using the `entryPoints.name.udp.timeout` option in the static configuration. See [EntryPoints documentation](../../../install-configuration/entrypoints.md) for details. ## Router Naming diff --git a/docs/content/user-guides/cert-manager.md b/docs/content/user-guides/cert-manager.md index e0b248003..db1afc4fe 100644 --- a/docs/content/user-guides/cert-manager.md +++ b/docs/content/user-guides/cert-manager.md @@ -56,11 +56,11 @@ The certificates can then be used in an Ingress / IngressRoute / HTTPRoute. ``` Let's see now how to use it with the various Kubernetes providers of Traefik Proxy. -The enabled providers can be seen on the [dashboard](../../operations/dashboard/) of Traefik Proxy and also in the INFO logs when Traefik Proxy starts. +The enabled providers can be seen on the [dashboard](../operations/dashboard.md) of Traefik Proxy and also in the INFO logs when Traefik Proxy starts. ### With an Ingress -To use this certificate with an Ingress, the [Kubernetes Ingress](../../providers/kubernetes-ingress/) provider has to be enabled. +To use this certificate with an Ingress, the [Kubernetes Ingress](../providers/kubernetes-ingress.md) provider has to be enabled. !!! info Traefik Helm Chart @@ -94,7 +94,7 @@ To use this certificate with an Ingress, the [Kubernetes Ingress](../../provider ### With an IngressRoute -To use this certificate with an IngressRoute, the [Kubernetes CRD](../../providers/kubernetes-crd/) provider has to be enabled. +To use this certificate with an IngressRoute, the [Kubernetes CRD](../providers/kubernetes-crd.md) provider has to be enabled. !!! info Traefik Helm Chart @@ -124,7 +124,7 @@ To use this certificate with an IngressRoute, the [Kubernetes CRD](../../provide ### With an HTTPRoute -To use this certificate with an HTTPRoute, the [Kubernetes Gateway](../../routing/providers/kubernetes-gateway/) provider has to be enabled. +To use this certificate with an HTTPRoute, the [Kubernetes Gateway](../routing/providers/kubernetes-gateway.md) provider has to be enabled. !!! info Traefik Helm Chart