Traefik & Rancher

A Story of Labels, Services & Containers

Rancher

Attach labels to your services and let Traefik do the rest!

This provider is specific to Rancher 1.x.

Rancher 2.x requires Kubernetes and does not have a metadata endpoint of its own for Traefik to query.As such, Rancher 2.x users should utilize the Kubernetes provider directly.

Configuration Examples

Configuring Rancher & Deploying / Exposing Services

Enabling the rancher provider

  1. [providers.rancher]

  1. providers:
  2.   rancher: {}

  1. --providers.rancher=true

Attaching labels to services

  1. labels:
  2.   - traefik.http.services.my-service.rule=Host(`mydomain.com`)

Routing Configuration

See the dedicated section in routing.

Provider Configuration

Browse the Reference

If you're in a hurry, maybe you'd rather go through the configuration reference:

  1. # Enable Rancher Provider.
  2. [providers.rancher]
  4.   # Expose Rancher services by default in Traefik.
  5.   exposedByDefault = true
  7.   # Enable watch Rancher changes.
  8.   watch = true
  10.   # Filter services with unhealthy states and inactive states.
  11.   enableServiceHealthFilter = true
  13.   # Defines the polling interval (in seconds).
  14.   refreshSeconds = 15
  16.   # Poll the Rancher metadata service for changes every `rancher.refreshSeconds`, which is less accurate
  17.   intervalPoll = false
  19.   # Prefix used for accessing the Rancher metadata service
  20.   prefix = "/latest"

  1. # Enable Rancher Provider.
  2. providers:
  3.   rancher:
  5.   # Expose Rancher services by default in Traefik.
  6.   exposedByDefault: true
  8.   # Enable watch Rancher changes.
  9.   watch: true
  11.   # Filter services with unhealthy states and inactive states.
  12.   enableServiceHealthFilter: true
  14.   # Defines the polling interval (in seconds).
  15.   refreshSeconds: 15
  17.   # Poll the Rancher metadata service for changes every `rancher.refreshSeconds`, which is less accurate
  18.   intervalPoll: false
  20.   # Prefix used for accessing the Rancher metadata service
  21.   prefix: /latest

  1. # Enable Rancher Provider.
  2. --providers.rancher=true
  4. # Expose Rancher services by default in Traefik.
  5. --providers.rancher.exposedByDefault=true
  7. # Enable watch Rancher changes.
  8. --providers.rancher.watch=true
  10. # Filter services with unhealthy states and inactive states.
  11. --providers.rancher.enableServiceHealthFilter=true
  13. # Defines the polling interval (in seconds).
  14. --providers.rancher.refreshSeconds=15
  16. # Poll the Rancher metadata service for changes every `rancher.refreshSeconds`, which is less accurate
  17. --providers.rancher.intervalPoll=false
  19. # Prefix used for accessing the Rancher metadata service
  20. --providers.rancher.prefix=/latest

exposedByDefault

Optional, Default=true

  1. [providers.rancher]
  2.   exposedByDefault = false
  3.   # ...

  1. providers:
  2.   rancher:
  3.     exposedByDefault: false
  4.     # ...

  1. --providers.rancher.exposedByDefault=false
  2. # ...

Expose Rancher services by default in Traefik.If set to false, services that don't have a traefik.enable=true label will be ignored from the resulting routing configuration.

See also Restrict the Scope of Service Discovery.

defaultRule

Optional, Default=Host({{ normalize .Name }})

  1. [providers.rancher]
  2.   defaultRule = "Host(`{{ .Name }}.{{ index .Labels \"customLabel\"}}`)"
  3.   # ...

  1. providers:
  2.   rancher:
  3.     defaultRule: "Host(`{{ .Name }}.{{ index .Labels \"customLabel\"}}`)"
  4.     # ...

  1. --providers.rancher.defaultRule=Host(`{{ .Name }}.{{ index .Labels \"customLabel\"}}`)
  2. # ...

The default host rule for all services.

For a given container if no routing rule was defined by a label, it is defined by this defaultRule instead.It must be a valid Go template,augmented with the sprig template functions.The service name can be accessed as the Name identifier,and the template has access to all the labels defined on this container.

This option can be overridden on a container basis with the traefik.http.routers.Router1.rule label.

enableServiceHealthFilter

Optional, Default=true

  1. [providers.rancher]
  2.   enableServiceHealthFilter = false
  3.   # ...

  1. providers:
  2.   rancher:
  3.     enableServiceHealthFilter: false
  4.     # ...

  1. --providers.rancher.enableServiceHealthFilter=false
  2. # ...

Filter services with unhealthy states and inactive states.

refreshSeconds

Optional, Default=15

  1. [providers.rancher]
  2.   refreshSeconds = 30
  3.   # ...

  1. providers:
  2.   rancher:
  3.     refreshSeconds: 30
  4.     # ...

  1. --providers.rancher.refreshSeconds=30
  2. # ...

Defines the polling interval (in seconds).

intervalPoll

Optional, Default=false

  1. [providers.rancher]
  2.   intervalPoll = true
  3.   # ...

  1. providers:
  2.   rancher:
  3.     intervalPoll: true
  4.     # ...

  1. --providers.rancher.intervalPoll=true
  2. # ...

Poll the Rancher metadata service for changes every rancher.refreshSeconds,which is less accurate than the default long polling technique which will provide near instantaneous updates to Traefik.

prefix

Optional, Default=/latest

  1. [providers.rancher]
  2.   prefix = "/test"
  3.   # ...

  1. providers:
  2.   rancher:
  3.     prefix: "/test"
  4.     # ...

  1. --providers.rancher.prefix=/test
  2. # ...

Prefix used for accessing the Rancher metadata service

constraints

Optional, Default=""

  1. [providers.rancher]
  2.   constraints = "Label(`a.label.name`,`foo`)"
  3.   # ...

  1. providers:
  2.   rancher:
  3.     constraints: "Label(`a.label.name`,`foo`)"
  4.     # ...

  1. --providers.rancher.constraints=Label(`a.label.name`,`foo`)
  2. # ...

Constraints is an expression that Traefik matches against the container's labels to determine whether to create any route for that container.That is to say, if none of the container's labels match the expression, no route for the 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.

Constraints Expression Examples

  1. # Includes only containers having a label with key `a.label.name` and value `foo`
  2. constraints = "Label(`a.label.name`, `foo`)"
  1. # Excludes containers having any label with key `a.label.name` and value `foo`
  2. constraints = "!Label(`a.label.name`, `value`)"
  1. # With logical AND.
  2. constraints = "Label(`a.label.name`, `valueA`) && Label(`another.label.name`, `valueB`)"
  1. # With logical OR.
  2. constraints = "Label(`a.label.name`, `valueA`) || Label(`another.label.name`, `valueB`)"
  1. # With logical AND and OR, with precedence set by parentheses.
  2. constraints = "Label(`a.label.name`, `valueA`) && (Label(`another.label.name`, `valueB`) || Label(`yet.another.label.name`, `valueC`))"
  1. # Includes only containers having a label with key `a.label.name` and a value matching the `a.+` regular expression.
  2. constraints = "LabelRegex(`a.label.name`, `a.+`)"

See also Restrict the Scope of Service Discovery.