Add Ingress annotations support

Co-authored-by: jbdoumenjou <jb.doumenjou@gmail.com>
2020-01-14 15:48:06 +01:00 · 2020-01-14 15:48:06 +01:00 · 6b7be462b8
commit 6b7be462b8
parent 4f52691f71
11 changed files with 1086 additions and 296 deletions
--- a/docs/content/providers/kubernetes-ingress.md
+++ b/docs/content/providers/kubernetes-ingress.md
@ -6,7 +6,11 @@ The Kubernetes Ingress Controller.
 The Traefik Kubernetes Ingress provider is a Kubernetes Ingress controller; that is to say,
 it manages access to a cluster services by supporting the [Ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/) specification.

-## Enabling and using the provider
+## Routing Configuration
+
+See the dedicated section in [routing](../routing/providers/kubernetes-ingress.md).
+
+## Enabling and Using the Provider

 As usual, the provider is enabled through the static configuration:

@ -23,43 +27,9 @@ providers:
 --providers.kubernetesingress=true
 ```

-The provider then watches for incoming ingresses events, such as the example below, and derives the corresponding dynamic configuration from it, which in turn will create the resulting routers, services, handlers, etc.
-
-```yaml tab="File (YAML)"
-kind: Ingress
-apiVersion: extensions/v1beta1
-metadata:
-  name: "foo"
-  namespace: production
-
-spec:
-  rules:
-    - host: foo.com
-      http:
-        paths:
-          - path: /bar
-            backend:
-              serviceName: service1
-              servicePort: 80
-          - path: /foo
-            backend:
-              serviceName: service1
-              servicePort: 80
-```
-
-## LetsEncrypt Support with the Ingress Provider
-
-By design, Traefik is a stateless application, meaning that it only derives its configuration from the environment it runs in, without additional configuration.
-For this reason, users can run multiple instances of Traefik at the same time to achieve HA, as is a common pattern in the kubernetes ecosystem.
-
-When using a single instance of Traefik with LetsEncrypt, no issues should be encountered, however this could be a single point of failure.
-Unfortunately, it is not possible to run multiple instances of Traefik 2.0 with LetsEncrypt enabled, because there is no way to ensure that the correct instance of Traefik will receive the challenge request, and subsequent responses.
-Previous versions of Traefik used a [KV store](https://docs.traefik.io/v1.7/configuration/acme/#storage) to attempt to achieve this, but due to sub-optimal performance was dropped as a feature in 2.0.
-
-If you require LetsEncrypt with HA in a kubernetes environment, we recommend using [TraefikEE](https://containo.us/traefikee/) where distributed LetsEncrypt is a supported feature.
-
-If you are wanting to continue to run Traefik Community Edition, LetsEncrypt HA can be achieved by using a Certificate Controller such as [Cert-Manager](https://docs.cert-manager.io/en/latest/index.html).
-When using Cert-Manager to manage certificates, it will create secrets in your namespaces that can be referenced as TLS secrets in your [ingress objects](https://kubernetes.io/docs/concepts/services-networking/ingress/#tls).
+The provider then watches for incoming ingresses events, such as the example below,
+and derives the corresponding dynamic configuration from it,
+which in turn will create the resulting routers, services, handlers, etc.

 ## Provider Configuration

@ -337,6 +307,20 @@ providers:
 --providers.kubernetesingress.throttleDuration=10s
 ```

