Improve documentation about Kubernetes IngressRoute

docs/content/https/tls.md

@@ -40,7 +40,7 @@ tls:
 
     In the above example, we've used the [file provider](../providers/file.md) to handle these definitions.
     It is the only available method to configure the certificates (as well as the options and the stores).
-    However, in [Kubernetes](../providers/kubernetes-crd.md), the certificates can and must be provided by [secrets](../routing/providers/kubernetes-crd.md#tls). 
+    However, in [Kubernetes](../providers/kubernetes-crd.md), the certificates can and must be provided by [secrets](https://kubernetes.io/docs/concepts/configuration/secret/). 
 
 ## Certificates Stores
 

docs/content/migration/v1-to-v2.md

@@ -104,7 +104,7 @@ Then any router can refer to an instance of the wanted middleware.
 
     ```yaml tab="K8s IngressRoute"
     # The definitions below require the definitions for the Middleware and IngressRoute kinds.
-    # https://docs.traefik.io/v2.0/providers/kubernetes-crd/#traefik-ingressroute-definition
+    # https://docs.traefik.io/v2.1/reference/dynamic-configuration/kubernetes-crd/#definitions
     apiVersion: traefik.containo.us/v1alpha1
     kind: Middleware
     metadata:
@@ -278,7 +278,7 @@ Then, a [router's TLS field](../routing/routers/index.md#tls) can refer to one o
 
     ```yaml tab="K8s IngressRoute"
     # The definitions below require the definitions for the TLSOption and IngressRoute kinds.
-    # https://docs.traefik.io/v2.0/providers/kubernetes-crd/#traefik-ingressroute-definition
+    # https://docs.traefik.io/v2.1/reference/dynamic-configuration/kubernetes-crd/#definitions
     apiVersion: traefik.containo.us/v1alpha1
     kind: TLSOption
     metadata:

docs/content/providers/docker.md

@@ -86,7 +86,7 @@ and [Docker Swarm Mode](https://docs.docker.com/engine/swarm/).
 ## Routing Configuration
 
 When using Docker as a [provider](https://docs.traefik.io/providers/overview/),
-Trafik uses [container labels](https://docs.docker.com/engine/reference/commandline/run/#set-metadata-on-container--l---label---label-file) to retrieve its routing configuration.
+Traefik uses [container labels](https://docs.docker.com/engine/reference/commandline/run/#set-metadata-on-container--l---label---label-file) to retrieve its routing configuration.
 
 See the list of labels in the dedicated [routing](../routing/providers/docker.md) section.
 

docs/content/providers/kubernetes-crd.md

@@ -8,9 +8,43 @@ Traefik used to support Kubernetes only through the [Kubernetes Ingress provider
 However, as the community expressed the need to benefit from Traefik features without resorting to (lots of) annotations,
 we ended up writing a [Custom Resource Definition](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/) (alias CRD in the following) for an IngressRoute type, defined below, in order to provide a better way to configure access to a Kubernetes cluster.
 
+## Configuration Requirements
+
+!!! tip "All Steps for a Successful Deployment"
+
+    * Add/update **all** the Traefik resources [definitions](../reference/dynamic-configuration/kubernetes-crd.md#definitions)
+    * Add/update the [RBAC](https://kubernetes.io/docs/reference/access-authn-authz/rbac/) for the Traefik custom resources
+    * Use [Helm Chart](../getting-started/install-traefik.md#use-the-helm-chart) or use a custom Traefik Deployment 
+        * Enable the kubernetesCRD provider
+        * Apply the needed kubernetesCRD provider [configuration](#provider-configuration)
+    * Add all needed traefik custom [resources](../reference/dynamic-configuration/kubernetes-crd.md#resources)
+ 
+??? example "Initializing Resource Definition and RBAC"
+
+    ```yaml tab="Traefik Resource Definition"
+    # All resources definition must be declared
+    --8<-- "content/reference/dynamic-configuration/kubernetes-crd-definition.yml"
+    ```
+
+    ```yaml tab="RBAC for Traefik CRD"
+    --8<-- "content/reference/dynamic-configuration/kubernetes-crd-rbac.yml"
+    ```
+
 ## Resource Configuration
 
-See the dedicated section in [routing](../routing/providers/kubernetes-crd.md).
+When using KubernetesCRD as a provider,
+Traefik uses [Custom Resource Definition](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/) to retrieve its routing configuration.
+Traefik Custom Resource Definitions are a Kubernetes implementation of the Traefik concepts. The main particularities are:
+
+* The usage of `name` **and** `namespace` to refer to another Kubernetes resource.
+* The usage of [secret](https://kubernetes.io/docs/concepts/configuration/secret/) for sensible data like:
+    * TLS certificate.
+    * Authentication data.
+* The structure of the configuration.
+* The obligation to declare all the [definitions](../reference/dynamic-configuration/kubernetes-crd.md#definitions).
+
+The Traefik CRD are building blocks which you can assemble according to your needs.
+See the list of CRDs in the dedicated [routing section](../routing/providers/kubernetes-crd.md).
 
 ## LetsEncrypt Support with the Custom Resource Definition Provider
 

docs/content/reference/dynamic-configuration/kubernetes-crd-definition.yml

@@ -0,0 +1,73 @@
+apiVersion: apiextensions.k8s.io/v1beta1
+kind: CustomResourceDefinition
+metadata:
+  name: ingressroutes.traefik.containo.us
+
+spec:
+  group: traefik.containo.us
+  version: v1alpha1
+  names:
+    kind: IngressRoute
+    plural: ingressroutes
+    singular: ingressroute
+  scope: Namespaced
+
+---
+apiVersion: apiextensions.k8s.io/v1beta1
+kind: CustomResourceDefinition
+metadata:
+  name: middlewares.traefik.containo.us
+
+spec:
+  group: traefik.containo.us
+  version: v1alpha1
+  names:
+    kind: Middleware
+    plural: middlewares
+    singular: middleware
+  scope: Namespaced
+
+---
+apiVersion: apiextensions.k8s.io/v1beta1
+kind: CustomResourceDefinition
+metadata:
+  name: ingressroutetcps.traefik.containo.us
+
+spec:
+  group: traefik.containo.us
+  version: v1alpha1
+  names:
+    kind: IngressRouteTCP
+    plural: ingressroutetcps
+    singular: ingressroutetcp
+  scope: Namespaced
+
+---
+apiVersion: apiextensions.k8s.io/v1beta1
+kind: CustomResourceDefinition
+metadata:
+  name: tlsoptions.traefik.containo.us
+
+spec:
+  group: traefik.containo.us
+  version: v1alpha1
+  names:
+    kind: TLSOption
+    plural: tlsoptions
+    singular: tlsoption
+  scope: Namespaced
+
+---
+apiVersion: apiextensions.k8s.io/v1beta1
+kind: CustomResourceDefinition
+metadata:
+  name: traefikservices.traefik.containo.us
+
+spec:
+  group: traefik.containo.us
+  version: v1alpha1
+  names:
+    kind: TraefikService
+    plural: traefikservices
+    singular: traefikservice
+  scope: Namespaced

docs/content/reference/dynamic-configuration/kubernetes-crd-ingressroutetcp-definition.yml

@@ -0,0 +1,13 @@
+apiVersion: apiextensions.k8s.io/v1beta1
+kind: CustomResourceDefinition
+metadata:
+  name: ingressroutetcps.traefik.containo.us
+
+spec:
+  group: traefik.containo.us
+  version: v1alpha1
+  names:
+    kind: IngressRouteTCP
+    plural: ingressroutetcps
+    singular: ingressroutetcp
+  scope: Namespaced

docs/content/reference/dynamic-configuration/kubernetes-crd-rbac.yml

@@ -0,0 +1,57 @@
+kind: ClusterRole
+apiVersion: rbac.authorization.k8s.io/v1beta1
+metadata:
+  name: traefik-ingress-controller
+
+rules:
+  - apiGroups:
+      - ""
+    resources:
+      - services
+      - endpoints
+      - secrets
+    verbs:
+      - get
+      - list
+      - watch
+  - apiGroups:
+      - extensions
+    resources:
+      - ingresses
+    verbs:
+      - get
+      - list
+      - watch
+  - apiGroups:
+      - extensions
+    resources:
+      - ingresses/status
+    verbs:
+      - update
+  - apiGroups:
+      - traefik.containo.us
+    resources:
+      - middlewares
+      - ingressroutes
+      - traefikservices
+      - ingressroutetcps
+      - tlsoptions
+    verbs:
+      - get
+      - list
+      - watch
+
+---
+kind: ClusterRoleBinding
+apiVersion: rbac.authorization.k8s.io/v1beta1
+metadata:
+  name: traefik-ingress-controller
+
+roleRef:
+  apiGroup: rbac.authorization.k8s.io
+  kind: ClusterRole
+  name: traefik-ingress-controller
+subjects:
+  - kind: ServiceAccount
+    name: traefik-ingress-controller
+    namespace: default

docs/content/reference/dynamic-configuration/kubernetes-crd-resource.yml

@@ -0,0 +1,157 @@
+apiVersion: traefik.containo.us/v1alpha1
+kind: TraefikService
+metadata:
+  name: wrr2
+  namespace: default
+
+spec:
+  weighted:
+    services:
+      - name: s1
+        weight: 1
+        port: 80
+        # Optional, as it is the default value
+        kind: Service
+      - name: s3
+        weight: 1
+        port: 80
+
+---
+apiVersion: traefik.containo.us/v1alpha1
+kind: TraefikService
+metadata:
+  name: wrr1
+  namespace: default
+
+spec:
+  weighted:
+    services:
+      - name: wrr2
+        kind: TraefikService
+        weight: 1
+      - name: s3
+        weight: 1
+        port: 80
+
+---
+apiVersion: traefik.containo.us/v1alpha1
+kind: TraefikService
+metadata:
+  name: mirror1
+  namespace: default
+
+spec:
+  mirroring:
+    name: s1
+    port: 80
+    mirrors:
+      - name: s3
+        percent: 20
+        port: 80
+      - name: mirror2
+        kind: TraefikService
+        percent: 20
+
+---
+apiVersion: traefik.containo.us/v1alpha1
+kind: TraefikService
+metadata:
+  name: mirror2
+  namespace: default
+
+spec:
+  mirroring:
+    name: wrr2
+    kind: TraefikService
+    mirrors:
+      - name: s2
+        # Optional, as it is the default value
+        kind: Service
+        percent: 20
+        port: 80
+
+---
+apiVersion: traefik.containo.us/v1alpha1
+kind: IngressRoute
+metadata:
+  name: ingressroute
+spec:
+  entryPoints:
+    - web
+    - web-secure
+  routes:
+    - match: Host(`foo.com`) && PathPrefix(`/bar`)
+      kind: Rule
+      priority: 12
+      # defining several services is possible and allowed, but for now the servers of
+      # all the services (for a given route) get merged altogether under the same
+      # load-balancing strategy.
+      services:
+        - name: s1
+          port: 80
+          healthCheck:
+            path: /health
+            host: baz.com
+            intervalSeconds: 7
+            timeoutSeconds: 60
+          # strategy defines the load balancing strategy between the servers. It defaults
+          # to Round Robin, and for now only Round Robin is supported anyway.
+          strategy: RoundRobin
+        - name: s2
+          port: 433
+          healthCheck:
+            path: /health
+            host: baz.com
+            intervalSeconds: 7
+            timeoutSeconds: 60
+    - match: PathPrefix(`/misc`)
+      services:
+        - name: s3
+          port: 80
+      middlewares:
+        - name: stripprefix
+        - name: addprefix
+    - match: PathPrefix(`/misc`)
+      services:
+        - name: s3
+          # Optional, as it is the default value
+          kind: Service
+          port: 8443
+          # scheme allow to override the scheme for the service. (ex: https or h2c)
+          scheme: https
+    - match: PathPrefix(`/lb`)
+      services:
+        - name: wrr1
+          kind: TraefikService
+    - match: PathPrefix(`/mirrored`)
+      services:
+        - name: mirror1
+          kind: TraefikService
+  # use an empty tls object for TLS with Let's Encrypt
+  tls:
+    secretName: supersecret
+    options:
+      name: myTLSOption
+      namespace: default
+
+---
+apiVersion: traefik.containo.us/v1alpha1
+kind: IngressRouteTCP
+metadata:
+  name: ingressroutetcp.crd
+  namespace: default
+
+spec:
+  entryPoints:
+    - footcp
+  routes:
+    - match: HostSNI(`bar.com`)
+      services:
+        - name: whoamitcp
+          port: 8080
+  tls:
+    secretName: foosecret
+    passthrough: false
+    options:
+      name: myTLSOption
+      namespace: default

docs/content/reference/dynamic-configuration/kubernetes-crd.md

@@ -3,6 +3,20 @@
 Dynamic configuration with Kubernetes Custom Resource
 {: .subtitle }
 
+## Definitions
+
 ```yaml
---8<-- "content/reference/dynamic-configuration/kubernetes-crd.yml"
+--8<-- "content/reference/dynamic-configuration/kubernetes-crd-definition.yml"
+```
+
+## Resources
+
+```yaml
+--8<-- "content/reference/dynamic-configuration/kubernetes-crd-resource.yml"
+```
+
+## RBAC
+
+```yaml
+--8<-- "content/reference/dynamic-configuration/kubernetes-crd-rbac.yml"
 ```