doc: kubernetes CRD provider

Co-authored-by: Jean-Baptiste Doumenjou <jb.doumenjou@gmail.com>

docs/content/middlewares/addprefix.md

@@ -26,6 +26,18 @@ The AddPrefix middleware updates the URL Path of the request before forwarding i
           - "traefik.http.middlewares.add-bar.addprefix.prefix=/bar"
     ```
 
+??? example "Kubernetes -- Prefixing with /bar"
+
+    ```yaml
+    apiVersion: traefik.containo.us/v1alpha1
+    kind: Middleware
+    metadata:
+      name: addprefix
+    spec:
+      addprefix:
+        prefix: /bar
+    ```
+
 ## Configuration Options
 
 ### prefix

docs/content/middlewares/overview.md

@@ -48,6 +48,45 @@ Pieces of middleware can be combined in chains to fit every scenario.
           - "traefik.http.middlewares.foo-add-prefix.addprefix.prefix=/foo",
     ```
 
+??? example "As a Kubernetes Traefik IngressRoute"
+
+    ```yaml
+    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: traefik.containo.us/v1alpha1
+    kind: Middleware
+    metadata:
+      name: stripprefix
+    spec:
+      stripprefix:
+        prefixes:
+          - /stripit
+
+    ---
+    apiVersion: traefik.containo.us/v1alpha1
+    kind: IngressRoute
+    metadata:
+      name: ingressroute.crd
+    spec:
+    # more fields...
+      routes:
+        # more fields...
+        middleware:
+        - name: stripprefix
+    ```
+
 ## Advanced Configuration
 
 When you declare a middleware, it lives in its `provider` namespace.

docs/content/providers/crd_ingress_route.yml

@@ -0,0 +1,13 @@
+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

docs/content/providers/crd_middlewares.yml

@@ -0,0 +1,13 @@
+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

docs/content/providers/kubernetes-crd.md

@@ -0,0 +1,122 @@
+# Traefik & Kubernetes
+
+The Kubernetes Ingress Controller, The Custom Resource Way.
+{: .subtitle }
+
+[comment]: # (Link "Kubernetes Ingress controller" to ./kubernetes-ingress.md)
+
+The Traefik Kubernetes provider used to be a Kubernetes Ingress controller in the strict sense of the term; that is to say,
+it would manage access to a cluster services by supporting the [Ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/) specification.
+
+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.
+
+## Traefik IngressRoute definition
+
+```yaml
+--8<-- "content/providers/crd_ingress_route.yml"
+```
+
+That `IngressRoute` kind can then be used to define an `IngressRoute` object, such as:
+
+```yaml
+apiVersion: traefik.containo.us/v1alpha1
+kind: IngressRoute
+metadata:
+  name: ingressroutefoo.crd
+
+spec:
+  entrypoints:
+    - web
+  routes:
+  # Match is the rule corresponding to an underlying router.
+  # Later on, match could be the simple form of a path prefix, e.g. just "/bar",
+  # but for now we only support a traefik style matching rule.
+  - match: Host(`foo.com`) && PathPrefix(`/bar`)
+    # kind could eventually be one of "Rule", "Path", "Host", "Method", "Header",
+    # "Parameter", etc, to support simpler forms of rule matching, but for now we
+    # only support "Rule".
+    kind: Rule
+    # Priority disambiguates rules of the same length, for route matching.
+    priority: 12
+    services:
+    - name: whoami
+      port: 80
+```
+
+## Middleware
+
+Additionally, to allow for the use of middlewares in an `IngressRoute`, we defined the CRD below for the `Middleware` kind.
+
+```yaml
+--8<-- "content/providers/crd_middlewares.yml"
+```
+
+Once the `Middleware` kind has been registered with the Kubernetes cluster, it can then be used in `IngressRoute` definitions, such as:
+
+```yaml
+apiVersion: traefik.containo.us/v1alpha1
+kind: Middleware
+metadata:
+  name: stripprefix
+
+spec:
+  stripprefix:
+    prefixes:
+      - /stripit
+
+---
+apiVersion: traefik.containo.us/v1alpha1
+kind: IngressRoute
+metadata:
+  name: ingressroutebar.crd
+
+spec:
+  entrypoints:
+    - web
+  routes:
+  - match: Host(`bar.com`) && PathPrefix(`/stripit`)
+    kind: Rule
+    services:
+    - name: whoami
+      port: 80
+    middlewares:
+    - name: stripprefix
+```
+
+## TLS
+
+To allow for TLS, we made use of the `Secret` kind, as it was already defined, and it can be directly used in an `IngressRoute`:
+
+```yaml
+apiVersion: v1
+kind: Secret
+metadata:
+  name: supersecret
+
+data:
+  tls.crt: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCi0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0=
+  tls.key: LS0tLS1CRUdJTiBQUklWQVRFIEtFWS0tLS0tCi0tLS0tRU5EIFBSSVZBVEUgS0VZLS0tLS0=
+
+---
+apiVersion: traefik.containo.us/v1alpha1
+kind: IngressRoute
+metadata:
+  name: ingressroutetls.crd
+
+spec:
+  entryPoints:
+    - web
+  routes:
+  - match: Host(`foo.com`) && PathPrefix(`/bar`)
+    kind: Rule
+    services:
+    - name: whoami
+      port: 443
+  tls:
+    secretName: supersecret
+```
+
+## Full reference example
+
+[Traefik IngressRoute Reference](../reference/providers/kubernetescrd.md).

