From 2683df7b5b412dcec0abaaf090ee6ceb886bb044 Mon Sep 17 00:00:00 2001 From: Romain Date: Tue, 20 Oct 2020 14:16:04 +0200 Subject: [PATCH] Fix ingress documentation --- docs/content/routing/entrypoints.md | 26 +- .../routing/providers/kubernetes-ingress.md | 417 ++++++++++++++++-- 2 files changed, 405 insertions(+), 38 deletions(-) diff --git a/docs/content/routing/entrypoints.md b/docs/content/routing/entrypoints.md index dc6d97d55..444b2f57a 100644 --- a/docs/content/routing/entrypoints.md +++ b/docs/content/routing/entrypoints.md @@ -212,8 +212,8 @@ If both TCP and UDP are wanted for the same port, two entryPoints definitions ar ``` ```bash tab="CLI" - entrypoints.specificIPv4.address=192.168.2.7:8888 - entrypoints.specificIPv6.address=[2001:db8::1]:8888 + --entrypoints.specificIPv4.address=192.168.2.7:8888 + --entrypoints.specificIPv6.address=[2001:db8::1]:8888 ``` Full details for how to specify `address` can be found in [net.Listen](https://golang.org/pkg/net/#Listen) (and [net.Dial](https://golang.org/pkg/net/#Dial)) of the doc for go. @@ -745,8 +745,8 @@ entryPoints: ``` ```bash tab="CLI" -entrypoints.websecure.address=:443 -entrypoints.websecure.http.middlewares=auth@file,strip@file +--entrypoints.websecure.address=:443 +--entrypoints.websecure.http.middlewares=auth@file,strip@file ``` ### TLS @@ -792,13 +792,13 @@ entryPoints: ``` ```bash tab="CLI" -entrypoints.websecure.address=:443 -entrypoints.websecure.http.tls.options=foobar -entrypoints.websecure.http.tls.certResolver=leresolver -entrypoints.websecure.http.tls.domains[0].main=example.com -entrypoints.websecure.http.tls.domains[0].sans=foo.example.com,bar.example.com -entrypoints.websecure.http.tls.domains[1].main=test.com -entrypoints.websecure.http.tls.domains[1].sans=foo.test.com,bar.test.com +--entrypoints.websecure.address=:443 +--entrypoints.websecure.http.tls.options=foobar +--entrypoints.websecure.http.tls.certResolver=leresolver +--entrypoints.websecure.http.tls.domains[0].main=example.com +--entrypoints.websecure.http.tls.domains[0].sans=foo.example.com,bar.example.com +--entrypoints.websecure.http.tls.domains[1].main=test.com +--entrypoints.websecure.http.tls.domains[1].sans=foo.test.com,bar.test.com ``` ??? example "Let's Encrypt" @@ -821,6 +821,6 @@ entrypoints.websecure.http.tls.domains[1].sans=foo.test.com,bar.test.com ``` ```bash tab="CLI" - entrypoints.websecure.address=:443 - entrypoints.websecure.http.tls.certResolver=leresolver + --entrypoints.websecure.address=:443 + --entrypoints.websecure.http.tls.certResolver=leresolver ``` diff --git a/docs/content/routing/providers/kubernetes-ingress.md b/docs/content/routing/providers/kubernetes-ingress.md index d4b982198..8b79402f8 100644 --- a/docs/content/routing/providers/kubernetes-ingress.md +++ b/docs/content/routing/providers/kubernetes-ingress.md @@ -114,16 +114,11 @@ which in turn will create the resulting routers, services, handlers, etc. - name: traefik image: traefik:v2.3 args: - - --log.level=DEBUG - - --api - - --api.insecure - --entrypoints.web.address=:80 - --providers.kubernetesingress ports: - name: web containerPort: 80 - - name: admin - containerPort: 8080 --- apiVersion: v1 @@ -139,10 +134,6 @@ which in turn will create the resulting routers, services, handlers, etc. port: 80 name: web targetPort: 80 - - protocol: TCP - port: 8080 - name: admin - targetPort: 8080 ``` ```yaml tab="Whoami" @@ -340,27 +331,379 @@ Please see [this documentation](https://kubernetes.io/docs/concepts/services-net ## TLS -### Communication Between Traefik and Pods +### Enabling TLS via HTTP Options on Entrypoint -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. +TLS can be enabled through the [HTTP options](../entrypoints.md#tls) of an Entrypoint: -There are 3 ways to configure Traefik to use https to communicate with pods: +```bash tab="CLI" +# Static configuration +--entrypoints.websecure.address=:443 +--entrypoints.websecure.http.tls +``` -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`. +```toml tab="File (TOML)" +# Static configuration +[entryPoints.websecure] + address = ":443" -If either of those configuration options exist, then the backend communication protocol is assumed to be TLS, -and will connect via TLS automatically. + [entryPoints.websecure.http.tls] +``` -!!! info +```yaml tab="File (YAML)" +# Static configuration +entryPoints: + websecure: + address: ':443' + http: + tls: {} +``` + +This way, any Ingress attached to this Entrypoint will have TLS termination by default. + +??? example "Configuring Kubernetes Ingress Controller with TLS on Entrypoint" - 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. + ```yaml tab="RBAC" + --- + 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 + - networking.k8s.io + resources: + - ingresses + - ingressclasses + verbs: + - get + - list + - watch + - apiGroups: + - extensions + resources: + - ingresses/status + verbs: + - update + + --- + 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 + ``` + + ```yaml tab="Ingress" + kind: Ingress + apiVersion: networking.k8s.io/v1beta1 + metadata: + name: myingress + annotations: + traefik.ingress.kubernetes.io/router.entrypoints: websecure + + spec: + rules: + - host: example.com + http: + paths: + - path: /bar + backend: + serviceName: whoami + servicePort: 80 + - path: /foo + backend: + serviceName: whoami + servicePort: 80 + ``` + + ```yaml tab="Traefik" + apiVersion: v1 + kind: ServiceAccount + metadata: + name: traefik-ingress-controller + + --- + kind: Deployment + apiVersion: apps/v1 + metadata: + name: traefik + labels: + app: traefik + + spec: + replicas: 1 + selector: + matchLabels: + app: traefik + template: + metadata: + labels: + app: traefik + spec: + serviceAccountName: traefik-ingress-controller + containers: + - name: traefik + image: traefik:v2.3 + args: + - --entrypoints.websecure.address=:443 + - --entrypoints.websecure.http.tls + - --providers.kubernetesingress + ports: + - name: websecure + containerPort: 443 + + --- + apiVersion: v1 + kind: Service + metadata: + name: traefik + spec: + type: LoadBalancer + selector: + app: traefik + ports: + - protocol: TCP + port: 443 + name: websecure + targetPort: 443 + ``` + + ```yaml tab="Whoami" + kind: Deployment + apiVersion: apps/v1 + metadata: + name: whoami + labels: + app: traefiklabs + name: whoami + + spec: + replicas: 2 + selector: + matchLabels: + app: traefiklabs + task: whoami + template: + metadata: + labels: + app: traefiklabs + task: whoami + spec: + containers: + - name: whoami + image: traefik/whoami + ports: + - containerPort: 80 + + --- + apiVersion: v1 + kind: Service + metadata: + name: whoami + + spec: + ports: + - name: http + port: 80 + selector: + app: traefiklabs + task: whoami + ``` + +### Enabling TLS via Annotations + +To enable TLS on the underlying router created from an Ingress, one should configure it through annotations: +```yaml +traefik.ingress.kubernetes.io/router.tls: "true" +``` + +For more options, please refer to the available [annotations](#on-ingress). + +??? example "Configuring Kubernetes Ingress Controller with TLS" + + ```yaml tab="RBAC" + --- + 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 + - networking.k8s.io + resources: + - ingresses + - ingressclasses + verbs: + - get + - list + - watch + - apiGroups: + - extensions + resources: + - ingresses/status + verbs: + - update + + --- + 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 + ``` + + ```yaml tab="Ingress" + kind: Ingress + apiVersion: networking.k8s.io/v1beta1 + metadata: + name: myingress + annotations: + traefik.ingress.kubernetes.io/router.entrypoints: websecure + traefik.ingress.kubernetes.io/router.tls: true + + spec: + rules: + - host: example.com + http: + paths: + - path: /bar + backend: + serviceName: whoami + servicePort: 80 + - path: /foo + backend: + serviceName: whoami + servicePort: 80 + ``` + + ```yaml tab="Traefik" + apiVersion: v1 + kind: ServiceAccount + metadata: + name: traefik-ingress-controller + + --- + kind: Deployment + apiVersion: apps/v1 + metadata: + name: traefik + labels: + app: traefik + + spec: + replicas: 1 + selector: + matchLabels: + app: traefik + template: + metadata: + labels: + app: traefik + spec: + serviceAccountName: traefik-ingress-controller + containers: + - name: traefik + image: traefik:v2.3 + args: + - --entrypoints.websecure.address=:443 + - --providers.kubernetesingress + ports: + - name: websecure + containerPort: 443 + + --- + apiVersion: v1 + kind: Service + metadata: + name: traefik + spec: + type: LoadBalancer + selector: + app: traefik + ports: + - protocol: TCP + port: 443 + name: websecure + targetPort: 443 + ``` + + ```yaml tab="Whoami" + kind: Deployment + apiVersion: apps/v1 + metadata: + name: whoami + labels: + app: traefiklabs + name: whoami + + spec: + replicas: 2 + selector: + matchLabels: + app: traefiklabs + task: whoami + template: + metadata: + labels: + app: traefiklabs + task: whoami + spec: + containers: + - name: whoami + image: traefik/whoami + ports: + - containerPort: 80 + + --- + apiVersion: v1 + kind: Service + metadata: + name: whoami + + spec: + ports: + - name: http + port: 80 + selector: + app: traefiklabs + task: whoami + ``` ### Certificates Management @@ -382,7 +725,9 @@ and will connect via TLS automatically. backend: serviceName: service1 servicePort: 80 - + # Only selects which certificate(s) should be loaded from the secret, in order to terminate TLS. + # Doesn't enable TLS for that ingress (hence for the underlying router). + # Please see the TLS annotations on ingress made for that purpose. tls: - secretName: supersecret ``` @@ -405,6 +750,28 @@ TLS certificates can be managed in Secrets objects. 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. +### 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. + ## Global Default Backend Ingresses Ingresses can be created that look like the following: