diff --git a/docs/content/middlewares/overview.md b/docs/content/middlewares/overview.md index 557811d41..f2b44fd14 100644 --- a/docs/content/middlewares/overview.md +++ b/docs/content/middlewares/overview.md @@ -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. +!!! 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 ```yaml tab="Docker" @@ -128,106 +133,6 @@ http: - 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 -@ -``` - -!!! 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 `-@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: - # -@kubernetescrd - "traefik.ingress.kubernetes.io/router.middlewares": appspace-stripprefix@kubernetescrd - spec: - # ... regular ingress definition - ``` - ## Available Middlewares | Middleware | Purpose | Area | diff --git a/docs/content/providers/overview.md b/docs/content/providers/overview.md index a3b26b028..7aa1fa1e8 100644 --- a/docs/content/providers/overview.md +++ b/docs/content/providers/overview.md @@ -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) - 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 +@ +``` + +!!! 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 `-@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: + # -@kubernetescrd + "traefik.ingress.kubernetes.io/router.middlewares": appspace-stripprefix@kubernetescrd + spec: + # ... regular ingress definition + ``` + ## Supported Providers Below is the list of the currently supported providers in Traefik.