traefik/docs/content/providers/overview.md

231 lines
8.7 KiB
Markdown
Raw Normal View History

---
title: "Traefik Configuration Discovery Overview"
description: "Configuration discovery in Traefik is achieved through Providers. The providers are infrastructure components. Read the documentation to learn more."
---
# Overview
Traefik's Many Friends
{: .subtitle }
![Providers](../assets/img/providers.png)
Configuration discovery in Traefik is achieved through _Providers_.
2021-02-11 18:04:03 +00:00
The _providers_ are infrastructure components, whether orchestrators, container engines, cloud providers, or key-value stores.
The idea is that Traefik queries the provider APIs in order to find relevant information about routing,
and when Traefik detects a change, it dynamically updates the routes.
## Orchestrators
2021-02-11 18:04:03 +00:00
While each provider is different, you can think of each as belonging to one of four categories:
2021-02-11 18:04:03 +00:00
- Label-based: each deployed container has a set of labels attached to it
- Key-Value-based: each deployed container updates a key-value store with relevant information
- Annotation-based: a separate object, with annotations, defines the characteristics of the container
- File-based: uses files to define configuration
## Provider Namespace
2021-02-11 18:04:03 +00:00
When you declare certain objects in the Traefik dynamic configuration,
such as middleware, services, TLS options or server transports, they reside in their provider's namespace.
For example, if you declare a middleware using a Docker label, it resides in the Docker provider namespace.
2021-02-11 18:04:03 +00:00
If you use multiple providers and wish to reference such an object declared in another provider
(e.g. referencing a cross-provider object like middleware), then the object name should be suffixed by the `@`
separator, and the provider name.
For the list of the providers names, see the [supported providers](#supported-providers) table below.
```text
<resource-name>@<provider-name>
```
!!! important "Kubernetes Namespace"
As Kubernetes also has its own notion of namespace,
2021-02-11 18:04:03 +00:00
one should not confuse the _provider namespace_ with the _Kubernetes Namespace_ of a resource when in the context of cross-provider usage.
In this case, since the definition of a Traefik dynamic configuration object is not in Kubernetes,
specifying a Kubernetes Namespace when referring to the resource does not make any sense.
On the other hand, if you were to declare a middleware as a Custom Resource in Kubernetes and use the non-CRD Ingress objects,
you would have to add the Kubernetes Namespace of the middleware to the annotation like this `<middleware-namespace>-<middleware-name>@kubernetescrd`.
2021-02-11 18:04:03 +00:00
!!! abstract "Referencing a Traefik Dynamic Configuration Object from Another Provider"
Declaring the add-foo-prefix in the file provider.
```yaml tab="File (YAML)"
http:
middlewares:
add-foo-prefix:
addPrefix:
prefix: "/foo"
```
```toml tab="File (TOML)"
[http.middlewares]
[http.middlewares.add-foo-prefix.addPrefix]
prefix = "/foo"
```
Using the add-foo-prefix middleware from other providers:
2023-05-10 13:28:05 +00:00
```yaml tab="Docker & Swarm"
your-container: #
image: your-docker-image
labels:
# Attach add-foo-prefix@file middleware (declared in file)
- "traefik.http.routers.my-container.middlewares=add-foo-prefix@file"
```
```yaml tab="Kubernetes Ingress Route"
2023-03-20 14:38:08 +00:00
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
name: ingressroutestripprefix
spec:
entryPoints:
- web
routes:
- match: Host(`example.com`)
kind: Rule
services:
- name: whoami
port: 80
middlewares:
- name: add-foo-prefix@file
# namespace: bar
# A namespace specification such as above is ignored
# when the cross-provider syntax is used.
```
2021-02-11 18:04:03 +00:00
```yaml tab="Kubernetes Ingress"
2023-03-20 14:38:08 +00:00
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
name: stripprefix
namespace: appspace
spec:
stripPrefix:
prefixes:
- /stripit
2021-02-11 18:04:03 +00:00
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: ingress
namespace: appspace
annotations:
# referencing a middleware from Kubernetes CRD provider:
# <middleware-namespace>-<middleware-name>@kubernetescrd
"traefik.ingress.kubernetes.io/router.middlewares": appspace-stripprefix@kubernetescrd
spec:
# ... regular ingress definition
```
2021-02-11 18:04:03 +00:00
## Supported Providers
2021-02-11 18:04:03 +00:00
Below is the list of the currently supported providers in Traefik.
| Provider | Type | Configuration Type | Provider Name |
|---------------------------------------------------|--------------|----------------------|---------------------|
| [Docker](./docker.md) | Orchestrator | Label | `docker` |
| [Kubernetes IngressRoute](./kubernetes-crd.md) | Orchestrator | Custom Resource | `kubernetescrd` |
| [Kubernetes Ingress](./kubernetes-ingress.md) | Orchestrator | Ingress | `kubernetes` |
| [Kubernetes Gateway API](./kubernetes-gateway.md) | Orchestrator | Gateway API Resource | `kubernetesgateway` |
| [Consul Catalog](./consul-catalog.md) | Orchestrator | Label | `consulcatalog` |
| [Nomad](./nomad.md) | Orchestrator | Label | `nomad` |
| [ECS](./ecs.md) | Orchestrator | Label | `ecs` |
| [File](./file.md) | Manual | YAML/TOML format | `file` |
| [Consul](./consul.md) | KV | KV | `consul` |
| [Etcd](./etcd.md) | KV | KV | `etcd` |
| [ZooKeeper](./zookeeper.md) | KV | KV | `zookeeper` |
| [Redis](./redis.md) | KV | KV | `redis` |
| [HTTP](./http.md) | Manual | JSON format | `http` |
2019-09-23 12:32:04 +00:00
!!! info "More Providers"
The current version of Traefik does not yet support every provider that Traefik v2.11 did.
See the [previous version (v2.11)](https://doc.traefik.io/traefik/v2.11/) for more information.
2021-02-11 18:04:03 +00:00
### Configuration Reload Frequency
#### `providers.providersThrottleDuration`
_Optional, Default: 2s_
2019-09-30 16:24:05 +00:00
In some cases, some providers might undergo a sudden burst of changes,
which would generate a lot of configuration change events.
If Traefik took them all into account,
2021-02-11 18:04:03 +00:00
that would trigger a lot more configuration reloads than is necessary,
2019-09-30 16:24:05 +00:00
or even useful.
In order to mitigate that, the `providers.providersThrottleDuration` option can be set.
It is the duration that Traefik waits for, after a configuration reload,
before taking into account any new configuration refresh event.
2021-02-11 18:04:03 +00:00
If multiple events occur within this time, only the most recent one is taken into account,
and all others are discarded.
2019-09-30 16:24:05 +00:00
This option cannot be set per provider,
2021-02-11 18:04:03 +00:00
but the throttling algorithm applies to each of them independently.
The value of `providers.providersThrottleDuration` should be provided in seconds or as a valid duration format,
see [time.ParseDuration](https://golang.org/pkg/time/#ParseDuration).
2019-09-30 16:24:05 +00:00
```yaml tab="File (YAML)"
providers:
providersThrottleDuration: 10s
```
```toml tab="File (TOML)"
[providers]
providers.providersThrottleDuration = 10s
```
2019-09-30 16:24:05 +00:00
```bash tab="CLI"
--providers.providersThrottleDuration=10s
```
<!--
TODO (document TCP VS HTTP dynamic configuration)
-->
## Restrict the Scope of Service Discovery
2021-02-11 18:04:03 +00:00
By default, Traefik creates routes for all detected containers.
2021-02-11 18:04:03 +00:00
If you want to limit the scope of the Traefik service discovery,
i.e. disallow route creation for some containers,
you can do so in two different ways:
2021-02-11 18:04:03 +00:00
- the generic configuration option `exposedByDefault`,
- a finer granularity mechanism based on constraints.
### `exposedByDefault` and `traefik.enable`
2021-02-11 18:04:03 +00:00
List of providers that support these features:
- [Docker](./docker.md#exposedbydefault)
- [ECS](./ecs.md#exposedbydefault)
2019-10-16 08:36:04 +00:00
- [Consul Catalog](./consul-catalog.md#exposedbydefault)
- [Nomad](./nomad.md#exposedbydefault)
### Constraints
List of providers that support constraints:
- [Docker](./docker.md#constraints)
- [ECS](./ecs.md#constraints)
2019-10-16 08:36:04 +00:00
- [Consul Catalog](./consul-catalog.md#constraints)
- [Nomad](./nomad.md#constraints)
- [Kubernetes CRD](./kubernetes-crd.md#labelselector)
2019-09-23 12:32:04 +00:00
- [Kubernetes Ingress](./kubernetes-ingress.md#labelselector)
2021-02-11 18:04:03 +00:00
- [Kubernetes Gateway](./kubernetes-gateway.md#labelselector)
2022-09-09 15:17:53 +00:00
{!traefik-for-business-applications.md!}