traefik/docs/content/middlewares/errorpages.md

118 lines
3.2 KiB
Markdown
Raw Normal View History

# ErrorPage
It Has Never Been Easier to Say That Something Went Wrong
{: .subtitle }
![ErrorPages](../assets/img/middleware/errorpages.png)
The ErrorPage middleware returns a custom page in lieu of the default, according to configured ranges of HTTP Status codes.
!!! important
The error page itself is _not_ hosted by Traefik.
## Configuration Examples
2019-03-29 11:34:05 +00:00
```yaml tab="Docker"
# Dynamic Custom Error Page for 5XX Status Code
labels:
2019-09-23 15:00:06 +00:00
- "traefik.http.middlewares.test-errorpage.errors.status=500-599"
- "traefik.http.middlewares.test-errorpage.errors.service=serviceError"
- "traefik.http.middlewares.test-errorpage.errors.query=/{status}.html"
2019-03-29 11:34:05 +00:00
```
2019-04-03 12:32:04 +00:00
```yaml tab="Kubernetes"
apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
name: test-errorpage
spec:
errors:
status:
- "500-599"
2019-04-03 12:32:04 +00:00
query: /{status}.html
service:
name: whoami
port: 80
2019-04-03 12:32:04 +00:00
```
2019-10-15 15:34:08 +00:00
```yaml tab="Consul Catalog"
# Dynamic Custom Error Page for 5XX Status Code
- "traefik.http.middlewares.test-errorpage.errors.status=500-599"
- "traefik.http.middlewares.test-errorpage.errors.service=serviceError"
- "traefik.http.middlewares.test-errorpage.errors.query=/{status}.html"
```
```json tab="Marathon"
"labels": {
"traefik.http.middlewares.test-errorpage.errors.status": "500-599",
"traefik.http.middlewares.test-errorpage.errors.service": "serviceError",
"traefik.http.middlewares.test-errorpage.errors.query": "/{status}.html"
}
```
2019-04-08 15:14:08 +00:00
```yaml tab="Rancher"
# Dynamic Custom Error Page for 5XX Status Code
labels:
2019-09-23 15:00:06 +00:00
- "traefik.http.middlewares.test-errorpage.errors.status=500-599"
- "traefik.http.middlewares.test-errorpage.errors.service=serviceError"
- "traefik.http.middlewares.test-errorpage.errors.query=/{status}.html"
2019-04-08 15:14:08 +00:00
```
2019-07-22 07:58:04 +00:00
```toml tab="File (TOML)"
2019-03-29 11:34:05 +00:00
# Custom Error Page for 5XX
[http.middlewares]
2019-07-01 09:30:05 +00:00
[http.middlewares.test-errorpage.errors]
2019-03-29 11:34:05 +00:00
status = ["500-599"]
2019-04-03 12:32:04 +00:00
service = "serviceError"
query = "/{status}.html"
2019-03-29 11:34:05 +00:00
[http.services]
# ... definition of error-handler-service and my-service
```
2019-07-22 07:58:04 +00:00
```yaml tab="File (YAML)"
# Custom Error Page for 5XX
http:
middlewares:
test-errorpage:
errors:
status:
2019-09-23 15:00:06 +00:00
- "500-599"
2019-07-22 07:58:04 +00:00
service: serviceError
query: "/{status}.html"
[http.services]
# ... definition of error-handler-service and my-service
```
2021-02-11 13:34:04 +00:00
!!! note ""
2019-09-03 16:02:05 +00:00
In this example, the error page URL is based on the status code (`query=/{status}.html`).
## Configuration Options
2019-04-03 12:32:04 +00:00
### `status`
2021-02-11 13:34:04 +00:00
The `status` option defines which status or range of statuses should result in an error page.
The status code ranges are inclusive (`500-599` will trigger with every code between `500` and `599`, `500` and `599` included).
2021-02-11 13:34:04 +00:00
!!! note ""
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 (`500-599`),
or a combination of the two (`404,418,500-599`).
2019-04-03 12:32:04 +00:00
### `service`
The service that will serve the new requested error page.
2021-02-11 13:34:04 +00:00
!!! note ""
In Kubernetes, you need to reference a Kubernetes Service instead of a Traefik service.
2019-04-03 12:32:04 +00:00
### `query`
2021-02-11 13:34:04 +00:00
The URL for the error page (hosted by `service`). You can use the `{status}` variable in the `query` option in order to insert the status code in the URL.