traefik/docs/content/middlewares/stripprefix.md

175 lines
4.5 KiB
Markdown
Raw Normal View History

2019-04-08 15:14:08 +00:00
# StripPrefix
Removing Prefixes From the Path Before Forwarding the Request
{: .subtitle }
2019-09-10 12:40:05 +00:00
<!--
TODO: add schema
-->
2019-04-08 15:14:08 +00:00
Remove the specified prefixes from the URL path.
## Configuration Examples
```yaml tab="Docker"
2019-04-29 17:00:05 +00:00
# Strip prefix /foobar and /fiibar
2019-04-08 15:14:08 +00:00
labels:
2019-09-23 15:00:06 +00:00
- "traefik.http.middlewares.test-stripprefix.stripprefix.prefixes=/foobar,/fiibar"
2019-04-08 15:14:08 +00:00
```
```yaml tab="Kubernetes"
2019-04-29 17:00:05 +00:00
# Strip prefix /foobar and /fiibar
2019-04-08 15:14:08 +00:00
apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
name: test-stripprefix
spec:
2019-06-18 07:50:05 +00:00
stripPrefix:
2019-06-11 18:42:04 +00:00
prefixes:
2019-09-23 15:00:06 +00:00
- /foobar
- /fiibar
2019-04-08 15:14:08 +00:00
```
2019-10-15 15:34:08 +00:00
```yaml tab="Consul Catalog"
# Strip prefix /foobar and /fiibar
- "traefik.http.middlewares.test-stripprefix.stripprefix.prefixes=/foobar,/fiibar"
```
```json tab="Marathon"
"labels": {
2019-09-09 08:36:08 +00:00
"traefik.http.middlewares.test-stripprefix.stripprefix.prefixes": "/foobar,/fiibar"
}
```
2019-04-08 15:14:08 +00:00
```yaml tab="Rancher"
2019-04-29 17:00:05 +00:00
# Strip prefix /foobar and /fiibar
2019-04-08 15:14:08 +00:00
labels:
2019-09-23 15:00:06 +00:00
- "traefik.http.middlewares.test-stripprefix.stripprefix.prefixes=/foobar,/fiibar"
2019-04-08 15:14:08 +00:00
```
2019-07-22 07:58:04 +00:00
```toml tab="File (TOML)"
2019-04-29 17:00:05 +00:00
# Strip prefix /foobar and /fiibar
2019-04-08 15:14:08 +00:00
[http.middlewares]
2019-07-01 09:30:05 +00:00
[http.middlewares.test-stripprefix.stripPrefix]
prefixes = ["/foobar", "/fiibar"]
2019-04-08 15:14:08 +00:00
```
2019-07-22 07:58:04 +00:00
```yaml tab="File (YAML)"
# Strip prefix /foobar and /fiibar
http:
middlewares:
test-stripprefix:
stripPrefix:
prefixes:
2019-09-23 15:00:06 +00:00
- "/foobar"
- "/fiibar"
2019-07-22 07:58:04 +00:00
```
2019-04-08 15:14:08 +00:00
## Configuration Options
### General
The StripPrefix middleware will:
- strip the matching path prefix.
- store the matching path prefix in a `X-Forwarded-Prefix` header.
!!! tip
Use a `StripPrefix` middleware if your backend listens on the root path (`/`) but should be routeable on a specific prefix.
### `prefixes`
The `prefixes` option defines the prefixes to strip from the request URL.
For instance, `/products` would match `/products` but also `/products/shoes` and `/products/shirts`.
Since the path is stripped prior to forwarding, your backend is expected to listen on `/`.
If your backend is serving assets (e.g., images or Javascript files), chances are it must return properly constructed relative URLs.
Continuing on the 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).
2019-04-08 15:14:08 +00:00
The `X-Forwarded-Prefix` header can be queried to build such URLs dynamically.
### `forceSlash`
_Optional, Default=true_
```yaml tab="Docker"
labels:
- "traefik.http.middlewares.example.stripprefix.prefixes=/foobar"
- "traefik.http.middlewares.example.stripprefix.forceslash=false"
```
```yaml tab="Kubernetes"
apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
name: example
spec:
stripPrefix:
prefixes:
- "/foobar"
forceSlash: false
```
```json tab="Marathon"
"labels": {
"traefik.http.middlewares.example.stripprefix.prefixes": "/foobar",
"traefik.http.middlewares.example.stripprefix.forceslash": "false"
}
```
```yaml tab="Rancher"
labels:
- "traefik.http.middlewares.example.stripprefix.prefixes=/foobar"
- "traefik.http.middlewares.example.stripprefix.forceSlash=false"
```
```toml tab="File (TOML)"
[http.middlewares]
[http.middlewares.example.stripPrefix]
prefixes = ["/foobar"]
forceSlash = false
```
```yaml tab="File (YAML)"
http:
middlewares:
example:
stripPrefix:
prefixes:
- "/foobar"
forceSlash: false
```
The `forceSlash` option makes sure that the resulting stripped path is not the empty string, by replacing it with `/` when necessary.
This option was added to keep the initial (non-intuitive) behavior of this middleware, in order to avoid introducing a breaking change.
It's recommended to explicitly set `forceSlash` to `false`.
??? info "Behavior examples"
- `forceSlash=true`
| Path | Prefix to strip | Result |
|------------|-----------------|--------|
| `/` | `/` | `/` |
| `/foo` | `/foo` | `/` |
| `/foo/` | `/foo` | `/` |
| `/foo/` | `/foo/` | `/` |
| `/bar` | `/foo` | `/bar` |
| `/foo/bar` | `/foo` | `/bar` |
- `forceSlash=false`
| Path | Prefix to strip | Result |
|------------|-----------------|--------|
| `/` | `/` | empty |
| `/foo` | `/foo` | empty |
| `/foo/` | `/foo` | `/` |
| `/foo/` | `/foo/` | empty |
| `/bar` | `/foo` | `/bar` |
| `/foo/bar` | `/foo` | `/bar` |