From 051f0c685572c33c40e82e7fd691633b91fb26c5 Mon Sep 17 00:00:00 2001 From: Timo Reimann Date: Thu, 20 Apr 2017 01:39:38 +0200 Subject: [PATCH] Improve documentation for frontend rules. Includes guidelines on proper usage of the more complex path matchers. --- docs/basics.md | 62 +++++++++++++++++++++++++++++++++++++------------- 1 file changed, 46 insertions(+), 16 deletions(-) diff --git a/docs/basics.md b/docs/basics.md index 7496b0d06..c98de1681 100644 --- a/docs/basics.md +++ b/docs/basics.md @@ -73,28 +73,58 @@ And here is another example with client certificate authentication: ## Frontends -A frontend is a set of rules that forwards the incoming traffic from an entrypoint to a backend. -Frontends can be defined using the following rules: +A frontend consists of a set of rules that determine how incoming requests are forwarded from an entrypoint to a backend. -- `Headers: Content-Type, application/json`: Headers adds a matcher for request header values. It accepts a sequence of key/value pairs to be matched. -- `HeadersRegexp: Content-Type, application/(text|json)`: Regular expressions can be used with headers as well. It accepts a sequence of key/value pairs, where the value has regex support. -- `Host: traefik.io, www.traefik.io`: Match request host with given host list. -- `HostRegexp: traefik.io, {subdomain:[a-z]+}.traefik.io`: Adds a matcher for the URL hosts. It accepts templates with zero or more URL variables enclosed by `{}`. Variables can define an optional regexp pattern to be matched. -- `Method: GET, POST, PUT`: Method adds a matcher for HTTP methods. It accepts a sequence of one or more methods to be matched. -- `Path: /products/, /articles/{category}/{id:[0-9]+}`: Path adds a matcher for the URL paths. It accepts templates with zero or more URL variables enclosed by `{}`. -- `PathStrip`: Same as `Path` but strip the given prefix from the request URL's Path. -- `PathPrefix`: PathPrefix adds a matcher for the URL path prefixes. This matches if the given template is a prefix of the full URL path. -- `PathPrefixStrip`: Same as `PathPrefix` but strip the given prefix from the request URL's Path. -- `AddPrefix`: Add prefix to the request URL's Path. +Rules may be classified in one of two groups: Modifiers and matchers. -You can use multiple values for a rule by separating them with `,`. -You can use multiple rules by separating them by `;`. +### Modifiers + +Modifier rules only modify the request. They do not have any impact on routing decisions being made. + +Following is the list of existing modifier rules: + +- `AddPrefix: /products`: Add path prefix to the existing request path prior to forwarding the request to the backend. + +### Matchers + +Matcher rules determine if a particular request should be forwarded to a backend. + +Separate multiple rule values by `,` (comma) in order to enable ANY semantics (i.e., forward a request if any rule matches). Does not work for `Headers` and `HeadersRegexp`. + +Separate multiple rule values by `;` (semicolon) in order to enable ALL semantics (i.e., forward a request if all rules match). You can optionally enable `passHostHeader` to forward client `Host` header to the backend. -In order to use path regular expressions, you must declare an arbitrarily named variable followed by the colon-separated regular expression, all enclosed in curly braces. Any pattern supported by [Go's regexp package](https://golang.org/pkg/regexp/) may be used. Example: `/posts/{id:[0-9]+}`. +Following is the list of existing matcher rules along with examples: -(Note that the variable has no special meaning; however, it is required by gorilla/mux which embeds the regular expression and defines the syntax.) +- `Headers: Content-Type, application/json`: Match HTTP header. It accepts a comma-separated key/value pair where both key and value must be literals. +- `HeadersRegexp: Content-Type, application/(text|json)`: Match HTTP header. It accepts a comma-separated key/value pair where the key must be a literal and the value may be a literal or a regular expression. +- `Host: traefik.io, www.traefik.io`: Match request host. It accepts a sequence of literal hosts. +- `HostRegexp: traefik.io, {subdomain:[a-z]+}.traefik.io`: Match request host. It accepts a sequence of literal and regular expression hosts. +- `Method: GET, POST, PUT`: Match request HTTP method. It accepts a sequence of HTTP methods. +- `Path: /products/, /articles/{category}/{id:[0-9]+}`: Match exact request path. It accepts a sequence of literal and regular expression paths. +- `PathStrip: /products/, /articles/{category}/{id:[0-9]+}`: Match exact path and strip off the path prior to forwarding the request to the backend. It accepts a sequence of literal and regular expression paths. +- `PathPrefix: /products/, /articles/{category}/{id:[0-9]+}`: Match request prefix path. It accepts a sequence of literal and regular expression prefix paths. +- `PathPrefixStrip: /products/, /articles/{category}/{id:[0-9]+}`: Match request prefix path and strip off the path prefix prior to forwarding the request to the backend. It accepts a sequence of literal and regular expression prefix paths. Starting with Traefik 1.3, the stripped prefix path will be available in the `X-Forwarded-Prefix` header. + +In order to use regular expressions with Host and Path matchers, you must declare an arbitrarily named variable followed by the colon-separated regular expression, all enclosed in curly braces. Any pattern supported by [Go's regexp package](https://golang.org/pkg/regexp/) may be used. Example: `/posts/{id:[0-9]+}`. + +(Note that the variable has no special meaning; however, it is required by the gorilla/mux dependency which embeds the regular expression and defines the syntax.) + +#### Path Matcher Usage Guidelines + +This section explains when to use the various path matchers. + +Use `Path` if your backend listens on the exact path only. For instance, `Path: /products` would match `/products` but not `/products/shoes`. + +Use a `*Prefix*` matcher if your backend listens on a particular base path but also serves requests on sub-paths. For instance, `PathPrefix: /products` would match `/products` but also `/products/shoes` and `/products/shirts`. Since the path is forwarded as-is, your backend is expected to listen on `/products`. + +Use a `*Strip` matcher if your backend listens on the root path (`/`) but should be routeable on a specific prefix. For instance, `PathPrefixStrip: /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). The `X-Forwarded-Prefix` header (available since Traefik 1.3) can be queried to build such URLs dynamically. + +Instead of distinguishing your backends by path only, you can add a Host matcher to the mix. That way, namespacing of your backends happens on the basis of hosts in addition to paths. + +### Examples Here is an example of frontends definition: