homelab/traefik
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

doc: structural review

Browse source 
- user-guide review.
- add DataDog and StatD configuration.
- sync sample.toml and doc.
- split entry points doc.
- Deprecated.
This commit is contained in:
Fernandez Ludovic 2017-08-26 12:12:44 +02:00 • committed by Traefiker
parent 24862402e5
commit 7c2ba62b56
32 changed files with 848 additions and 695 deletions
Download patch file Download diff file Expand all files Collapse all files

51
docs/basics.md
View file

@ -1,5 +1,6 @@
# Basics
# Concepts
## Concepts
Let's take our example from the [overview](https://docs.traefik.io/#overview) again:
@ -24,7 +25,7 @@ Routes are created using requests fields (`Host`, `Path`, `Headers`...) and can
- The [frontend](#frontends) will then send the request to a [backend](#backends). A backend can be composed by one or more [servers](#servers), and by a load-balancing strategy.
- Finally, the [server](#servers) will forward the request to the corresponding microservice in the private network.
## Entrypoints
### Entrypoints
Entrypoints are the network entry points into Træfik.
They can be defined using:
@ -71,13 +72,13 @@ And here is another example with client certificate authentication:
- One or several files containing Certificate Authorities in PEM format are added.
- It is possible to have multiple CA:s in the same file or keep them in separate files.
## Frontends
### Frontends
A frontend consists of a set of rules that determine how incoming requests are forwarded from an entrypoint to a backend.
Rules may be classified in one of two groups: Modifiers and matchers.
### Modifiers
#### Modifiers
Modifier rules only modify the request. They do not have any impact on routing decisions being made.
@ -86,7 +87,7 @@ 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.
- `ReplacePath: /serverless-path`: Replaces the path and adds the old path to the `X-Replaced-Path` header. Useful for mapping to AWS Lambda or Google Cloud Functions.
### Matchers
#### Matchers
Matcher rules determine if a particular request should be forwarded to a backend.
@ -115,7 +116,7 @@ In order to use regular expressions with Host and Path matchers, you must declar
(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
##### Path Matcher Usage Guidelines
This section explains when to use the various path matchers.
@ -128,7 +129,7 @@ If your backend is serving assets (e.g., images or Javascript files), chances ar
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
#### Examples
Here is an example of frontends definition:
@ -157,7 +158,7 @@ Here is an example of frontends definition:
- `frontend2` will forward the traffic to the `backend1` if the rule `Host:localhost,{subdomain:[a-z]+}.localhost` is matched (forwarding client `Host` header to the backend)
- `frontend3` will forward the traffic to the `backend2` if the rules `Host:test3.localhost` **AND** `Path:/test` are matched
### Combining multiple rules
#### Combining multiple rules
As seen in the previous example, you can combine multiple rules.
In TOML file, you can use multiple routes:
@ -193,7 +194,7 @@ Finally, you can create a rule to bind multiple domains or Path to a frontend, u
rule = "Path:/test1,/test2"
```
### Rules Order
#### Rules Order
When combining `Modifier` rules with `Matcher` rules, it is important to remember that `Modifier` rules **ALWAYS** apply after the `Matcher` rules.
The following rules are both `Matchers` and `Modifiers`, so the `Matcher` portion of the rule will apply first, and the `Modifier` will apply later.
@ -212,7 +213,7 @@ The following rules are both `Matchers` and `Modifiers`, so the `Matcher` portio
5. `AddPrefix`
6. `ReplacePath`
### Priorities
#### Priorities
By default, routes will be sorted (in descending order) using rules length (to avoid path overlap):
`PathPrefix:/12345` will be matched before `PathPrefix:/1234` that will be matched before `PathPrefix:/1`.
@ -237,7 +238,7 @@ You can customize priority by frontend:
Here, `frontend1` will be matched before `frontend2` (`10 > 5`).
### Custom headers
#### Custom headers
Custom headers can be configured through the frontends, to add headers to either requests or responses that match the frontend's rules. This allows for setting headers such as `X-Script-Name` to be added to the request, or custom headers to be added to the response:
@ -255,7 +256,7 @@ Custom headers can be configured through the frontends, to add headers to either
In this example, all matches to the path `/cheese` will have the `X-Script-Name` header added to the proxied request, and the `X-Custom-Response-Header` added to the response.
### Security headers
#### Security headers
Security related headers (HSTS headers, SSL redirection, Browser XSS filter, etc) can be added and configured per frontend in a similar manner to the custom headers above. This functionality allows for some easy security features to quickly be set. An example of some of the security headers:
@ -277,7 +278,7 @@ Security related headers (HSTS headers, SSL redirection, Browser XSS filter, etc
In this example, traffic routed through the first frontend will have the `X-Frame-Options` header set to `DENY`, and the second will only allow HTTPS request through, otherwise will return a 301 HTTPS redirect.
## Backends
### Backends
A backend is responsible to load-balance the traffic coming from one or more frontends to a set of http servers.
Various methods of load-balancing are supported:
@ -364,7 +365,7 @@ To use a different port for the healthcheck:
port = 8080
```
## Servers
### Servers
Servers are simply defined using a `URL`. You can also apply a custom `weight` to each server (this will be used by load-balancing).
@ -397,7 +398,7 @@ Here is an example of backends and servers definition:
- `backend2` will forward the traffic to two servers: `http://172.17.0.4:80"` with weight `1` and `http://172.17.0.5:80` with weight `2` using `drr` load-balancing strategy.
- a circuit breaker is added on `backend1` using the expression `NetworkErrorRatio() > 0.5`: watch error ratio over 10 second sliding window
## Custom Error pages
### Custom Error pages
Custom error pages can be returned, in lieu of the default, according to frontend-configured ranges of HTTP Status codes.
In the example below, if a 503 status is returned from the frontend "website", the custom error page at http://2.3.4.5/503.html is returned with the actual status code set in the HTTP header.
@ -430,7 +431,7 @@ Instead, the query parameter can also be set to some generic error page like so:
Now the 500s.html error page is returned for the configured code range.
The configured status code ranges are inclusive; that is, in the above example, the 500s.html page will be returned for status codes 500 through, and including, 599.
# Configuration
## Configuration
Træfik's configuration has two parts:
@ -438,7 +439,7 @@ Træfik's configuration has two parts:
- The [dynamic Træfik configuration](/basics#dynamic-trfk-configuration) which can be hot-reloaded (no need to restart the process).
## Static Træfik configuration
### Static Træfik configuration
The static configuration is the global configuration which is setting up connections to configuration backends and entrypoints.
@ -454,7 +455,7 @@ It means that arguments override configuration file, and key-value store overrid
Note that the provider-enabling argument parameters (e.g., `--docker`) set all default values for the specific provider. It must not be used if a configuration source with less precedence wants to set a non-default provider value.
### Configuration file
#### Configuration file
By default, Træfik will try to find a `traefik.toml` in the following places:
@ -470,7 +471,7 @@ $ traefik --configFile=foo/bar/myconfigfile.toml
Please refer to the [global configuration](/toml/#global-configuration) section to get documentation on it.
### Arguments
#### Arguments
Each argument (and command) is described in the help section:
@ -480,7 +481,7 @@ $ traefik --help
Note that all default values will be displayed as well.
### Key-value stores
#### Key-value stores
Træfik supports several Key-value stores:
@ -491,7 +492,7 @@ Træfik supports several Key-value stores:
Please refer to the [User Guide Key-value store configuration](/user-guide/kv-config/) section to get documentation on it.
## Dynamic Træfik configuration
### Dynamic Træfik configuration
The dynamic configuration concerns :
@ -506,7 +507,7 @@ Routes to services will be created and updated instantly at any changes.
Please refer to the [configuration backends](/toml/#configuration-backends) section to get documentation on it.
# Commands
## Commands
Usage: `traefik [command] [--flag=flag_argument]`
@ -530,7 +531,7 @@ Note that each command is described at the beginning of the help section:
$ traefik --help
```
## Command: bug
### Command: bug
Here is the easiest way to submit a pre-filled issue on [Træfik GitHub](https://github.com/containous/traefik).
@ -540,7 +541,7 @@ $ traefik bug
See https://www.youtube.com/watch?v=Lyz62L8m93I.
## Command: healthcheck
### Command: healthcheck
This command allows to check the health of Traefik. Its exit status is `0` if Traefik is healthy and `1` if it is unhealthy.
This can be used with Docker [HEALTHCHECK](https://docs.docker.com/engine/reference/builder/#healthcheck) instruction or any other health check orchestration mechanism.
@ -552,7 +553,7 @@ $ traefik healthcheck
OK: http://:8082/ping
```
# Log Rotation
## Log Rotation
Traefik will close and reopen its log files, assuming they're configured, on receipt of a USR1 signal. This allows the logs
to be rotated and processed by an external program, such as `logrotate`.