2017-08-26 10:12:44 +00:00
# Rancher Backend
2017-09-11 17:10:04 +00:00
Træfik can be configured to use Rancher as a backend configuration.
## Global Configuration
2017-08-26 10:12:44 +00:00
```toml
################################################################
# Rancher configuration backend
################################################################
2017-09-11 17:10:04 +00:00
# Enable Rancher configuration backend.
2017-08-26 10:12:44 +00:00
[rancher]
# Default domain used.
# Can be overridden by setting the "traefik.domain" label on an service.
#
# Required
#
domain = "rancher.localhost"
2017-09-11 17:10:04 +00:00
# Enable watch Rancher changes.
2017-08-26 10:12:44 +00:00
#
# Optional
# Default: true
#
2017-09-05 13:58:03 +00:00
watch = true
2017-08-26 10:12:44 +00:00
2017-09-11 17:10:04 +00:00
# Polling interval (in seconds).
2017-08-26 10:12:44 +00:00
#
# Optional
2017-09-11 17:10:04 +00:00
# Default: 15
2017-08-26 10:12:44 +00:00
#
2017-09-05 13:58:03 +00:00
refreshSeconds = 15
2017-08-26 10:12:44 +00:00
2017-09-11 17:10:04 +00:00
# Expose Rancher services by default in Traefik.
2017-08-26 10:12:44 +00:00
#
# Optional
# Default: true
#
2017-09-05 13:58:03 +00:00
exposedByDefault = false
2017-08-26 10:12:44 +00:00
2017-09-11 17:10:04 +00:00
# Filter services with unhealthy states and inactive states.
2017-08-26 10:12:44 +00:00
#
# Optional
# Default: false
#
2017-09-05 13:58:03 +00:00
enableServiceHealthFilter = true
2018-03-26 13:32:04 +00:00
# Override default configuration template.
# For advanced users :)
#
# Optional
#
# filename = "rancher.tmpl"
# Override template version
# For advanced users :)
#
# Optional
# - "1": previous template version (must be used only with older custom templates, see "filename")
# - "2": current template version (must be used to force template version when "filename" is used)
#
2018-04-15 22:34:03 +00:00
# templateVersion = 2
2017-08-26 10:12:44 +00:00
```
2017-09-11 17:10:04 +00:00
To enable constraints see [backend-specific constraints section ](/configuration/commons/#backend-specific ).
2017-08-26 10:12:44 +00:00
## Rancher Metadata Service
```toml
# Enable Rancher metadata service configuration backend instead of the API
2017-09-11 17:10:04 +00:00
# configuration backend.
2017-08-26 10:12:44 +00:00
#
# Optional
# Default: false
#
[rancher.metadata]
2018-04-06 07:38:03 +00:00
# Poll the Rancher metadata service for changes every `rancher.refreshSeconds`.
2017-08-26 10:12:44 +00:00
# NOTE: this is less accurate than the default long polling technique which
# will provide near instantaneous updates to Traefik
#
# Optional
# Default: false
#
2017-09-05 13:58:03 +00:00
intervalPoll = true
2017-08-26 10:12:44 +00:00
2017-09-11 17:10:04 +00:00
# Prefix used for accessing the Rancher metadata service.
2017-08-26 10:12:44 +00:00
#
# Optional
# Default: "/latest"
#
2017-09-05 13:58:03 +00:00
prefix = "/2016-07-29"
2017-08-26 10:12:44 +00:00
```
## Rancher API
```toml
2017-09-11 17:10:04 +00:00
# Enable Rancher API configuration backend.
2017-08-26 10:12:44 +00:00
#
# Optional
# Default: true
#
[rancher.api]
2017-09-11 17:10:04 +00:00
# Endpoint to use when connecting to the Rancher API.
2017-08-26 10:12:44 +00:00
#
# Required
2017-09-05 13:58:03 +00:00
endpoint = "http://rancherserver.example.com/v1"
2017-08-26 10:12:44 +00:00
2017-09-11 17:10:04 +00:00
# AccessKey to use when connecting to the Rancher API.
2017-08-26 10:12:44 +00:00
#
# Required
2017-09-05 13:58:03 +00:00
accessKey = "XXXXXXXXXXXXXXXXXXXX"
2017-08-26 10:12:44 +00:00
2017-09-11 17:10:04 +00:00
# SecretKey to use when connecting to the Rancher API.
2017-08-26 10:12:44 +00:00
#
# Required
2017-09-05 13:58:03 +00:00
secretKey = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
2017-08-26 10:12:44 +00:00
```
2017-08-28 12:33:07 +00:00
!!! note
If Traefik needs access to the Rancher API, you need to set the `endpoint` , `accesskey` and `secretkey` parameters.
2017-09-07 10:02:03 +00:00
2017-09-11 17:10:04 +00:00
To enable Traefik to fetch information about the Environment it's deployed in only, you need to create an `Environment API Key` .
2017-08-28 12:33:07 +00:00
This can be found within the API Key advanced options.
2017-08-26 10:12:44 +00:00
2017-11-05 12:02:03 +00:00
Add these labels to traefik docker deployment to autogenerated these values:
```
io.rancher.container.agent.role: environment
io.rancher.container.create_agent: true
```
2018-03-26 13:32:04 +00:00
## Labels: overriding default behavior
### On Containers
2017-08-26 10:12:44 +00:00
2018-03-26 13:32:04 +00:00
Labels can be used on task containers to override default behavior:
2017-08-26 10:12:44 +00:00
2017-12-20 15:48:17 +00:00
| Label | Description |
|------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
2018-04-17 18:59:18 +00:00
| `traefik.domain` | Default domain used for frontend rules. |
2017-12-20 15:48:17 +00:00
| `traefik.enable=false` | Disable this container in Træfik |
| `traefik.port=80` | Register this port. Useful when the container exposes multiples ports. |
| `traefik.protocol=https` | Override the default `http` protocol |
| `traefik.weight=10` | Assign this weight to the container |
| `traefik.backend=foo` | Give the name `foo` to the generated backend for this container. |
2018-01-31 14:32:04 +00:00
| `traefik.backend.buffering.maxRequestBodyBytes=0` | See [buffering ](/configuration/commons/#buffering ) section. |
| `traefik.backend.buffering.maxResponseBodyBytes=0` | See [buffering ](/configuration/commons/#buffering ) section. |
| `traefik.backend.buffering.memRequestBodyBytes=0` | See [buffering ](/configuration/commons/#buffering ) section. |
| `traefik.backend.buffering.memResponseBodyBytes=0` | See [buffering ](/configuration/commons/#buffering ) section. |
| `traefik.backend.buffering.retryExpression=EXPR` | See [buffering ](/configuration/commons/#buffering ) section. |
2017-12-20 15:48:17 +00:00
| `traefik.backend.circuitbreaker.expression=EXPR` | Create a [circuit breaker ](/basics/#backends ) to be used against the backend |
| `traefik.backend.healthcheck.path=/health` | Enable health check for the backend, hitting the container at `path` . |
| `traefik.backend.healthcheck.port=8080` | Allow to use a different port for the health check. |
| `traefik.backend.healthcheck.interval=1s` | Define the health check interval. |
| `traefik.backend.loadbalancer.method=drr` | Override the default `wrr` load balancer algorithm |
| `traefik.backend.loadbalancer.stickiness=true` | Enable backend sticky sessions |
| `traefik.backend.loadbalancer.stickiness.cookieName=NAME` | Manually set the cookie name for sticky sessions |
| `traefik.backend.loadbalancer.sticky=true` | Enable backend sticky sessions (DEPRECATED) |
| `traefik.backend.maxconn.amount=10` | Set a maximum number of connections to the backend.< br > Must be used in conjunction with the below label to take effect. |
| `traefik.backend.maxconn.extractorfunc=client.ip` | Set the function to be used against the request to determine what to limit maximum connections to the backend by.< br > Must be used in conjunction with the above label to take effect. |
| `traefik.frontend.auth.basic=EXPR` | Sets basic authentication for that frontend in CSV format: `User:Hash,User:Hash` |
| `traefik.frontend.entryPoints=http,https` | Assign this frontend to entry points `http` and `https` .< br > Overrides `defaultEntryPoints` |
| `traefik.frontend.errors.<name>.backend=NAME` | See [custom error pages ](/configuration/commons/#custom-error-pages ) section. |
| `traefik.frontend.errors.<name>.query=PATH` | See [custom error pages ](/configuration/commons/#custom-error-pages ) section. |
| `traefik.frontend.errors.<name>.status=RANGE` | See [custom error pages ](/configuration/commons/#custom-error-pages ) section. |
| `traefik.frontend.passHostHeader=true` | Forward client `Host` header to the backend. |
| `traefik.frontend.passTLSCert=true` | Forward TLS Client certificates to the backend. |
| `traefik.frontend.priority=10` | Override default frontend priority |
2018-02-01 07:04:03 +00:00
| `traefik.frontend.rateLimit.extractorFunc=EXP` | See [rate limiting ](/configuration/commons/#rate-limiting ) section. |
| `traefik.frontend.rateLimit.rateSet.<name>.period=6` | See [rate limiting ](/configuration/commons/#rate-limiting ) section. |
| `traefik.frontend.rateLimit.rateSet.<name>.average=6` | See [rate limiting ](/configuration/commons/#rate-limiting ) section. |
| `traefik.frontend.rateLimit.rateSet.<name>.burst=6` | See [rate limiting ](/configuration/commons/#rate-limiting ) section. |
2017-12-20 15:48:17 +00:00
| `traefik.frontend.redirect.entryPoint=https` | Enables Redirect to another entryPoint for that frontend (e.g. HTTPS) |
| `traefik.frontend.redirect.regex=^http://localhost/(.*)` | Redirect to another URL for that frontend.< br > Must be set with `traefik.frontend.redirect.replacement` . |
| `traefik.frontend.redirect.replacement=http://mydomain/$1` | Redirect to another URL for that frontend.< br > Must be set with `traefik.frontend.redirect.regex` . |
2018-02-01 07:04:03 +00:00
| `traefik.frontend.redirect.permanent=true` | Return 301 instead of 302. |
2017-12-20 15:48:17 +00:00
| `traefik.frontend.rule=EXPR` | Override the default frontend rule. Default: `Host:{service_name}.{stack_name}.{domain}` . |
2018-03-23 16:40:04 +00:00
| `traefik.frontend.whiteList.sourceRange=RANGE` | List of IP-Ranges which are allowed to access.< br > An unset or empty list allows all Source-IPs to access.< br > If one of the Net-Specifications are invalid, the whole list is invalid and allows all Source-IPs to access. |
| `traefik.frontend.whiteList.useXForwardedFor=true` | Use `X-Forwarded-For` header as valid source of IP for the white list. |
2017-12-20 15:48:17 +00:00
2018-03-26 13:32:04 +00:00
#### Custom Headers
2018-02-16 15:04:05 +00:00
| Label | Description |
|-------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `traefik.frontend.headers.customRequestHeaders=EXPR ` | Provides the container with custom request headers that will be appended to each request forwarded to the container.< br > Format: < code > HEADER:value|| HEADER2:value2</ code > |
| `traefik.frontend.headers.customResponseHeaders=EXPR` | Appends the headers to each response returned by the container, before forwarding the response to the client.< br > Format: < code > HEADER:value|| HEADER2:value2</ code > |
2018-03-26 13:32:04 +00:00
#### Security Headers
2017-12-20 15:48:17 +00:00
| Label | Description |
|----------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `traefik.frontend.headers.allowedHosts=EXPR` | Provides a list of allowed hosts that requests will be processed.< br > Format: `Host1,Host2` |
2018-03-26 13:32:04 +00:00
| `traefik.frontend.headers.hostsProxyHeaders=EXPR` | Provides a list of headers that the proxied hostname may be stored.< br > Format: `HEADER1,HEADER2` |
2017-12-20 15:48:17 +00:00
| `traefik.frontend.headers.SSLRedirect=true` | Forces the frontend to redirect to SSL if a non-SSL request is sent. |
| `traefik.frontend.headers.SSLTemporaryRedirect=true` | Forces the frontend to redirect to SSL if a non-SSL request is sent, but by sending a 302 instead of a 301. |
| `traefik.frontend.headers.SSLHost=HOST` | This setting configures the hostname that redirects will be based on. Default is "", which is the same host as the request. |
| `traefik.frontend.headers.SSLProxyHeaders=EXPR` | Header combinations that would signify a proper SSL Request (Such as `X-Forwarded-For:https` ).< br > Format: < code > HEADER:value|| HEADER2:value2</ code > |
| `traefik.frontend.headers.STSSeconds=315360000` | Sets the max-age of the STS header. |
| `traefik.frontend.headers.STSIncludeSubdomains=true` | Adds the `IncludeSubdomains` section of the STS header. |
| `traefik.frontend.headers.STSPreload=true` | Adds the preload flag to the STS header. |
| `traefik.frontend.headers.forceSTSHeader=false` | Adds the STS header to non-SSL requests. |
| `traefik.frontend.headers.frameDeny=false` | Adds the `X-Frame-Options` header with the value of `DENY` . |
| `traefik.frontend.headers.customFrameOptionsValue=VALUE` | Overrides the `X-Frame-Options` header with the custom value. |
| `traefik.frontend.headers.contentTypeNosniff=true` | Adds the `X-Content-Type-Options` header with the value `nosniff` . |
| `traefik.frontend.headers.browserXSSFilter=true` | Adds the X-XSS-Protection header with the value `1; mode=block` . |
2018-03-02 13:24:03 +00:00
| `traefik.frontend.headers.customBrowserXSSValue=VALUE` | Set custom value for X-XSS-Protection header. This overrides the BrowserXssFilter option. |
2017-12-20 15:48:17 +00:00
| `traefik.frontend.headers.contentSecurityPolicy=VALUE` | Adds CSP Header with the custom value. |
| `traefik.frontend.headers.publicKey=VALUE` | Adds pinned HTST public key header. |
| `traefik.frontend.headers.referrerPolicy=VALUE` | Adds referrer policy header. |
| `traefik.frontend.headers.isDevelopment=false` | This will cause the `AllowedHosts` , `SSLRedirect` , and `STSSeconds` /`STSIncludeSubdomains` options to be ignored during development.< br > When deploying to production, be sure to set this to false. |
2018-03-26 13:32:04 +00:00
### On containers with Multiple Ports (segment labels)
Segment labels are used to define routes to a container exposing multiple ports.
A segment is a group of labels that apply to a port exposed by a container.
You can define as many segments as ports exposed in a container.
Segment labels override the default behavior.
| Label | Description |
|---------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------|
2018-04-17 18:59:18 +00:00
| `traefik.<segment_name>.domain` | Default domain used for frontend rules. |
2018-03-26 13:32:04 +00:00
| `traefik.<segment_name>.port=PORT` | Overrides `traefik.port` . If several ports need to be exposed, the segment labels could be used. |
| `traefik.<segment_name>.protocol` | Overrides `traefik.protocol` . |
| `traefik.<segment_name>.weight` | Assign this segment weight. Overrides `traefik.weight` . |
| `traefik.<segment_name>.frontend.auth.basic` | Sets a Basic Auth for that frontend |
| `traefik.<segment_name>.frontend.backend=BACKEND` | Assign this segment frontend to `BACKEND` . Default is to assign to the segment backend. |
| `traefik.<segment_name>.frontend.entryPoints` | Overrides `traefik.frontend.entrypoints` |
| `traefik.<segment_name>.frontend.errors.<name>.backend=NAME` | See [custom error pages ](/configuration/commons/#custom-error-pages ) section. |
| `traefik.<segment_name>.frontend.errors.<name>.query=PATH` | See [custom error pages ](/configuration/commons/#custom-error-pages ) section. |
| `traefik.<segment_name>.frontend.errors.<name>.status=RANGE` | See [custom error pages ](/configuration/commons/#custom-error-pages ) section. |
| `traefik.<segment_name>.frontend.passHostHeader` | Overrides `traefik.frontend.passHostHeader` . |
| `traefik.<segment_name>.frontend.passTLSCert` | Overrides `traefik.frontend.passTLSCert` . |
| `traefik.<segment_name>.frontend.priority` | Overrides `traefik.frontend.priority` . |
| `traefik.<segment_name>.frontend.rateLimit.extractorFunc=EXP` | See [rate limiting ](/configuration/commons/#rate-limiting ) section. |
| `traefik.<segment_name>.frontend.rateLimit.rateSet.<name>.period=6` | See [rate limiting ](/configuration/commons/#rate-limiting ) section. |
| `traefik.<segment_name>.frontend.rateLimit.rateSet.<name>.average=6` | See [rate limiting ](/configuration/commons/#rate-limiting ) section. |
| `traefik.<segment_name>.frontend.rateLimit.rateSet.<name>.burst=6` | See [rate limiting ](/configuration/commons/#rate-limiting ) section. |
| `traefik.<segment_name>.frontend.redirect.entryPoint=https` | Overrides `traefik.frontend.redirect.entryPoint` . |
| `traefik.<segment_name>.frontend.redirect.regex=^http://localhost/(.*)` | Overrides `traefik.frontend.redirect.regex` . |
| `traefik.<segment_name>.frontend.redirect.replacement=http://mydomain/$1` | Overrides `traefik.frontend.redirect.replacement` . |
| `traefik.<segment_name>.frontend.redirect.permanent=true` | Return 301 instead of 302. |
| `traefik.<segment_name>.frontend.rule` | Overrides `traefik.frontend.rule` . |
| `traefik.<segment_name>.frontend.whiteList.sourceRange=RANGE` | Overrides `traefik.frontend.whiteList.sourceRange` . |
| `traefik.<segment_name>.frontend.whiteList.useXForwardedFor=true` | Overrides `traefik.frontend.whiteList.useXForwardedFor` . |
#### Custom Headers
| Label | Description |
|----------------------------------------------------------------------|-----------------------------------------------------------------|
| `traefik.<segment_name>.frontend.headers.customRequestHeaders=EXPR ` | overrides `traefik.frontend.headers.customRequestHeaders=EXPR ` |
| `traefik.<segment_name>.frontend.headers.customResponseHeaders=EXPR` | overrides `traefik.frontend.headers.customResponseHeaders=EXPR` |
#### Security Headers
| Label | Description |
|-------------------------------------------------------------------------|--------------------------------------------------------------------|
| `traefik.<segment_name>.frontend.headers.allowedHosts=EXPR` | overrides `traefik.frontend.headers.allowedHosts=EXPR` |
| `traefik.<segment_name>.frontend.headers.hostsProxyHeaders=EXPR` | overrides `traefik.frontend.headers.hostsProxyHeaders=EXPR` |
| `traefik.<segment_name>.frontend.headers.SSLRedirect=true` | overrides `traefik.frontend.headers.SSLRedirect=true` |
| `traefik.<segment_name>.frontend.headers.SSLTemporaryRedirect=true` | overrides `traefik.frontend.headers.SSLTemporaryRedirect=true` |
| `traefik.<segment_name>.frontend.headers.SSLHost=HOST` | overrides `traefik.frontend.headers.SSLHost=HOST` |
| `traefik.<segment_name>.frontend.headers.SSLProxyHeaders=EXPR` | overrides `traefik.frontend.headers.SSLProxyHeaders=EXPR` |
| `traefik.<segment_name>.frontend.headers.STSSeconds=315360000` | overrides `traefik.frontend.headers.STSSeconds=315360000` |
| `traefik.<segment_name>.frontend.headers.STSIncludeSubdomains=true` | overrides `traefik.frontend.headers.STSIncludeSubdomains=true` |
| `traefik.<segment_name>.frontend.headers.STSPreload=true` | overrides `traefik.frontend.headers.STSPreload=true` |
| `traefik.<segment_name>.frontend.headers.forceSTSHeader=false` | overrides `traefik.frontend.headers.forceSTSHeader=false` |
| `traefik.<segment_name>.frontend.headers.frameDeny=false` | overrides `traefik.frontend.headers.frameDeny=false` |
| `traefik.<segment_name>.frontend.headers.customFrameOptionsValue=VALUE` | overrides `traefik.frontend.headers.customFrameOptionsValue=VALUE` |
| `traefik.<segment_name>.frontend.headers.contentTypeNosniff=true` | overrides `traefik.frontend.headers.contentTypeNosniff=true` |
| `traefik.<segment_name>.frontend.headers.browserXSSFilter=true` | overrides `traefik.frontend.headers.browserXSSFilter=true` |
| `traefik.<segment_name>.frontend.headers.customBrowserXSSValue=VALUE` | overrides `traefik.frontend.headers.customBrowserXSSValue=VALUE` |
| `traefik.<segment_name>.frontend.headers.contentSecurityPolicy=VALUE` | overrides `traefik.frontend.headers.contentSecurityPolicy=VALUE` |
| `traefik.<segment_name>.frontend.headers.publicKey=VALUE` | overrides `traefik.frontend.headers.publicKey=VALUE` |
| `traefik.<segment_name>.frontend.headers.referrerPolicy=VALUE` | overrides `traefik.frontend.headers.referrerPolicy=VALUE` |
| `traefik.<segment_name>.frontend.headers.isDevelopment=false` | overrides `traefik.frontend.headers.isDevelopment=false` |
