From 51ee77b96fabd53a0422ba5fcda6f95b27162cfc Mon Sep 17 00:00:00 2001 From: Romain Date: Fri, 11 Jun 2021 10:00:14 +0200 Subject: [PATCH] Explains Traefik HTTP response status codes Co-authored-by: Jean-Baptiste Doumenjou <925513+jbdoumenjou@users.noreply.github.com> Co-authored-by: Tom Moulard --- docs/content/getting-started/faq.md | 126 ++++++++++++++++++++++++++++ docs/mkdocs.yml | 1 + 2 files changed, 127 insertions(+) create mode 100644 docs/content/getting-started/faq.md diff --git a/docs/content/getting-started/faq.md b/docs/content/getting-started/faq.md new file mode 100644 index 000000000..89d678116 --- /dev/null +++ b/docs/content/getting-started/faq.md @@ -0,0 +1,126 @@ +# FAQ + +## Why is Traefik Answering `XXX` HTTP Response Status Code? + +Traefik is a dynamic reverse proxy, +and while the documentation often demonstrates configuration options through file examples, +the core feature of Traefik is its dynamic configurability, +directly reacting to changes from providers over time. + +Notably, a part of the configuration is [static](../configuration-overview/#the-static-configuration), +and can be provided by a file on startup, whereas various providers, +such as the file provider, +contribute dynamically all along the traefik instance lifetime to its [dynamic configuration](../configuration-overview/#the-dynamic-configuration) changes. + +In addition, the configuration englobes concepts such as the EntryPoint which can be seen as a listener on the Transport Layer (TCP), +as apposed to the Router which is more about the Presentation (TLS) and Application layers (HTTP). +And there can be as many routers as one wishes for a given EntryPoint. + +In other words, for a given Entrypoint, +at any given time the traffic seen is not bound to be just about one protocol. +It could be HTTP, or otherwise. Over TLS, or not. +Not to mention that dynamic configuration changes potentially make that kind of traffic vary over time. + +Therefore, in this dynamic context, +the static configuration of an `entryPoint` does not give any hint whatsoever about how the traffic going through that `entryPoint` is going to be routed. +Or whether it's even going to be routed at all, +i.e. whether there is a Router matching the kind of traffic going through it. + +### `404 Not found` + +Traefik returns a `404` response code in the following situations: + +- A request reaching an EntryPoint that has no Routers +- An HTTP request reaching an EntryPoint that has no HTTP Router +- An HTTPS request reaching an EntryPoint that has no HTTPS Router +- A request reaching an EntryPoint that has HTTP/HTTPS Routers that cannot be matched + +From Traefik's point of view, +every time a request cannot be matched with a router the correct response code is a `404 Not found`. + +In this situation, the response code is not a `503 Service Unavailable` +because Traefik is not able to confirm that the lack of a matching router for a request is only temporary. +Traefik's routing configuration is dynamic and aggregated from different providers, +hence it's not possible to assume at any moment that a specific route should be handled or not. + +??? info "This behavior is consistent with rfc7231" + + ```txt + The server is currently unable to handle the request due to a + temporary overloading or maintenance of the server. The implication + is that this is a temporary condition which will be alleviated after + some delay. If known, the length of the delay MAY be indicated in a + Retry-After header. If no Retry-After is given, the client SHOULD + handle the response as it would for a 500 response. + + Note: The existence of the 503 status code does not imply that a + server must use it when becoming overloaded. Some servers may wish + to simply refuse the connection. + ``` + + Extract from [rfc7231#section-6.6.4](https://datatracker.ietf.org/doc/html/rfc7231#section-6.6.4). + +### `502 Bad Gateway` + +Traefik returns a `502` response code when an error happens while contacting the upstream service. + +### `503 Service Unavailable` + +Traefik returns a `503` response code when a Router has been matched +but there are no servers ready to handle the request. + +This situation is encountered when a service has been explicitly configured without servers, +or when a service has healthcheck enabled and all servers are unhealthy. + +### `XXX` Instead of `404` + +Sometimes, the `404` response code doesn't play well with other parties or services (such as CDNs). + +In these situations, you may want Traefik to always reply with a `503` response code, +instead of a `404` response code. + +To achieve this behavior, a simple catchall router, +with the lowest possible priority and routing to a service without servers, +can handle all the requests when no other router has been matched. + +The example below is a file provider only version (`yaml`) of what this configuration could look like: + +```yaml tab="Static configuration" +# traefik.yaml + +entrypoints: + web: + address: :80 + +providers: + file: + filename: dynamic.yaml +``` + +```yaml tab="Dynamic configuration" +# dynamic.yaml + +http: + routers: + catchall: + # attached only to web entryPoint + entryPoints: + - "web" + # catchall rule + rule: "PathPrefix(`/`)" + service: unavailable + # lowest possible priority + # evaluated when no other router is matched + priority: 1 + + services: + # Service that will always answer a 503 Service Unavailable response + unavailable: + loadBalancer: + servers: {} +``` + +!!! info "Dedicated service" + If there is a need for a response code other than a `503` and/or a custom message, + the principle of the above example above (a catchall router) still stands, + but the `unavailable` service should be adapted to fit such a need. diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index fe176494c..85749c598 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -68,6 +68,7 @@ nav: - 'Quick Start': 'getting-started/quick-start.md' - 'Configuration Introduction': 'getting-started/configuration-overview.md' - 'Install Traefik': 'getting-started/install-traefik.md' + - 'Frequently Asked Questions': 'getting-started/faq.md' - 'Configuration Discovery': - 'Overview': 'providers/overview.md' - 'Docker': 'providers/docker.md'