homelab/traefik
1
0
Fork 0
Code Activity

Merge branch v3.5 into v3.6

Browse source
This commit is contained in:
kevinpollet 2025-11-07 15:11:08 +01:00
commit 83beb8a19c
No known key found for this signature in database
GPG key ID: 0C9A5DDD1B292453
14 changed files with 435 additions and 318 deletions
Download patch file Download diff file Expand all files Collapse all files

26
docs/content/getting-started/configuration-overview.md
View file

@ -1,6 +1,6 @@
---
title: "Traefik Configuration Documentation"
description: "Get started with Traefik Proxy. This page will introduce you to the dynamic routing and startup configurations. Read the technical documentation."
description: "Get started with Traefik Proxy. This page will introduce you to the routing and install configurations. Read the technical documentation."
---
# Configuration Introduction
@ -8,39 +8,37 @@ description: "Get started with Traefik Proxy. This page will introduce you to th
How the Magic Happens
{: .subtitle }
![Configuration](../assets/img/static-dynamic-configuration.png)
Configuration in Traefik can refer to two different things:
- The fully dynamic routing configuration (referred to as the _routing configuration_, formerly known as the _dynamic configuration_)
- The startup configuration (referred to as the _install configuration_, formerly known as the _static configuration_)
- The install (startup) configuration (formerly known as the _static configuration_)
- The routing configuration (formerly known as the _dynamic configuration_)
Elements in the install configuration_ set up connections to [providers](../providers/overview.md) and define the [entrypoints](../routing/entrypoints.md) Traefik will listen to (these elements don't change often).
Elements in the _install configuration_ set up connections to [providers](../providers/overview.md) and define the [entrypoints](../routing/entrypoints.md) Traefik will listen to (these elements don't change often).
The _dynamic configuration_ contains everything that defines how the requests are handled by your system.
The _routing configuration_ contains everything that defines how the requests are handled by your system.
This configuration can change and is seamlessly hot-reloaded, without any request interruption or connection loss.
!!! warning "Incompatible Configuration"
Please be aware that the old configurations for Traefik v1.x are NOT compatible with the v2.x config as of now.
If you are running v2, please ensure you are using a v2 configuration.
## The Dynamic Configuration
## The Routing Configuration
Traefik gets its _dynamic configuration_ from [providers](../providers/overview.md): whether an orchestrator, a service registry, or a plain old configuration file.
Traefik gets its _routing configuration_ from [providers](../providers/overview.md): whether an orchestrator, a service registry, or a plain old configuration file.
Since this configuration is specific to your infrastructure choices, we invite you to refer to the [dedicated section of this documentation](../routing/overview.md).
!!! info ""
In the [Quick Start example](../getting-started/quick-start.md), the routing configuration comes from docker in the form of labels attached to your containers.
In the [Quick Start example](../getting-started/docker.md), the whoami application routing configuration comes from docker in the form of a label attached to the whoami container.
!!! info "HTTPS Certificates also belong to the routing configuration."
You can add / update / remove them without restarting your Traefik instance.
## The Static Configuration
## The Install Configuration
There are three different, **mutually exclusive** (i.e. you can use only one at the same time), ways to define static configuration options in Traefik:
There are three different, **mutually exclusive** (i.e. you can use only one at the same time), ways to define install configuration options in Traefik:
1. In a configuration file
1. In the command-line arguments
@ -56,7 +54,7 @@ Once positioned, this option sets (and resets) all the default values of the sub
### Configuration File
At startup, Traefik searches for static configuration in a file named `traefik.yml` (or `traefik.yaml` or `traefik.toml`) in:
At startup, Traefik searches for install configuration in a file named `traefik.yml` (or `traefik.yaml` or `traefik.toml`) in:
- `/etc/traefik/`
- `$XDG_CONFIG_HOME/`
@ -86,7 +84,7 @@ Check the [CLI reference](../reference/install-configuration/configuration-optio
### Environment Variables
All available environment variables can be found in the [static configuration environment overview](../reference/install-configuration/configuration-options.md).
All available environment variables can be found in the [install configuration environment overview](../reference/install-configuration/configuration-options.md).
## Available Configuration Options

53
docs/content/reference/install-configuration/tls/certificate-resolvers/acme.md
View file

@ -73,32 +73,37 @@ certificatesResolvers:
ACME certificate resolvers have the following configuration options:
| Field | Description | Default | Required |
|:--------------------------------------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:-----------------------------------------------|:---------|
| <a id="opt-acme-email" href="#opt-acme-email" title="#opt-acme-email">`acme.email`</a> | Email address used for registration. | "" | Yes |
| <a id="opt-acme-caServer" href="#opt-acme-caServer" title="#opt-acme-caServer">`acme.caServer`</a> | CA server to use. | https://acme-v02.api.letsencrypt.org/directory | No |
| <a id="opt-acme-preferredChain" href="#opt-acme-preferredChain" title="#opt-acme-preferredChain">`acme.preferredChain`</a> | Preferred chain to use. If the CA offers multiple certificate chains, prefer the chain with an issuer matching this Subject Common Name. If no match, the default offered chain will be used. | "" | No |
| <a id="opt-acme-keyType" href="#opt-acme-keyType" title="#opt-acme-keyType">`acme.keyType`</a> | KeyType to use. | "RSA4096" | No |
| Field | Description | Default | Required |
|:------|:------------|:--------|:---------|
| <a id="opt-acme-email" href="#opt-acme-email" title="#opt-acme-email">`acme.email`</a> | Email address used for registration. | "" | Yes |
| <a id="opt-acme-caServer" href="#opt-acme-caServer" title="#opt-acme-caServer">`acme.caServer`</a> | CA server to use. | https://acme-v02.api.letsencrypt.org/directory | No |
| <a id="opt-acme-preferredChain" href="#opt-acme-preferredChain" title="#opt-acme-preferredChain">`acme.preferredChain`</a> | Preferred chain to use. If the CA offers multiple certificate chains, prefer the chain with an issuer matching this Subject Common Name. If no match, the default offered chain will be used. | "" | No |
| <a id="opt-acme-keyType" href="#opt-acme-keyType" title="#opt-acme-keyType">`acme.keyType`</a> | KeyType to use. | "RSA4096" | No |
| <a id="opt-acme-disableCommonName" href="#opt-acme-disableCommonName" title="#opt-acme-disableCommonName">`acme.disableCommonName`</a> | Disable common name inside CSR and certificates. | false | No |
| <a id="opt-acme-eab" href="#opt-acme-eab" title="#opt-acme-eab">`acme.eab`</a> | Enable external account binding. | | No |
| <a id="opt-acme-eab-kid" href="#opt-acme-eab-kid" title="#opt-acme-eab-kid">`acme.eab.kid`</a> | Key identifier from External CA. | "" | No |
| <a id="opt-acme-eab-hmacEncoded" href="#opt-acme-eab-hmacEncoded" title="#opt-acme-eab-hmacEncoded">`acme.eab.hmacEncoded`</a> | HMAC key from External CA, should be in Base64 URL Encoding without padding format. | "" | No |
| <a id="opt-acme-certificatesDuration" href="#opt-acme-certificatesDuration" title="#opt-acme-certificatesDuration">`acme.certificatesDuration`</a> | The certificates' duration in hours, exclusively used to determine renewal dates. | 2160 | No |
| <a id="opt-acme-clientTimeout" href="#opt-acme-clientTimeout" title="#opt-acme-clientTimeout">`acme.clientTimeout`</a> | Timeout for HTTP Client used to communicate with the ACME server. | 2m | No |
| <a id="opt-acme-clientResponseHeaderTimeout" href="#opt-acme-clientResponseHeaderTimeout" title="#opt-acme-clientResponseHeaderTimeout">`acme.clientResponseHeaderTimeout`</a> | Timeout for response headers for HTTP Client used to communicate with the ACME server. | 30s | No |
| <a id="opt-acme-dnsChallenge" href="#opt-acme-dnsChallenge" title="#opt-acme-dnsChallenge">`acme.dnsChallenge`</a> | Enable DNS-01 challenge. More information [here](#dnschallenge). | - | No |
| <a id="opt-acme-dnsChallenge-provider" href="#opt-acme-dnsChallenge-provider" title="#opt-acme-dnsChallenge-provider">`acme.dnsChallenge.provider`</a> | DNS provider to use. | "" | No |
| <a id="opt-acme-dnsChallenge-resolvers" href="#opt-acme-dnsChallenge-resolvers" title="#opt-acme-dnsChallenge-resolvers">`acme.dnsChallenge.resolvers`</a> | DNS servers to resolve the FQDN authority. | [] | No |
| <a id="opt-acme-dnsChallenge-propagation-delayBeforeChecks" href="#opt-acme-dnsChallenge-propagation-delayBeforeChecks" title="#opt-acme-dnsChallenge-propagation-delayBeforeChecks">`acme.dnsChallenge.propagation.delayBeforeChecks`</a> | By default, the provider will verify the TXT DNS challenge record before letting ACME verify. If `delayBeforeCheck` is greater than zero, this check is delayed for the configured duration in seconds. This is Useful if internal networks block external DNS queries. | 0s | No |
| <a id="opt-acme-dnsChallenge-propagation-disableChecks" href="#opt-acme-dnsChallenge-propagation-disableChecks" title="#opt-acme-dnsChallenge-propagation-disableChecks">`acme.dnsChallenge.propagation.disableChecks`</a> | Disables the challenge TXT record propagation checks, before notifying ACME that the DNS challenge is ready. Please note that disabling checks can prevent the challenge from succeeding. | false | No |
| <a id="opt-acme-dnsChallenge-propagation-requireAllRNS" href="#opt-acme-dnsChallenge-propagation-requireAllRNS" title="#opt-acme-dnsChallenge-propagation-requireAllRNS">`acme.dnsChallenge.propagation.requireAllRNS`</a> | Enables the challenge TXT record to be propagated to all recursive nameservers. If you have disabled authoritative nameservers checks (with `propagation.disableANSChecks`), it is recommended to check all recursive nameservers instead. | false | No |
| <a id="opt-acme-dnsChallenge-propagation-disableANSChecks" href="#opt-acme-dnsChallenge-propagation-disableANSChecks" title="#opt-acme-dnsChallenge-propagation-disableANSChecks">`acme.dnsChallenge.propagation.disableANSChecks`</a> | Disables the challenge TXT record propagation checks against authoritative nameservers. This option will skip the propagation check against the nameservers of the authority (SOA). It should be used only if the nameservers of the authority are not reachable. | false | No |
| <a id="opt-acme-httpChallenge" href="#opt-acme-httpChallenge" title="#opt-acme-httpChallenge">`acme.httpChallenge`</a> | Enable HTTP-01 challenge. More information [here](#httpchallenge). | | No |
| <a id="opt-acme-httpChallenge-entryPoint" href="#opt-acme-httpChallenge-entryPoint" title="#opt-acme-httpChallenge-entryPoint">`acme.httpChallenge.entryPoint`</a> | EntryPoint to use for the HTTP-01 challenges. Must be reachable by Let's Encrypt through port 80 | "" | Yes |
| <a id="opt-acme-httpChallenge-delay" href="#opt-acme-httpChallenge-delay" title="#opt-acme-httpChallenge-delay">`acme.httpChallenge.delay`</a> | The delay between the creation of the challenge and the validation. A value lower than or equal to zero means no delay. | 0 | No |
| <a id="opt-acme-tlsChallenge" href="#opt-acme-tlsChallenge" title="#opt-acme-tlsChallenge">`acme.tlsChallenge`</a> | Enable TLS-ALPN-01 challenge. Traefik must be reachable by Let's Encrypt through port 443. More information [here](#tlschallenge). | - | No |
| <a id="opt-acme-profile" href="#opt-acme-profile" title="#opt-acme-profile">`acme.profile`</a> | Certificate profile to use. | "" | No |
| <a id="opt-acme-caCertificates" href="#opt-acme-caCertificates" title="#opt-acme-caCertificates">`acme.caCertificates`</a> | Specify the paths to PEM encoded CA Certificates that can be used to authenticate an ACME server with an HTTPS certificate not issued by a CA in the system-wide trusted root list. | [] | No |
| <a id="opt-acme-caSystemCertPool" href="#opt-acme-caSystemCertPool" title="#opt-acme-caSystemCertPool">`acme.caSystemCertPool`</a> | Defines if the certificates pool must use a copy of the system cert pool. | false | No |
| <a id="opt-acme-caServerName" href="#opt-acme-caServerName" title="#opt-acme-caServerName">`acme.caServerName`</a> | Specify the CA server name that can be used to authenticate an ACME server with an HTTPS certificate not issued by a CA in the system-wide trusted root list. | "" | No |
| <a id="opt-acme-emailAddresses" href="#opt-acme-emailAddresses" title="#opt-acme-emailAddresses">`acme.emailAddresses`</a> | CSR email addresses to use. | "" | No |
| <a id="opt-acme-eab" href="#opt-acme-eab" title="#opt-acme-eab">`acme.eab`</a> | Enable external account binding. | | No |
| <a id="opt-acme-eab-kid" href="#opt-acme-eab-kid" title="#opt-acme-eab-kid">`acme.eab.kid`</a> | Key identifier from External CA. | "" | No |
| <a id="opt-acme-eab-hmacEncoded" href="#opt-acme-eab-hmacEncoded" title="#opt-acme-eab-hmacEncoded">`acme.eab.hmacEncoded`</a> | HMAC key from External CA, should be in Base64 URL Encoding without padding format. | "" | No |
| <a id="opt-acme-certificatesDuration" href="#opt-acme-certificatesDuration" title="#opt-acme-certificatesDuration">`acme.certificatesDuration`</a> | The certificates' duration in hours, exclusively used to determine renewal dates. | 2160 | No |
| <a id="opt-acme-clientTimeout" href="#opt-acme-clientTimeout" title="#opt-acme-clientTimeout">`acme.clientTimeout`</a> | Timeout for HTTP Client used to communicate with the ACME server. | 2m | No |
| <a id="opt-acme-clientResponseHeaderTimeout" href="#opt-acme-clientResponseHeaderTimeout" title="#opt-acme-clientResponseHeaderTimeout">`acme.clientResponseHeaderTimeout`</a> | Timeout for response headers for HTTP Client used to communicate with the ACME server. | 30s | No |
| <a id="opt-acme-dnsChallenge" href="#opt-acme-dnsChallenge" title="#opt-acme-dnsChallenge">`acme.dnsChallenge`</a> | Enable DNS-01 challenge. More information [here](#dnschallenge). | - | No |
| <a id="opt-acme-dnsChallenge-provider" href="#opt-acme-dnsChallenge-provider" title="#opt-acme-dnsChallenge-provider">`acme.dnsChallenge.provider`</a> | DNS provider to use. | "" | No |
| <a id="opt-acme-dnsChallenge-resolvers" href="#opt-acme-dnsChallenge-resolvers" title="#opt-acme-dnsChallenge-resolvers">`acme.dnsChallenge.resolvers`</a> | DNS servers to resolve the FQDN authority. | [] | No |
| <a id="opt-acme-dnsChallenge-propagation-delayBeforeChecks" href="#opt-acme-dnsChallenge-propagation-delayBeforeChecks" title="#opt-acme-dnsChallenge-propagation-delayBeforeChecks">`acme.dnsChallenge.propagation.delayBeforeChecks`</a> | By default, the provider will verify the TXT DNS challenge record before letting ACME verify. If `delayBeforeCheck` is greater than zero, this check is delayed for the configured duration in seconds. This is Useful if internal networks block external DNS queries. | 0s | No |
| <a id="opt-acme-dnsChallenge-propagation-disableChecks" href="#opt-acme-dnsChallenge-propagation-disableChecks" title="#opt-acme-dnsChallenge-propagation-disableChecks">`acme.dnsChallenge.propagation.disableChecks`</a> | Disables the challenge TXT record propagation checks, before notifying ACME that the DNS challenge is ready. Please note that disabling checks can prevent the challenge from succeeding. | false | No |
| <a id="opt-acme-dnsChallenge-propagation-requireAllRNS" href="#opt-acme-dnsChallenge-propagation-requireAllRNS" title="#opt-acme-dnsChallenge-propagation-requireAllRNS">`acme.dnsChallenge.propagation.requireAllRNS`</a> | Enables the challenge TXT record to be propagated to all recursive nameservers. If you have disabled authoritative nameservers checks (with `propagation.disableANSChecks`), it is recommended to check all recursive nameservers instead. | false | No |
| <a id="opt-acme-dnsChallenge-propagation-disableANSChecks" href="#opt-acme-dnsChallenge-propagation-disableANSChecks" title="#opt-acme-dnsChallenge-propagation-disableANSChecks">`acme.dnsChallenge.propagation.disableANSChecks`</a> | Disables the challenge TXT record propagation checks against authoritative nameservers. This option will skip the propagation check against the nameservers of the authority (SOA). It should be used only if the nameservers of the authority are not reachable. | false | No |
| <a id="opt-acme-httpChallenge" href="#opt-acme-httpChallenge" title="#opt-acme-httpChallenge">`acme.httpChallenge`</a> | Enable HTTP-01 challenge. More information [here](#httpchallenge). | | No |
| <a id="opt-acme-httpChallenge-entryPoint" href="#opt-acme-httpChallenge-entryPoint" title="#opt-acme-httpChallenge-entryPoint">`acme.httpChallenge.entryPoint`</a> | EntryPoint to use for the HTTP-01 challenges. Must be reachable by Let's Encrypt through port 80 | "" | Yes |
| <a id="opt-acme-httpChallenge-delay" href="#opt-acme-httpChallenge-delay" title="#opt-acme-httpChallenge-delay">`acme.httpChallenge.delay`</a> | The delay between the creation of the challenge and the validation. A value lower than or equal to zero means no delay. | 0 | No |
| <a id="opt-acme-tlsChallenge" href="#opt-acme-tlsChallenge" title="#opt-acme-tlsChallenge">`acme.tlsChallenge`</a> | Enable TLS-ALPN-01 challenge. Traefik must be reachable by Let's Encrypt through port 443. More information [here](#tlschallenge). | - | No |
| <a id="opt-acme-tlschallenge-delay" href="#opt-acme-tlschallenge-delay" title="#opt-acme-tlschallenge-delay">`acme.tlschallenge.delay`</a> | The delay between the creation of the challenge and the validation. A value lower than or equal to zero means no delay. | 0 | No |
| <a id="opt-acme-storage" href="#opt-acme-storage" title="#opt-acme-storage">`acme.storage`</a> | File path used for certificates storage. | "acme.json" | Yes |
| <a id="opt-acme-storage" href="#opt-acme-storage" title="#opt-acme-storage">`acme.storage`</a> | File path used for certificates storage. | "acme.json" | Yes |
## Automatic Certificate Renewal

2
docs/content/reference/routing-configuration/http/middlewares/compress.md
View file

@ -53,7 +53,7 @@ spec:
|:-----------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:--------|:---------|
| <a id="opt-excludedContentTypes" href="#opt-excludedContentTypes" title="#opt-excludedContentTypes">`excludedContentTypes`</a> | List of content types to compare the `Content-Type` header of the incoming requests and responses before compressing. <br /> The responses with content types defined in `excludedContentTypes` are not compressed. <br /> Content types are compared in a case-insensitive, whitespace-ignored manner. <br /> **The `excludedContentTypes` and `includedContentTypes` options are mutually exclusive.** | "" | No |
| <a id="opt-defaultEncoding" href="#opt-defaultEncoding" title="#opt-defaultEncoding">`defaultEncoding`</a> | specifies the default encoding if the `Accept-Encoding` header is not in the request or contains a wildcard (`*`). | "" | No |
| <a id="opt-encodings" href="#opt-encodings" title="#opt-encodings">`encodings`</a> | Specifies the list of supported compression encodings. At least one encoding value must be specified, and valid entries are `zstd` (Zstandard), `br` (Brotli), and `gzip` (Gzip). The order of the list also sets the priority, the top entry has the highest priority. | zstd, br, gzip | No |
| <a id="opt-encodings" href="#opt-encodings" title="#opt-encodings">`encodings`</a> | Specifies the list of supported compression encodings. At least one encoding value must be specified, and valid entries are `zstd` (Zstandard), `br` (Brotli), and `gzip` (Gzip). The order of the list also sets the priority, the top entry has the highest priority. | gzip, br, zstd | No |
| <a id="opt-includedContentTypes" href="#opt-includedContentTypes" title="#opt-includedContentTypes">`includedContentTypes`</a> | List of content types to compare the `Content-Type` header of the responses before compressing. <br /> The responses with content types defined in `includedContentTypes` are compressed. <br /> Content types are compared in a case-insensitive, whitespace-ignored manner.<br /> **The `excludedContentTypes` and `includedContentTypes` options are mutually exclusive.** | "" | No |
| <a id="opt-minResponseBodyBytes" href="#opt-minResponseBodyBytes" title="#opt-minResponseBodyBytes">`minResponseBodyBytes`</a> | `Minimum amount of bytes a response body must have to be compressed. <br />Responses smaller than the specified values will **not** be compressed. | 1024 | No |