New Install Reference Documentation
This commit is contained in:
Sheddy
GitHub
parent
2b35c7e205
commit
47b4df71bf
33 changed files with 4718 additions and 17 deletions
|
|
@ -0,0 +1,205 @@
|
|||
---
|
||||
title: "Traefik AWS ECS Documentation"
|
||||
description: "Configuration discovery in Traefik is achieved through Providers. Read the technical documentation for leveraging AWS ECS in Traefik."
|
||||
---
|
||||
|
||||
# Traefik & AWS ECS
|
||||
|
||||
## Configuration Example
|
||||
|
||||
You can enable the ECS provider with as detailed below:
|
||||
|
||||
```yaml tab="File (YAML)"
|
||||
providers:
|
||||
ecs: {}
|
||||
```
|
||||
|
||||
```toml tab="File (TOML)"
|
||||
[providers.ecs]
|
||||
```
|
||||
|
||||
```bash tab="CLI"
|
||||
--providers.ecs=true
|
||||
```
|
||||
|
||||
## Configuration Options
|
||||
|
||||
| Field | Description | Default | Required |
|
||||
|:------|:----------------------------------------------------------|:---------------------|:---------|
|
||||
| `providers.providersThrottleDuration` | Minimum amount of time to wait for, after a configuration reload, before taking into account any new configuration refresh event.<br />If multiple events occur within this time, only the most recent one is taken into account, and all others are discarded.<br />**This option cannot be set per provider, but the throttling algorithm applies to each of them independently.** | 2s | No |
|
||||
| `providers.ecs.autoDiscoverClusters` | Search for services in cluster list. If set to `true` service discovery is enabled for all clusters. | false | No |
|
||||
| `providers.ecs.ecsAnywhere` | Enable ECS Anywhere support. | false | No |
|
||||
| `providers.ecs.clusters` | Search for services in cluster list. This option is ignored if `autoDiscoverClusters` is set to `true`. | `["default"]` | No |
|
||||
| `providers.ecs.exposedByDefault` | Expose ECS services by default in Traefik. | true | No |
|
||||
| `providers.ecs.constraints` | Defines an expression that Traefik matches against the container labels to determine whether to create any route for that container. See [here](#constraints) for more information. | true | No |
|
||||
| `providers.ecs.healthyTasksOnly` | Defines whether Traefik discovers only healthy tasks (`HEALTHY` healthStatus). | false | No |
|
||||
| `providers.ecs.defaultRule` | The Default Host rule for all services. See [here](#defaultrule) for more information. | ```"Host(`{{ normalize .Name }}`)"``` | No |
|
||||
| `providers.ecs.refreshSeconds` | Defines the polling interval (in seconds). | 15 | No |
|
||||
| `providers.ecs.region` | Defines the region of the ECS instance. See [here](#credentials) for more information. | "" | No |
|
||||
| `providers.ecs.accessKeyID` | Defines the Access Key ID for the ECS instance. See [here](#credentials) for more information. | "" | No |
|
||||
| `providers.ecs.secretAccessKey` | Defines the Secret Access Key for the ECS instance. See [here](#credentials) for more information. | "" | No |
|
||||
|
||||
### `constraints`
|
||||
|
||||
The `constraints` option can be set to an expression that Traefik matches against the container labels (task),
|
||||
to determine whether to create any route for that container.
|
||||
If none of the container labels match the expression, no route for that container is created.
|
||||
If the expression is empty, all detected containers are included.
|
||||
|
||||
The expression syntax is based on the `Label("key", "value")`, and `LabelRegex("key", "value")` functions,
|
||||
as well as the usual boolean logic, as shown in examples below.
|
||||
|
||||
??? example "Constraints Expression Examples"
|
||||
|
||||
```toml
|
||||
# Includes only containers having a label with key `a.label.name` and value `foo`
|
||||
constraints = "Label(`a.label.name`, `foo`)"
|
||||
```
|
||||
|
||||
```toml
|
||||
# Excludes containers having any label with key `a.label.name` and value `foo`
|
||||
constraints = "!Label(`a.label.name`, `value`)"
|
||||
```
|
||||
|
||||
```toml
|
||||
# With logical AND.
|
||||
constraints = "Label(`a.label.name`, `valueA`) && Label(`another.label.name`, `valueB`)"
|
||||
```
|
||||
|
||||
```toml
|
||||
# With logical OR.
|
||||
constraints = "Label(`a.label.name`, `valueA`) || Label(`another.label.name`, `valueB`)"
|
||||
```
|
||||
|
||||
```toml
|
||||
# With logical AND and OR, with precedence set by parentheses.
|
||||
constraints = "Label(`a.label.name`, `valueA`) && (Label(`another.label.name`, `valueB`) || Label(`yet.another.label.name`, `valueC`))"
|
||||
```
|
||||
|
||||
```toml
|
||||
# Includes only containers having a label with key `a.label.name` and a value matching the `a.+` regular expression.
|
||||
constraints = "LabelRegex(`a.label.name`, `a.+`)"
|
||||
```
|
||||
|
||||
```yaml tab="File (YAML)"
|
||||
providers:
|
||||
ecs:
|
||||
constraints: "Label(`a.label.name`,`foo`)"
|
||||
# ...
|
||||
```
|
||||
|
||||
```toml tab="File (TOML)"
|
||||
[providers.ecs]
|
||||
constraints = "Label(`a.label.name`,`foo`)"
|
||||
# ...
|
||||
```
|
||||
|
||||
```bash tab="CLI"
|
||||
--providers.ecs.constraints="Label(`a.label.name`,`foo`)"
|
||||
# ...
|
||||
```
|
||||
|
||||
For additional information, refer to [Restrict the Scope of Service Discovery](../overview.md#restrict-the-scope-of-service-discovery).
|
||||
|
||||
### `defaultRule`
|
||||
|
||||
The `defaultRule` option defines what routing rule to apply to a container if no rule is defined by a label.
|
||||
|
||||
It must be a valid [Go template](https://pkg.go.dev/text/template/), and can use
|
||||
[sprig template functions](https://masterminds.github.io/sprig/).
|
||||
The container service name can be accessed with the `Name` identifier,
|
||||
and the template has access to all the labels defined on this container.
|
||||
|
||||
```yaml tab="File (YAML)"
|
||||
providers:
|
||||
ecs:
|
||||
defaultRule: "Host(`{{ .Name }}.{{ index .Labels \"customLabel\"}}`)"
|
||||
# ...
|
||||
```
|
||||
|
||||
```toml tab="File (TOML)"
|
||||
[providers.ecs]
|
||||
defaultRule = "Host(`{{ .Name }}.{{ index .Labels \"customLabel\"}}`)"
|
||||
# ...
|
||||
```
|
||||
|
||||
```bash tab="CLI"
|
||||
--providers.ecs.defaultRule='Host(`{{ .Name }}.{{ index .Labels "customLabel"}}`)'
|
||||
# ...
|
||||
```
|
||||
|
||||
??? info "Default rule and Traefik service"
|
||||
|
||||
The exposure of the Traefik container, combined with the default rule mechanism,
|
||||
can lead to create a router targeting itself in a loop.
|
||||
In this case, to prevent an infinite loop,
|
||||
Traefik adds an internal middleware to refuse the request if it comes from the same router.
|
||||
|
||||
### Credentials
|
||||
|
||||
This defines the credentials for the ECS instance
|
||||
|
||||
If `region` is not provided, it is resolved from the EC2 metadata endpoint for EC2 tasks.
|
||||
In a FARGATE context it is resolved from the `AWS_REGION` environment variable.
|
||||
|
||||
If `accessKeyID` and `secretAccessKey` are not provided, credentials are resolved in the following order:
|
||||
|
||||
- Using the environment variables `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and `AWS_SESSION_TOKEN`.
|
||||
- Using shared credentials, determined by `AWS_PROFILE` and `AWS_SHARED_CREDENTIALS_FILE`, defaults to `default` and `~/.aws/credentials`.
|
||||
- Using EC2 instance role or ECS task role
|
||||
|
||||
```yaml tab="File (YAML)"
|
||||
providers:
|
||||
ecs:
|
||||
region: us-east-1
|
||||
accessKeyID: "abc"
|
||||
secretAccessKey: "123"
|
||||
# ...
|
||||
```
|
||||
|
||||
```toml tab="File (TOML)"
|
||||
[providers.ecs]
|
||||
region = "us-east-1"
|
||||
accessKeyID = "abc"
|
||||
secretAccessKey = "123"
|
||||
```
|
||||
|
||||
```bash tab="CLI"
|
||||
--providers.ecs.region="us-east-1"
|
||||
--providers.ecs.accessKeyID="abc"
|
||||
--providers.ecs.secretAccessKey="123"
|
||||
# ...
|
||||
```
|
||||
|
||||
## Policy
|
||||
|
||||
Traefik needs the following policy to read ECS information:
|
||||
|
||||
```json
|
||||
{
|
||||
"Version": "2012-10-17",
|
||||
"Statement": [
|
||||
{
|
||||
"Sid": "TraefikECSReadAccess",
|
||||
"Effect": "Allow",
|
||||
"Action": [
|
||||
"ecs:ListClusters",
|
||||
"ecs:DescribeClusters",
|
||||
"ecs:ListTasks",
|
||||
"ecs:DescribeTasks",
|
||||
"ecs:DescribeContainerInstances",
|
||||
"ecs:DescribeTaskDefinition",
|
||||
"ec2:DescribeInstances",
|
||||
"ssm:DescribeInstanceInformation"
|
||||
],
|
||||
"Resource": [
|
||||
"*"
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
!!! info "ECS Anywhere"
|
||||
|
||||
Please note that the `ssm:DescribeInstanceInformation` action is required for ECS anywhere instances discovery.
|
||||
|
|
@ -0,0 +1,124 @@
|
|||
---
|
||||
title: "Traefik File Documentation"
|
||||
description: "The file provider in Traefik Proxy lets you define the dynamic configuration in a YAML or TOML file. Read the technical documentation."
|
||||
---
|
||||
|
||||
# File
|
||||
|
||||
The file provider lets you define the [install configuration](../overview.md) in a YAML or TOML file.
|
||||
|
||||
It supports providing configuration through a single configuration file or multiple separate files.
|
||||
|
||||
!!! info
|
||||
|
||||
The file provider is the default format used throughout the documentation to show samples of the configuration for many features.
|
||||
|
||||
!!! tip
|
||||
|
||||
The file provider can be a good solution for reusing common elements from other providers (e.g. declaring allowlist middlewares, basic authentication, ...)
|
||||
|
||||
## Configuration Example
|
||||
|
||||
You can enable the file provider as detailed below:
|
||||
|
||||
```yaml tab="File (YAML)"
|
||||
providers:
|
||||
file:
|
||||
directory: "/path/to/dynamic/conf"
|
||||
```
|
||||
|
||||
```toml tab="File (TOML)"
|
||||
[providers.file]
|
||||
directory = "/path/to/dynamic/conf"
|
||||
```
|
||||
|
||||
```bash tab="CLI"
|
||||
--providers.file.directory=/path/to/dynamic/conf
|
||||
```
|
||||
|
||||
Declaring the Routers, Middlewares & Services:
|
||||
|
||||
```yaml tab="YAML"
|
||||
http:
|
||||
# Add the router
|
||||
routers:
|
||||
router0:
|
||||
entryPoints:
|
||||
- web
|
||||
middlewares:
|
||||
- my-basic-auth
|
||||
service: service-foo
|
||||
rule: Path(`/foo`)
|
||||
|
||||
# Add the middleware
|
||||
middlewares:
|
||||
my-basic-auth:
|
||||
basicAuth:
|
||||
users:
|
||||
- test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/
|
||||
- test2:$apr1$d9hr9HBB$4HxwgUir3HP4EsggP/QNo0
|
||||
usersFile: etc/traefik/.htpasswd
|
||||
|
||||
# Add the service
|
||||
services:
|
||||
service-foo:
|
||||
loadBalancer:
|
||||
servers:
|
||||
- url: http://foo/
|
||||
- url: http://bar/
|
||||
passHostHeader: false
|
||||
```
|
||||
|
||||
```toml tab="TOML"
|
||||
[http]
|
||||
# Add the router
|
||||
[http.routers]
|
||||
[http.routers.router0]
|
||||
entryPoints = ["web"]
|
||||
middlewares = ["my-basic-auth"]
|
||||
service = "service-foo"
|
||||
rule = "Path(`/foo`)"
|
||||
|
||||
# Add the middleware
|
||||
[http.middlewares]
|
||||
[http.middlewares.my-basic-auth.basicAuth]
|
||||
users = ["test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/",
|
||||
"test2:$apr1$d9hr9HBB$4HxwgUir3HP4EsggP/QNo0"]
|
||||
usersFile = "etc/traefik/.htpasswd"
|
||||
|
||||
# Add the service
|
||||
[http.services]
|
||||
[http.services.service-foo]
|
||||
[http.services.service-foo.loadBalancer]
|
||||
[[http.services.service-foo.loadBalancer.servers]]
|
||||
url = "http://foo/"
|
||||
[[http.services.service-foo.loadBalancer.servers]]
|
||||
url = "http://bar/"
|
||||
```
|
||||
|
||||
## Configuration Options
|
||||
|
||||
| Field | Description | Default | Required |
|
||||
|:------|:----------------------------------------------------------|:---------------------|:---------|
|
||||
| `providers.providersThrottleDuration` | Minimum amount of time to wait for, after a configuration reload, before taking into account any new configuration refresh event.<br />If multiple events occur within this time, only the most recent one is taken into account, and all others are discarded.<br />**This option cannot be set per provider, but the throttling algorithm applies to each of them independently.** | 2s | No |
|
||||
| `providers.file.filename` | Defines the path to the configuration file. | "" | Yes |
|
||||
| `providers.file.directory` | Defines the path to the directory that contains the configuration files. The `filename` and `directory` options are mutually exclusive. It is recommended to use `directory`. | "" | Yes |
|
||||
| `providers.file.watch` | Set the `watch` option to `true` to allow Traefik to automatically watch for file changes. It works with both the `filename` and the `directory` options. | true | No |
|
||||
|
||||
!!! warning "Limitations"
|
||||
|
||||
With the file provider, Traefik listens for file system notifications to update the dynamic configuration.
|
||||
|
||||
If you use a mounted/bound file system in your orchestrator (like docker or kubernetes), the way the files are linked may be a source of errors.
|
||||
If the link between the file systems is broken, when a source file/directory is changed/renamed, nothing will be reported to the linked file/directory, so the file system notifications will be neither triggered nor caught.
|
||||
|
||||
For example, in Docker, if the host file is renamed, the link to the mounted file is broken and the container's file is no longer updated.
|
||||
To avoid this kind of issue, it is recommended to:
|
||||
|
||||
* set the Traefik [**directory**](#directory) configuration with the parent directory
|
||||
* mount/bind the parent directory
|
||||
|
||||
As it is very difficult to listen to all file system notifications, Traefik uses [fsnotify](https://github.com/fsnotify/fsnotify).
|
||||
If using a directory with a mounted directory does not fix your issue, please check your file system compatibility with fsnotify.
|
||||
|
||||
{!traefik-for-business-applications.md!}
|
||||
|
|
@ -0,0 +1,66 @@
|
|||
---
|
||||
title: "Traefik HTTP Documentation"
|
||||
description: "Provide your dynamic configuration via an HTTP(S) endpoint and let Traefik Proxy do the rest. Read the technical documentation."
|
||||
---
|
||||
|
||||
# Traefik & HTTP
|
||||
|
||||
Provide your [install configuration](../overview.md) via an HTTP(S) endpoint and let Traefik do the rest!
|
||||
|
||||
## Configuration Example
|
||||
|
||||
You can enable the HTTP provider as detailed below:
|
||||
|
||||
```yaml tab="File (YAML)"
|
||||
providers:
|
||||
http:
|
||||
endpoint: "http://127.0.0.1:9000/api"
|
||||
```
|
||||
|
||||
```toml tab="File (TOML)"
|
||||
[providers.http]
|
||||
endpoint = "http://127.0.0.1:9000/api"
|
||||
```
|
||||
|
||||
```bash tab="CLI"
|
||||
--providers.http.endpoint=http://127.0.0.1:9000/api
|
||||
```
|
||||
|
||||
## Configuration Options
|
||||
|
||||
| Field | Description | Default | Required |
|
||||
|:------|:----------------------------------------------------------|:---------------------|:---------|
|
||||
| `providers.providersThrottleDuration` | Minimum amount of time to wait for, after a configuration reload, before taking into account any new configuration refresh event.<br />If multiple events occur within this time, only the most recent one is taken into account, and all others are discarded.<br />**This option cannot be set per provider, but the throttling algorithm applies to each of them independently.** | 2s | No |
|
||||
| `providers.http.endpoint` | Defines the HTTP(S) endpoint to poll. | "" | Yes |
|
||||
| `providers.http.pollInterval` | Defines the polling interval. | 5s | No |
|
||||
| `providers.http.pollTimeout` | Defines the polling timeout when connecting to the endpoint. | 5s | No |
|
||||
| `providers.http.headers` | Defines custom headers to be sent to the endpoint. | "" | No |
|
||||
| `providers.http.tls.ca` | Defines the path to the certificate authority used for the secure connection to the endpoint, it defaults to the system bundle. | "" | No |
|
||||
| `providers.http.tls.cert` | Defines the path to the public certificate used for the secure connection to the endpoint. When using this option, setting the `key` option is required. | "" | Yes |
|
||||
| `providers.http.tls.key` | Defines the path to the private key used for the secure connection to the endpoint. When using this option, setting the `cert` option is required. | "" | Yes |
|
||||
| `providers.http.tls.insecureSkipVerify` | Instructs the provider to accept any certificate presented by endpoint when establishing a TLS connection, regardless of the hostnames the certificate covers. | false | No |
|
||||
|
||||
### headers
|
||||
|
||||
Defines custom headers to be sent to the endpoint.
|
||||
|
||||
```yaml tab="File (YAML)"
|
||||
providers:
|
||||
http:
|
||||
headers:
|
||||
name: value
|
||||
```
|
||||
|
||||
```toml tab="File (TOML)"
|
||||
[providers.http.headers]
|
||||
name = "value"
|
||||
```
|
||||
|
||||
```bash tab="CLI"
|
||||
[providers.http.headers]
|
||||
--providers.http.headers.name=value
|
||||
```
|
||||
|
||||
## Routing Configuration
|
||||
|
||||
The HTTP provider uses the same configuration as the [File Provider](./file.md) in YAML or JSON format.
|
||||
Loading…
Add table
Add a link
Reference in a new issue