New Routing Reference Documentation #11330
Open
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
sheddy-traefik
force-pushed
the
feat/reference-routing-config
branch
3 times, most recently
from
3240a8d to
44be9f2
Compare
sdelicata
added
area/documentation
status/2-needs-review
kind/enhancement
sheddy-traefik
force-pushed
the
feat/reference-routing-config
branch
2 times, most recently
from
2ce40c7 to
11f2c38
Compare
sheddy-traefik
force-pushed
the
feat/reference-routing-config
branch
4 times, most recently
from
331c5d7 to
5c2a7f9
Compare
youkoulayley
requested changes
Jan 17, 2025
Comment on lines
+19
to
+44
| | Middleware | Purpose | Area | | ||
| |-------------------------------------------|---------------------------------------------------|-----------------------------| | ||
| | [AddPrefix](addprefix.md) | Adds a Path Prefix | Path Modifier | | ||
| | [BasicAuth](basicauth.md) | Adds Basic Authentication | Security, Authentication | | ||
| | [Buffering](buffering.md) | Buffers the request/response | Request Lifecycle | | ||
| | [Chain](chain.md) | Combines multiple pieces of middleware | Misc | | ||
| | [CircuitBreaker](circuitbreaker.md) | Prevents calling unhealthy services | Request Lifecycle | | ||
| | [Compress](compress.md) | Compresses the response | Content Modifier | | ||
| | [ContentType](contenttype.md) | Handles Content-Type auto-detection | Misc | | ||
| | [DigestAuth](digestauth.md) | Adds Digest Authentication | Security, Authentication | | ||
| | [Errors](errorpages.md) | Defines custom error pages | Request Lifecycle | | ||
| | [ForwardAuth](forwardauth.md) | Delegates Authentication | Security, Authentication | | ||
| | [GrpcWeb](grpcweb.md) | Converts gRPC Web requests to HTTP/2 gRPC requests. | Reqyest | | ||
| | [Headers](headers.md) | Adds / Updates headers | Security | | ||
| | [IPAllowList](ipallowlist.md) | Limits the allowed client IPs | Security, Request lifecycle | | ||
| | [InFlightReq](inflightreq.md) | Limits the number of simultaneous connections | Security, Request lifecycle | | ||
| | [PassTLSClientCert](passtlsclientcert.md) | Adds Client Certificates in a Header | Security | | ||
| | [RateLimit](ratelimit.md) | Limits the call frequency | Security, Request lifecycle | | ||
| | [RedirectScheme](redirectscheme.md) | Redirects based on scheme | Request lifecycle | | ||
| | [RedirectRegex](redirectregex.md) | Redirects based on regex | Request lifecycle | | ||
| | [ReplacePath](replacepath.md) | Changes the path of the request | Path Modifier | | ||
| | [ReplacePathRegex](replacepathregex.md) | Changes the path of the request | Path Modifier | | ||
| | [Retry](retry.md) | Automatically retries in case of error | Request lifecycle | | ||
| | [StripPrefix](stripprefix.md) | Changes the path of the request | Path Modifier | | ||
| | [StripPrefixRegex](stripprefixregex.md) | Changes the path of the request | Path Modifier | | ||
|
|
There was a problem hiding this comment.
Suggested change
| | Middleware | Purpose | Area | | |
| |-------------------------------------------|---------------------------------------------------|-----------------------------| | |
| | [AddPrefix](addprefix.md) | Adds a Path Prefix | Path Modifier | | |
| | [BasicAuth](basicauth.md) | Adds Basic Authentication | Security, Authentication | | |
| | [Buffering](buffering.md) | Buffers the request/response | Request Lifecycle | | |
| | [Chain](chain.md) | Combines multiple pieces of middleware | Misc | | |
| | [CircuitBreaker](circuitbreaker.md) | Prevents calling unhealthy services | Request Lifecycle | | |
| | [Compress](compress.md) | Compresses the response | Content Modifier | | |
| | [ContentType](contenttype.md) | Handles Content-Type auto-detection | Misc | | |
| | [DigestAuth](digestauth.md) | Adds Digest Authentication | Security, Authentication | | |
| | [Errors](errorpages.md) | Defines custom error pages | Request Lifecycle | | |
| | [ForwardAuth](forwardauth.md) | Delegates Authentication | Security, Authentication | | |
| | [GrpcWeb](grpcweb.md) | Converts gRPC Web requests to HTTP/2 gRPC requests. | Reqyest | | |
| | [Headers](headers.md) | Adds / Updates headers | Security | | |
| | [IPAllowList](ipallowlist.md) | Limits the allowed client IPs | Security, Request lifecycle | | |
| | [InFlightReq](inflightreq.md) | Limits the number of simultaneous connections | Security, Request lifecycle | | |
| | [PassTLSClientCert](passtlsclientcert.md) | Adds Client Certificates in a Header | Security | | |
| | [RateLimit](ratelimit.md) | Limits the call frequency | Security, Request lifecycle | | |
| | [RedirectScheme](redirectscheme.md) | Redirects based on scheme | Request lifecycle | | |
| | [RedirectRegex](redirectregex.md) | Redirects based on regex | Request lifecycle | | |
| | [ReplacePath](replacepath.md) | Changes the path of the request | Path Modifier | | |
| | [ReplacePathRegex](replacepathregex.md) | Changes the path of the request | Path Modifier | | |
| | [Retry](retry.md) | Automatically retries in case of error | Request lifecycle | | |
| | [StripPrefix](stripprefix.md) | Changes the path of the request | Path Modifier | | |
| | [StripPrefixRegex](stripprefixregex.md) | Changes the path of the request | Path Modifier | | |
| | Middleware | Purpose | Area | | |
| |-------------------------------------------|-----------------------------------------------------|-----------------------------| | |
| | [AddPrefix](addprefix.md) | Adds a Path Prefix | Path Modifier | | |
| | [BasicAuth](basicauth.md) | Adds Basic Authentication | Security, Authentication | | |
| | [Buffering](buffering.md) | Buffers the request/response | Request Lifecycle | | |
| | [Chain](chain.md) | Combines multiple pieces of middleware | Misc | | |
| | [CircuitBreaker](circuitbreaker.md) | Prevents calling unhealthy services | Request Lifecycle | | |
| | [Compress](compress.md) | Compresses the response | Content Modifier | | |
| | [ContentType](contenttype.md) | Handles Content-Type auto-detection | Misc | | |
| | [DigestAuth](digestauth.md) | Adds Digest Authentication | Security, Authentication | | |
| | [Errors](errorpages.md) | Defines custom error pages | Request Lifecycle | | |
| | [ForwardAuth](forwardauth.md) | Delegates Authentication | Security, Authentication | | |
| | [GrpcWeb](grpcweb.md) | Converts gRPC Web requests to HTTP/2 gRPC requests. | Request Lifecycle | | |
| | [Headers](headers.md) | Adds / Updates headers | Security | | |
| | [IPAllowList](ipallowlist.md) | Limits the allowed client IPs | Security, Request lifecycle | | |
| | [InFlightReq](inflightreq.md) | Limits the number of simultaneous connections | Security, Request lifecycle | | |
| | [PassTLSClientCert](passtlsclientcert.md) | Adds Client Certificates in a Header | Security | | |
| | [RateLimit](ratelimit.md) | Limits the call frequency | Security, Request lifecycle | | |
| | [RedirectScheme](redirectscheme.md) | Redirects based on scheme | Request lifecycle | | |
| | [RedirectRegex](redirectregex.md) | Redirects based on regex | Request lifecycle | | |
| | [ReplacePath](replacepath.md) | Changes the path of the request | Path Modifier | | |
| | [ReplacePathRegex](replacepathregex.md) | Changes the path of the request | Path Modifier | | |
| | [Retry](retry.md) | Automatically retries in case of error | Request lifecycle | | |
| | [StripPrefix](stripprefix.md) | Changes the path of the request | Path Modifier | | |
| | [StripPrefixRegex](stripprefixregex.md) | Changes the path of the request | Path Modifier | |
| description: "In Traefik Proxy's HTTP middleware, the PassTLSClientCert adds selected data from passed client TLS certificates to headers. Read the technical documentation." | ||
| --- | ||
|
|
||
| The `passTLSClientCert` middleware adds the selected data from the passed client TLS certificate to a header |
There was a problem hiding this comment.
Suggested change
| The `passTLSClientCert` middleware adds the selected data from the passed client TLS certificate to a header | |
| The `passTLSClientCert` middleware adds the selected data from the passed client TLS certificate to a header. |
| The rate is defined by dividing `average` by `period`. | ||
| For a rate below 1 req/s, define a `period` larger than a second | ||
|
|
||
| The middleware is based on a [token bucket](https://en.wikipedia.org/wiki/Token_bucket) implementation. |
There was a problem hiding this comment.
Suggested change
| The middleware is based on a [token bucket](https://en.wikipedia.org/wiki/Token_bucket) implementation. |
It's already been said in the introduction to this page, so perhaps we don't need to repeat it?
| For a rate below 1 req/s, define a `period` larger than a second | ||
|
|
||
| The middleware is based on a [token bucket](https://en.wikipedia.org/wiki/Token_bucket) implementation. | ||
| In this analogy, the `average` and `period` parameters define the **rate** at which the bucket refills, and the `burst` is the size (volume) of the bucket |
There was a problem hiding this comment.
Suggested change
| In this analogy, the `average` and `period` parameters define the **rate** at which the bucket refills, and the `burst` is the size (volume) of the bucket | |
| In this analogy, the `average` and `period` parameters define the **rate** at which the bucket refills, and the `burst` is the size (volume) of the bucket. |
Maybe put this in the introduction after the token bucket part?
| In the example above, the middleware allows up to 100 connections in parallel (`burst`). | ||
| Each connection consumes a token, once the 100 tokens are consumed, the other ones are blocked until at least one token is available in the bucket. | ||
|
|
||
| When the bucket is not full, on token is generated every 10 seconds (6 every 1 minutes (`period` / `average`)) |
There was a problem hiding this comment.
Suggested change
| When the bucket is not full, on token is generated every 10 seconds (6 every 1 minutes (`period` / `average`)) | |
| When the bucket is not full, one token is generated every 10 seconds (6 every 1 minutes (`period` / `average`)). |
Comment on lines
+5
to
+8
|
|
||
|
|
||
|
|
||
| ## Configuration Examples |
There was a problem hiding this comment.
Suggested change
| ## Configuration Examples | |
| ## Configuration Examples |
sheddy-traefik
force-pushed
the
feat/reference-routing-config
branch
from
1586c8f to
d430954
Compare
sdelicata
requested changes
Jan 17, 2025
|
|
||
| - If both `users` and `usersFile` are provided, the two are merged. | ||
| The contents of `usersFile` have precedence over the values in `users`. | ||
| - For security reasons, the field `users` doesn't exist for Kubernetes IngressRoute, and one should use the `secret` field instead. |
There was a problem hiding this comment.
Suggested change
| - For security reasons, the field `users` doesn't exist for Kubernetes IngressRoute, and one should use the `secret` field instead. | |
| Because it does not make much sense to refer to a file path on Kubernetes, the `usersFile` field doesn't exist for Kubernetes IngressRoute, and one should use the `secret` field instead. |
There was a problem hiding this comment.
I'd rewrite this statement, i don't agree with how it sounds
|
|
||
| | Field | Description | Default | Required | | ||
| |:-----------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:--------|:---------| | ||
| | `prefix` | String to add **before** the current path in the requested URL. It should include a leading slash (`/`). | | Yes | |
There was a problem hiding this comment.
Suggested change
| | `prefix` | String to add **before** the current path in the requested URL. It should include a leading slash (`/`). | | Yes | | |
| | `prefix` | String to add **before** the current path in the requested URL. It should include a leading slash (`/`). | "" | Yes | |
|
|
||
| | Field | Description | Default | Required | | ||
| |:------|:------------|:--------|:---------| | ||
| | `middlewares` | List of middlewares to chain.<br /> The middlewares have to be in the same namespace as the `chain` middleware. | | Yes | |
There was a problem hiding this comment.
| middlewares | List of middlewares to chain.
The middlewares have to be in the same namespace as the chain middleware. | [] | Yes |
| | Field | Description | Default | Required | | ||
| |:------|:------------|:--------|:---------| | ||
| | `expression` | Condition to open the circuit breaker and applies the fallback mechanism instead of calling your services.<br />More information [here](#expression) | 100ms | No | | ||
| | `checkPeriod` | The interval between successive checks of the circuit breaker condition (when in standby state). | 100ms | No | |
There was a problem hiding this comment.
In the configuration options table we're talking about the circuit breaker "state" but at the bottom of the page we're using "status". It could be a good idea to standardize the term.
| |`encodings` | 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 | | ||
| | `includedContentTypes` | 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 | | ||
| | `minResponseBodyBytes` | `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 | | ||
|
|
There was a problem hiding this comment.
The defaultEncoding option is missing here.
|
|
||
|  | ||
|
|
||
| The `compress` middleware compresses response. It supports Gzip and Brotli compression |
There was a problem hiding this comment.
Suggested change
| The `compress` middleware compresses response. It supports Gzip and Brotli compression | |
| The `compress` middleware compresses response. It supports Gzip, Brotli and Zstandard compression |
|
|
||
| Responses are compressed when the following criteria are all met: | ||
|
|
||
| - The `Accept-Encoding` request header contains `gzip`, `*`, and/or `br` with or without [quality values](https://developer.mozilla.org/en-US/docs/Glossary/Quality_values). |
There was a problem hiding this comment.
Zstandard is missing here too.
lbenguigui
requested changes
Jan 17, 2025
|
|
||
| | Field | Description | Default | Required | | ||
| |:-----------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:--------|:---------| | ||
| | `regex` | List of regular expressions to match the path prefix from the request URL.<br /> For instance, `/products` also matches `/products/shoes` and `/products/shirts`.<br />oOre information [here](#regex). | | No | |
There was a problem hiding this comment.
Suggested change
| | `regex` | List of regular expressions to match the path prefix from the request URL.<br /> For instance, `/products` also matches `/products/shoes` and `/products/shirts`.<br />oOre information [here](#regex). | | No | | |
| | `regex` | List of regular expressions to match the path prefix from the request URL.<br /> For instance, `/products` also matches `/products/shoes` and `/products/shirts`.<br />More information [here](#regex). | | No | |
| description: "In Traefik Proxy's HTTP middleware, StripPrefixRegex removes prefixes from paths before forwarding requests, using regex. Read the technical documentation." | ||
| --- | ||
|
|
||
| The `stripPrefixRegex` middleware strips the matching path prefix and stores it in a `X-Forwarded-Prefix` header. |
There was a problem hiding this comment.
I believe it should be "an X-Forwarded-Prefix" instead of "a X-Forwarded-Prefix"
|
|
||
| Use a `stripPrefixRegex` middleware if your backend listens on the root path (`/`) but should be exposed on a specific prefix. | ||
|
|
||
| ## Configuration Example |
There was a problem hiding this comment.
I believe examples are missing
|
|
||
| !!! tip | ||
|
|
||
| Use a `StripPrefix` middleware if your backend listens on the root path (`/`) but should be exposed on a specific prefix |
There was a problem hiding this comment.
Suggested change
| Use a `StripPrefix` middleware if your backend listens on the root path (`/`) but should be exposed on a specific prefix | |
| Use a `StripPrefix` middleware if your backend listens on the root path (`/`) but should be exposed on a specific prefix. |
| description: "In Traefik Proxy's HTTP middleware, StripPrefix removes prefixes from paths before forwarding requests. Read the technical documentation." | ||
| --- | ||
|
|
||
| The `stripPrefix` middleware strips the matching path prefix and stores it in a `X-Forwarded-Prefix` header. |
There was a problem hiding this comment.
Suggested change
| The `stripPrefix` middleware strips the matching path prefix and stores it in a `X-Forwarded-Prefix` header. | |
| The `stripPrefix` middleware strips the matching path prefix and stores it in an `X-Forwarded-Prefix` header. |
| The `replacePath1 middleware will: | ||
|
|
||
| - Replace the actual path with the specified one. | ||
| - Store the original path in a `X-Replaced-Path` header |
There was a problem hiding this comment.
Suggested change
| - Store the original path in a `X-Replaced-Path` header | |
| - Store the original path in an `X-Replaced-Path` header |
| description: "In Traefik Proxy's HTTP middleware, ReplacePath updates paths before forwarding requests. Read the technical documentation." | ||
| --- | ||
|
|
||
| The `replacePath1 middleware will: |
There was a problem hiding this comment.
Suggested change
| The `replacePath1 middleware will: | |
| The `replacePath` middleware will: |
| name: test-replacepath | ||
| spec: | ||
| replacePath: | ||
| path: /foo |
There was a problem hiding this comment.
Suggested change
| path: /foo | |
| path: "/foo" |
| - "traefik.http.middlewares.test-replacepath.replacepath.path=/foo" | ||
| ``` | ||
|
|
||
| ## Configuration Option |
There was a problem hiding this comment.
Suggested change
| ## Configuration Option | |
| ## Configuration Options |
| description: "In Traefik Proxy's HTTP middleware, RedirectScheme redirects clients to different schemes/ports. Read the technical documentation." | ||
| --- | ||
|
|
||
| The RedirectScheme middleware redirects the request if the request scheme is different from the configured scheme. |
There was a problem hiding this comment.
Suggested change
| The RedirectScheme middleware redirects the request if the request scheme is different from the configured scheme. | |
| The `redirectScheme` middleware redirects the request if the request scheme is different from the configured scheme. |
jspdown
requested changes
Jan 17, 2025
| !!! info | ||
|
|
||
| The scope of the Content-Type middleware is the MIME type detection done by the core of Traefik (the server part). | ||
| Therefore, it has no effect against any other `Content-Type` header modifications (e.g.: in another middleware such as compress). |
There was a problem hiding this comment.
I don't understand this paragraph. It's not something you wrote but I think it's a good opportunity to improve this. I think we should rather say something like:
If any middleware, no matter its position in the chain, sets the Content-Type header (e.g, headers, compress, ... middlewares), the contentType middleware will have no effect.
| # Enable auto-detection | ||
| [http.middlewares] | ||
| [http.middlewares.autodetect.contentType] | ||
|
|
|
|
||
| | Field | Description | Default | Required | | ||
| |:-----------|:---------------------------------------------------------------------------------|:--------|:---------| | ||
| | `users` | Array of authorized users. Each user must be declared using the `name:realm:encoded-password` format.<br /> The option `users` supports Kubernetes secrets.<br />(More information [here](#users))| "" | No | |
There was a problem hiding this comment.
Suggested change
| | `users` | Array of authorized users. Each user must be declared using the `name:realm:encoded-password` format.<br /> The option `users` supports Kubernetes secrets.<br />(More information [here](#users))| "" | No | | |
| | `users` | Array of authorized users. Each user must be declared using the `name:realm:encoded-password` format.<br /> The option `users` supports Kubernetes secrets.<br />(More information [here](#users))| [] | No | |
|
|
||
| ### users | ||
|
|
||
| - If both `users` and `usersFile` are provided, the two are merged. The contents of `usersFile` have precedence over the values in `users`. |
There was a problem hiding this comment.
Maybe we can merge the users and usersFile section since they explain the same thing.
| - If both `users` and `usersFile` are provided, the two are merged. The contents of `usersFile` have precedence over the values in `users`. | ||
| - For security reasons, the field `users` doesn't exist for Kubernetes IngressRoute, and one should use the `secret` field instead. | ||
|
|
||
| #### Passwords format |
There was a problem hiding this comment.
WDYT about moving this section before users. It looks like the most important think to know about this middleware.
Suggested change
| #### Passwords format | |
| ### Passwords format |
| `contentTypeNosniff` | Set `contentTypeNosniff` to true to add the `X-Content-Type-Options` header with the value `nosniff`. | false | No | ||
| `browserXssFilter` | Set `browserXssFilter` to true to add the `X-XSS-Protection` header with the value `1; mode=block`. | false | No | ||
| `customBrowserXSSValue` | allows the `X-XSS-Protection` header value to be set with a custom value. This overrides the `BrowserXssFilter` option. | | No | ||
| `contentSecurityPolicy` | allows the `Content-Security-Policy` header value to be set with a custom value. | | No |
There was a problem hiding this comment.
Suggested change
| `contentSecurityPolicy` | allows the `Content-Security-Policy` header value to be set with a custom value. | | No | |
| `contentSecurityPolicy` | allows the `Content-Security-Policy` header value to be set with a custom value. | false | No |
| `browserXssFilter` | Set `browserXssFilter` to true to add the `X-XSS-Protection` header with the value `1; mode=block`. | false | No | ||
| `customBrowserXSSValue` | allows the `X-XSS-Protection` header value to be set with a custom value. This overrides the `BrowserXssFilter` option. | | No | ||
| `contentSecurityPolicy` | allows the `Content-Security-Policy` header value to be set with a custom value. | | No | ||
| `contentSecurityPolicyReportOnly` | allows the `Content-Security-Policy-Report-Only` header value to be set with a custom value. | | No |
There was a problem hiding this comment.
Suggested change
| `contentSecurityPolicyReportOnly` | allows the `Content-Security-Policy-Report-Only` header value to be set with a custom value. | | No | |
| `contentSecurityPolicyReportOnly` | allows the `Content-Security-Policy-Report-Only` header value to be set with a custom value. | "" | No |
| `customBrowserXSSValue` | allows the `X-XSS-Protection` header value to be set with a custom value. This overrides the `BrowserXssFilter` option. | | No | ||
| `contentSecurityPolicy` | allows the `Content-Security-Policy` header value to be set with a custom value. | | No | ||
| `contentSecurityPolicyReportOnly` | allows the `Content-Security-Policy-Report-Only` header value to be set with a custom value. | | No | ||
| `publicKey` | Implements HPKP for certificate pinning. | | No |
There was a problem hiding this comment.
Suggested change
| `publicKey` | Implements HPKP for certificate pinning. | | No | |
| `publicKey` | Implements HPKP for certificate pinning. | "" | No |
| `contentSecurityPolicy` | allows the `Content-Security-Policy` header value to be set with a custom value. | | No | ||
| `contentSecurityPolicyReportOnly` | allows the `Content-Security-Policy-Report-Only` header value to be set with a custom value. | | No | ||
| `publicKey` | Implements HPKP for certificate pinning. | | No | ||
| `referrerPolicy` | Controls forwarding of `Referer` header. | | No |
There was a problem hiding this comment.
Suggested change
| `referrerPolicy` | Controls forwarding of `Referer` header. | | No | |
| `referrerPolicy` | Controls forwarding of `Referer` header. | "" | No |
| `contentSecurityPolicyReportOnly` | allows the `Content-Security-Policy-Report-Only` header value to be set with a custom value. | | No | ||
| `publicKey` | Implements HPKP for certificate pinning. | | No | ||
| `referrerPolicy` | Controls forwarding of `Referer` header. | | No | ||
| `permissionsPolicy` | allows sites to control browser features. | None | No |
There was a problem hiding this comment.
Suggested change
| `permissionsPolicy` | allows sites to control browser features. | None | No | |
| `permissionsPolicy` | allows sites to control browser features. | "" | No |
rtribotte
requested changes
Jan 17, 2025
|
|
||
| # Providing Dynamic Configuration to Traefik | ||
|
|
||
| Traefik relies on dynamic configuration to discover the services it needs to route traffic to. There are several ways to provide this dynamic configuration, depending on your environment and preferences. This guide covers the different methods available: |
There was a problem hiding this comment.
In this sentence, I find that using "discover" to be a bit misleading.
Traefik, through its providers, discovers services that are holding their dynamic configuration.
Since we are using the discovery concept to reflect how Traefik is actually getting the dynamic configuration, I think saying that the dynamic configuration helps Traefik to discover services is then confusing.
|
|
||
| - File Provider: Use TOML or YAML files. | ||
| - Docker and ECS Providers: Use container labels. | ||
| - Other Providers: Use tags or Annotations |
There was a problem hiding this comment.
Maybe this part could better emphasis Kubernetes providers.
|
|
||
| ## Using the File Provider | ||
|
|
||
| The File provider allows you to define dynamic configuration in static files using either TOML or YAML syntax. This method is ideal for environments where services are not automatically discovered or when you prefer to manage configurations manually. |
There was a problem hiding this comment.
Suggested change
| The File provider allows you to define dynamic configuration in static files using either TOML or YAML syntax. This method is ideal for environments where services are not automatically discovered or when you prefer to manage configurations manually. | |
| The File provider allows you to define dynamic configuration in static files using either TOML or YAML syntax. This method is ideal for environments where services cannot be automatically discovered or when you prefer to manage configurations manually. |
Comment on lines
+23
to
+31
| providers: | ||
| file: | ||
| directory: "/path/to/dynamic/conf" | ||
| ``` | ||
|
|
||
| ```toml tab="TOML" | ||
| [providers.file] | ||
| filename = "/path/to/your/configuration/file.toml" | ||
| ``` |
There was a problem hiding this comment.
Both examples are different, this would be better to stick to file or directory in both.
| @@ -0,0 +1,43 @@ | |||
| --- | |||
| title: "ServersTransport" | |||
| description: "ServersTransport allows configuring the connection between Traefik and the HTTP servers in Kubernetes." | |||
There was a problem hiding this comment.
Suggested change
| description: "ServersTransport allows configuring the connection between Traefik and the HTTP servers in Kubernetes." | |
| description: "ServersTransport allows configuring the connection between Traefik and the HTTP servers." |
|
|
||
| The WRR is able to load balance the requests between multiple services based on weights. | ||
|
|
||
| This strategy is only available to load balance between services and not between servers. |
There was a problem hiding this comment.
Suggested change
| This strategy is only available to load balance between services and not between servers. | |
| This strategy is only available to load balance between services and not between servers. To load balance between servers based on weights, the Load Balancer service should be used instead. |
Comment on lines
+62
to
+63
| ???+ "Load Balancing -- Using the File Provider" | ||
|
|
There was a problem hiding this comment.
Suggested change
| ???+ "Load Balancing -- Using the File Provider" |
To be consistent within this page the examples should probably always shown.
| | `caServer` | Defines the CA server to use. More information [here](#caserver). | "https://acme-v02.api.letsencrypt.org/directory" | Yes | | ||
| | `storage` | Defines the location where the ACME certificates are saved to. More information [here](#storage) | "acme.json" | Yes | | ||
| | `certificatesDuration` | Defines the renewal period and interval for a certificate. More information [here](#certificatesduration) | 2160 | No | | ||
| | `preferredChain` | Defines the preferred chain to use. | 2160 | No | |
There was a problem hiding this comment.
Suggested change
| | `preferredChain` | Defines the preferred chain to use. | 2160 | No | | |
| | `preferredChain` | Defines the preferred chain to use. <br /> 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 | |
| | `certificatesDuration` | Defines the renewal period and interval for a certificate. More information [here](#certificatesduration) | 2160 | No | | ||
| | `preferredChain` | Defines the preferred chain to use. | 2160 | No | | ||
| | `keyType` | Defines the key type used for generating certificate private key. It supports 'EC256', 'EC384', 'RSA2048', 'RSA4096', 'RSA8192'. | RSA4096 | No | | ||
| | `caCertificates` | Defines the 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 | |
There was a problem hiding this comment.
Suggested change
| | `caCertificates` | Defines the 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 | | |
| | `caCertificates` | Defines 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 | |
| clientAuthType: RequireAndVerifyClientCert | ||
| ``` | ||
|
|
||
| ## Let's Encrypt |
There was a problem hiding this comment.
I think most of this section contains "Install documentation" and certificate resolvers, is it expected here?
mmatur
requested changes
Jan 21, 2025
| ```yaml | ||
| traefik.tcp.services.myservice.loadbalancer.serverstransport=foobar@file | ||
| ``` | ||
|
|
There was a problem hiding this comment.
WDYT to add a section for TCP Middlewares?
|
|
||
| We recommend to *not* use tags to store sensitive data (certificates, credentials, etc). | ||
| Instead, we recommend to store sensitive data in a safer storage (secrets, file, etc). | ||
|
|
There was a problem hiding this comment.
There is no section ## Configuration Examples in this provider. Do we have to add one?
| See [serverstransport](../http/load-balancing/serverstransport.md) for more information. | ||
|
|
||
| ```yaml | ||
| - "traefik.http.services.<service_name>.loadbalancer.serverstransport=foobar@file" |
There was a problem hiding this comment.
Suggested change
| - "traefik.http.services.<service_name>.loadbalancer.serverstransport=foobar@file" | |
| - "traefik.http.services.myservice.loadbalancer.serverstransport=foobar@file" |
| See [priority](../tcp/router/rules-and-priority.md) for more information. | ||
|
|
||
| ```yaml | ||
| - "traefik.tcp.routers.myrouter.priority=42" |
There was a problem hiding this comment.
Suggested change
| - "traefik.tcp.routers.myrouter.priority=42" | |
| - "traefik.tcp.routers.mytcprouter.priority=42" |
| See [serverstransport](../tcp/serverstransport.md) for more information. | ||
|
|
||
| ```yaml | ||
| traefik.tcp.services.myservice.loadbalancer.serverstransport=foobar@file |
There was a problem hiding this comment.
Suggested change
| traefik.tcp.services.myservice.loadbalancer.serverstransport=foobar@file | |
| traefik.tcp.services.mytcpservice.loadbalancer.serverstransport=foobar@file |
| ```yaml | ||
| - "traefik.http.services.myservice.loadbalancer.server.scheme=http" | ||
| ``` | ||
|
|
There was a problem hiding this comment.
traefik.http.services.<service_name>.loadbalancer.server.weight is missing
| my-container: | ||
| # ... | ||
| deploy: | ||
| labels: |
| ```yaml | ||
| - "traefik.tcp.routers.mytcprouter.rule=HostSNI(`example.com`)" | ||
| ``` | ||
|
|
There was a problem hiding this comment.
traefik.tcp.routers.<router_name>.ruleSyntax is missing
| ```yaml | ||
| - "traefik.tcp.services.<service_name>.loadbalancer.serverstransport=foobar@file" | ||
| ``` | ||
|
|
There was a problem hiding this comment.
traefik.tcp.services.<service_name>.loadbalancer.terminationDelay is missing
| ```yaml | ||
| - "traefik.tcp.services.<service_name>.loadbalancer.serverstransport=foobar@file" | ||
| ``` | ||
|
|
There was a problem hiding this comment.
TCP middleware section is missing
juliens
requested changes
Jan 23, 2025
| | `serverstransport.`<br />`serverName` | Configures the server name that will be used for SNI. | | No | | ||
| | `serverstransport.`<br />`certificates` | Defines the list of certificates (as file paths, or data bytes) that will be set as client certificates for mTLS. | | No | | ||
| | `serverstransport.`<br />`insecureSkipVerify` | Controls whether the server's certificate chain and host name is verified. | false | No | | ||
| | `serverstransport.`<br />`rootcas` | Set of root certificate authorities to use when verifying server certificates. (for mTLS connections). | | No | |
| [http.services.mirrored-api] | ||
| [http.services.mirrored-api.mirroring] | ||
| [http.services.mirrored-api.mirroring.healthCheck] | ||
| service = "appv1" |
There was a problem hiding this comment.
this line should before the "healthCheck" line.
| @@ -0,0 +1,194 @@ | |||
| --- | |||
| title: "Kubernetes IngressRouteTCP" | |||
| description: "An IngressRouteTCP is a Traefik CRD is in charge of connecting incoming requests to the Services that can handle them in TCP." | |||
There was a problem hiding this comment.
It's more "connecting an incoming connection to the Services".
| This registers the `IngressRouteTCP` kind and other Traefik-specific resources. | ||
|
|
||
| !!! note "General" | ||
| If both HTTP routers and TCP routers listen to the same EntryPoint, the TCP routers will apply before the HTTP routers. If no matching route is found for the TCP routers, then the HTTP routers will take over. |
There was a problem hiding this comment.
Suggested change
| If both HTTP routers and TCP routers listen to the same EntryPoint, the TCP routers will apply before the HTTP routers. If no matching route is found for the TCP routers, then the HTTP routers will take over. | |
| If both HTTP routers and TCP routers are connected to the same EntryPoint, the TCP routers will apply before the HTTP routers. If no matching route is found for the TCP routers, then the HTTP routers will take over. |
|
|
||
| ##### Healthcheck | ||
|
|
||
| As the healthchech cannot be done using the usual Kubernetes livenessprobe and readinessprobe, the `IngressRouteTC`P brings an option to check the ExternalName Service health. |
There was a problem hiding this comment.
Suggested change
| As the healthchech cannot be done using the usual Kubernetes livenessprobe and readinessprobe, the `IngressRouteTC`P brings an option to check the ExternalName Service health. | |
| As the healthchech cannot be done using the usual Kubernetes livenessprobe and readinessprobe, the `IngressRouteTCP` brings an option to check the ExternalName Service health. |
| |-------------------------------------|-----------------------------|-------------------------------------------|-----------------------| | ||
| | `dialTimeout` | The amount of time to wait until a connection to a server can be established. If zero, no timeout exists. | 30s | No | | ||
| | `dialKeepAlive` | The interval between keep-alive probes for an active network connection.<br />If this option is set to zero, keep-alive probes are sent with a default value (currently 15 seconds),<br />if supported by the protocol and operating system. Network protocols or operating systems that do not support keep-alives ignore this field.<br />If negative, keep-alive probes are turned off.| | No | | ||
| | `terminationDelay` | Defines the delay to wait before fully terminating the connection, after one connected peer has closed its writing capability.| | No | |
There was a problem hiding this comment.
Suggested change
| | `terminationDelay` | Defines the delay to wait before fully terminating the connection, after one connected peer has closed its writing capability.| | No | | |
| | `terminationDelay` | Defines the delay to wait before fully terminating the connection, after one connected peer has closed its writing capability.| 100ms | No | |
| | `dialKeepAlive` | The interval between keep-alive probes for an active network connection.<br />If this option is set to zero, keep-alive probes are sent with a default value (currently 15 seconds),<br />if supported by the protocol and operating system. Network protocols or operating systems that do not support keep-alives ignore this field.<br />If negative, keep-alive probes are turned off.| | No | | ||
| | `terminationDelay` | Defines the delay to wait before fully terminating the connection, after one connected peer has closed its writing capability.| | No | | ||
| | `tls.serverName` | ServerName used to contact the server. | "" | No | | ||
| | `tls.insecureSkipVerify` | Controls whether the server's certificate chain and host name is verified. | "" | No | |
There was a problem hiding this comment.
Suggested change
| | `tls.insecureSkipVerify` | Controls whether the server's certificate chain and host name is verified. | "" | No | | |
| | `tls.insecureSkipVerify` | Controls whether the server's certificate chain and host name is verified. | false | No | |
| | `routes[n].services[n].proxyProtocol.version` | Defines the [PROXY protocol](../../../install-configuration/entrypoints.md#proxyprotocol-and-load-balancers) version. | | | | ||
| | `routes[n].services[n].serversTransport` | Defines the [ServersTransportTCP](./serverstransporttcp.md).<br />The `ServersTransport` namespace is assumed to be the [Kubernetes service](https://kubernetes.io/docs/concepts/services-networking/service/) namespace. | | | | ||
| | `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. | 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. | false | no | |
There was a problem hiding this comment.
Suggested change
| | `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. | 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 | |
| description: "Learn how to configure a Traefik Proxy Kubernetes Middleware to reach TCP Services, which handle incoming requests. Read the technical documentation." | ||
| --- | ||
|
|
||
| `MiddlewareTCP` is the CRD implementation of a [Traefik TCP middleware](../../http/middlewares/overview.md). |
There was a problem hiding this comment.
Suggested change
| `MiddlewareTCP` is the CRD implementation of a [Traefik TCP middleware](../../http/middlewares/overview.md). | |
| `MiddlewareTCP` is the CRD implementation of a [Traefik TCP middleware](../../tcp/middlewares/overview.md). |
| description : 'Understand the service routing configuration for the Kubernetes ServerTransportTCP & Traefik CRD' | ||
| --- | ||
|
|
||
| `ServersTransportTCP` is the CRD implementation of [ServersTransportTCP](./serverstransporttcp.md). |
There was a problem hiding this comment.
Suggested change
| `ServersTransportTCP` is the CRD implementation of [ServersTransportTCP](./serverstransporttcp.md). | |
| `ServersTransportTCP` is the CRD implementation of [ServersTransportTCP](../../tcp/serverstransport.md). |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
What does this PR do?
Following a series of discussions with @emilevauge and @nmengin, we decided to create a new reference section in the documentation. This PR replaces the previous "Dynamic Configuration" with a new menu item called "Routing Configuration".
This PR has also been rebased on branch v3.2
Motivation
The motivation behind this pull request is to have a more strucutured reference documentation for Traefik proxy. This new change brings a more accurate and well defined reference section in the docs.
More