Moving Provider Namespace documentation topic to Configuration Discovery section

This commit is contained in:
Andrew Savinykh 2020-10-16 01:54:04 +13:00 committed by GitHub
parent b80f89e3db
commit b1ba42410b
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
2 changed files with 105 additions and 100 deletions

View file

@ -11,6 +11,11 @@ There are several available middleware in Traefik, some can modify the request,
Pieces of middleware can be combined in chains to fit every scenario. Pieces of middleware can be combined in chains to fit every scenario.
!!! warning "Provider Namespace"
Be aware of the concept of Providers Namespace described in the [Configuration Discovery](../providers/overview.md#provider-namespace) section.
It also applies to Middlewares.
## Configuration Example ## Configuration Example
```yaml tab="Docker" ```yaml tab="Docker"
@ -128,106 +133,6 @@ http:
- url: "http://127.0.0.1:80" - url: "http://127.0.0.1:80"
``` ```
## Provider Namespace
When you declare a middleware, it lives in its provider's namespace.
For example, if you declare a middleware using a Docker label, under the hoods, it will reside in the docker provider namespace.
If you use multiple providers and wish to reference a middleware declared in another provider
(aka referencing a cross-provider middleware),
then you'll have to append to the middleware name, the `@` separator, followed by the provider name.
```text
<resource-name>@<provider-name>
```
!!! important "Kubernetes Namespace"
As Kubernetes also has its own notion of namespace, one should not confuse the "provider namespace"
with the "kubernetes namespace" of a resource when in the context of a cross-provider usage.
In this case, since the definition of the middleware is not in kubernetes,
specifying a "kubernetes namespace" when referring to the resource does not make any sense,
and therefore this specification would be ignored even if present.
On the other hand, if you declare the middleware as a Custom Resource in Kubernetes and use the
non-crd Ingress objects, you'll have to add the kubernetes namespace of the middleware to the
annotation like this `<middleware-namespace>-<middleware-name>@kubernetescrd`.
!!! abstract "Referencing a Middleware from Another Provider"
Declaring the add-foo-prefix in the file provider.
```toml tab="File (TOML)"
[http.middlewares]
[http.middlewares.add-foo-prefix.addPrefix]
prefix = "/foo"
```
```yaml tab="File (YAML)"
http:
middlewares:
add-foo-prefix:
addPrefix:
prefix: "/foo"
```
Using the add-foo-prefix middleware from other providers:
```yaml tab="Docker"
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"
apiVersion: traefik.containo.us/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.
```
```yaml tab="Kubernetes Ingress"
apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
name: stripprefix
namespace: appspace
spec:
stripPrefix:
prefixes:
- /stripit
---
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
```
## Available Middlewares ## Available Middlewares
| Middleware | Purpose | Area | | Middleware | Purpose | Area |

View file

@ -22,6 +22,106 @@ Even if each provider is different, we can categorize them in four groups:
- Annotation based (a separate object, with annotations, defines the characteristics of the container) - Annotation based (a separate object, with annotations, defines the characteristics of the container)
- File based (the good old configuration file) - File based (the good old configuration file)
## Provider Namespace
When you declare certain objects, in Traefik dynamic configuration,
such as middleware, service, TLS options or servers transport, they live in its provider's namespace.
For example, if you declare a middleware using a Docker label, under the hoods, it will reside in the docker provider namespace.
If you use multiple providers and wish to reference such an object declared in another provider
(aka referencing a cross-provider object, e.g. middleware), then you'll have to append the `@` separator,
followed by the provider name to the object name.
```text
<resource-name>@<provider-name>
```
!!! important "Kubernetes Namespace"
As Kubernetes also has its own notion of namespace,
one should not confuse the "provider namespace" with the "kubernetes namespace" of a resource when in the context of a 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,
and therefore this specification would be ignored even if present.
On the other hand, if you, say, declare a middleware as a Custom Resource in Kubernetes and use the non-crd Ingress objects,
you'll have to add the Kubernetes namespace of the middleware to the annotation like this `<middleware-namespace>-<middleware-name>@kubernetescrd`.
!!! abstract "Referencing a Traedik dynamic configuration object from Another Provider"
Declaring the add-foo-prefix in the file provider.
```toml tab="File (TOML)"
[http.middlewares]
[http.middlewares.add-foo-prefix.addPrefix]
prefix = "/foo"
```
```yaml tab="File (YAML)"
http:
middlewares:
add-foo-prefix:
addPrefix:
prefix: "/foo"
```
Using the add-foo-prefix middleware from other providers:
```yaml tab="Docker"
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"
apiVersion: traefik.containo.us/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.
```
```yaml tab="Kubernetes Ingress"
apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
name: stripprefix
namespace: appspace
spec:
stripPrefix:
prefixes:
- /stripit
---
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
```
## Supported Providers ## Supported Providers
Below is the list of the currently supported providers in Traefik. Below is the list of the currently supported providers in Traefik.