New Routing Reference Documentation
This commit is contained in:
Sheddy
GitHub
parent
3c99135bf9
commit
b7170df2c3
65 changed files with 12109 additions and 26 deletions
|
|
@ -0,0 +1,59 @@
|
|||
---
|
||||
title: "Traefik AddPrefix Documentation"
|
||||
description: "Learn how to implement the HTTP AddPrefix middleware in Traefik Proxy to updates request paths before being forwarded. Read the technical documentation."
|
||||
---
|
||||
|
||||
|
||||
|
||||
The `addPrefix` middleware updates the path of a request before forwarding it.
|
||||
|
||||
## Configuration Examples
|
||||
|
||||
```yaml tab="Structured (YAML)"
|
||||
# Prefixing with /foo
|
||||
http:
|
||||
middlewares:
|
||||
add-foo:
|
||||
addPrefix:
|
||||
prefix: "/foo"
|
||||
```
|
||||
|
||||
```toml tab="Structured (TOML)"
|
||||
# Prefixing with /foo
|
||||
[http.middlewares]
|
||||
[http.middlewares.add-foo.addPrefix]
|
||||
prefix = "/foo"
|
||||
```
|
||||
|
||||
```yaml tab="Labels"
|
||||
# Prefixing with /foo
|
||||
labels:
|
||||
- "traefik.http.middlewares.add-foo.addprefix.prefix=/foo"
|
||||
```
|
||||
|
||||
```json tab="Tags"
|
||||
// Prefixing with /foo
|
||||
{
|
||||
// ...
|
||||
"Tags": [
|
||||
"traefik.http.middlewares.add-foo.addprefix.prefix=/foo"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
```yaml tab="Kubernetes"
|
||||
# Prefixing with /foo
|
||||
apiVersion: traefik.io/v1alpha1
|
||||
kind: Middleware
|
||||
metadata:
|
||||
name: add-foo
|
||||
spec:
|
||||
addPrefix:
|
||||
prefix: /foo
|
||||
```
|
||||
|
||||
## Configuration Options
|
||||
|
||||
| Field | Description | Default | Required |
|
||||
|:-----------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:--------|:---------|
|
||||
| `prefix` | String to add **before** the current path in the requested URL. It should include a leading slash (`/`). | "" | Yes |
|
||||
|
|
@ -0,0 +1,97 @@
|
|||
---
|
||||
title: "Traefik BasicAuth Documentation"
|
||||
description: "The HTTP basic authentication (BasicAuth) middleware in Traefik Proxy restricts access to your Services to known users. Read the technical documentation."
|
||||
---
|
||||
|
||||
|
||||
|
||||
The `basicAuth` middleware grants access to services to authorized users only.
|
||||
|
||||
## Configuration Examples
|
||||
|
||||
```yaml tab="Structured (YAML)"
|
||||
# Declaring the user list
|
||||
http:
|
||||
middlewares:
|
||||
test-auth:
|
||||
basicAuth:
|
||||
users:
|
||||
- "test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/"
|
||||
- "test2:$apr1$d9hr9HBB$4HxwgUir3HP4EsggP/QNo0"
|
||||
```
|
||||
|
||||
```toml tab="Structured (TOML)"
|
||||
# Declaring the user list
|
||||
[http.middlewares]
|
||||
[http.middlewares.test-auth.basicAuth]
|
||||
users = [
|
||||
"test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/",
|
||||
"test2:$apr1$d9hr9HBB$4HxwgUir3HP4EsggP/QNo0",
|
||||
]
|
||||
```
|
||||
|
||||
```yaml tab="Labels"
|
||||
# Declaring the user list
|
||||
#
|
||||
# Note: when used in docker-compose.yml all dollar signs in the hash need to be doubled for escaping.
|
||||
# To create user:password pair, it's possible to use this command:
|
||||
# echo $(htpasswd -nB user) | sed -e s/\\$/\\$\\$/g
|
||||
#
|
||||
# Also, note that dollar signs should NOT be doubled when not evaluated (e.g. Ansible docker_container module).
|
||||
labels:
|
||||
- "traefik.http.middlewares.test-auth.basicauth.users=test:$$apr1$$H6uskkkW$$IgXLP6ewTrSuBkTrqE8wj/,test2:$$apr1$$d9hr9HBB$$4HxwgUir3HP4EsggP/QNo0"
|
||||
```
|
||||
|
||||
```json tab="Tags"
|
||||
{
|
||||
// ...
|
||||
"Tags": [
|
||||
"traefik.http.middlewares.test-auth.basicauth.users=test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/,test2:$apr1$d9hr9HBB$4HxwgUir3HP4EsggP/QNo0"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
```yaml tab="Kubernetes"
|
||||
# Declaring the user list
|
||||
apiVersion: traefik.io/v1alpha1
|
||||
kind: Middleware
|
||||
metadata:
|
||||
name: test-auth
|
||||
spec:
|
||||
basicAuth:
|
||||
secret: secretName
|
||||
```
|
||||
|
||||
## Configuration Options
|
||||
|
||||
| Field | Description | Default | Required |
|
||||
|:-----------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:--------|:---------|
|
||||
| `users` | Array of authorized users. Each user must be declared using the `name:hashed-password` format. (More information [here](#users))| "" | No |
|
||||
| `usersFile` | Path to an external file that contains the authorized users for the middleware. <br />The file content is a list of `name:hashed-password`. (More information [here](#usersfile)) | "" | No |
|
||||
| `realm` | Allow customizing the realm for the authentication.| "traefik" | No |
|
||||
| `headerField` | Allow defining a header field to store the authenticated user.| "" | No |
|
||||
| `removeHeader` | Allow removing the authorization header before forwarding the request to your service. | false | No |
|
||||
|
||||
### Passwords format
|
||||
|
||||
Passwords must be hashed using MD5, SHA1, or BCrypt.
|
||||
Use `htpasswd` to generate the passwords.
|
||||
|
||||
### users & usersFile
|
||||
|
||||
- If both `users` and `usersFile` are provided, they are merged. The contents of `usersFile` have precedence over the values in users.
|
||||
- Because referencing a file path isn’t feasible on Kubernetes, the `users` & `usersFile` field isn’t used in Kubernetes IngressRoute. Instead, use the `secret` field.
|
||||
|
||||
#### Kubernetes Secrets
|
||||
|
||||
The option `users` supports Kubernetes secrets.
|
||||
|
||||
!!! note "Kubernetes `kubernetes.io/basic-auth` secret type"
|
||||
|
||||
Kubernetes supports a special `kubernetes.io/basic-auth` secret type.
|
||||
This secret must contain two keys: `username` and `password`.
|
||||
|
||||
Please note that these keys are not hashed or encrypted in any way, and therefore is less secure than other methods.
|
||||
You can find more information on the [Kubernetes Basic Authentication Secret Documentation](https://kubernetes.io/docs/concepts/configuration/secret/#basic-authentication-secret)
|
||||
|
||||
{!traefik-for-business-applications.md!}
|
||||
|
|
@ -0,0 +1,76 @@
|
|||
---
|
||||
title: "Traefik Buffering Documentation"
|
||||
description: "The HTTP buffering middleware in Traefik Proxy limits the size of requests that can be forwarded to Services. Read the technical documentation."
|
||||
---
|
||||
|
||||
|
||||
|
||||
The `buffering` middleware limits the size of requests that can be forwarded to services.
|
||||
|
||||
With buffering, Traefik reads the entire request into memory (possibly buffering large requests into disk), and rejects requests that are over a specified size limit.
|
||||
|
||||
This can help services avoid large amounts of data (`multipart/form-data` for example), and can minimize the time spent sending data to a Service
|
||||
|
||||
## Configuration Examples
|
||||
|
||||
```yaml tab="Structured (YAML)"
|
||||
# Sets the maximum request body to 2MB
|
||||
http:
|
||||
middlewares:
|
||||
limit:
|
||||
buffering:
|
||||
maxRequestBodyBytes: 2000000
|
||||
```
|
||||
|
||||
```toml tab="Structured (TOML)"
|
||||
# Sets the maximum request body to 2MB
|
||||
[http.middlewares]
|
||||
[http.middlewares.limit.buffering]
|
||||
maxRequestBodyBytes = 2000000
|
||||
```
|
||||
|
||||
```yaml tab="Labels"
|
||||
# Sets the maximum request body to 2MB
|
||||
labels:
|
||||
- "traefik.http.middlewares.limit.buffering.maxRequestBodyBytes=2000000"
|
||||
```
|
||||
|
||||
```json tab="Tags"
|
||||
// Sets the maximum request body to 2MB
|
||||
{
|
||||
// ...
|
||||
"Tags": [
|
||||
"traefik.http.middlewares.test-auth.basicauth.users=test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/,test2:$apr1$d9hr9HBB$4HxwgUir3HP4EsggP/QNo0"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
```yaml tab="Kubernetes"
|
||||
# Sets the maximum request body to 2MB
|
||||
apiVersion: traefik.io/v1alpha1
|
||||
kind: Middleware
|
||||
metadata:
|
||||
name: limit
|
||||
spec:
|
||||
buffering:
|
||||
maxRequestBodyBytes: 2000000
|
||||
```
|
||||
|
||||
## Configuration Options
|
||||
|
||||
| Field | Description | Default | Required |
|
||||
|:------|:------------|:--------|:---------|
|
||||
| `maxRequestBodyBytes` | Maximum allowed body size for the request (in bytes). <br /> If the request exceeds the allowed size, it is not forwarded to the Service, and the client gets a `413` (Request Entity Too Large) response. | 0 | No |
|
||||
| `memRequestBodyBytes` | Threshold (in bytes) from which the request will be buffered on disk instead of in memory with the `memRequestBodyBytes` option.| 1048576 | No |
|
||||
| `maxResponseBodyBytes` | Maximum allowed response size from the Service (in bytes). <br /> If the response exceeds the allowed size, it is not forwarded to the client. The client gets a `500` (Internal Server Error) response instead. | 0 | No |
|
||||
| `memResponseBodyBytes` | Threshold (in bytes) from which the response will be buffered on disk instead of in memory with the `memResponseBodyBytes` option.| 1048576 | No |
|
||||
| `retryExpression` | Replay the request using `retryExpression`.<br /> More information [here](#retryexpression). | "" | No |
|
||||
|
||||
### retryExpression
|
||||
|
||||
The retry expression is defined as a logical combination of the functions below with the operators AND (`&&`) and OR (`||`).
|
||||
At least one function is required:
|
||||
|
||||
- `Attempts()` number of attempts (the first one counts).
|
||||
- `ResponseCode()` response code of the Service.
|
||||
- `IsNetworkError()` whether the response code is related to networking error.
|
||||
|
|
@ -0,0 +1,171 @@
|
|||
---
|
||||
title: "Traefik Chain Middleware Documentation"
|
||||
description: "The HTTP chain middleware lets you define reusable combinations of other middleware, to reuse the same groups. Read the technical documentation."
|
||||
---
|
||||
|
||||
The `chain` middleware enables you to define reusable combinations of other pieces of middleware.
|
||||
It makes it effortless to reuse the same groups.
|
||||
|
||||
## Configuration Example
|
||||
|
||||
Below is an example of a Chain containing `AllowList`, `BasicAuth`, and `RedirectScheme`.
|
||||
|
||||
```yaml tab="Structured (YAML)"
|
||||
# ...
|
||||
http:
|
||||
routers:
|
||||
router1:
|
||||
service: service1
|
||||
middlewares:
|
||||
- secured
|
||||
rule: "Host(`mydomain`)"
|
||||
|
||||
middlewares:
|
||||
secured:
|
||||
chain:
|
||||
middlewares:
|
||||
- https-only
|
||||
- known-ips
|
||||
- auth-users
|
||||
|
||||
auth-users:
|
||||
basicAuth:
|
||||
users:
|
||||
- "test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/"
|
||||
|
||||
https-only:
|
||||
redirectScheme:
|
||||
scheme: https
|
||||
|
||||
known-ips:
|
||||
ipAllowList:
|
||||
sourceRange:
|
||||
- "192.168.1.7"
|
||||
- "127.0.0.1/32"
|
||||
|
||||
services:
|
||||
service1:
|
||||
loadBalancer:
|
||||
servers:
|
||||
- url: "http://127.0.0.1:80"
|
||||
```
|
||||
|
||||
```toml tab="Structured (TOML)"
|
||||
# ...
|
||||
[http.routers]
|
||||
[http.routers.router1]
|
||||
service = "service1"
|
||||
middlewares = ["secured"]
|
||||
rule = "Host(`mydomain`)"
|
||||
|
||||
[http.middlewares]
|
||||
[http.middlewares.secured.chain]
|
||||
middlewares = ["https-only", "known-ips", "auth-users"]
|
||||
|
||||
[http.middlewares.auth-users.basicAuth]
|
||||
users = ["test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/"]
|
||||
|
||||
[http.middlewares.https-only.redirectScheme]
|
||||
scheme = "https"
|
||||
|
||||
[http.middlewares.known-ips.ipAllowList]
|
||||
sourceRange = ["192.168.1.7", "127.0.0.1/32"]
|
||||
|
||||
[http.services]
|
||||
[http.services.service1]
|
||||
[http.services.service1.loadBalancer]
|
||||
[[http.services.service1.loadBalancer.servers]]
|
||||
url = "http://127.0.0.1:80"
|
||||
```
|
||||
|
||||
```yaml tab="Labels"
|
||||
labels:
|
||||
- "traefik.http.routers.router1.service=service1"
|
||||
- "traefik.http.routers.router1.middlewares=secured"
|
||||
- "traefik.http.routers.router1.rule=Host(`mydomain`)"
|
||||
- "traefik.http.middlewares.secured.chain.middlewares=https-only,known-ips,auth-users"
|
||||
- "traefik.http.middlewares.auth-users.basicauth.users=test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/"
|
||||
- "traefik.http.middlewares.https-only.redirectscheme.scheme=https"
|
||||
- "traefik.http.middlewares.known-ips.ipallowlist.sourceRange=192.168.1.7,127.0.0.1/32"
|
||||
- "traefik.http.services.service1.loadbalancer.server.port=80"
|
||||
```
|
||||
|
||||
```json tab="Tags"
|
||||
{
|
||||
// ...
|
||||
"Tags": [
|
||||
"traefik.http.routers.router1.service=service1",
|
||||
"traefik.http.routers.router1.middlewares=secured",
|
||||
"traefik.http.routers.router1.rule=Host(`mydomain`)",
|
||||
"traefik.http.middlewares.secured.chain.middlewares=https-only,known-ips,auth-users",
|
||||
"traefik.http.middlewares.auth-users.basicauth.users=test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/",
|
||||
"traefik.http.middlewares.https-only.redirectscheme.scheme=https",
|
||||
"traefik.http.middlewares.known-ips.ipallowlist.sourceRange=192.168.1.7,127.0.0.1/32",
|
||||
"traefik.http.services.service1.loadbalancer.server.port=80"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
```yaml tab="Kubernetes"
|
||||
apiVersion: traefik.io/v1alpha1
|
||||
kind: IngressRoute
|
||||
metadata:
|
||||
name: test
|
||||
namespace: default
|
||||
spec:
|
||||
entryPoints:
|
||||
- web
|
||||
routes:
|
||||
- match: Host(`mydomain`)
|
||||
kind: Rule
|
||||
services:
|
||||
- name: whoami
|
||||
port: 80
|
||||
middlewares:
|
||||
- name: secured
|
||||
---
|
||||
apiVersion: traefik.io/v1alpha1
|
||||
kind: Middleware
|
||||
metadata:
|
||||
name: secured
|
||||
spec:
|
||||
chain:
|
||||
middlewares:
|
||||
- name: https-only
|
||||
- name: known-ips
|
||||
- name: auth-users
|
||||
---
|
||||
apiVersion: traefik.io/v1alpha1
|
||||
kind: Middleware
|
||||
metadata:
|
||||
name: auth-users
|
||||
spec:
|
||||
basicAuth:
|
||||
users:
|
||||
- test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/
|
||||
---
|
||||
apiVersion: traefik.io/v1alpha1
|
||||
kind: Middleware
|
||||
metadata:
|
||||
name: https-only
|
||||
spec:
|
||||
redirectScheme:
|
||||
scheme: https
|
||||
---
|
||||
apiVersion: traefik.io/v1alpha1
|
||||
kind: Middleware
|
||||
metadata:
|
||||
name: known-ips
|
||||
spec:
|
||||
ipAllowList:
|
||||
sourceRange:
|
||||
- 192.168.1.7
|
||||
- 127.0.0.1/32
|
||||
```
|
||||
|
||||
|
||||
## Configuration Options
|
||||
|
||||
| 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 |
|
||||
|
|
@ -0,0 +1,143 @@
|
|||
---
|
||||
title: "Traefik CircuitBreaker Documentation"
|
||||
description: "The HTTP circuit breaker in Traefik Proxy prevents stacking requests to unhealthy Services, resulting in cascading failures. Read the technical documentation."
|
||||
---
|
||||
|
||||
|
||||
|
||||
The HTTP circuit breaker prevents stacking requests to unhealthy Services, resulting in cascading failures.
|
||||
|
||||
When your system is healthy, the circuit is closed (normal operations).
|
||||
When your system becomes unhealthy, the circuit opens, and the requests are no longer forwarded, but instead are handled by a fallback mechanism.
|
||||
|
||||
To assess if your system is healthy, the circuit breaker constantly monitors the services.
|
||||
|
||||
The circuit breaker only analyzes what happens *after* its position within the middleware chain. What happens *before* has no impact on its state.
|
||||
|
||||
Each router gets its own instance of a given circuit breaker.
|
||||
One circuit breaker instance can be open while the other remains closed: their state is not shared.
|
||||
|
||||
This is the expected behavior, we want you to be able to define what makes a service healthy without having to declare a circuit breaker for each route.
|
||||
|
||||
## Configuration Examples
|
||||
|
||||
```yaml tab="Structured (YAML)"
|
||||
# Latency Check
|
||||
http:
|
||||
middlewares:
|
||||
latency-check:
|
||||
circuitBreaker:
|
||||
expression: "LatencyAtQuantileMS(50.0) > 100"
|
||||
```
|
||||
|
||||
```toml tab="Structured (TOML)"
|
||||
# Latency Check
|
||||
[http.middlewares]
|
||||
[http.middlewares.latency-check.circuitBreaker]
|
||||
expression = "LatencyAtQuantileMS(50.0) > 100"
|
||||
```
|
||||
|
||||
```yaml tab="Labels"
|
||||
# Latency Check
|
||||
labels:
|
||||
- "traefik.http.middlewares.latency-check.circuitbreaker.expression=LatencyAtQuantileMS(50.0) > 100"
|
||||
```
|
||||
|
||||
```json tab="Tags"
|
||||
{
|
||||
//..
|
||||
"Tags" : [
|
||||
"traefik.http.middlewares.latency-check.circuitbreaker.expression=LatencyAtQuantileMS(50.0) > 100"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
```yaml tab="Kubernetes"
|
||||
# Latency Check
|
||||
apiVersion: traefik.io/v1alpha1
|
||||
kind: Middleware
|
||||
metadata:
|
||||
name: latency-check
|
||||
spec:
|
||||
circuitBreaker:
|
||||
expression: LatencyAtQuantileMS(50.0) > 100
|
||||
```
|
||||
|
||||
## Configuration Options
|
||||
|
||||
| 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 |
|
||||
| `fallbackDuration` | The duration for which the circuit breaker will wait before trying to recover (from a tripped state). | 10s | No |
|
||||
| `recoveryDuration` | The duration for which the circuit breaker will try to recover (as soon as it is in recovering state). | 10s | No |
|
||||
| `responseCode` | The status code that the circuit breaker will return while it is in the open state. | 503 | No |
|
||||
|
||||
### expression
|
||||
|
||||
The `expression` option can check three different metrics:
|
||||
|
||||
| Metrics | Description | Example |
|
||||
|:------|:------------|:--------|
|
||||
| `NetworkErrorRatio` | The network error ratio to open the circuit breaker. | `NetworkErrorRatio() > 0.30` opens the circuit breaker at a 30% ratio of network errors |
|
||||
| `ResponseCodeRatio` | The status code ratio to open the circuit breaker.<br />More information [below](#responsecoderatio) | `ResponseCodeRatio(500, 600, 0, 600) > 0.25` opens the circuit breaker if 25% of the requests returned a 5XX status (amongst the request that returned a status code from 0 to 5XX) |
|
||||
| `LatencyAtQuantileMS` | The latency at a quantile in milliseconds to open the circuit breaker when a given proportion of your requests become too slow.<br /> Only floating point number (with the trailing .0) for the quantile value. | `LatencyAtQuantileMS(50.0) > 100` opens the circuit breaker when the median latency (quantile 50) reaches 100ms. |
|
||||
|
||||
#### ResponseCodeRatio
|
||||
|
||||
- It accepts four parameters, `from`, `to`, `dividedByFrom`, `dividedByTo`.
|
||||
- The operation that will be computed is sum(`to` -> `from`) / sum (`dividedByFrom` -> `dividedByTo`). If sum (`dividedByFrom` -> `dividedByTo`) equals 0, then `ResponseCodeRatio` returns 0.
|
||||
- `from` is inclusive, `to` is exclusive.
|
||||
|
||||
#### Using Multiple Metrics
|
||||
|
||||
You can combine multiple metrics using operators in your `expression`.
|
||||
|
||||
Supported operators are:
|
||||
|
||||
- AND (`&&`)
|
||||
- OR (`||`)
|
||||
|
||||
For example, `ResponseCodeRatio(500, 600, 0, 600) > 0.30 || NetworkErrorRatio() > 0.10` triggers the circuit breaker when 30% of the requests return a 5XX status code, or when the ratio of network errors reaches 10%.
|
||||
|
||||
#### Operators
|
||||
|
||||
Here is the list of supported operators:
|
||||
|
||||
- Greater than (`>`)
|
||||
- Greater or equal than (`>=`)
|
||||
- Lesser than (`<`)
|
||||
- Lesser or equal than (`<=`)
|
||||
- Equal (`==`)
|
||||
- Not Equal (`!=`)
|
||||
|
||||
### Fallback mechanism
|
||||
|
||||
The fallback mechanism returns a `HTTP 503 Service Unavailable` to the client instead of calling the target service.
|
||||
This behavior cannot be configured.
|
||||
|
||||
## State
|
||||
|
||||
There are three possible states for your circuit breaker:
|
||||
|
||||
- `Closed` (your service operates normally).
|
||||
- `Open` (the fallback mechanism takes over your service).
|
||||
- `Recovering` (the circuit breaker tries to resume normal operations by progressively sending requests to your service).
|
||||
|
||||
### Closed
|
||||
|
||||
While the circuit is closed, the circuit breaker only collects metrics to analyze the behavior of the requests.
|
||||
|
||||
At specified intervals (`checkPeriod`), the circuit breaker evaluates `expression` to decide if its state must change.
|
||||
|
||||
### Open
|
||||
|
||||
While open, the fallback mechanism takes over the normal service calls for a duration of `FallbackDuration`.
|
||||
The fallback mechanism returns a `HTTP 503` (or `ResponseCode`) to the client.
|
||||
After this duration, it enters the recovering state.
|
||||
|
||||
### Recovering
|
||||
|
||||
While recovering, the circuit breaker sends linearly increasing amounts of requests to your service (for `RecoveryDuration`).
|
||||
If your service fails during recovery, the circuit breaker opens again.
|
||||
If the service operates normally during the entire recovery duration, then the circuit breaker closes.
|
||||
|
|
@ -0,0 +1,80 @@
|
|||
---
|
||||
title: "Traefik Compress Documentation"
|
||||
description: "Traefik Proxy's HTTP middleware lets you compress responses before sending them to the client. Read the technical documentation."
|
||||
---
|
||||
|
||||
The `compress` middleware compresses response. It supports Gzip, Brotli and Zstandard compression
|
||||
|
||||
## Configuration Examples
|
||||
|
||||
```yaml tab="Structured (YAML)"
|
||||
# Enable compression
|
||||
http:
|
||||
middlewares:
|
||||
test-compress:
|
||||
compress: {}
|
||||
```
|
||||
|
||||
```toml tab="Structured (TOML)"
|
||||
# Enable compression
|
||||
[http.middlewares]
|
||||
[http.middlewares.test-compress.compress]
|
||||
```
|
||||
|
||||
```yaml tab="Labels"
|
||||
# Enable compression
|
||||
labels:
|
||||
- "traefik.http.middlewares.test-compress.compress=true"
|
||||
```
|
||||
|
||||
```json tab="Tags"
|
||||
// Enable compression
|
||||
{
|
||||
//...
|
||||
"Tags": [
|
||||
"traefik.http.middlewares.test-compress.compress=true"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
```yaml tab="Kubernetes"
|
||||
# Enable compression
|
||||
apiVersion: traefik.io/v1alpha1
|
||||
kind: Middleware
|
||||
metadata:
|
||||
name: test-compress
|
||||
spec:
|
||||
compress: {}
|
||||
```
|
||||
|
||||
## Configuration Options
|
||||
|
||||
| Field | Description | Default | Required |
|
||||
|:-----------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:--------|:---------|
|
||||
|`excludedContentTypes` | 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 |
|
||||
|`defaultEncoding` | specifies the default encoding if the `Accept-Encoding` header is not in the request or contains a wildcard (`*`). | "" | No |
|
||||
|`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 |
|
||||
|
||||
## Compression activation
|
||||
|
||||
The activation of compression, and the compression method choice rely (among other things) on the request's `Accept-Encoding` header.
|
||||
|
||||
Responses are compressed when the following criteria are all met:
|
||||
|
||||
- The `Accept-Encoding` request header contains `gzip`, `*`, and/or `br`, and/or `zstd` with or without [quality values](https://developer.mozilla.org/en-US/docs/Glossary/Quality_values).
|
||||
If the `Accept-Encoding` request header is absent, the response won't be encoded.
|
||||
If it is present, but its value is the empty string, then compression is turned off.
|
||||
- The response is not already compressed, that is the `Content-Encoding` response header is not already set.
|
||||
- The response`Content-Type` header is not one among the `excludedContentTypes` options, or is one among the `includedContentTypes` options.
|
||||
- The response body is larger than the configured minimum amount of bytes(option `minResponseBodyBytes`) (default is `1024`).
|
||||
|
||||
## Empty Content-Type Header
|
||||
|
||||
If the `Content-Type` header is not defined, or empty, the compress middleware will automatically [detect](https://mimesniff.spec.whatwg.org/) a content type.
|
||||
It will also set the `Content-Type` header according to the detected MIME type.
|
||||
|
||||
## GRPC application
|
||||
|
||||
Note that `application/grpc` is never compressed.
|
||||
|
|
@ -0,0 +1,53 @@
|
|||
---
|
||||
title: "Traefik ContentType Documentation"
|
||||
description: "Traefik Proxy's HTTP middleware automatically sets the `Content-Type` header value when it is not set by the backend. Read the technical documentation."
|
||||
---
|
||||
|
||||
The `contentType` middleware sets the `Content-Type` header value to the media type detected from the response content,
|
||||
when it is not set by the backend.
|
||||
|
||||
!!! info
|
||||
|
||||
The `contentType` middleware only applies when Traefik detects the MIME type. If any middleware (such as Headers or Compress) sets the `contentType` header at any point in the chain, the `contentType` middleware has no effect.
|
||||
|
||||
## Configuration Examples
|
||||
|
||||
```yaml tab="Structured (YAML)"
|
||||
# Enable auto-detection
|
||||
http:
|
||||
middlewares:
|
||||
autodetect:
|
||||
contentType: {}
|
||||
```
|
||||
|
||||
```toml tab="Structured (TOML)"
|
||||
# Enable auto-detection
|
||||
[http.middlewares]
|
||||
[http.middlewares.autodetect.contentType]
|
||||
```
|
||||
|
||||
```yaml tab="Labels"
|
||||
# Enable auto-detection
|
||||
labels:
|
||||
- "traefik.http.middlewares.autodetect.contenttype=true"
|
||||
```
|
||||
|
||||
```json tab="Tags"
|
||||
// Enable auto-detection
|
||||
{
|
||||
// ...
|
||||
"Tags": [
|
||||
"traefik.http.middlewares.autodetect.contenttype=true"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
```yaml tab="Kubernetes"
|
||||
# Enable auto-detection
|
||||
apiVersion: traefik.io/v1alpha1
|
||||
kind: Middleware
|
||||
metadata:
|
||||
name: autodetect
|
||||
spec:
|
||||
contentType: {}
|
||||
```
|
||||
|
|
@ -0,0 +1,87 @@
|
|||
---
|
||||
title: "Traefik DigestAuth Documentation"
|
||||
description: "Traefik Proxy's HTTP DigestAuth middleware restricts access to your services to known users. Read the technical documentation."
|
||||
---
|
||||
|
||||
|
||||
|
||||
The `DigestAuth` middleware grants access to services to authorized users only.
|
||||
|
||||
## Configuration Examples
|
||||
|
||||
```yaml tab="Structured (YAML)"
|
||||
# Declaring the user list
|
||||
http:
|
||||
middlewares:
|
||||
test-auth:
|
||||
digestAuth:
|
||||
users:
|
||||
- "test:traefik:a2688e031edb4be6a3797f3882655c05"
|
||||
- "test2:traefik:518845800f9e2bfb1f1f740ec24f074e"
|
||||
```
|
||||
|
||||
```toml tab="Structured (TOML)"
|
||||
# Declaring the user list
|
||||
[http.middlewares]
|
||||
[http.middlewares.test-auth.digestAuth]
|
||||
users = [
|
||||
"test:traefik:a2688e031edb4be6a3797f3882655c05",
|
||||
"test2:traefik:518845800f9e2bfb1f1f740ec24f074e",
|
||||
]
|
||||
```
|
||||
|
||||
```yaml tab="Labels"
|
||||
# Declaring the user list
|
||||
labels:
|
||||
- "traefik.http.middlewares.test-auth.digestauth.users=test:traefik:a2688e031edb4be6a3797f3882655c05,test2:traefik:518845800f9e2bfb1f1f740ec24f074e"
|
||||
```
|
||||
|
||||
```json tab="Tags"
|
||||
// Declaring the user list
|
||||
{
|
||||
//...
|
||||
"Tags" : [
|
||||
"traefik.http.middlewares.test-auth.digestauth.users=test:traefik:a2688e031edb4be6a3797f3882655c05,test2:traefik:518845800f9e2bfb1f1f740ec24f074e"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
```yaml tab="Kubernetes"
|
||||
# Declaring the user list
|
||||
apiVersion: traefik.io/v1alpha1
|
||||
kind: Middleware
|
||||
metadata:
|
||||
name: test-auth
|
||||
spec:
|
||||
digestAuth:
|
||||
secret: userssecret
|
||||
```
|
||||
|
||||
## Configuration Options
|
||||
|
||||
| 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--usersfile))| [] | No |
|
||||
| `usersFile` | Path to an external file that contains the authorized users for the middleware. <br />The file content is a list of `name:realm:encoded-password`. (More information [here](#users--usersfile)) | "" | No |
|
||||
| `realm` | Allow customizing the realm for the authentication.| "traefik" | No |
|
||||
| `headerField` | Allow defining a header field to store the authenticated user.| "" | No |
|
||||
| `removeHeader` | Allow removing the authorization header before forwarding the request to your service. | false | No |
|
||||
|
||||
### Passwords format
|
||||
|
||||
Passwords must be hashed using MD5, SHA1, or BCrypt.
|
||||
Use `htpasswd` to generate the passwords.
|
||||
|
||||
### users & usersFile
|
||||
|
||||
- If both `users` and `usersFile` are provided, they are merged. The contents of `usersFile` have precedence over the values in users.
|
||||
- Because referencing a file path isn’t feasible on Kubernetes, the `users` & `usersFile` field isn’t used in Kubernetes IngressRoute. Instead, use the `secret` field.
|
||||
|
||||
### Kubernetes Secrets
|
||||
|
||||
On Kubernetes, you don’t use the `users` or `usersFile` fields. Instead, you reference a Kubernetes secret using the `secret` field in your Middleware resource. This secret can be one of two types:
|
||||
|
||||
- `kubernetes.io/basic-auth secret`: This secret type contains two keys—`username` and `password`—but is generally suited for a smaller number of users. Please note that these keys are not hashed or encrypted in any way, and therefore is less secure than the other method.
|
||||
- Opaque secret with a users field: Here, the secret contains a single string field (often called `users`) where each line represents a user. This approach allows you to store multiple users in one secret.
|
||||
|
||||
{!traefik-for-business-applications.md!}
|
||||
|
|
@ -0,0 +1,108 @@
|
|||
---
|
||||
title: "Traefik Errors Documentation"
|
||||
description: "In Traefik Proxy, the Errors middleware returns custom pages according to configured ranges of HTTP Status codes. Read the technical documentation."
|
||||
---
|
||||
|
||||
|
||||
|
||||
The `errors` middleware returns a custom page in lieu of the default, according to configured ranges of HTTP Status codes.
|
||||
|
||||
## Configuration Examples
|
||||
|
||||
```yaml tab="Structured (YAML)"
|
||||
# Dynamic Custom Error Page for 5XX Status Code excluding 502 and 504
|
||||
http:
|
||||
middlewares:
|
||||
test-errors:
|
||||
errors:
|
||||
status:
|
||||
- "500"
|
||||
- "501"
|
||||
- "503"
|
||||
- "505-599"
|
||||
service: error-handler-service
|
||||
query: "/{status}.html"
|
||||
|
||||
services:
|
||||
# ... definition of the error-handler-service
|
||||
```
|
||||
|
||||
```toml tab="Structured (TOML)"
|
||||
# Dynamic Custom Error Page for 5XX Status Code excluding 502 and 504
|
||||
[http.middlewares]
|
||||
[http.middlewares.test-errors.errors]
|
||||
status = ["500","501","503","505-599"]
|
||||
service = "error-handler-service"
|
||||
query = "/{status}.html"
|
||||
|
||||
[http.services]
|
||||
# ... definition of the error-handler-service
|
||||
```
|
||||
|
||||
```yaml tab="Labels"
|
||||
# Dynamic Custom Error Page for 5XX Status Code
|
||||
labels:
|
||||
- "traefik.http.middlewares.test-errors.errors.status=500,501,503,505-599"
|
||||
- "traefik.http.middlewares.test-errors.errors.service=error-handler-service"
|
||||
- "traefik.http.middlewares.test-errors.errors.query=/{status}.html"
|
||||
```
|
||||
|
||||
```json tab="Tags"
|
||||
// Dynamic Custom Error Page for 5XX Status Code excluding 502 and 504
|
||||
{
|
||||
// ...
|
||||
"Tags": [
|
||||
"traefik.http.middlewares.test-errors.errors.status=500,501,503,505-599",
|
||||
"traefik.http.middlewares.test-errors.errors.service=error-handler-service",
|
||||
"traefik.http.middlewares.test-errors.errors.query=/{status}.html"
|
||||
]
|
||||
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
```yaml tab="Kubernetes"
|
||||
apiVersion: traefik.io/v1alpha1
|
||||
kind: Middleware
|
||||
metadata:
|
||||
name: test-errors
|
||||
spec:
|
||||
errors:
|
||||
status:
|
||||
- "500"
|
||||
- "501"
|
||||
- "503"
|
||||
- "505-599"
|
||||
query: /{status}.html
|
||||
service:
|
||||
name: error-handler-service
|
||||
port: 80
|
||||
```
|
||||
|
||||
## Configuration Options
|
||||
|
||||
| Field | Description | Default | Required |
|
||||
|:-----------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:--------|:---------|
|
||||
| `status` | Defines which status or range of statuses should result in an error page.<br/> The status code ranges are inclusive (`505-599` will trigger with every code between `505` and `599`, `505` and `599` included).<br /> You can define either a status code as a number (`500`), as multiple comma-separated numbers (`500,502`), as ranges by separating two codes with a dash (`505-599`), or a combination of the two (`404,418,505-599`). | [] | No |
|
||||
| `service` | The service that will serve the new requested error page.<br /> More information [here](#service-and-hostheader). | "" | No |
|
||||
| `query` | The URL for the error page (hosted by `service`).<br /> More information [here](#query) | "" | No |
|
||||
|
||||
### service and HostHeader
|
||||
|
||||
By default, the client `Host` header value is forwarded to the configured error service.
|
||||
To forward the `Host` value corresponding to the configured error service URL,
|
||||
the [`passHostHeader`](../../../../routing/services/index.md#pass-host-header) option must be set to `false`.
|
||||
|
||||
!!!info "Kubernetes"
|
||||
When specifying a service in Kubernetes (e.g., in an IngressRoute), you need to reference the `name`, `namespace`, and `port` of your Kubernetes Service resource. For example, `my-service.my-namespace@kubernetescrd` (or `my-service.my-namespace@kubernetescrd:80`) ensures that requests go to the correct service and port.
|
||||
|
||||
### query
|
||||
|
||||
There are multiple variables that can be placed in the `query` option to insert values in the URL.
|
||||
|
||||
The table below lists all the available variables and their associated values.
|
||||
|
||||
| Variable | Value |
|
||||
|------------|------------------------------------------------------------------|
|
||||
| `{status}` | The response status code. |
|
||||
| `{url}` | The [escaped](https://pkg.go.dev/net/url#QueryEscape) request URL.|
|
||||
|
|
@ -0,0 +1,98 @@
|
|||
---
|
||||
title: "Traefik ForwardAuth Documentation"
|
||||
description: "In Traefik Proxy, the HTTP ForwardAuth middleware delegates authentication to an external Service. Read the technical documentation."
|
||||
---
|
||||
|
||||
|
||||
|
||||
The `forwardAuth` middleware delegates authentication to an external service.
|
||||
If the service answers with a 2XX code, access is granted, and the original request is performed.
|
||||
Otherwise, the response from the authentication server is returned.
|
||||
|
||||
## Configuration Example
|
||||
|
||||
```yaml tab="Structured (YAML)"
|
||||
# Forward authentication to example.com
|
||||
http:
|
||||
middlewares:
|
||||
test-auth:
|
||||
forwardAuth:
|
||||
address: "https://example.com/auth"
|
||||
```
|
||||
|
||||
```toml tab="Structured (TOML)"
|
||||
# Forward authentication to example.com
|
||||
[http.middlewares]
|
||||
[http.middlewares.test-auth.forwardAuth]
|
||||
address = "https://example.com/auth"
|
||||
```
|
||||
|
||||
```yaml tab="Labels"
|
||||
# Forward authentication to example.com
|
||||
labels:
|
||||
- "traefik.http.middlewares.test-auth.forwardauth.address=https://example.com/auth"
|
||||
```
|
||||
|
||||
```json tab="Tags"
|
||||
// Forward authentication to example.com
|
||||
{
|
||||
"Tags" : [
|
||||
"traefik.http.middlewares.test-auth.forwardauth.address=https://example.com/auth"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
```yaml tab="Kubernetes"
|
||||
# Forward authentication to example.com
|
||||
apiVersion: traefik.io/v1alpha1
|
||||
kind: Middleware
|
||||
metadata:
|
||||
name: test-auth
|
||||
spec:
|
||||
forwardAuth:
|
||||
address: https://example.com/auth
|
||||
```
|
||||
|
||||
## Configuration Options
|
||||
|
||||
| Field | Description | Default | Required |
|
||||
|:-----------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:--------|:---------|
|
||||
| `address` | Authentication server address. | "" | Yes |
|
||||
| `trustForwardHeader` | Trust all `X-Forwarded-*` headers. | false | No |
|
||||
| `authResponseHeaders` | List of headers to copy from the authentication server response and set on forwarded request, replacing any existing conflicting headers. | [] | No |
|
||||
| `authResponseHeadersRegex` | Regex to match by the headers to copy from the authentication server response and set on forwarded request, after stripping all headers that match the regex.<br /> More information [here](#authresponseheadersregex). | "" | No |
|
||||
| `authRequestHeaders` | List of the headers to copy from the request to the authentication server. <br /> It allows filtering headers that should not be passed to the authentication server. <br /> If not set or empty, then all request headers are passed. | [] | No |
|
||||
| `addAuthCookiesToResponse` | List of cookies to copy from the authentication server to the response, replacing any existing conflicting cookie from the forwarded response.<br /> Please note that all backend cookies matching the configured list will not be added to the response. | [] | No |
|
||||
| `forwardBody` | Sets the `forwardBody` option to `true` to send the Body. As body is read inside Traefik before forwarding, this breaks streaming. | false | No |
|
||||
| `maxBodySize` | Set the `maxBodySize` to limit the body size in bytes. If body is bigger than this, it returns a 401 (unauthorized). | -1 | No |
|
||||
| `headerField` | Defines a header field to store the authenticated user. | "" | No |
|
||||
| `preserveLocationHeader` | Defines whether to forward the Location header to the client as is or prefix it with the domain name of the authentication server. | false | No |
|
||||
| `PreserveRequestMethod` | Defines whether to preserve the original request method while forwarding the request to the authentication server. | false | No |
|
||||
| `tls.ca` | Sets the path to the certificate authority used for the secured connection to the authentication server, it defaults to the system bundle. | "" | No |
|
||||
| `tls.cert` | Sets the path to the public certificate used for the secure connection to the authentication server. When using this option, setting the key option is required. | "" | No |
|
||||
| `tls.key` | Sets the path to the private key used for the secure connection to the authentication server. When using this option, setting the `cert` option is required. | "" | No |
|
||||
| `tls.caSecret` | Defines the secret that contains the certificate authority used for the secured connection to the authentication server, it defaults to the system bundle. **This option is only available for the Kubernetes CRD**. | | No |
|
||||
| `tls.certSecret` | Defines the secret that contains both the private and public certificates used for the secure connection to the authentication server. **This option is only available for the Kubernetes CRD**. | | No |
|
||||
| `tls.insecureSkipVerify` | During TLS connections, if this option is set to `true`, the authentication server will accept any certificate presented by the server regardless of the host names it covers. | false | No |
|
||||
|
||||
### authResponseHeadersRegex
|
||||
|
||||
It allows partial matching of the regular expression against the header key.
|
||||
|
||||
The start of string (`^`) and end of string (`$`) anchors should be used to ensure a full match against the header key.
|
||||
|
||||
Regular expressions and replacements can be tested using online tools such as [Go Playground](https://play.golang.org/p/mWU9p-wk2ru) or the [Regex101](https://regex101.com/r/58sIgx/2).
|
||||
|
||||
## Forward-Request Headers
|
||||
|
||||
The following request properties are provided to the forward-auth target endpoint as `X-Forwarded-` headers.
|
||||
|
||||
| Property | Forward-Request Header |
|
||||
|-------------------|------------------------|
|
||||
| HTTP Method | X-Forwarded-Method |
|
||||
| Protocol | X-Forwarded-Proto |
|
||||
| Host | X-Forwarded-Host |
|
||||
| Request URI | X-Forwarded-Uri |
|
||||
| Source IP-Address | X-Forwarded-For |
|
||||
|
||||
{!traefik-for-business-applications.md!}
|
||||
|
|
@ -0,0 +1,67 @@
|
|||
---
|
||||
title: "Traefik GrpcWeb Documentation"
|
||||
description: "In Traefik Proxy's HTTP middleware, GrpcWeb converts a gRPC Web requests to HTTP/2 gRPC requests. Read the technical documentation."
|
||||
---
|
||||
|
||||
The `grpcWeb` middleware converts gRPC Web requests to HTTP/2 gRPC requests before forwarding them to the backends.
|
||||
|
||||
!!! tip
|
||||
|
||||
Please note, that Traefik needs to communicate using gRPC with the backends (h2c or HTTP/2 over TLS).
|
||||
Check out the [gRPC](../../../../user-guides/grpc.md) user guide for more details.
|
||||
|
||||
## Configuration Examples
|
||||
|
||||
```yaml tab="Structured (YAML)"
|
||||
http:
|
||||
middlewares:
|
||||
test-grpcweb:
|
||||
grpcWeb:
|
||||
allowOrigins:
|
||||
- "*"
|
||||
```
|
||||
|
||||
```toml tab="Structured (TOML)"
|
||||
[http.middlewares]
|
||||
[http.middlewares.test-grpcweb.grpcWeb]
|
||||
allowOrigins = ["*"]
|
||||
```
|
||||
|
||||
```yaml tab="Labels"
|
||||
labels:
|
||||
- "traefik.http.middlewares.test-grpcweb.grpcweb.allowOrigins=*"
|
||||
```
|
||||
|
||||
```json tab="Tags"
|
||||
{
|
||||
//...
|
||||
"Tags" : [
|
||||
"traefik.http.middlewares.test-grpcweb.grpcWeb.allowOrigins=*"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
```yaml tab="Kubernetes"
|
||||
apiVersion: traefik.io/v1alpha1
|
||||
kind: Middleware
|
||||
metadata:
|
||||
name: test-grpcweb
|
||||
spec:
|
||||
grpcWeb:
|
||||
allowOrigins:
|
||||
- "*"
|
||||
```
|
||||
|
||||
## Configuration Options
|
||||
|
||||
| Field | Description | Default | Required |
|
||||
|:-----------------------------|:------------------------------------------|:--------|:---------|
|
||||
| `allowOrigins` | List of allowed origins. <br /> A wildcard origin `*` can also be configured to match all requests.<br /> More information [here](#alloworigins). | [] | No |
|
||||
|
||||
### allowOrigins
|
||||
|
||||
More information including how to use the settings can be found at:
|
||||
|
||||
- [Mozilla.org](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Origin)
|
||||
- [w3](https://fetch.spec.whatwg.org/#http-access-control-allow-origin)
|
||||
- [IETF](https://tools.ietf.org/html/rfc6454#section-7.1)
|
||||
|
|
@ -0,0 +1,328 @@
|
|||
---
|
||||
title: "Traefik Headers Documentation"
|
||||
description: "In Traefik Proxy, the HTTP headers middleware manages the headers of requests and responses. Read the technical documentation."
|
||||
---
|
||||
|
||||
|
||||
|
||||
The Headers middleware manages the headers of requests and responses.
|
||||
|
||||
By default, the following headers are automatically added when proxying requests:
|
||||
|
||||
| Property | HTTP Header |
|
||||
|---------------------------|----------------------------|
|
||||
| Client's IP | X-Forwarded-For, X-Real-Ip |
|
||||
| Host | X-Forwarded-Host |
|
||||
| Port | X-Forwarded-Port |
|
||||
| Protocol | X-Forwarded-Proto |
|
||||
| Proxy Server's Hostname | X-Forwarded-Server |
|
||||
|
||||
## Configuration Examples
|
||||
|
||||
### Adding Headers to the Request and the Response
|
||||
|
||||
The following example adds the `X-Script-Name` header to the proxied request and the `X-Custom-Response-Header` header to the response
|
||||
|
||||
```yaml tab="Structured (YAML)"
|
||||
http:
|
||||
middlewares:
|
||||
testHeader:
|
||||
headers:
|
||||
customRequestHeaders:
|
||||
X-Script-Name: "test"
|
||||
customResponseHeaders:
|
||||
X-Custom-Response-Header: "value"
|
||||
```
|
||||
|
||||
```toml tab="Structured (TOML)"
|
||||
[http.middlewares]
|
||||
[http.middlewares.testHeader.headers]
|
||||
[http.middlewares.testHeader.headers.customRequestHeaders]
|
||||
X-Script-Name = "test"
|
||||
[http.middlewares.testHeader.headers.customResponseHeaders]
|
||||
X-Custom-Response-Header = "value"
|
||||
```
|
||||
|
||||
```yaml tab="Labels"
|
||||
labels:
|
||||
- "traefik.http.middlewares.testHeader.headers.customrequestheaders.X-Script-Name=test"
|
||||
- "traefik.http.middlewares.testHeader.headers.customresponseheaders.X-Custom-Response-Header=value"
|
||||
```
|
||||
|
||||
```json tab="Tags"
|
||||
{
|
||||
//...
|
||||
"Tags": [
|
||||
"traefik.http.middlewares.testheader.headers.customrequestheaders.X-Script-Name=test",
|
||||
"traefik.http.middlewares.testheader.headers.customresponseheaders.X-Custom-Response-Header=value"
|
||||
]
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
```yaml tab="Kubernetes"
|
||||
apiVersion: traefik.io/v1alpha1
|
||||
kind: Middleware
|
||||
metadata:
|
||||
name: test-header
|
||||
spec:
|
||||
headers:
|
||||
customRequestHeaders:
|
||||
X-Script-Name: "test"
|
||||
customResponseHeaders:
|
||||
X-Custom-Response-Header: "value"
|
||||
```
|
||||
|
||||
### Adding and Removing Headers
|
||||
|
||||
In the following example, requests are proxied with an extra `X-Script-Name` header while their `X-Custom-Request-Header` header gets stripped,
|
||||
and responses are stripped of their `X-Custom-Response-Header` header.
|
||||
|
||||
```yaml tab="Structured (YAML)"
|
||||
http:
|
||||
middlewares:
|
||||
testHeader:
|
||||
headers:
|
||||
customRequestHeaders:
|
||||
X-Script-Name: "test" # Adds
|
||||
X-Custom-Request-Header: "" # Removes
|
||||
customResponseHeaders:
|
||||
X-Custom-Response-Header: "" # Removes
|
||||
```
|
||||
|
||||
```toml tab="Structured (TOML)"
|
||||
[http.middlewares]
|
||||
[http.middlewares.testHeader.headers]
|
||||
[http.middlewares.testHeader.headers.customRequestHeaders]
|
||||
X-Script-Name = "test" # Adds
|
||||
X-Custom-Request-Header = "" # Removes
|
||||
[http.middlewares.testHeader.headers.customResponseHeaders]
|
||||
X-Custom-Response-Header = "" # Removes
|
||||
```
|
||||
|
||||
```yaml tab="Labels"
|
||||
labels:
|
||||
- "traefik.http.middlewares.testheader.headers.customrequestheaders.X-Script-Name=test"
|
||||
- "traefik.http.middlewares.testheader.headers.customrequestheaders.X-Custom-Request-Header="
|
||||
- "traefik.http.middlewares.testheader.headers.customresponseheaders.X-Custom-Response-Header="
|
||||
```
|
||||
|
||||
```json tab="Tags"
|
||||
{
|
||||
"Tags" : [
|
||||
"traefik.http.middlewares.testheader.headers.customrequestheaders.X-Script-Name=test",
|
||||
"traefik.http.middlewares.testheader.headers.customrequestheaders.X-Custom-Request-Header=",
|
||||
"traefik.http.middlewares.testheader.headers.customresponseheaders.X-Custom-Response-Header="
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
```yaml tab="Kubernetes"
|
||||
apiVersion: traefik.io/v1alpha1
|
||||
kind: Middleware
|
||||
metadata:
|
||||
name: test-header
|
||||
spec:
|
||||
headers:
|
||||
customRequestHeaders:
|
||||
X-Script-Name: "test" # Adds
|
||||
X-Custom-Request-Header: "" # Removes
|
||||
customResponseHeaders:
|
||||
X-Custom-Response-Header: "" # Removes
|
||||
```
|
||||
|
||||
### Using Security Headers
|
||||
|
||||
Security-related headers (HSTS headers, Browser XSS filter, etc) can be managed similarly to custom headers as shown above.
|
||||
This functionality makes it possible to easily use security features by adding headers.
|
||||
|
||||
```yaml tab="Structured (YAML)"
|
||||
http:
|
||||
middlewares:
|
||||
testHeader:
|
||||
headers:
|
||||
frameDeny: true
|
||||
browserXssFilter: true
|
||||
```
|
||||
|
||||
```toml tab="Structured (TOML)"
|
||||
[http.middlewares]
|
||||
[http.middlewares.testHeader.headers]
|
||||
frameDeny = true
|
||||
browserXssFilter = true
|
||||
```
|
||||
|
||||
```yaml tab="Labels"
|
||||
labels:
|
||||
- "traefik.http.middlewares.testHeader.headers.framedeny=true"
|
||||
- "traefik.http.middlewares.testHeader.headers.browserxssfilter=true"
|
||||
```
|
||||
|
||||
```json tab="Tags"
|
||||
{
|
||||
"Tags" : [
|
||||
"traefik.http.middlewares.testheader.headers.framedeny=true",
|
||||
"traefik.http.middlewares.testheader.headers.browserxssfilter=true"
|
||||
]
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
```yaml tab="Kubernetes"
|
||||
apiVersion: traefik.io/v1alpha1
|
||||
kind: Middleware
|
||||
metadata:
|
||||
name: test-header
|
||||
spec:
|
||||
headers:
|
||||
frameDeny: true
|
||||
browserXssFilter: true
|
||||
```
|
||||
|
||||
### CORS Headers
|
||||
|
||||
CORS (Cross-Origin Resource Sharing) headers can be added and configured in a manner similar to the custom headers above.
|
||||
This functionality allows for more advanced security features to quickly be set.
|
||||
If CORS headers are set, then the middleware does not pass preflight requests to any service,
|
||||
instead the response will be generated and sent back to the client directly.
|
||||
Please note that the example below is by no means authoritative or exhaustive,
|
||||
and should not be used as is for production.
|
||||
|
||||
```yaml tab="Structured (YAML)"
|
||||
http:
|
||||
middlewares:
|
||||
testHeader:
|
||||
headers:
|
||||
accessControlAllowMethods:
|
||||
- GET
|
||||
- OPTIONS
|
||||
- PUT
|
||||
accessControlAllowHeaders: "*"
|
||||
accessControlAllowOriginList:
|
||||
- https://foo.bar.org
|
||||
- https://example.org
|
||||
accessControlMaxAge: 100
|
||||
addVaryHeader: true
|
||||
```
|
||||
|
||||
```toml tab="Structured (TOML)"
|
||||
[http.middlewares]
|
||||
[http.middlewares.testHeader.headers]
|
||||
accessControlAllowMethods = ["GET", "OPTIONS", "PUT"]
|
||||
accessControlAllowHeaders = [ "*" ]
|
||||
accessControlAllowOriginList = ["https://foo.bar.org","https://example.org"]
|
||||
accessControlMaxAge = 100
|
||||
addVaryHeader = true
|
||||
```
|
||||
|
||||
```yaml tab="Labels"
|
||||
labels:
|
||||
- "traefik.http.middlewares.testheader.headers.accesscontrolallowmethods=GET,OPTIONS,PUT"
|
||||
- "traefik.http.middlewares.testheader.headers.accesscontrolallowheaders=*"
|
||||
- "traefik.http.middlewares.testheader.headers.accesscontrolalloworiginlist=https://foo.bar.org,https://example.org"
|
||||
- "traefik.http.middlewares.testheader.headers.accesscontrolmaxage=100"
|
||||
- "traefik.http.middlewares.testheader.headers.addvaryheader=true"
|
||||
```
|
||||
|
||||
```json tab="Tags"
|
||||
{
|
||||
"Tags" : [
|
||||
"traefik.http.middlewares.testheader.headers.accesscontrolallowmethods=GET,OPTIONS,PUT",
|
||||
"traefik.http.middlewares.testheader.headers.accesscontrolallowheaders=*",
|
||||
"traefik.http.middlewares.testheader.headers.accesscontrolalloworiginlist=https://foo.bar.org,https://example.org",
|
||||
"traefik.http.middlewares.testheader.headers.accesscontrolmaxage=100",
|
||||
"traefik.http.middlewares.testheader.headers.addvaryheader=true"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
```yaml tab="Kubernetes"
|
||||
apiVersion: traefik.io/v1alpha1
|
||||
kind: Middleware
|
||||
metadata:
|
||||
name: test-header
|
||||
spec:
|
||||
headers:
|
||||
accessControlAllowMethods:
|
||||
- "GET"
|
||||
- "OPTIONS"
|
||||
- "PUT"
|
||||
accessControlAllowHeaders:
|
||||
- "*"
|
||||
accessControlAllowOriginList:
|
||||
- "https://foo.bar.org"
|
||||
- "https://example.org"
|
||||
accessControlMaxAge: 100
|
||||
addVaryHeader: true
|
||||
```
|
||||
|
||||
## Configuration Options
|
||||
|
||||
!!! warning
|
||||
|
||||
Custom headers will overwrite existing headers if they have identical names.
|
||||
|
||||
!!! note ""
|
||||
|
||||
The detailed documentation for security headers can be found in [unrolled/secure](https://github.com/unrolled/secure#available-options).
|
||||
|
||||
| Field | Description | Default | Required |
|
||||
| ----------------------------- | ------------------------------------------------- | --------- | -------- |
|
||||
| `customRequestHeaders` | Lists the header names and values for requests. | [] | No |
|
||||
| `customResponseHeaders` | Lists the header names and values for responses. | [] | No |
|
||||
| `accessControlAllowCredentials` | Indicates if the request can include user credentials.| false | No |
|
||||
| `accessControlAllowHeaders` | Specifies allowed request header names. | [] | No |
|
||||
| `accessControlAllowMethods` | Specifies allowed request methods. | [] | No |
|
||||
| `accessControlAllowOriginList` | Specifies allowed origins. More information [here](#accesscontrolalloworiginlist) | [] | No |
|
||||
| `accessControlAllowOriginListRegex` | Allows origins matching regex. More information [here](#accesscontrolalloworiginlistregex) | [] | No |
|
||||
| `accessControlExposeHeaders` | Specifies which headers are safe to expose to the API of a CORS API specification. | [] | No |
|
||||
| `accessControlMaxAge` | Time (in seconds) to cache preflight requests. | 0 | No |
|
||||
| `addVaryHeader` | Used in conjunction with `accessControlAllowOriginList` to determine whether the `Vary` header should be added or modified to demonstrate that server responses can differ based on the value of the origin header. | false | No |
|
||||
| `allowedHosts` | Lists allowed domain names. | [] | No |
|
||||
| `hostsProxyHeaders` | Specifies header keys for proxied hostname. | [] | No |
|
||||
| `sslProxyHeaders` | Defines a set of header keys with associated values that would indicate a valid HTTPS request. It can be useful when using other proxies (example: `"X-Forwarded-Proto": "https"`). | {} | No |
|
||||
| `stsSeconds` | Max age for `Strict-Transport-Security` header. | 0 | No |
|
||||
| `stsIncludeSubdomains` | If set to `true`, the `includeSubDomains` directive is appended to the `Strict-Transport-Security` header. | false | No |
|
||||
| `stsPreload` | Adds preload flag to STS header. | false | No |
|
||||
| `forceSTSHeader` | Adds STS header for HTTP connections. | false | No |
|
||||
| `frameDeny` | Set `frameDeny` to `true` to add the `X-Frame-Options` header with the value of `DENY`. | false | No |
|
||||
| `customFrameOptionsValue` | allows the `X-Frame-Options` header value to be set with a custom value. This overrides the `FrameDeny` option. | "" | No |
|
||||
| `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. | false | No |
|
||||
| `contentSecurityPolicy` | allows the `Content-Security-Policy` header value to be set with a custom value. | false | 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. | "" | No |
|
||||
| `isDevelopment` | Set `true` when developing to mitigate the unwanted effects of the `AllowedHosts`, SSL, and STS options. Usually testing takes place using HTTP, not HTTPS, and on `localhost`, not your production domain. | false | No |
|
||||
|
||||
### `accessControlAllowOriginList`
|
||||
|
||||
The `accessControlAllowOriginList` indicates whether a resource can be shared by returning different values.
|
||||
|
||||
A wildcard origin `*` can also be configured, and matches all requests.
|
||||
If this value is set by a backend service, it will be overwritten by Traefik.
|
||||
|
||||
This value can contain a list of allowed origins.
|
||||
|
||||
More information including how to use the settings can be found at:
|
||||
|
||||
- [Mozilla.org](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Origin)
|
||||
- [w3](https://fetch.spec.whatwg.org/#http-access-control-allow-origin)
|
||||
- [IETF](https://tools.ietf.org/html/rfc6454#section-7.1)
|
||||
|
||||
Traefik no longer supports the `null` value, as it is [no longer recommended as a return value](https://w3c.github.io/webappsec-cors-for-developers/#avoid-returning-access-control-allow-origin-null).
|
||||
|
||||
### `accessControlAllowOriginListRegex`
|
||||
|
||||
The `accessControlAllowOriginListRegex` option is the counterpart of the `accessControlAllowOriginList` option with regular expressions instead of origin values.
|
||||
It allows all origins that contain any match of a regular expression in the `accessControlAllowOriginList`.
|
||||
|
||||
!!! tip
|
||||
|
||||
Regular expressions and replacements can be tested using online tools such as [Go Playground](https://play.golang.org/p/mWU9p-wk2ru) or the [Regex101](https://regex101.com/r/58sIgx/2).
|
||||
|
||||
When defining a regular expression within YAML, any escaped character needs to be escaped twice: `example\.com` needs to be written as `example\\.com`.
|
||||
|
||||
{!traefik-for-business-applications.md!}
|
||||
|
|
@ -0,0 +1,115 @@
|
|||
---
|
||||
title: "Traefik InFlightReq Documentation"
|
||||
description: "Traefik Proxy's HTTP middleware lets you limit the number of simultaneous in-flight requests. Read the technical documentation."
|
||||
---
|
||||
|
||||
The `inFlightReq` middleware proactively prevents services from being overwhelmed with high load.
|
||||
|
||||
## Configuration Examples
|
||||
|
||||
```yaml tab="Structured (YAML)"
|
||||
# Limiting to 10 simultaneous connections
|
||||
http:
|
||||
middlewares:
|
||||
test-inflightreq:
|
||||
inFlightReq:
|
||||
amount: 10
|
||||
```
|
||||
|
||||
```toml tab="Structured (TOML)"
|
||||
# Limiting to 10 simultaneous connections
|
||||
[http.middlewares]
|
||||
[http.middlewares.test-inflightreq.inFlightReq]
|
||||
amount = 10
|
||||
```
|
||||
|
||||
```yaml tab="Labels"
|
||||
labels:
|
||||
- "traefik.http.middlewares.test-inflightreq.inflightreq.amount=10"
|
||||
```
|
||||
|
||||
```json tab="Consul Catalog"
|
||||
// Limiting to 10 simultaneous connections
|
||||
{
|
||||
"Tags" : [
|
||||
"traefik.http.middlewares.test-inflightreq.inflightreq.amount=10"
|
||||
]
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
```yaml tab="Kubernetes"
|
||||
apiVersion: traefik.io/v1alpha1
|
||||
kind: Middleware
|
||||
metadata:
|
||||
name: test-inflightreq
|
||||
spec:
|
||||
inFlightReq:
|
||||
amount: 10
|
||||
```
|
||||
|
||||
## Configuration Options
|
||||
|
||||
<!-- markdownlint-disable MD013 -->
|
||||
|
||||
| Field | Description | Default | Required |
|
||||
|:-----------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:--------|:---------|
|
||||
| `amount` | The `amount` option defines the maximum amount of allowed simultaneous in-flight request. <br /> The middleware responds with `HTTP 429 Too Many Requests` if there are already `amount` requests in progress (based on the same `sourceCriterion` strategy). | 0 | No |
|
||||
| `sourceCriterion.requestHost` | Whether to consider the request host as the source.<br /> More information about `sourceCriterion`[here](#sourcecriterion). | false | No |
|
||||
| `sourceCriterion.requestHeaderName` | Name of the header used to group incoming requests.<br /> More information about `sourceCriterion`[here](#sourcecriterion). | "" | No |
|
||||
| `sourceCriterion.ipStrategy.depth` | Depth position of the IP to select in the `X-Forwarded-For` header (starting from the right).<br />0 means no depth.<br />If greater than the total number of IPs in `X-Forwarded-For`, then the client IP is empty<br />If higher than 0, the `excludedIPs` options is not evaluated.<br /> More information about [`sourceCriterion`](#sourcecriterion), [`ipStrategy](#ipstrategy), and [`depth`](#example-of-depth--x-forwarded-for) below. | 0 | No |
|
||||
| `sourceCriterion.ipStrategy.excludedIPs` | Allows Traefik to scan the `X-Forwarded-For` header and select the first IP not in the list.<br />If `depth` is specified, `excludedIPs` is ignored.<br /> More information about [`sourceCriterion`](#sourcecriterion), [`ipStrategy](#ipstrategy), and [`excludedIPs`](#example-of-excludedips--x-forwarded-for) below. | | No |
|
||||
| `sourceCriterion.ipStrategy.ipv6Subnet` | If `ipv6Subnet` is provided and the selected IP is IPv6, the IP is transformed into the first IP of the subnet it belongs to. <br /> More information about [`sourceCriterion`](#sourcecriterion), [`ipStrategy.ipv6Subnet`](#ipstrategyipv6subnet), and [`excludedIPs`](#example-of-excludedips--x-forwarded-for) below. | | No |
|
||||
|
||||
### sourceCriterion
|
||||
|
||||
The `sourceCriterion` option defines what criterion is used to group requests as originating from a common source.
|
||||
If several strategies are defined at the same time, an error will be raised.
|
||||
If none are set, the default is to use the `requestHost`.
|
||||
|
||||
### ipStrategy
|
||||
|
||||
The `ipStrategy` option defines three parameters that configures how Traefik determines the client IP: `depth`, `excludedIPs` and `ipv6Subnet`.
|
||||
|
||||
As a middleware, `inFlightReq` happens before the actual proxying to the backend takes place.
|
||||
In addition, the previous network hop only gets appended to `X-Forwarded-For` during the last stages of proxying, that is after it has already passed through the middleware.
|
||||
Therefore, during InFlightReq, as the previous network hop is not yet present in `X-Forwarded-For`, it cannot be used and/or relied upon.
|
||||
|
||||
### `ipStrategy.ipv6Subnet`
|
||||
|
||||
This strategy applies to `Depth` and `RemoteAddr` strategy only.
|
||||
If `ipv6Subnet` is provided and the selected IP is IPv6, the IP is transformed into the first IP of the subnet it belongs to.
|
||||
|
||||
This is useful for grouping IPv6 addresses into subnets to prevent bypassing this middleware by obtaining a new IPv6.
|
||||
|
||||
- `ipv6Subnet` is ignored if its value is outside 0-128 interval
|
||||
|
||||
#### Example of ipv6Subnet
|
||||
|
||||
If `ipv6Subnet` is provided, the IP is transformed in the following way.
|
||||
|
||||
| IP | ipv6Subnet | clientIP |
|
||||
|---------------------------|--------------|-----------------------|
|
||||
| `"::abcd:1111:2222:3333"` | `64` | `"::0:0:0:0"` |
|
||||
| `"::abcd:1111:2222:3333"` | `80` | `"::abcd:0:0:0:0"` |
|
||||
| `"::abcd:1111:2222:3333"` | `96` | `"::abcd:1111:0:0:0"` |
|
||||
|
||||
### Example of Depth & X-Forwarded-For
|
||||
|
||||
If `depth` is set to 2, and the request `X-Forwarded-For` header is `"10.0.0.1,11.0.0.1,12.0.0.1,13.0.0.1"` then the "real" client IP is `"10.0.0.1"` (at depth 4) but the IP used as the criterion is `"12.0.0.1"` (`depth=2`).
|
||||
|
||||
| X-Forwarded-For | depth | clientIP |
|
||||
|-----------------------------------------|---------|--------------|
|
||||
| `"10.0.0.1,11.0.0.1,12.0.0.1,13.0.0.1"` | `1` | `"13.0.0.1"` |
|
||||
| `"10.0.0.1,11.0.0.1,12.0.0.1,13.0.0.1"` | `3` | `"11.0.0.1"` |
|
||||
| `"10.0.0.1,11.0.0.1,12.0.0.1,13.0.0.1"` | `5` | `""` |
|
||||
|
||||
### Example of ExcludedIPs & X-Forwarded-For
|
||||
|
||||
| X-Forwarded-For | excludedIPs | clientIP |
|
||||
|-----------------------------------------|-----------------------|--------------|
|
||||
| `"10.0.0.1,11.0.0.1,12.0.0.1,13.0.0.1"` | `"12.0.0.1,13.0.0.1"` | `"11.0.0.1"` |
|
||||
| `"10.0.0.1,11.0.0.1,12.0.0.1,13.0.0.1"` | `"15.0.0.1,13.0.0.1"` | `"12.0.0.1"` |
|
||||
| `"10.0.0.1,11.0.0.1,12.0.0.1,13.0.0.1"` | `"10.0.0.1,13.0.0.1"` | `"12.0.0.1"` |
|
||||
| `"10.0.0.1,11.0.0.1,12.0.0.1,13.0.0.1"` | `"15.0.0.1,16.0.0.1"` | `"13.0.0.1"` |
|
||||
| `"10.0.0.1,11.0.0.1"` | `"10.0.0.1,11.0.0.1"` | `""` |
|
||||
|
|
@ -0,0 +1,120 @@
|
|||
---
|
||||
title: "Traefik HTTP Middlewares IPAllowList"
|
||||
description: "Learn how to use IPAllowList in HTTP middleware for limiting clients to specific IPs in Traefik Proxy. Read the technical documentation."
|
||||
---
|
||||
|
||||
`ipAllowList` accepts / refuses requests based on the client IP.
|
||||
|
||||
## Configuration Example
|
||||
|
||||
```yaml tab="Structured (YAML)"
|
||||
# Accepts request from defined IP
|
||||
http:
|
||||
middlewares:
|
||||
test-ipallowlist:
|
||||
ipAllowList:
|
||||
sourceRange:
|
||||
- "127.0.0.1/32"
|
||||
- "192.168.1.7"
|
||||
```
|
||||
|
||||
```toml tab="Structured (TOML)"
|
||||
# Accepts request from defined IP
|
||||
[http.middlewares]
|
||||
[http.middlewares.test-ipallowlist.ipAllowList]
|
||||
sourceRange = ["127.0.0.1/32", "192.168.1.7"]
|
||||
```
|
||||
|
||||
```yaml tab="Labels"
|
||||
# Accepts request from defined IP
|
||||
labels:
|
||||
- "traefik.http.middlewares.test-ipallowlist.ipallowlist.sourcerange=127.0.0.1/32, 192.168.1.7"
|
||||
```
|
||||
|
||||
```json tab="Tags"
|
||||
// Accepts request from defined IP
|
||||
{
|
||||
"Tags" : [
|
||||
"traefik.http.middlewares.test-ipallowlist.ipallowlist.sourcerange=127.0.0.1/32, 192.168.1.7"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
```yaml tab="Kubernetes"
|
||||
apiVersion: traefik.io/v1alpha1
|
||||
kind: Middleware
|
||||
metadata:
|
||||
name: test-ipallowlist
|
||||
spec:
|
||||
ipAllowList:
|
||||
sourceRange:
|
||||
- 127.0.0.1/32
|
||||
- 192.168.1.7
|
||||
```
|
||||
|
||||
## Configuration Options
|
||||
|
||||
| Field | Description | Default | Required |
|
||||
|:-----------|:------------------------------|:--------|:---------|
|
||||
| `sourceRange` | List of allowed IPs (or ranges of allowed IPs by using CIDR notation). | | Yes |
|
||||
| `ipStrategy.depth` | Depth position of the IP to select in the `X-Forwarded-For` header (starting from the right).<br />0 means no depth.<br />If greater than the total number of IPs in `X-Forwarded-For`, then the client IP is empty<br /> If higher than 0, the `excludedIPs` options is not evaluated.<br /> More information about [`ipStrategy](#ipstrategy), and [`depth`](#example-of-depth--x-forwarded-for) below. | 0 | No |
|
||||
| `ipStrategy.excludedIPs` | Allows Traefik to scan the `X-Forwarded-For` header and select the first IP not in the list.<br />If `depth` is specified, `excludedIPs` is ignored.<br /> More information about [`ipStrategy](#ipstrategy), and [`excludedIPs`](#example-of-excludedips--x-forwarded-for) below. | | No |
|
||||
| `ipStrategy.ipv6Subnet` | If `ipv6Subnet` is provided and the selected IP is IPv6, the IP is transformed into the first IP of the subnet it belongs to. <br />More information about [`ipStrategy.ipv6Subnet`](#ipstrategyipv6subnet), and [`excludedIPs`](#example-of-excludedips--x-forwarded-for) below. | | No |
|
||||
|
||||
### ipStrategy
|
||||
|
||||
The `ipStrategy` option defines two parameters that configures how Traefik determines the client IP: `depth`, and `excludedIPs`.
|
||||
|
||||
If no strategy is set, the default behavior is to match `sourceRange` against the Remote address found in the request.
|
||||
|
||||
As a middleware, passlisting happens before the actual proxying to the backend takes place.
|
||||
In addition, the previous network hop only gets appended to `X-Forwarded-For` during the last stages of proxying, that is after it has already passed through passlisting.
|
||||
Therefore, during passlisting, as the previous network hop is not yet present in `X-Forwarded-For`, it cannot be matched against `sourceRange`.
|
||||
|
||||
#### `ipStrategy.depth`
|
||||
|
||||
The `depth` option tells Traefik to use the `X-Forwarded-For` header and take the IP located at the `depth` position (starting from the right).
|
||||
|
||||
- If `depth` is greater than the total number of IPs in `X-Forwarded-For`, then the client IP will be empty.
|
||||
- `depth` is ignored if its value is less than or equal to 0.
|
||||
|
||||
If `ipStrategy.ipv6Subnet` is provided and the selected IP is IPv6, the IP is transformed into the first IP of the subnet it belongs to.
|
||||
|
||||
### `ipStrategy.ipv6Subnet`
|
||||
|
||||
This strategy applies to `Depth` and `RemoteAddr` strategy only.
|
||||
If `ipv6Subnet` is provided and the selected IP is IPv6, the IP is transformed into the first IP of the subnet it belongs to.
|
||||
|
||||
This is useful for grouping IPv6 addresses into subnets to prevent bypassing this middleware by obtaining a new IPv6.
|
||||
|
||||
- `ipv6Subnet` is ignored if its value is outside 0-128 interval
|
||||
|
||||
#### Example of ipv6Subnet
|
||||
|
||||
If `ipv6Subnet` is provided, the IP is transformed in the following way.
|
||||
|
||||
| IP | ipv6Subnet | clientIP |
|
||||
|---------------------------|--------------|-----------------------|
|
||||
| `"::abcd:1111:2222:3333"` | `64` | `"::0:0:0:0"` |
|
||||
| `"::abcd:1111:2222:3333"` | `80` | `"::abcd:0:0:0:0"` |
|
||||
| `"::abcd:1111:2222:3333"` | `96` | `"::abcd:1111:0:0:0"` |
|
||||
|
||||
### Example of Depth & X-Forwarded-For
|
||||
|
||||
If `depth` is set to 2, and the request `X-Forwarded-For` header is `"10.0.0.1,11.0.0.1,12.0.0.1,13.0.0.1"` then the "real" client IP is `"10.0.0.1"` (at depth 4) but the IP used as the criterion is `"12.0.0.1"` (`depth=2`).
|
||||
|
||||
| X-Forwarded-For | depth | clientIP |
|
||||
|-----------------------------------------|---------|--------------|
|
||||
| `"10.0.0.1,11.0.0.1,12.0.0.1,13.0.0.1"` | `1` | `"13.0.0.1"` |
|
||||
| `"10.0.0.1,11.0.0.1,12.0.0.1,13.0.0.1"` | `3` | `"11.0.0.1"` |
|
||||
| `"10.0.0.1,11.0.0.1,12.0.0.1,13.0.0.1"` | `5` | `""` |
|
||||
|
||||
### Example of ExcludedIPs & X-Forwarded-For
|
||||
|
||||
| X-Forwarded-For | excludedIPs | clientIP |
|
||||
|-----------------------------------------|-----------------------|--------------|
|
||||
| `"10.0.0.1,11.0.0.1,12.0.0.1,13.0.0.1"` | `"12.0.0.1,13.0.0.1"` | `"11.0.0.1"` |
|
||||
| `"10.0.0.1,11.0.0.1,12.0.0.1,13.0.0.1"` | `"15.0.0.1,13.0.0.1"` | `"12.0.0.1"` |
|
||||
| `"10.0.0.1,11.0.0.1,12.0.0.1,13.0.0.1"` | `"10.0.0.1,13.0.0.1"` | `"12.0.0.1"` |
|
||||
| `"10.0.0.1,11.0.0.1,12.0.0.1,13.0.0.1"` | `"15.0.0.1,16.0.0.1"` | `"13.0.0.1"` |
|
||||
| `"10.0.0.1,11.0.0.1"` | `"10.0.0.1,11.0.0.1"` | `""` |
|
||||
|
|
@ -0,0 +1,51 @@
|
|||
---
|
||||
title: "Traefik Proxy Middleware Overview"
|
||||
description: "There are several available middleware in Traefik Proxy used to modify requests or headers, take charge of redirections, add authentication, and so on."
|
||||
---
|
||||
|
||||
# HTTP Middleware Overview
|
||||
|
||||
Attached to the routers, pieces of middleware are a means of tweaking the requests before they are sent to your service (or before the answer from the services are sent to the clients).
|
||||
|
||||
There are several available middlewares in Traefik, some can modify the request, the headers, some are in charge of redirections, some add authentication, and so on.
|
||||
|
||||
Middlewares that use the same protocol can be combined into chains to fit every scenario.
|
||||
|
||||
!!! warning "Provider Namespace"
|
||||
|
||||
Be aware of the concept of Providers Namespace described in the [Configuration Discovery](../../../install-configuration/providers/overview.md#provider-namespace) section.
|
||||
It also applies to Middlewares.
|
||||
|
||||
## Available HTTP Middlewares
|
||||
|
||||
| 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 |
|
||||
| [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 |
|
||||
|
||||
## Community Middlewares
|
||||
|
||||
Please take a look at the community-contributed plugins in the [plugin catalog](https://plugins.traefik.io/plugins).
|
||||
|
||||
{!traefik-for-business-applications.md!}
|
||||
|
|
@ -0,0 +1,366 @@
|
|||
---
|
||||
title: "Traefik PassTLSClientCert Documentation"
|
||||
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.
|
||||
|
||||
## Configuration Examples
|
||||
|
||||
Pass the pem in the `X-Forwarded-Tls-Client-Cert` header:
|
||||
|
||||
```yaml tab="Structured (YAML)"
|
||||
# Pass the pem in the `X-Forwarded-Tls-Client-Cert` header.
|
||||
http:
|
||||
middlewares:
|
||||
test-passtlsclientcert:
|
||||
passTLSClientCert:
|
||||
pem: true
|
||||
```
|
||||
|
||||
```toml tab="Structured (TOML)"
|
||||
# Pass the pem in the `X-Forwarded-Tls-Client-Cert` header.
|
||||
[http.middlewares]
|
||||
[http.middlewares.test-passtlsclientcert.passTLSClientCert]
|
||||
pem = true
|
||||
```
|
||||
|
||||
```yaml tab="Labels"
|
||||
# Pass the pem in the `X-Forwarded-Tls-Client-Cert` header.
|
||||
labels:
|
||||
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.pem=true"
|
||||
```
|
||||
|
||||
```json tab="Tags"
|
||||
// Pass the pem in the `X-Forwarded-Tls-Client-Cert` header
|
||||
{
|
||||
"Tags": [
|
||||
"traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.pem=true"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
```yaml tab="Kubernetes"
|
||||
apiVersion: traefik.io/v1alpha1
|
||||
kind: Middleware
|
||||
metadata:
|
||||
name: test-passtlsclientcert
|
||||
spec:
|
||||
passTLSClientCert:
|
||||
pem: true
|
||||
```
|
||||
|
||||
??? example "Pass the pem in the `X-Forwarded-Tls-Client-Cert` header"
|
||||
|
||||
```yaml tab="Structured (YAML)"
|
||||
# Pass all the available info in the `X-Forwarded-Tls-Client-Cert-Info` header
|
||||
http:
|
||||
middlewares:
|
||||
test-passtlsclientcert:
|
||||
passTLSClientCert:
|
||||
info:
|
||||
notAfter: true
|
||||
notBefore: true
|
||||
sans: true
|
||||
subject:
|
||||
country: true
|
||||
province: true
|
||||
locality: true
|
||||
organization: true
|
||||
organizationalUnit: true
|
||||
commonName: true
|
||||
serialNumber: true
|
||||
domainComponent: true
|
||||
issuer:
|
||||
country: true
|
||||
province: true
|
||||
locality: true
|
||||
organization: true
|
||||
commonName: true
|
||||
serialNumber: true
|
||||
domainComponent: true
|
||||
```
|
||||
|
||||
```toml tab="Structured (TOML)"
|
||||
# Pass all the available info in the `X-Forwarded-Tls-Client-Cert-Info` header
|
||||
[http.middlewares]
|
||||
[http.middlewares.test-passtlsclientcert.passTLSClientCert]
|
||||
[http.middlewares.test-passtlsclientcert.passTLSClientCert.info]
|
||||
notAfter = true
|
||||
notBefore = true
|
||||
sans = true
|
||||
[http.middlewares.test-passtlsclientcert.passTLSClientCert.info.subject]
|
||||
country = true
|
||||
province = true
|
||||
locality = true
|
||||
organization = true
|
||||
organizationalUnit = true
|
||||
commonName = true
|
||||
serialNumber = true
|
||||
domainComponent = true
|
||||
[http.middlewares.test-passtlsclientcert.passTLSClientCert.info.issuer]
|
||||
country = true
|
||||
province = true
|
||||
locality = true
|
||||
organization = true
|
||||
commonName = true
|
||||
serialNumber = true
|
||||
domainComponent = true
|
||||
```
|
||||
|
||||
```yaml tab="Labels"
|
||||
# Pass all the available info in the `X-Forwarded-Tls-Client-Cert-Info` header
|
||||
labels:
|
||||
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.notafter=true"
|
||||
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.notbefore=true"
|
||||
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.sans=true"
|
||||
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.serialnumber=true"
|
||||
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.subject.commonname=true"
|
||||
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.subject.country=true"
|
||||
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.subject.domaincomponent=true"
|
||||
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.subject.locality=true"
|
||||
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.subject.organization=true"
|
||||
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.subject.organizationalunit=true"
|
||||
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.subject.province=true"
|
||||
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.subject.serialnumber=true"
|
||||
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.issuer.commonname=true"
|
||||
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.issuer.country=true"
|
||||
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.issuer.domaincomponent=true"
|
||||
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.issuer.locality=true"
|
||||
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.issuer.organization=true"
|
||||
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.issuer.province=true"
|
||||
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.issuer.serialnumber=true"
|
||||
```
|
||||
|
||||
```json tab="Tags"
|
||||
// Pass all the available info in the `X-Forwarded-Tls-Client-Cert-Info` header
|
||||
{
|
||||
//...
|
||||
"Tags" : [
|
||||
"traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.notafter=true",
|
||||
"traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.notbefore=true",
|
||||
"traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.sans=true",
|
||||
"traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.subject.commonname=true",
|
||||
"traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.subject.country=true",
|
||||
"traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.subject.domaincomponent=true",
|
||||
"traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.subject.locality=true",
|
||||
"traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.subject.organization=true",
|
||||
"traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.subject.organizationalunit=true",
|
||||
"traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.subject.province=true",
|
||||
"traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.subject.serialnumber=true",
|
||||
"traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.issuer.commonname=true",
|
||||
"traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.issuer.country=true",
|
||||
"traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.issuer.domaincomponent=true",
|
||||
"traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.issuer.locality=true",
|
||||
"traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.issuer.organization=true",
|
||||
"traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.issuer.province=true",
|
||||
"traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.issuer.serialnumber=true"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
```yaml tab="Kubernetes"
|
||||
# Pass all the available info in the `X-Forwarded-Tls-Client-Cert-Info` header
|
||||
apiVersion: traefik.io/v1alpha1
|
||||
kind: Middleware
|
||||
metadata:
|
||||
name: test-passtlsclientcert
|
||||
spec:
|
||||
passTLSClientCert:
|
||||
info:
|
||||
notAfter: true
|
||||
notBefore: true
|
||||
sans: true
|
||||
subject:
|
||||
country: true
|
||||
province: true
|
||||
locality: true
|
||||
organization: true
|
||||
organizationalUnit: true
|
||||
commonName: true
|
||||
serialNumber: true
|
||||
domainComponent: true
|
||||
issuer:
|
||||
country: true
|
||||
province: true
|
||||
locality: true
|
||||
organization: true
|
||||
commonName: true
|
||||
serialNumber: true
|
||||
domainComponent: true
|
||||
```
|
||||
|
||||
## General Information
|
||||
|
||||
`passTLSClientCert` can add two headers to the request:
|
||||
|
||||
- `X-Forwarded-Tls-Client-Cert` that contains the pem.
|
||||
- `X-Forwarded-Tls-Client-Cert-Info` that contains all the selected certificate information in an escaped string.
|
||||
|
||||
!!! info
|
||||
|
||||
- `X-Forwarded-Tls-Client-Cert-Info` header value is a string that has been escaped in order to be a valid URL query.
|
||||
- These options only work accordingly to the MutualTLS configuration. i.e, only the certificates that match the `clientAuth.clientAuthType` policy are passed.
|
||||
|
||||
??? example "Example of a complete certificate and explaining each of the middleware options"
|
||||
|
||||
```txt
|
||||
Certificate:
|
||||
Data:
|
||||
Version: 3 (0x2)
|
||||
Serial Number: 1 (0x1)
|
||||
Signature Algorithm: sha1WithRSAEncryption
|
||||
Issuer: DC=org, DC=cheese, O=Cheese, O=Cheese 2, OU=Simple Signing Section, OU=Simple Signing Section 2, CN=Simple Signing CA, CN=Simple Signing CA 2, C=FR, C=US, L=TOULOUSE, L=LYON, ST=Signing State, ST=Signing State 2/emailAddress=simple@signing.com/emailAddress=simple2@signing.com
|
||||
Validity
|
||||
Not Before: Dec 6 11:10:16 2018 GMT
|
||||
Not After : Dec 5 11:10:16 2020 GMT
|
||||
Subject: DC=org, DC=cheese, O=Cheese, O=Cheese 2, OU=Simple Signing Section, OU=Simple Signing Section 2, CN=*.example.org, CN=*.example.com, C=FR, C=US, L=TOULOUSE, L=LYON, ST=Cheese org state, ST=Cheese com statemailAddress=cert@example.org/emailAddress=cert@sexample.com
|
||||
Subject Public Key Info:
|
||||
Public Key Algorithm: rsaEncryption
|
||||
RSA Public-Key: (2048 bit)
|
||||
Modulus:
|
||||
00:de:77:fa:8d:03:70:30:39:dd:51:1b:cc:60:db:
|
||||
a9:5a:13:b1:af:fe:2c:c6:38:9b:88:0a:0f:8e:d9:
|
||||
1b:a1:1d:af:0d:66:e4:13:5b:bc:5d:36:92:d7:5e:
|
||||
d0:fa:88:29:d3:78:e1:81:de:98:b2:a9:22:3f:bf:
|
||||
8a:af:12:92:63:d4:a9:c3:f2:e4:7e:d2:dc:a2:c5:
|
||||
39:1c:7a:eb:d7:12:70:63:2e:41:47:e0:f0:08:e8:
|
||||
dc:be:09:01:ec:28:09:af:35:d7:79:9c:50:35:d1:
|
||||
6b:e5:87:7b:34:f6:d2:31:65:1d:18:42:69:6c:04:
|
||||
11:83:fe:44:ae:90:92:2d:0b:75:39:57:62:e6:17:
|
||||
2f:47:2b:c7:53:dd:10:2d:c9:e3:06:13:d2:b9:ba:
|
||||
63:2e:3c:7d:83:6b:d6:89:c9:cc:9d:4d:bf:9f:e8:
|
||||
a3:7b:da:c8:99:2b:ba:66:d6:8e:f8:41:41:a0:c9:
|
||||
d0:5e:c8:11:a4:55:4a:93:83:87:63:04:63:41:9c:
|
||||
fb:68:04:67:c2:71:2f:f2:65:1d:02:5d:15:db:2c:
|
||||
d9:04:69:85:c2:7d:0d:ea:3b:ac:85:f8:d4:8f:0f:
|
||||
c5:70:b2:45:e1:ec:b2:54:0b:e9:f7:82:b4:9b:1b:
|
||||
2d:b9:25:d4:ab:ca:8f:5b:44:3e:15:dd:b8:7f:b7:
|
||||
ee:f9
|
||||
Exponent: 65537 (0x10001)
|
||||
X509v3 extensions:
|
||||
X509v3 Key Usage: critical
|
||||
Digital Signature, Key Encipherment
|
||||
X509v3 Basic Constraints:
|
||||
CA:FALSE
|
||||
X509v3 Extended Key Usage:
|
||||
TLS Web Server Authentication, TLS Web Client Authentication
|
||||
X509v3 Subject Key Identifier:
|
||||
94:BA:73:78:A2:87:FB:58:28:28:CF:98:3B:C2:45:70:16:6E:29:2F
|
||||
X509v3 Authority Key Identifier:
|
||||
keyid:1E:52:A2:E8:54:D5:37:EB:D5:A8:1D:E4:C2:04:1D:37:E2:F7:70:03
|
||||
|
||||
X509v3 Subject Alternative Name:
|
||||
DNS:*.example.org, DNS:*.example.net, DNS:*.example.com, IP Address:10.0.1.0, IP Address:10.0.1.2, email:test@example.org, email:test@example.net
|
||||
Signature Algorithm: sha1WithRSAEncryption
|
||||
76:6b:05:b0:0e:34:11:b1:83:99:91:dc:ae:1b:e2:08:15:8b:
|
||||
16:b2:9b:27:1c:02:ac:b5:df:1b:d0:d0:75:a4:2b:2c:5c:65:
|
||||
ed:99:ab:f7:cd:fe:38:3f:c3:9a:22:31:1b:ac:8c:1c:c2:f9:
|
||||
5d:d4:75:7a:2e:72:c7:85:a9:04:af:9f:2a:cc:d3:96:75:f0:
|
||||
8e:c7:c6:76:48:ac:45:a4:b9:02:1e:2f:c0:15:c4:07:08:92:
|
||||
cb:27:50:67:a1:c8:05:c5:3a:b3:a6:48:be:eb:d5:59:ab:a2:
|
||||
1b:95:30:71:13:5b:0a:9a:73:3b:60:cc:10:d0:6a:c7:e5:d7:
|
||||
8b:2f:f9:2e:98:f2:ff:81:14:24:09:e3:4b:55:57:09:1a:22:
|
||||
74:f1:f6:40:13:31:43:89:71:0a:96:1a:05:82:1f:83:3a:87:
|
||||
9b:17:25:ef:5a:55:f2:2d:cd:0d:4d:e4:81:58:b6:e3:8d:09:
|
||||
62:9a:0c:bd:e4:e5:5c:f0:95:da:cb:c7:34:2c:34:5f:6d:fc:
|
||||
60:7b:12:5b:86:fd:df:21:89:3b:48:08:30:bf:67:ff:8c:e6:
|
||||
9b:53:cc:87:36:47:70:40:3b:d9:90:2a:d2:d2:82:c6:9c:f5:
|
||||
d1:d8:e0:e6:fd:aa:2f:95:7e:39:ac:fc:4e:d4:ce:65:b3:ec:
|
||||
c6:98:8a:31
|
||||
-----BEGIN CERTIFICATE-----
|
||||
MIIGWjCCBUKgAwIBAgIBATANBgkqhkiG9w0BAQUFADCCAYQxEzARBgoJkiaJk/Is
|
||||
ZAEZFgNvcmcxFjAUBgoJkiaJk/IsZAEZFgZjaGVlc2UxDzANBgNVBAoMBkNoZWVz
|
||||
ZTERMA8GA1UECgwIQ2hlZXNlIDIxHzAdBgNVBAsMFlNpbXBsZSBTaWduaW5nIFNl
|
||||
Y3Rpb24xITAfBgNVBAsMGFNpbXBsZSBTaWduaW5nIFNlY3Rpb24gMjEaMBgGA1UE
|
||||
AwwRU2ltcGxlIFNpZ25pbmcgQ0ExHDAaBgNVBAMME1NpbXBsZSBTaWduaW5nIENB
|
||||
IDIxCzAJBgNVBAYTAkZSMQswCQYDVQQGEwJVUzERMA8GA1UEBwwIVE9VTE9VU0Ux
|
||||
DTALBgNVBAcMBExZT04xFjAUBgNVBAgMDVNpZ25pbmcgU3RhdGUxGDAWBgNVBAgM
|
||||
D1NpZ25pbmcgU3RhdGUgMjEhMB8GCSqGSIb3DQEJARYSc2ltcGxlQHNpZ25pbmcu
|
||||
Y29tMSIwIAYJKoZIhvcNAQkBFhNzaW1wbGUyQHNpZ25pbmcuY29tMB4XDTE4MTIw
|
||||
NjExMTAxNloXDTIwMTIwNTExMTAxNlowggF2MRMwEQYKCZImiZPyLGQBGRYDb3Jn
|
||||
MRYwFAYKCZImiZPyLGQBGRYGY2hlZXNlMQ8wDQYDVQQKDAZDaGVlc2UxETAPBgNV
|
||||
BAoMCENoZWVzZSAyMR8wHQYDVQQLDBZTaW1wbGUgU2lnbmluZyBTZWN0aW9uMSEw
|
||||
HwYDVQQLDBhTaW1wbGUgU2lnbmluZyBTZWN0aW9uIDIxFTATBgNVBAMMDCouY2hl
|
||||
ZXNlLm9yZzEVMBMGA1UEAwwMKi5jaGVlc2UuY29tMQswCQYDVQQGEwJGUjELMAkG
|
||||
A1UEBhMCVVMxETAPBgNVBAcMCFRPVUxPVVNFMQ0wCwYDVQQHDARMWU9OMRkwFwYD
|
||||
VQQIDBBDaGVlc2Ugb3JnIHN0YXRlMRkwFwYDVQQIDBBDaGVlc2UgY29tIHN0YXRl
|
||||
MR4wHAYJKoZIhvcNAQkBFg9jZXJ0QGNoZWVzZS5vcmcxHzAdBgkqhkiG9w0BCQEW
|
||||
EGNlcnRAc2NoZWVzZS5jb20wggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIB
|
||||
AQDed/qNA3AwOd1RG8xg26laE7Gv/izGOJuICg+O2RuhHa8NZuQTW7xdNpLXXtD6
|
||||
iCnTeOGB3piyqSI/v4qvEpJj1KnD8uR+0tyixTkceuvXEnBjLkFH4PAI6Ny+CQHs
|
||||
KAmvNdd5nFA10Wvlh3s09tIxZR0YQmlsBBGD/kSukJItC3U5V2LmFy9HK8dT3RAt
|
||||
yeMGE9K5umMuPH2Da9aJycydTb+f6KN72siZK7pm1o74QUGgydBeyBGkVUqTg4dj
|
||||
BGNBnPtoBGfCcS/yZR0CXRXbLNkEaYXCfQ3qO6yF+NSPD8VwskXh7LJUC+n3grSb
|
||||
Gy25JdSryo9bRD4V3bh/t+75AgMBAAGjgeAwgd0wDgYDVR0PAQH/BAQDAgWgMAkG
|
||||
A1UdEwQCMAAwHQYDVR0lBBYwFAYIKwYBBQUHAwEGCCsGAQUFBwMCMB0GA1UdDgQW
|
||||
BBSUunN4oof7WCgoz5g7wkVwFm4pLzAfBgNVHSMEGDAWgBQeUqLoVNU369WoHeTC
|
||||
BB034vdwAzBhBgNVHREEWjBYggwqLmNoZWVzZS5vcmeCDCouY2hlZXNlLm5ldIIM
|
||||
Ki5jaGVlc2UuY29thwQKAAEAhwQKAAECgQ90ZXN0QGNoZWVzZS5vcmeBD3Rlc3RA
|
||||
Y2hlZXNlLm5ldDANBgkqhkiG9w0BAQUFAAOCAQEAdmsFsA40EbGDmZHcrhviCBWL
|
||||
FrKbJxwCrLXfG9DQdaQrLFxl7Zmr983+OD/DmiIxG6yMHML5XdR1ei5yx4WpBK+f
|
||||
KszTlnXwjsfGdkisRaS5Ah4vwBXEBwiSyydQZ6HIBcU6s6ZIvuvVWauiG5UwcRNb
|
||||
CppzO2DMENBqx+XXiy/5Lpjy/4EUJAnjS1VXCRoidPH2QBMxQ4lxCpYaBYIfgzqH
|
||||
mxcl71pV8i3NDU3kgVi2440JYpoMveTlXPCV2svHNCw0X238YHsSW4b93yGJO0gI
|
||||
-----END CERTIFICATE-----
|
||||
```
|
||||
|
||||
## Configuration Options
|
||||
|
||||
| Field | Description | Default | Required |
|
||||
|:-----------|:------------------------------------------------------------|:--------|:---------|
|
||||
| `pem` | Fills the `X-Forwarded-Tls-Client-Cert` header with the certificate information.<br /> More information [here](#pem). | false | No |
|
||||
| `info.serialNumber` | Add the `Serial Number` of the certificate.<br /> More information about `info` [here](#info). | false | No |
|
||||
| `info.notAfter` | Add the `Not After` information from the `Validity` part. <br /> More information about `info` [here](#info). | false | No |
|
||||
| `info.notBefore` | Add the `Not Before` information from the `Validity` part. <br />More information about `info` [here](#info). | false | No |
|
||||
| `info.sans` | Add the `Subject Alternative Name` information from the `Subject Alternative Name` part. <br /> More information about `info` [here](#info). | false | No |
|
||||
| `info.subject` | The `info.subject` selects the specific client certificate subject details you want to add to the `X-Forwarded-Tls-Client-Cert-Info` header. <br />More information about `info` [here](#info). | false | No |
|
||||
| `info.subject.country` | Add the `country` information into the subject.<br /> The data is taken from the subject part with the `C` key. <br />More information about `info` [here](#info). | false | No |
|
||||
| `info.subject.province` | Add the `province` information into the subject.<br /> The data is taken from the subject part with the `ST` key. <br />More information about `info` [here](#info). | false | No |
|
||||
| `info.subject.locality` | Add the `locality` information into the subject.<br /> The data is taken from the subject part with the `L` key. <br />More information about `info` [here](#info). | false | No |
|
||||
| `info.subject.organization` | Add the `organization` information into the subject.<br /> The data is taken from the subject part with the `O` key. <br />More information about `info` [here](#info). | false | No |
|
||||
| `info.subject.organizationalUnit` | Add the `organizationalUnit` information into the subject.<br /> The data is taken from the subject part with the `OU` key. <br />More information about `info` [here](#info). | false | No |
|
||||
| `info.subject.commonName` | Add the `commonName` information into the subject.<br /> The data is taken from the subject part with the `CN` key.| false | No |
|
||||
| `info.subject.serialNumber` | Add the `serialNumber` information into the subject.<br /> The data is taken from the subject part with the `SN` key.| false | No |
|
||||
| `info.subject.domainComponent` | Add the `domainComponent` information into the subject.<br />The data is taken from the subject part with the `DC` key. <br />More information about `info` [here](#info). | false | No |
|
||||
| `info.issuer` | The `info.issuer` selects the specific client certificate issuer details you want to add to the `X-Forwarded-Tls-Client-Cert-Info` header. <br />More information about `info` [here](#info). | false | No |
|
||||
| `info.issuer.country` | Add the `country` information into the issuer.<br /> The data is taken from the issuer part with the `C` key. <br />More information about `info` [here](#info). | false | No |
|
||||
| `info.issuer.province` | Add the `province` information into the issuer.<br />The data is taken from the issuer part with the `ST` key. <br />More information about `info` [here](#info). | false | No |
|
||||
| `info.issuer.locality` | Add the `locality` information into the issuer.<br /> The data is taken from the issuer part with the `L` key. <br />More information about `info` [here](#info). | false | No |
|
||||
| `info.issuer.organization` | Add the `organization` information into the issuer.<br /> The data is taken from the issuer part with the `O` key. <br />More information about `info` [here](#info). | false | No |
|
||||
| `info.issuer.commonName` |Add the `commonName` information into the issuer.<br /> The data is taken from the issuer part with the `CN` key. <br />More information about `info` [here](#info). | false | No |
|
||||
| `info.issuer.serialNumber` |Add the `serialNumber` information into the issuer.<br /> The data is taken from the issuer part with the `SN` key. <br />More information about `info` [here](#info). | false | No |
|
||||
| `info.issuer.domainComponent` | Add the `domainComponent` information into the issuer.<br /> The data is taken from the issuer part with the `DC` key. <br />More information about `info` [here](#info). | false | No |
|
||||
|
||||
### pem
|
||||
|
||||
#### Data Format
|
||||
|
||||
The delimiters and `\n` will be removed.
|
||||
If there are more than one certificate, they are separated by a "`,`".
|
||||
|
||||
#### Header size
|
||||
|
||||
The `X-Forwarded-Tls-Client-Cert` header value could exceed the web server header size limit
|
||||
|
||||
The header size limit of web servers is commonly between 4kb and 8kb.
|
||||
If that turns out to be a problem, and if reconfiguring the server to allow larger headers is not an option,
|
||||
one can alleviate the problem by selecting only the interesting parts of the cert,
|
||||
through the use of the `info` options described below. (And by setting `pem` to false).
|
||||
|
||||
### info
|
||||
|
||||
The `info` option selects the specific client certificate details you want to add to the `X-Forwarded-Tls-Client-Cert-Info` header.
|
||||
|
||||
#### Data Format
|
||||
|
||||
The value of the header is an escaped concatenation of all the selected certificate details.
|
||||
Unless specified otherwise, all the header values examples are shown unescaped, for readability.
|
||||
|
||||
If there are more than one certificate, they are separated by a `,`.
|
||||
|
||||
The following example shows such a concatenation, when all the available fields are selected:
|
||||
|
||||
```text
|
||||
Subject="DC=org,DC=cheese,C=FR,C=US,ST=Cheese org state,ST=Cheese com state,L=TOULOUSE,L=LYON,O=Cheese,O=Cheese 2,CN=*.example.com";Issuer="DC=org,DC=cheese,C=FR,C=US,ST=Signing State,ST=Signing State 2,L=TOULOUSE,L=LYON,O=Cheese,O=Cheese 2,CN=Simple Signing CA 2";NB="1544094616";NA="1607166616";SAN="*.example.org,*.example.net,*.example.com,test@example.org,test@example.net,10.0.1.0,10.0.1.2"
|
||||
```
|
||||
|
|
@ -0,0 +1,150 @@
|
|||
---
|
||||
title: "Traefik RateLimit Documentation"
|
||||
description: "Traefik Proxy's HTTP RateLimit middleware ensures Services receive fair amounts of requests. Read the technical documentation."
|
||||
---
|
||||
|
||||
The `rateLimit` middleware ensures that services will receive a *fair* amount of requests, and allows you to define what fair is.
|
||||
|
||||
It 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
|
||||
|
||||
## Rate and Burst
|
||||
|
||||
The rate is defined by dividing `average` by `period`.
|
||||
For a rate below 1 req/s, define a `period` larger than a second
|
||||
|
||||
## Configuration Example
|
||||
|
||||
```yaml tab="Structured (YAML)"
|
||||
# Here, an average of 100 requests per second is allowed.
|
||||
# In addition, a burst of 200 requests is allowed.
|
||||
http:
|
||||
middlewares:
|
||||
test-ratelimit:
|
||||
rateLimit:
|
||||
average: 100
|
||||
burst: 200
|
||||
```
|
||||
|
||||
```toml tab="Structured (TOML)"
|
||||
# Here, an average of 100 requests per second is allowed.
|
||||
# In addition, a burst of 200 requests is allowed.
|
||||
[http.middlewares]
|
||||
[http.middlewares.test-ratelimit.rateLimit]
|
||||
average = 100
|
||||
burst = 200
|
||||
```
|
||||
|
||||
```yaml tab="Labels"
|
||||
# Here, an average of 100 requests per second is allowed.
|
||||
# In addition, a burst of 200 requests is allowed.
|
||||
labels:
|
||||
- "traefik.http.middlewares.test-ratelimit.ratelimit.average=100"
|
||||
- "traefik.http.middlewares.test-ratelimit.ratelimit.burst=200"
|
||||
```
|
||||
|
||||
```json tab="Tags"
|
||||
// Here, an average of 100 requests per second is allowed.
|
||||
// In addition, a burst of 200 requests is allowed.
|
||||
{
|
||||
"Tags": [
|
||||
"traefik.http.middlewares.test-ratelimit.ratelimit.average=100",
|
||||
"traefik.http.middlewares.test-ratelimit.ratelimit.burst=50"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
```yaml tab="Kubernetes"
|
||||
# Here, an average of 100 requests per second is allowed.
|
||||
# In addition, a burst of 200 requests is allowed.
|
||||
apiVersion: traefik.io/v1alpha1
|
||||
kind: Middleware
|
||||
metadata:
|
||||
name: test-ratelimit
|
||||
spec:
|
||||
rateLimit:
|
||||
average: 100
|
||||
burst: 200
|
||||
```
|
||||
|
||||
## Configuration Options
|
||||
|
||||
| Field | Description | Default | Required |
|
||||
|:-----------|:-------------------------------------------------------|:--------|:---------|
|
||||
| `average` | Number of requests used to define the rate using the `period`.<br /> 0 means **no rate limiting**.<br />More information [here](#rate-and-burst). | 0 | No |
|
||||
| `period` | Period of time used to define the rate.<br />More information [here](#rate-and-burst). | 1s | No |
|
||||
| `burst` | Maximum number of requests allowed to go through at the very same moment.<br />More information [here](#rate-and-burst).| 1 | No |
|
||||
| `sourceCriterion.requestHost` | Whether to consider the request host as the source.<br />More information about `sourceCriterion`[here](#sourcecriterion). | false | No |
|
||||
| `sourceCriterion.requestHeaderName` | Name of the header used to group incoming requests.<br />More information about `sourceCriterion`[here](#sourcecriterion). | "" | No |
|
||||
| `sourceCriterion.ipStrategy.depth` | Depth position of the IP to select in the `X-Forwarded-For` header (starting from the right).<br />0 means no depth.<br />If greater than the total number of IPs in `X-Forwarded-For`, then the client IP is empty<br />If higher than 0, the `excludedIPs` options is not evaluated.<br />More information about [`sourceCriterion`](#sourcecriterion), [`ipStrategy`](#ipstrategy), and [`depth`](#sourcecriterionipstrategydepth) below. | 0 | No |
|
||||
| `sourceCriterion.ipStrategy.excludedIPs` | Allows scanning the `X-Forwarded-For` header and select the first IP not in the list.<br />If `depth` is specified, `excludedIPs` is ignored.<br />More information about [`sourceCriterion`](#sourcecriterion), [`ipStrategy`](#ipstrategy), and [`excludedIPs`](#sourcecriterionipstrategyexcludedips) below. | | No |
|
||||
| `sourceCriterion.ipStrategy.ipv6Subnet` | If `ipv6Subnet` is provided and the selected IP is IPv6, the IP is transformed into the first IP of the subnet it belongs to. <br />More information about [`sourceCriterion`](#sourcecriterion), [`ipStrategy.ipv6Subnet`](#sourcecriterionipstrategyipv6subnet) below. | | No |
|
||||
|
||||
### sourceCriterion
|
||||
|
||||
The `sourceCriterion` option defines what criterion is used to group requests as originating from a common source.
|
||||
If several strategies are defined at the same time, an error will be raised.
|
||||
If none are set, the default is to use the request's remote address field (as an `ipStrategy`).
|
||||
|
||||
### ipStrategy
|
||||
|
||||
The `ipStrategy` option defines three parameters that configures how Traefik determines the client IP: `depth`, `excludedIPs` and `ipv6Subnet`.
|
||||
|
||||
As a middleware, rate-limiting happens before the actual proxying to the backend takes place.
|
||||
In addition, the previous network hop only gets appended to `X-Forwarded-For` during the last stages of proxying, that is after it has already passed through rate-limiting.
|
||||
Therefore, during rate-limiting, as the previous network hop is not yet present in `X-Forwarded-For`, it cannot be found and/or relied upon.
|
||||
|
||||
### `sourceCriterion.ipStrategy.ipv6Subnet`
|
||||
|
||||
This strategy applies to `Depth` and `RemoteAddr` strategy only.
|
||||
If `ipv6Subnet` is provided and the selected IP is IPv6, the IP is transformed into the first IP of the subnet it belongs to.
|
||||
|
||||
This is useful for grouping IPv6 addresses into subnets to prevent bypassing this middleware by obtaining a new IPv6.
|
||||
|
||||
- `ipv6Subnet` is ignored if its value is outside of 0-128 interval
|
||||
|
||||
#### Example of ipv6Subnet
|
||||
|
||||
If `ipv6Subnet` is provided, the IP is transformed in the following way.
|
||||
|
||||
| `IP` | `ipv6Subnet` | clientIP |
|
||||
|---------------------------|--------------|-----------------------|
|
||||
| `"::abcd:1111:2222:3333"` | `64` | `"::0:0:0:0"` |
|
||||
| `"::abcd:1111:2222:3333"` | `80` | `"::abcd:0:0:0:0"` |
|
||||
| `"::abcd:1111:2222:3333"` | `96` | `"::abcd:1111:0:0:0"` |
|
||||
|
||||
### sourceCriterion.ipStrategy.depth
|
||||
|
||||
If `depth` is set to 2, and the request `X-Forwarded-For` header is `"10.0.0.1,11.0.0.1,12.0.0.1,13.0.0.1"` then the "real" client IP is `"10.0.0.1"` (at depth 4) but the IP used as the criterion is `"12.0.0.1"` (`depth=2`).
|
||||
|
||||
| `X-Forwarded-For` | `depth` | clientIP |
|
||||
|-----------------------------------------|---------|--------------|
|
||||
| `"10.0.0.1,11.0.0.1,12.0.0.1,13.0.0.1"` | `1` | `"13.0.0.1"` |
|
||||
| `"10.0.0.1,11.0.0.1,12.0.0.1,13.0.0.1"` | `3` | `"11.0.0.1"` |
|
||||
| `"10.0.0.1,11.0.0.1,12.0.0.1,13.0.0.1"` | `5` | `""` |
|
||||
|
||||
### sourceCriterion.ipStrategy.excludedIPs
|
||||
|
||||
Contrary to what the name might suggest, this option is *not* about excluding an IP from the rate limiter, and therefore cannot be used to deactivate rate limiting for some IPs.
|
||||
|
||||
`excludedIPs` is meant to address two classes of somewhat distinct use-cases:
|
||||
|
||||
1. Distinguish IPs which are behind the same (set of) reverse-proxies so that each of them contributes, independently to the others, to its own rate-limit "bucket" (cf the [token bucket](https://en.wikipedia.org/wiki/Token_bucket)).
|
||||
In this case, `excludedIPs` should be set to match the list of `X-Forwarded-For IPs` that are to be excluded, in order to find the actual clientIP.
|
||||
|
||||
Example to use each IP as a distinct source:
|
||||
|
||||
| X-Forwarded-For | excludedIPs | clientIP |
|
||||
|--------------------------------|-----------------------|--------------|
|
||||
| `"10.0.0.1,11.0.0.1,12.0.0.1"` | `"11.0.0.1,12.0.0.1"` | `"10.0.0.1"` |
|
||||
| `"10.0.0.2,11.0.0.1,12.0.0.1"` | `"11.0.0.1,12.0.0.1"` | `"10.0.0.2"` |
|
||||
|
||||
2. Group together a set of IPs (also behind a common set of reverse-proxies) so that they are considered the same source, and all contribute to the same rate-limit bucket.
|
||||
|
||||
Example to group IPs together as same source:
|
||||
|
||||
| X-Forwarded-For | excludedIPs | clientIP |
|
||||
|--------------------------------|--------------|--------------|
|
||||
| `"10.0.0.1,11.0.0.1,12.0.0.1"` | `"12.0.0.1"` | `"11.0.0.1"` |
|
||||
| `"10.0.0.2,11.0.0.1,12.0.0.1"` | `"12.0.0.1"` | `"11.0.0.1"` |
|
||||
| `"10.0.0.3,11.0.0.1,12.0.0.1"` | `"12.0.0.1"` | `"11.0.0.1"` |
|
||||
|
|
@ -0,0 +1,88 @@
|
|||
---
|
||||
title: "Traefik RedirectRegex Documentation"
|
||||
description: "In Traefik Proxy's HTTP middleware, RedirectRegex redirecting clients to different locations. Read the technical documentation."
|
||||
---
|
||||
|
||||
The `RedirectRegex` redirects a request using regex matching and replacement.
|
||||
|
||||
## Configuration Examples
|
||||
|
||||
```yaml tab="Structured (YAML)"
|
||||
# Redirect with domain replacement
|
||||
http:
|
||||
middlewares:
|
||||
test-redirectregex:
|
||||
redirectRegex:
|
||||
regex: "^http://localhost/(.*)"
|
||||
replacement: "http://mydomain/${1}"
|
||||
```
|
||||
|
||||
```toml tab="Structured (TOML)"
|
||||
# Redirect with domain replacement
|
||||
[http.middlewares]
|
||||
[http.middlewares.test-redirectregex.redirectRegex]
|
||||
regex = "^http://localhost/(.*)"
|
||||
replacement = "http://mydomain/${1}"
|
||||
```
|
||||
|
||||
```yaml tab="Labels"
|
||||
# Redirect with domain replacement
|
||||
# Note: all dollar signs need to be doubled for escaping.
|
||||
labels:
|
||||
- "traefik.http.middlewares.test-redirectregex.redirectregex.regex=^http://localhost/(.*)"
|
||||
- "traefik.http.middlewares.test-redirectregex.redirectregex.replacement=http://mydomain/$${1}"
|
||||
```
|
||||
|
||||
```json tab="Tags"
|
||||
// Redirect with domain replacement
|
||||
// Note: all dollar signs need to be doubled for escaping.
|
||||
{
|
||||
// ...
|
||||
"Tags" : [
|
||||
"traefik.http.middlewares.test-redirectregex.redirectregex.regex=^http://localhost/(.*)"
|
||||
"traefik.http.middlewares.test-redirectregex.redirectregex.replacement=http://mydomain/$${1}"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
```yaml tab="Kubernetes"
|
||||
# Redirect with domain replacement
|
||||
apiVersion: traefik.io/v1alpha1
|
||||
kind: Middleware
|
||||
metadata:
|
||||
name: test-redirectregex
|
||||
spec:
|
||||
redirectRegex:
|
||||
regex: ^http://localhost/(.*)
|
||||
replacement: http://mydomain/${1}
|
||||
```
|
||||
|
||||
## Configuration Options
|
||||
|
||||
<!-- markdownlint-disable MD013 -->
|
||||
|
||||
| Field | Description | Default | Required |
|
||||
|:-----------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:--------|:---------|
|
||||
| `regex` | The `regex` option is the regular expression to match and capture elements from the request URL.| "" | Yes |
|
||||
| `permanent` | Enable a permanent redirection. | false | No |
|
||||
| `replacement` | The `replacement` option defines how to modify the URL to have the new target URL..<br /> `$1x` is equivalent to `${1x}`, not `${1}x` (see [Regexp.Expand](https://golang.org/pkg/regexp/#Regexp.Expand)), so use `${1}` syntax. | "" | No |
|
||||
|
||||
### `regex`
|
||||
|
||||
The `regex` option is the regular expression to match and capture elements from the request URL.
|
||||
|
||||
!!! tip
|
||||
|
||||
Regular expressions and replacements can be tested using online tools such as [Go Playground](https://play.golang.org/p/mWU9p-wk2ru) or the [Regex101](https://regex101.com/r/58sIgx/2).
|
||||
|
||||
When defining a regular expression within YAML, any escaped character needs to be escaped twice: `example\.com` needs to be written as `example\\.com`.
|
||||
|
||||
### `replacement`
|
||||
|
||||
The `replacement` option defines how to modify the URL to have the new target URL.
|
||||
|
||||
!!! warning
|
||||
|
||||
Care should be taken when defining replacement expand variables: `$1x` is equivalent to `${1x}`, not `${1}x` (see [Regexp.Expand](https://golang.org/pkg/regexp/#Regexp.Expand)), so use `${1}` syntax.
|
||||
|
||||
{!traefik-for-business-applications.md!}
|
||||
|
|
@ -0,0 +1,74 @@
|
|||
---
|
||||
title: "Traefik RedirectScheme Documentation"
|
||||
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.
|
||||
|
||||
!!! warning "When behind another reverse-proxy"
|
||||
|
||||
When there is at least one other reverse-proxy between the client and Traefik,
|
||||
the other reverse-proxy (i.e. the last hop) needs to be a [trusted](../../../install-configuration/entrypoints.md#configuration-options) one.
|
||||
|
||||
Otherwise, Traefik would clean up the X-Forwarded headers coming from this last hop,
|
||||
and as the RedirectScheme middleware relies on them to determine the scheme used,
|
||||
it would not function as intended.
|
||||
|
||||
## Configuration Examples
|
||||
|
||||
```yaml tab="Structured (YAML)"
|
||||
# Redirect to https
|
||||
http:
|
||||
middlewares:
|
||||
test-redirectscheme:
|
||||
redirectScheme:
|
||||
scheme: https
|
||||
permanent: true
|
||||
```
|
||||
|
||||
```toml tab="Structured (TOML)"
|
||||
# Redirect to https
|
||||
[http.middlewares]
|
||||
[http.middlewares.test-redirectscheme.redirectScheme]
|
||||
scheme = "https"
|
||||
permanent = true
|
||||
```
|
||||
|
||||
```yaml tab="Labels"
|
||||
# Redirect to https
|
||||
labels:
|
||||
- "traefik.http.middlewares.test-redirectscheme.redirectscheme.scheme=https"
|
||||
- "traefik.http.middlewares.test-redirectscheme.redirectscheme.permanent=true"
|
||||
```
|
||||
|
||||
```json tab="Tags"
|
||||
// Redirect to https
|
||||
{
|
||||
// ...
|
||||
"Tags": [
|
||||
"traefik.http.middlewares.test-redirectscheme.redirectscheme.scheme=https"
|
||||
"traefik.http.middlewares.test-redirectscheme.redirectscheme.permanent=true"
|
||||
]
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
```yaml tab="Kubernetes"
|
||||
# Redirect to https
|
||||
apiVersion: traefik.io/v1alpha1
|
||||
kind: Middleware
|
||||
metadata:
|
||||
name: test-redirectscheme
|
||||
spec:
|
||||
redirectScheme:
|
||||
scheme: https
|
||||
permanent: true
|
||||
```
|
||||
|
||||
## Configuration Options
|
||||
|
||||
| Field | Description | Default | Required |
|
||||
|:-----------------------------|----------------------------------------------------------|:--------|:---------|
|
||||
| `scheme` | Scheme of the new URL. | "" | Yes |
|
||||
| `permanent` | Enable a permanent redirection. | false | No |
|
||||
| `port` | Port of the new URL.<br />Set a string, **not** a numeric value. | "" | No |
|
||||
|
|
@ -0,0 +1,60 @@
|
|||
---
|
||||
title: "Traefik ReplacePath Documentation"
|
||||
description: "In Traefik Proxy's HTTP middleware, ReplacePath updates paths before forwarding requests. Read the technical documentation."
|
||||
---
|
||||
|
||||
The `replacePath` middleware will:
|
||||
|
||||
- Replace the actual path with the specified one.
|
||||
- Store the original path in a `X-Replaced-Path` header
|
||||
|
||||
## Configuration Examples
|
||||
|
||||
```yaml tab="Structured (YAML)"
|
||||
# Replace the path with /foo
|
||||
http:
|
||||
middlewares:
|
||||
test-replacepath:
|
||||
replacePath:
|
||||
path: "/foo"
|
||||
```
|
||||
|
||||
```toml tab="Structured (TOML)"
|
||||
# Replace the path with /foo
|
||||
[http.middlewares]
|
||||
[http.middlewares.test-replacepath.replacePath]
|
||||
path = "/foo"
|
||||
```
|
||||
|
||||
```yaml tab="Labels"
|
||||
# Replace the path with /foo
|
||||
labels:
|
||||
- "traefik.http.middlewares.test-replacepath.replacepath.path=/foo"
|
||||
```
|
||||
|
||||
```json tab="Tags"
|
||||
// Replace the path with /foo
|
||||
{
|
||||
// ...
|
||||
"Tags" : [
|
||||
"traefik.http.middlewares.test-replacepath.replacepath.path=/foo"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
```yaml tab="Kubernetes"
|
||||
# Replace the path with /foo
|
||||
apiVersion: traefik.io/v1alpha1
|
||||
kind: Middleware
|
||||
metadata:
|
||||
name: test-replacepath
|
||||
spec:
|
||||
replacePath:
|
||||
path: "/foo"
|
||||
```
|
||||
|
||||
## Configuration Options
|
||||
|
||||
| Field | Description |
|
||||
|:------|:------------|
|
||||
| `path` | The `path` option defines the path to use as replacement in the request URL. |
|
||||
|
|
@ -0,0 +1,67 @@
|
|||
---
|
||||
title: "Traefik ReplacePathRegex Documentation"
|
||||
description: "In Traefik Proxy's HTTP middleware, ReplacePathRegex updates paths before forwarding requests, using a regex. Read the technical documentation."
|
||||
---
|
||||
|
||||
The `replacePathRegex` middleware will:
|
||||
|
||||
- Replace the matching path with the specified one.
|
||||
- Store the original path in an `X-Replaced-Path` header
|
||||
|
||||
## Configuration Examples
|
||||
|
||||
```yaml tab="File (YAML)"
|
||||
# Replace path with regex
|
||||
http:
|
||||
middlewares:
|
||||
test-replacepathregex:
|
||||
replacePathRegex:
|
||||
regex: "^/foo/(.*)"
|
||||
replacement: "/bar/$1"
|
||||
```
|
||||
|
||||
```toml tab="File (TOML)"
|
||||
# Replace path with regex
|
||||
[http.middlewares]
|
||||
[http.middlewares.test-replacepathregex.replacePathRegex]
|
||||
regex = "^/foo/(.*)"
|
||||
replacement = "/bar/$1"
|
||||
```
|
||||
|
||||
```yaml tab="Kubernetes"
|
||||
# Replace path with regex
|
||||
apiVersion: traefik.io/v1alpha1
|
||||
kind: Middleware
|
||||
metadata:
|
||||
name: test-replacepathregex
|
||||
spec:
|
||||
replacePathRegex:
|
||||
regex: "^/foo/(.*)"
|
||||
replacement: "/bar/$1"
|
||||
```
|
||||
|
||||
```yaml tab="Docker & Swarm"
|
||||
# Replace path with regex
|
||||
labels:
|
||||
- "traefik.http.middlewares.test-replacepathregex.replacepathregex.regex=^/foo/(.*)"
|
||||
- "traefik.http.middlewares.test-replacepathregex.replacepathregex.replacement=/bar/$$1"
|
||||
```
|
||||
|
||||
```yaml tab="Consul Catalog"
|
||||
# Replace path with regex
|
||||
- "traefik.http.middlewares.test-replacepathregex.replacepathregex.regex=^/foo/(.*)"
|
||||
- "traefik.http.middlewares.test-replacepathregex.replacepathregex.replacement=/bar/$1"
|
||||
```
|
||||
|
||||
## Configuration Options
|
||||
|
||||
| Field | Description | Default | Required |
|
||||
|:-----------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:--------|:---------|
|
||||
| `regex` | Regular expression to match and capture the path from the request URL. | | Yes |
|
||||
| `replacement` | Replacement path format, which can include captured variables.<br /> `$1x` is equivalent to `${1x}`, not `${1}x` (see [Regexp.Expand](https://golang.org/pkg/regexp/#Regexp.Expand)), so use `${1}` syntax. | | No
|
||||
|
||||
!!! tip
|
||||
|
||||
Regular expressions and replacements can be tested using online tools such as [Go Playground](https://play.golang.org/p/mWU9p-wk2ru) or the [Regex101](https://regex101.com/r/58sIgx/2).
|
||||
|
||||
When defining a regular expression within YAML, any escaped character needs to be escaped twice: `example\.com` needs to be written as `example\\.com`.
|
||||
|
|
@ -0,0 +1,68 @@
|
|||
---
|
||||
title: "Traefik HTTP Retry Documentation"
|
||||
description: "Configure Traefik Proxy's HTTP Retry middleware, so you can retry requests to a backend server until it succeeds. Read the technical documentation."
|
||||
---
|
||||
|
||||
The `retry` middleware retries requests a given number of times to a backend server if that server does not reply.
|
||||
As soon as the server answers, the middleware stops retrying, regardless of the response status.
|
||||
|
||||
The Retry middleware has an optional configuration to enable an exponential backoff.
|
||||
|
||||
## Configuration Examples
|
||||
|
||||
```yaml tab="Structured (YAML)"
|
||||
# Retry 4 times with exponential backoff
|
||||
http:
|
||||
middlewares:
|
||||
test-retry:
|
||||
retry:
|
||||
attempts: 4
|
||||
initialInterval: 100ms
|
||||
```
|
||||
|
||||
```toml tab="Structured (TOML)"
|
||||
# Retry 4 times with exponential backoff
|
||||
[http.middlewares]
|
||||
[http.middlewares.test-retry.retry]
|
||||
attempts = 4
|
||||
initialInterval = "100ms"
|
||||
```
|
||||
|
||||
```yaml tab="Labels"
|
||||
# Retry 4 times with exponential backoff
|
||||
labels:
|
||||
- "traefik.http.middlewares.test-retry.retry.attempts=4"
|
||||
- "traefik.http.middlewares.test-retry.retry.initialinterval=100ms"
|
||||
```
|
||||
|
||||
```json tab="Tags"
|
||||
// Retry 4 times with exponential backoff
|
||||
|
||||
{
|
||||
// ...
|
||||
"Tags" : [
|
||||
"traefik.http.middlewares.test-retry.retry.attempts=4",
|
||||
"traefik.http.middlewares.test-retry.retry.initialinterval=100ms"
|
||||
]
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
```yaml tab="Kubernetes"
|
||||
# Retry 4 times with exponential backoff
|
||||
apiVersion: traefik.io/v1alpha1
|
||||
kind: Middleware
|
||||
metadata:
|
||||
name: test-retry
|
||||
spec:
|
||||
retry:
|
||||
attempts: 4
|
||||
initialInterval: 100ms
|
||||
```
|
||||
|
||||
## Configuration Options
|
||||
|
||||
| Field | Description | Default | Required |
|
||||
|:------|:------------|:--------|:---------|
|
||||
| `attempts` | number of times the request should be retried. | | Yes |
|
||||
| `initialInterval` | First wait time in the exponential backoff series. <br />The maximum interval is calculated as twice the `initialInterval`. <br /> If unspecified, requests will be retried immediately.<br /> Defined in seconds or as a valid duration format, see [time.ParseDuration](https://golang.org/pkg/time/#ParseDuration). | 0 | No |
|
||||
|
|
@ -0,0 +1,66 @@
|
|||
---
|
||||
title: "Traefik StripPrefix Documentation"
|
||||
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 an `X-Forwarded-Prefix` header.
|
||||
|
||||
!!! tip
|
||||
|
||||
Use a `StripPrefix` middleware if your backend listens on the root path (`/`) but should be exposed on a specific prefix.
|
||||
|
||||
## Configuration Examples
|
||||
|
||||
```yaml tab="Structured (YAML)"
|
||||
# Strip prefix /foobar and /fiibar
|
||||
http:
|
||||
middlewares:
|
||||
test-stripprefix:
|
||||
stripPrefix:
|
||||
prefixes:
|
||||
- "/foobar"
|
||||
- "/fiibar"
|
||||
```
|
||||
|
||||
```toml tab="Structured (TOML)"
|
||||
# Strip prefix /foobar and /fiibar
|
||||
[http.middlewares]
|
||||
[http.middlewares.test-stripprefix.stripPrefix]
|
||||
prefixes = ["/foobar", "/fiibar"]
|
||||
```
|
||||
|
||||
```yaml tab="Labels"
|
||||
# Strip prefix /foobar and /fiibar
|
||||
labels:
|
||||
- "traefik.http.middlewares.test-stripprefix.stripprefix.prefixes=/foobar,/fiibar"
|
||||
```
|
||||
|
||||
```json tab="Tags"
|
||||
// Strip prefix /foobar and /fiibar
|
||||
{
|
||||
"Tags" : [
|
||||
"traefik.http.middlewares.test-stripprefix.stripprefix.prefixes=/foobar,/fiibar"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
```yaml tab="Kubernetes"
|
||||
# Strip prefix /foobar and /fiibar
|
||||
apiVersion: traefik.io/v1alpha1
|
||||
kind: Middleware
|
||||
metadata:
|
||||
name: test-stripprefix
|
||||
spec:
|
||||
stripPrefix:
|
||||
prefixes:
|
||||
- /foobar
|
||||
- /fiibar
|
||||
```
|
||||
|
||||
## Configuration Options
|
||||
|
||||
| Field | Description | Default | Required |
|
||||
|:-----------------------------|:--------------------------------------------------------------|:--------|:---------|
|
||||
| `prefixes` | List of prefixes to strip from the request URL.<br />If your backend is serving assets (for example, images or JavaScript files), it can use the `X-Forwarded-Prefix` header to construct relative URLs. | [] | No |
|
||||
|
||||
{!traefik-for-business-applications.md!}
|
||||
|
|
@ -0,0 +1,70 @@
|
|||
---
|
||||
title: "Traefik StripPrefixRegex Documentation"
|
||||
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 an `X-Forwarded-Prefix` header.
|
||||
|
||||
!!! tip
|
||||
|
||||
Use a `stripPrefixRegex` middleware if your backend listens on the root path (`/`) but should be exposed on a specific prefix.
|
||||
|
||||
## Configuration Example
|
||||
|
||||
```yaml tab="Structured (YAML)"
|
||||
http:
|
||||
middlewares:
|
||||
test-stripprefixregex:
|
||||
stripPrefixRegex:
|
||||
regex:
|
||||
- "/foo/[a-z0-9]+/[0-9]+/"
|
||||
```
|
||||
|
||||
```toml tab="Structured (TOML)"
|
||||
[http.middlewares]
|
||||
[http.middlewares.test-stripprefixregex.stripPrefixRegex]
|
||||
regex = ["/foo/[a-z0-9]+/[0-9]+/"]
|
||||
```
|
||||
|
||||
```yaml tab="Labels"
|
||||
labels:
|
||||
- "traefik.http.middlewares.test-stripprefixregex.stripprefixregex.regex=/foo/[a-z0-9]+/[0-9]+/"
|
||||
```
|
||||
|
||||
```yaml tab="Tags"
|
||||
{
|
||||
//..
|
||||
"Tags" : [
|
||||
"traefik.http.middlewares.test-stripprefixregex.stripprefixregex.regex=/foo/[a-z0-9]+/[0-9]+/"
|
||||
]
|
||||
}
|
||||
-
|
||||
```
|
||||
|
||||
```yaml tab="Kubernetes"
|
||||
apiVersion: traefik.io/v1alpha1
|
||||
kind: Middleware
|
||||
metadata:
|
||||
name: test-stripprefixregex
|
||||
spec:
|
||||
stripPrefixRegex:
|
||||
regex:
|
||||
- "/foo/[a-z0-9]+/[0-9]+/"
|
||||
```
|
||||
|
||||
## Configuration Options
|
||||
|
||||
| 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 />More information [here](#regex). | | No |
|
||||
|
||||
### regex
|
||||
|
||||
If your backend is serving assets (for example, images or JavaScript files), it can use the `X-Forwarded-Prefix` header to construct relative URLs.
|
||||
Using the previous example, the backend should return `/products/shoes/image.png` (and not `/images.png`, which Traefik would likely not be able to associate with the same backend).
|
||||
|
||||
!!! tip
|
||||
|
||||
Regular expressions and replacements can be tested using online tools such as [Go Playground](https://play.golang.org/p/mWU9p-wk2ru) or the [Regex101](https://regex101.com/r/58sIgx/2).
|
||||
|
||||
When defining a regular expression within YAML, any escaped character needs to be escaped twice: `example\.com` needs to be written as `example\\.com`.
|
||||
Loading…
Add table
Add a link
Reference in a new issue