docs/content/providers/kubernetes-ingress.md

@@ -0,0 +1,6 @@
+# Traefik & Kubernetes
+
+Kubernetes Ingress.
+{: .subtitle }
+
+TODO

docs/content/providers/overview.md

@@ -8,7 +8,8 @@ Traefik's Many Friends
 Configuration discovery in Traefik is achieved through _Providers_.
 
 The _providers_ are existing infrastructure components, whether orchestrators, container engines, cloud providers, or key-value stores. 
-The idea is that Traefik will query the providers' API in order to find relevant information about routing, and each time Traefik detects a change, it dynamically updates the routes.
+The idea is that Traefik will query the providers' API in order to find relevant information about routing,
+and each time Traefik detects a change, it dynamically updates the routes.
 
 Deploy and forget is Traefik's credo.
 
@@ -25,12 +26,12 @@ Even if each provider is different, we can categorize them in four groups:
 
 Below is the list of the currently supported providers in Traefik. 
 
-| Provider                    | Type         | Configuration Type |
+| Provider                        | Type         | Configuration Type |
-|-----------------------------|--------------|--------------------|
+|---------------------------------|--------------|--------------------|
-| [Docker](./docker.md)       | Orchestrator | Label              |
+| [Docker](./docker.md)           | Orchestrator | Label              |
-| [File](./file.md)           | Orchestrator | Custom Annotation  |
+| [File](./file.md)               | Orchestrator | Custom Annotation  |
-| Kubernetes (not documented) | Orchestrator | Custom Annotation  |
+| [Kubernetes](kubernetes-crd.md) | Orchestrator | Custom Resource    |
-| Marathon (not documented)   | Orchestrator | Label              |
+| Marathon (not yet documented)   | Orchestrator | Label              |
 
 !!! note "More Providers"
 
@@ -38,7 +39,8 @@ Below is the list of the currently supported providers in Traefik.
     
 ## Constraints Configuration
 
-If you want to limit the scope of Traefik service discovery, you can set constraints. Doing so, Traefik will create routes for containers that match these constraints only.
+If you want to limit the scope of Traefik service discovery, you can set constraints.
+Doing so, Traefik will create routes for containers that match these constraints only.
 
 ??? example "Containers with the api Tag"
 

docs/content/reference/providers/kubernetescrd.md

@@ -0,0 +1,81 @@
+# Kubernetes -- Reference
+
+## Kubernetes
+
+```yaml
+################################################################
+# Kubernetes Provider
+################################################################
+
+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: traefik.containo.us/v1alpha1
+kind: IngressRoute
+metadata:
+  name: ingressroute.crd
+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
+    middleware:
+    - name: stripprefix
+    - name: addprefix
+  tls:
+    secretName: supersecret
+```

docs/mkdocs.yml

@@ -66,9 +66,11 @@ markdown_extensions:
 
 # Page tree
 nav:
+  - '': 'providers/kubernetes-ingress.md'
   - '': 'reference/acme.md'
   - '': 'reference/providers/docker.md'
   - '': 'reference/providers/file.md'
+  - '': 'reference/providers/kubernetescrd.md'
   - '': 'reference/entrypoints.md'
   - 'Welcome': 'index.md'
   - 'Getting Started':
@@ -79,6 +81,7 @@ nav:
       - 'Overview': 'providers/overview.md'
       - 'Docker': 'providers/docker.md'
       - 'File': 'providers/file.md'
+      - 'Kubernetes IngressRoute': 'providers/kubernetes-crd.md'
   - 'Routing & Load Balancing':
       - 'Overview': 'routing/overview.md'
       - 'Entrypoints': 'routing/entrypoints.md'