traefik/docs/content/providers/marathon.md

591 lines
13 KiB
Markdown
Raw Normal View History

---
title: "Traefik Configuration for Marathon"
description: "Traefik Proxy can be configured to use Marathon as a provider. Read the technical documentation to learn how."
---
# Traefik & Marathon
Traefik can be configured to use Marathon as a provider.
{: .subtitle }
2021-02-11 18:04:03 +00:00
For additional information, refer to [Marathon user guide](../user-guides/marathon.md).
## Configuration Examples
??? example "Configuring Marathon & Deploying / Exposing Applications"
2021-02-11 18:04:03 +00:00
Enabling the Marathon provider
2019-07-02 15:36:04 +00:00
```yaml tab="File (YAML)"
providers:
marathon: {}
```
2021-02-11 18:04:03 +00:00
```toml tab="File (TOML)"
[providers.marathon]
```
2019-07-02 15:36:04 +00:00
```bash tab="CLI"
2019-07-22 07:58:04 +00:00
--providers.marathon=true
2019-04-17 08:58:04 +00:00
```
2021-02-11 18:04:03 +00:00
Attaching labels to Marathon applications
```json
{
"id": "/whoami",
"container": {
"type": "DOCKER",
"docker": {
"image": "traefik/whoami",
"network": "BRIDGE",
"portMappings": [
{
"containerPort": 80,
"hostPort": 0,
"protocol": "tcp"
}
]
}
},
"labels": {
"traefik.http.Routers.app.Rule": "PathPrefix(`/app`)"
}
}
```
2019-09-23 12:32:04 +00:00
## Routing Configuration
2019-09-23 12:32:04 +00:00
See the dedicated section in [routing](../routing/providers/marathon.md).
## Provider Configuration
### `basic`
_Optional_
2021-02-11 18:04:03 +00:00
Enables Marathon basic authentication.
2019-07-02 15:36:04 +00:00
```yaml tab="File (YAML)"
providers:
marathon:
basic:
httpBasicAuthUser: foo
httpBasicPassword: bar
```
```toml tab="File (TOML)"
[providers.marathon.basic]
httpBasicAuthUser = "foo"
httpBasicPassword = "bar"
```
2019-07-02 15:36:04 +00:00
```bash tab="CLI"
--providers.marathon.basic.httpbasicauthuser=foo
--providers.marathon.basic.httpbasicpassword=bar
2019-04-17 08:58:04 +00:00
```
### `dcosToken`
_Optional_
2021-02-11 18:04:03 +00:00
Datacenter Operating System (DCOS) Token for DCOS environment.
If set, it overrides the Authorization header.
2019-07-02 15:36:04 +00:00
```toml tab="File (YAML)"
providers:
marathon:
dcosToken: "xxxxxx"
# ...
```
```toml tab="File (TOML)"
[providers.marathon]
dcosToken = "xxxxxx"
# ...
```
2019-07-02 15:36:04 +00:00
```bash tab="CLI"
--providers.marathon.dcosToken=xxxxxx
2019-04-17 08:58:04 +00:00
```
### `defaultRule`
2019-04-17 08:58:04 +00:00
_Optional, Default=```Host(`{{ normalize .Name }}`)```_
2021-02-11 18:04:03 +00:00
The default host rule for all services.
For a given application, if no routing rule was defined by a label, it is defined by this `defaultRule` instead.
2021-09-10 09:42:07 +00:00
It must be a valid [Go template](https://pkg.go.dev/text/template/),
2021-08-31 16:54:06 +00:00
and can include [sprig template functions](https://masterminds.github.io/sprig/).
2021-02-11 18:04:03 +00:00
The app ID can be accessed with the `Name` identifier,
and the template has access to all the labels defined on this Marathon application.
2019-07-02 15:36:04 +00:00
```yaml tab="File (YAML)"
providers:
marathon:
defaultRule: "Host(`{{ .Name }}.{{ index .Labels \"customLabel\"}}`)"
# ...
```
```toml tab="File (TOML)"
[providers.marathon]
defaultRule = "Host(`{{ .Name }}.{{ index .Labels \"customLabel\"}}`)"
# ...
```
2019-07-02 15:36:04 +00:00
```bash tab="CLI"
--providers.marathon.defaultRule=Host(`{{ .Name }}.{{ index .Labels \"customLabel\"}}`)
2019-07-02 15:36:04 +00:00
# ...
```
??? 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.
2019-07-02 15:36:04 +00:00
### `dialerTimeout`
_Optional, Default=5s_
2021-02-11 18:04:03 +00:00
Amount of time the Marathon provider should wait before timing out,
when trying to open a TCP connection to a Marathon master.
The value of `dialerTimeout` should be provided in seconds or as a valid duration format,
see [time.ParseDuration](https://golang.org/pkg/time/#ParseDuration).
```yaml tab="File (YAML)"
2019-07-02 15:36:04 +00:00
providers:
marathon:
dialerTimeout: "10s"
# ...
2019-04-17 08:58:04 +00:00
```
```toml tab="File (TOML)"
[providers.marathon]
dialerTimeout = "10s"
# ...
```
2019-07-02 15:36:04 +00:00
```bash tab="CLI"
--providers.marathon.dialerTimeout=10s
```
### `endpoint`
_Optional, Default=http://127.0.0.1:8080_
2021-02-11 18:04:03 +00:00
Marathon server endpoint.
You can optionally specify multiple endpoints.
```yaml tab="File (YAML)"
2019-07-02 15:36:04 +00:00
providers:
marathon:
endpoint: "http://10.241.1.71:8080,10.241.1.72:8080,10.241.1.73:8080"
# ...
```
```toml tab="File (TOML)"
[providers.marathon]
endpoint = "http://10.241.1.71:8080,10.241.1.72:8080,10.241.1.73:8080"
# ...
```
2019-07-02 15:36:04 +00:00
```bash tab="CLI"
--providers.marathon.endpoint=http://10.241.1.71:8080,10.241.1.72:8080,10.241.1.73:8080
2019-04-17 08:58:04 +00:00
```
### `exposedByDefault`
_Optional, Default=true_
2021-02-11 18:04:03 +00:00
Exposes Marathon applications by default through Traefik.
If set to `false`, applications that do not have a `traefik.enable=true` label are ignored from the resulting routing configuration.
For additional information, refer to [Restrict the Scope of Service Discovery](./overview.md#restrict-the-scope-of-service-discovery).
2019-07-02 15:36:04 +00:00
```yaml tab="File (YAML)"
providers:
marathon:
exposedByDefault: false
# ...
```
```toml tab="File (TOML)"
[providers.marathon]
exposedByDefault = false
# ...
```
2019-07-02 15:36:04 +00:00
```bash tab="CLI"
--providers.marathon.exposedByDefault=false
# ...
```
### `constraints`
_Optional, Default=""_
2021-02-11 18:04:03 +00:00
The `constraints` option can be set to an expression that Traefik matches against the application labels to determine whether
to create any route for that application. If none of the application labels match the expression, no route for that application is
created. In addition, the expression is also matched against the application constraints, such as described
in [Marathon constraints](https://mesosphere.github.io/marathon/docs/constraints.html).
If the expression is empty, all detected applications are included.
2019-04-17 08:58:04 +00:00
2021-02-11 18:04:03 +00:00
The expression syntax is based on the `Label("key", "value")`, and `LabelRegex("key", "value")` functions, as well as the usual boolean logic.
In addition, to match against Marathon constraints, the function `MarathonConstraint("field:operator:value")` can be used, where the field, operator, and value parts are concatenated in a single string using the `:` separator.
2019-04-17 08:58:04 +00:00
??? example "Constraints Expression Examples"
```toml
# Includes only applications having a label with key `a.label.name` and value `foo`
constraints = "Label(`a.label.name`, `foo`)"
```
2021-02-11 18:04:03 +00:00
```toml
# Excludes applications having any label with key `a.label.name` and value `foo`
constraints = "!Label(`a.label.name`, `value`)"
```
2021-02-11 18:04:03 +00:00
```toml
# With logical AND.
constraints = "Label(`a.label.name`, `valueA`) && Label(`another.label.name`, `valueB`)"
```
2021-02-11 18:04:03 +00:00
```toml
# With logical OR.
constraints = "Label(`a.label.name`, `valueA`) || Label(`another.label.name`, `valueB`)"
```
2021-02-11 18:04:03 +00:00
```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`))"
```
2021-02-11 18:04:03 +00:00
```toml
# Includes only applications having a label with key `a.label.name` and a value matching the `a.+` regular expression.
2019-09-05 08:48:04 +00:00
constraints = "LabelRegex(`a.label.name`, `a.+`)"
```
```toml
# Includes only applications having a Marathon constraint with field `A`, operator `B`, and value `C`.
constraints = "MarathonConstraint(`A:B:C`)"
```
```toml
# Uses both Marathon constraint and application label with logical operator.
constraints = "MarathonConstraint(`A:B:C`) && Label(`a.label.name`, `value`)"
```
2021-02-11 18:04:03 +00:00
For additional information, refer to [Restrict the Scope of Service Discovery](./overview.md#restrict-the-scope-of-service-discovery).
```yaml tab="File (YAML)"
providers:
marathon:
constraints: "Label(`a.label.name`,`foo`)"
# ...
```
```toml tab="File (TOML)"
[providers.marathon]
constraints = "Label(`a.label.name`,`foo`)"
# ...
```
2021-02-11 18:04:03 +00:00
```bash tab="CLI"
--providers.marathon.constraints=Label(`a.label.name`,`foo`)
# ...
```
2019-07-02 15:36:04 +00:00
### `forceTaskHostname`
_Optional, Default=false_
2021-02-11 18:04:03 +00:00
By default, the task IP address (as returned by the Marathon API) is used as backend server if an IP-per-task configuration can be found;
otherwise, the name of the host running the task is used.
The latter behavior can be enforced by setting this option to `true`.
2019-07-02 15:36:04 +00:00
```yaml tab="File (YAML)"
providers:
marathon:
forceTaskHostname: true
# ...
```
```toml tab="File (TOML)"
[providers.marathon]
forceTaskHostname = true
# ...
```
2019-07-02 15:36:04 +00:00
```bash tab="CLI"
--providers.marathon.forceTaskHostname=true
# ...
```
### `keepAlive`
_Optional, Default=10s_
2021-02-11 18:04:03 +00:00
Set the TCP Keep Alive duration for the Marathon HTTP Client.
The value of `keepAlive` should be provided in seconds or as a valid duration format,
see [time.ParseDuration](https://golang.org/pkg/time/#ParseDuration).
2019-07-02 15:36:04 +00:00
```yaml tab="File (YAML)"
providers:
marathon:
keepAlive: "30s"
# ...
```
```toml tab="File (TOML)"
[providers.marathon]
keepAlive = "30s"
# ...
```
2019-07-02 15:36:04 +00:00
```bash tab="CLI"
--providers.marathon.keepAlive=30s
# ...
```
### `respectReadinessChecks`
_Optional, Default=false_
2021-02-11 18:04:03 +00:00
Applications may define readiness checks which are probed by Marathon during deployments periodically, and these check results are exposed via the API.
Enabling `respectReadinessChecks` causes Traefik to filter out tasks whose readiness checks have not succeeded.
Note that the checks are only valid during deployments.
See the Marathon guide for details.
2019-07-02 15:36:04 +00:00
```yaml tab="File (YAML)"
providers:
marathon:
respectReadinessChecks: true
# ...
```
```toml tab="File (TOML)"
[providers.marathon]
respectReadinessChecks = true
# ...
```
2019-07-02 15:36:04 +00:00
```bash tab="CLI"
--providers.marathon.respectReadinessChecks=true
# ...
```
### `responseHeaderTimeout`
_Optional, Default=60s_
2021-02-11 18:04:03 +00:00
Amount of time the Marathon provider should wait before timing out when waiting for the first response header
from a Marathon master.
The value of `responseHeaderTimeout` should be provided in seconds or as a valid duration format,
see [time.ParseDuration](https://golang.org/pkg/time/#ParseDuration).
2019-07-02 15:36:04 +00:00
```yaml tab="File (YAML)"
providers:
marathon:
responseHeaderTimeout: "66s"
# ...
```
```toml tab="File (TOML)"
[providers.marathon]
responseHeaderTimeout = "66s"
# ...
```
2019-07-02 15:36:04 +00:00
```bash tab="CLI"
--providers.marathon.responseHeaderTimeout=66s
2019-07-02 15:36:04 +00:00
# ...
```
2019-09-09 08:36:08 +00:00
### `tls`
_Optional_
Defines the TLS configuration used for the secure connection to Marathon.
2019-09-09 08:36:08 +00:00
#### `ca`
`ca` is the path to the certificate authority used for the secure connection to Marathon,
it defaults to the system bundle.
2019-09-09 08:36:08 +00:00
```yaml tab="File (YAML)"
providers:
marathon:
tls:
ca: path/to/ca.crt
```
```toml tab="File (TOML)"
[providers.marathon.tls]
ca = "path/to/ca.crt"
```
2019-09-09 08:36:08 +00:00
```bash tab="CLI"
--providers.marathon.tls.ca=path/to/ca.crt
```
#### `cert`
_Optional_
2019-09-09 08:36:08 +00:00
`cert` is the path to the public certificate used for the secure connection to Marathon.
When using this option, setting the `key` option is required.
2019-09-09 08:36:08 +00:00
```yaml tab="File (YAML)"
providers:
marathon:
tls:
cert: path/to/foo.cert
key: path/to/foo.key
```
```toml tab="File (TOML)"
[providers.marathon.tls]
cert = "path/to/foo.cert"
key = "path/to/foo.key"
```
2019-09-09 08:36:08 +00:00
```bash tab="CLI"
--providers.marathon.tls.cert=path/to/foo.cert
--providers.marathon.tls.key=path/to/foo.key
```
#### `key`
2019-09-09 08:36:08 +00:00
_Optional_
`key` is the path to the private key used for the secure connection to Marathon.
When using this option, setting the `cert` option is required.
2019-09-09 08:36:08 +00:00
2019-07-02 15:36:04 +00:00
```yaml tab="File (YAML)"
providers:
2019-09-09 08:36:08 +00:00
marathon:
2019-07-02 15:36:04 +00:00
tls:
2019-09-09 08:36:08 +00:00
cert: path/to/foo.cert
key: path/to/foo.key
2019-07-02 15:36:04 +00:00
```
```toml tab="File (TOML)"
[providers.marathon.tls]
cert = "path/to/foo.cert"
key = "path/to/foo.key"
```
2019-07-02 15:36:04 +00:00
```bash tab="CLI"
2019-09-09 08:36:08 +00:00
--providers.marathon.tls.cert=path/to/foo.cert
--providers.marathon.tls.key=path/to/foo.key
```
#### `insecureSkipVerify`
_Optional, Default=false_
2019-09-09 08:36:08 +00:00
2021-02-11 18:04:03 +00:00
If `insecureSkipVerify` is `true`, the TLS connection to Marathon accepts any certificate presented by the server regardless of the hostnames it covers.
2019-09-09 08:36:08 +00:00
```yaml tab="File (YAML)"
providers:
marathon:
tls:
insecureSkipVerify: true
```
```toml tab="File (TOML)"
[providers.marathon.tls]
insecureSkipVerify = true
```
2019-09-09 08:36:08 +00:00
```bash tab="CLI"
--providers.marathon.tls.insecureSkipVerify=true
```
2019-07-02 15:36:04 +00:00
### `tlsHandshakeTimeout`
_Optional, Default=5s_
2021-02-11 18:04:03 +00:00
Amount of time the Marathon provider should wait before timing out,
when waiting for the TLS handshake to complete.
The value of `tlsHandshakeTimeout` should be provided in seconds or as a valid duration format,
see [time.ParseDuration](https://golang.org/pkg/time/#ParseDuration).
2019-07-02 15:36:04 +00:00
```yaml tab="File (YAML)"
providers:
marathon:
tlsHandshakeTimeout: "10s"
2019-07-02 15:36:04 +00:00
# ...
```
```toml tab="File (TOML)"
[providers.marathon]
tlsHandshakeTimeout = "10s"
# ...
```
2019-07-02 15:36:04 +00:00
```bash tab="CLI"
--providers.marathon.tlsHandshakeTimeout=10s
2019-07-02 15:36:04 +00:00
# ...
```
### `trace`
_Optional, Default=false_
2021-02-11 18:04:03 +00:00
Displays additional provider logs when available.
2019-07-02 15:36:04 +00:00
```yaml tab="File (YAML)"
providers:
marathon:
trace: true
# ...
```
```toml tab="File (TOML)"
[providers.marathon]
trace = true
# ...
```
2019-07-02 15:36:04 +00:00
```bash tab="CLI"
--providers.marathon.trace=true
# ...
```
### `watch`
_Optional, Default=true_
2021-02-11 18:04:03 +00:00
When set to `true`, watches for Marathon changes.
2019-07-02 15:36:04 +00:00
```yaml tab="File (YAML)"
providers:
marathon:
watch: false
# ...
```
```toml tab="File (TOML)"
[providers.marathon]
watch = false
# ...
```
2019-07-02 15:36:04 +00:00
```bash tab="CLI"
--providers.marathon.watch=false
# ...
```