-## Further
+### Further

 If one wants to know more about the various aspects of the Ingress spec that Traefik supports, many examples of Ingresses definitions are located in the tests [data](https://github.com/containous/traefik/tree/v2.0/pkg/provider/kubernetes/ingress/fixtures) of the Traefik repository.
+
+## LetsEncrypt Support with the Ingress Provider
+
+By design, Traefik is a stateless application, meaning that it only derives its configuration from the environment it runs in, without additional configuration.
+For this reason, users can run multiple instances of Traefik at the same time to achieve HA, as is a common pattern in the kubernetes ecosystem.
+
+When using a single instance of Traefik with LetsEncrypt, no issues should be encountered, however this could be a single point of failure.
+Unfortunately, it is not possible to run multiple instances of Traefik 2.0 with LetsEncrypt enabled, because there is no way to ensure that the correct instance of Traefik will receive the challenge request, and subsequent responses.
+Previous versions of Traefik used a [KV store](https://docs.traefik.io/v1.7/configuration/acme/#storage) to attempt to achieve this, but due to sub-optimal performance was dropped as a feature in 2.0.
+
+If you require LetsEncrypt with HA in a kubernetes environment, we recommend using [TraefikEE](https://containo.us/traefikee/) where distributed LetsEncrypt is a supported feature.
+
+If you are wanting to continue to run Traefik Community Edition, LetsEncrypt HA can be achieved by using a Certificate Controller such as [Cert-Manager](https://docs.cert-manager.io/en/latest/index.html).
+When using Cert-Manager to manage certificates, it will create secrets in your namespaces that can be referenced as TLS secrets in your [ingress objects](https://kubernetes.io/docs/concepts/services-networking/ingress/#tls).
--- a/docs/content/routing/providers/kubernetes-ingress.md
+++ b/docs/content/routing/providers/kubernetes-ingress.md
@ -0,0 +1,298 @@
+# Traefik & Kubernetes
+
+The Kubernetes Ingress Controller.
+{: .subtitle }
+
+## Routing Configuration
+
+The provider then watches for incoming ingresses events, such as the example below,
+and derives the corresponding dynamic configuration from it,
+which in turn will create the resulting routers, services, handlers, etc.
+
+```yaml
+kind: Ingress
+apiVersion: extensions/v1beta1
+metadata:
+  name: foo
+  namespace: production
+
+spec:
+  rules:
+  - host: foo.com
+    http:
+      paths:
+      - path: /bar
+        backend:
+          serviceName: service1
+          servicePort: 80
+      - path: /foo
+        backend:
+          serviceName: service1
+          servicePort: 80
+
+  tls:
+  - secretName: mySecret
+```
+
+### Annotations
+
+??? example
+    
+    ```yaml tab="Ingress"
+    kind: Ingress
+    apiVersion: extensions/v1beta1
+    metadata:
+      name: foo
+      namespace: production
+      annotations:
+        traefik.ingress.kubernetes.io/router.entrypoints: web
+    
+    spec:
+      rules:
+      - host: foo.com
+        http:
+          paths:
+          - path: /bar
+            backend:
+              serviceName: service1
+              servicePort: 80
+          - path: /foo
+            backend:
+              serviceName: service1
+              servicePort: 80
+    ```
+    
+    ```yaml tab="Service"
+    kind: Service
+    apiVersion: v1
+    metadata:
+      name: service1
+      namespace: testing
+      annotations:
+        traefik.ingress.kubernetes.io/service.passhostheader: "false"
+    
+    spec:
+      ports:
+      - port: 80
+      clusterIp: 10.0.0.1
+    ```
+
+#### On Ingress
+
+??? info "`traefik.ingress.kubernetes.io/router.entrypoints`"
+
+    See [entry points](../routers/index.md#entrypoints) for more information.
+
+    ```yaml
+    traefik.ingress.kubernetes.io/router.entrypoints: ep1,ep2
+    ```
+
+??? info "`traefik.ingress.kubernetes.io/router.middlewares`"
+
+    See [middlewares](../routers/index.md#middlewares) and [middlewares overview](../../middlewares/overview.md) for more information.
+
+    ```yaml
+    traefik.ingress.kubernetes.io/router.middlewares: auth@file,prefix@kuberntes-crd,cb@file
+    ```
+
+??? info "`traefik.ingress.kubernetes.io/router.priority`"
+
+    See [priority](../routers/index.md#priority) for more information.
+
+    ```yaml
+    traefik.ingress.kubernetes.io/router.priority: "42"
+    ```
+
+??? info "`traefik.ingress.kubernetes.io/router.pathmatcher`"
+
+    Overrides the default router rule type used for a path.  
+    Only path-related matcher name can be specified: `Path`, `PathPrefix`.
+    
+    Default `PathPrefix`
+
+    ```yaml
+    traefik.ingress.kubernetes.io/router.pathmatcher: Path
+    ```
+
+??? info "`traefik.ingress.kubernetes.io/router.tls`"
+
+    See [tls](../routers/index.md#tls) for more information.
+
+    ```yaml
+    traefik.ingress.kubernetes.io/router.tls: "true"
+    ```
+
+??? info "`traefik.ingress.kubernetes.io/router.tls.certresolver`"
+
+    See [certResolver](../routers/index.md#certresolver) for more information.
+
+    ```yaml
+    traefik.ingress.kubernetes.io/router.tls.certresolver: myresolver
+    ```
+
+??? info "`traefik.ingress.kubernetes.io/router.tls.domains.n.main`"
+
+    See [domains](../routers/index.md#domains) for more information.
+
+    ```yaml
+    traefik.ingress.kubernetes.io/router.tls.domains.0.main: foobar.com
+    ```
+
+??? info "`traefik.ingress.kubernetes.io/router.tls.domains.n.sans`"
+
+    See [domains](../routers/index.md#domains) for more information.
+
+    ```yaml
+    traefik.ingress.kubernetes.io/router.tls.domains.0.sans: test.foobar.com,dev.foobar.com
+    ```
+
+??? info "`traefik.ingress.kubernetes.io/router.tls.options`"
+
+    See [options](../routers/index.md#options) for more information.
+
+    ```yaml
+    traefik.ingress.kubernetes.io/router.tls.options: foobar
+    ```
+
+#### On Service
+
+??? info "`traefik.ingress.kubernetes.io/service.serversscheme`"
+
+    Overrides the default scheme.
+
+    ```yaml
+    traefik.ingress.kubernetes.io/service.serversscheme: h2c
+    ```
+
+??? info "`traefik.ingress.kubernetes.io/service.passhostheader`"
+
+    See [pass Host header](../services/index.md#pass-host-header) for more information.
+
+    ```yaml
+    traefik.ingress.kubernetes.io/service.passhostheader: "true"
+    ```
+
+??? info "`traefik.ingress.kubernetes.io/service.sticky`"
+
+    See [sticky sessions](../services/index.md#sticky-sessions) for more information.
+
+    ```yaml
+    traefik.ingress.kubernetes.io/service.sticky: "true"
+    ```
+
+??? info "`traefik.ingress.kubernetes.io/service.sticky.cookie.httponly`"
+
+    See [sticky sessions](../services/index.md#sticky-sessions) for more information.
+
+    ```yaml
+    traefik.ingress.kubernetes.io/service.sticky.cookie.httponly: "true"
+    ```
+
+??? info "`traefik.ingress.kubernetes.io/service.sticky.cookie.name`"
+
+    See [sticky sessions](../services/index.md#sticky-sessions) for more information.
+
+    ```yaml
+    traefik.ingress.kubernetes.io/service.sticky.cookie.name: foobar
+    ```
+
+??? info "`traefik.ingress.kubernetes.io/service.sticky.cookie.secure`"
+
+    See [sticky sessions](../services/index.md#sticky-sessions) for more information.
+
+    ```yaml
+    traefik.ingress.kubernetes.io/service.sticky.cookie.secure: "true"
+    ```
+
+### TLS
+
+#### Communication Between Traefik and Pods
+
+Traefik automatically requests endpoint information based on the service provided in the ingress spec.
+Although Traefik will connect directly to the endpoints (pods),
+it still checks the service port to see if TLS communication is required.
+
+There are 3 ways to configure Traefik to use https to communicate with pods:
+
+1. If the service port defined in the ingress spec is `443` (note that you can still use `targetPort` to use a different port on your pod).
+1. If the service port defined in the ingress spec has a name that starts with https (such as `https-api`, `https-web` or just `https`).
+1. If the ingress spec includes the annotation `traefik.ingress.kubernetes.io/service.serversscheme: https`.
+
+If either of those configuration options exist, then the backend communication protocol is assumed to be TLS,
+and will connect via TLS automatically.
+
+!!! info
+    
+    Please note that by enabling TLS communication between traefik and your pods,
+    you will have to have trusted certificates that have the proper trust chain and IP subject name.
+    If this is not an option, you may need to skip TLS certificate verification.
+    See the [insecureSkipVerify](../../routing/overview.md#insecureskipverify) setting for more details.
+
+#### Certificates Management
+
+??? example "Using a secret"
+    
+    ```yaml tab="Ingress"
+    kind: Ingress
+    apiVersion: extensions/v1beta1
+    metadata:
+      name: foo
+      namespace: production
+    
+    spec:
+      rules:
+      - host: foo.com
+        http:
+          paths:
+          - path: /bar
+            backend:
+              serviceName: service1
+              servicePort: 80
+    
+      tls:
+      - secretName: supersecret
+    ```
+      
+    ```yaml tab="Secret"
+    apiVersion: v1
+    kind: Secret
+    metadata:
+      name: supersecret
+    
+    data:
+      tls.crt: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCi0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0=
+      tls.key: LS0tLS1CRUdJTiBQUklWQVRFIEtFWS0tLS0tCi0tLS0tRU5EIFBSSVZBVEUgS0VZLS0tLS0=
+    ```
+
+TLS certificates can be managed in Secrets objects.
+
+!!! info
+    
+    Only TLS certificates provided by users can be stored in Kubernetes Secrets.
+    [Let's Encrypt](../../https/acme.md) certificates cannot be managed in Kubernetes Secrets yet.
+
+## Global Default Backend Ingresses
+
+Ingresses can be created that look like the following:
+
+```yaml
+apiVersion: extensions/v1beta1
+kind: Ingress
+metadata:
+ name: cheese
+
+spec:
+ backend:
+   serviceName: stilton
+   servicePort: 80
+```
+
+This ingress follows the Global Default Backend property of ingresses.
+This will allow users to create a "default router" that will match all unmatched requests.
+
+!!! info
+    
+    Due to Traefik's use of priorities, you may have to set this ingress priority lower than other ingresses in your environment,
+    to avoid this global ingress from satisfying requests that could match other ingresses.
+    
+    To do this, use the `traefik.ingress.kubernetes.io/router.priority` annotation (as seen in [Annotations on Ingress](#on-ingress)) on your ingresses accordingly.