From 62c03b33185e982c162df207f5168a29e08f25b4 Mon Sep 17 00:00:00 2001 From: Ludovic Fernandez Date: Wed, 17 Apr 2019 11:48:05 +0200 Subject: [PATCH] k8s static configuration explanation --- docs/content/providers/kubernetes-crd.md | 136 +++++++++++++++++++-- docs/content/user-guides/crd-acme/index.md | 14 +-- 2 files changed, 136 insertions(+), 14 deletions(-) diff --git a/docs/content/providers/kubernetes-crd.md b/docs/content/providers/kubernetes-crd.md index 881f68f93..b1e9400b1 100644 --- a/docs/content/providers/kubernetes-crd.md +++ b/docs/content/providers/kubernetes-crd.md @@ -13,7 +13,133 @@ it would manage access to a cluster services by supporting the [Ingress](https:/ 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 +## Provider Configuration + +### `endpoint` + +_Optional, Default=empty_ + +The Kubernetes server endpoint as URL. + +When deployed into Kubernetes, Traefik will read the environment variables `KUBERNETES_SERVICE_HOST` and `KUBERNETES_SERVICE_PORT` or `KUBECONFIG` to construct the endpoint. + +The access token will be looked up in `/var/run/secrets/kubernetes.io/serviceaccount/token` and the SSL CA certificate in `/var/run/secrets/kubernetes.io/serviceaccount/ca.crt`. +Both are provided mounted automatically when deployed inside Kubernetes. + +The endpoint may be specified to override the environment variable values inside a cluster. + +When the environment variables are not found, Traefik will try to connect to the Kubernetes API server with an external-cluster client. +In this case, the endpoint is required. +Specifically, it may be set to the URL used by `kubectl proxy` to connect to a Kubernetes cluster using the granted authentication and authorization of the associated kubeconfig. + +```toml tab="File" +[Providers.KubernetesCRD] + endpoint = "http://localhost:8080" + # ... +``` + +```txt tab="CLI" +--providers.kubernetescrd +--providers.kubernetescrd.endpoint="http://localhost:8080" +``` + +### `token` + +_Optional, Default=empty_ + +Bearer token used for the Kubernetes client configuration. + +```toml tab="File" +[Providers.KubernetesCRD] + token = "mytoken" + # ... +``` + +```txt tab="CLI" +--providers.kubernetescrd +--providers.kubernetescrd.token="mytoken" +``` + +### `certAuthFilePath` + +_Optional, Default=empty_ + +Path to the certificate authority file. +Used for the Kubernetes client configuration. + +```toml tab="File" +[Providers.KubernetesCRD] + certAuthFilePath = "/my/ca.crt" + # ... +``` + +```txt tab="CLI" +--providers.kubernetescrd +--providers.kubernetescrd.certauthfilepath="/my/ca.crt" +``` + +### `namespaces` + +_Optional, Default: all namespaces (empty array)_ + +Array of namespaces to watch. + +```toml tab="File" +[Providers.KubernetesCRD] + namespaces = ["default", "production"] + # ... +``` + +```txt tab="CLI" +--providers.kubernetescrd +--providers.kubernetescrd.namespaces="default,production" +``` + +### `labelselector` + +_Optional,Default: empty (process all Ingresses)_ + +By default, Traefik processes all Ingress objects in the configured namespaces. +A label selector can be defined to filter on specific Ingress objects only. + +See [label-selectors](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#label-selectors) for details. + +```toml tab="File" +[Providers.KubernetesCRD] + labelselector = "A and not B" + # ... +``` + +```txt tab="CLI" +--providers.kubernetescrd +--providers.kubernetescrd.labelselector="A and not B" +``` + +### `ingressClass` + +_Optional, Default: empty_ + +Value of `kubernetes.io/ingress.class` annotation that identifies Ingress objects to be processed. + +If the parameter is non-empty, only Ingresses containing an annotation with the same value are processed. +Otherwise, Ingresses missing the annotation, having an empty value, or the value `traefik` are processed. + +```toml tab="File" +[Providers.KubernetesCRD] + ingressClass = "traefik-internal" + # ... +``` + +```txt tab="CLI" +--providers.kubernetescrd +--providers.kubernetescrd.ingressclass="traefik-internal" +``` + +## Resource Configuration + +If you're in a hurry, maybe you'd rather go through the [dynamic](../reference/dynamic-configuration/kubernetes-crd.md) configuration reference. + +### Traefik IngressRoute definition ```yaml --8<-- "content/providers/crd_ingress_route.yml" @@ -46,7 +172,7 @@ spec: port: 80 ``` -## Middleware +### Middleware Additionally, to allow for the use of middlewares in an `IngressRoute`, we defined the CRD below for the `Middleware` kind. @@ -86,7 +212,7 @@ spec: - name: stripprefix ``` -## TLS +### 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`: @@ -119,10 +245,6 @@ spec: secretName: supersecret ``` -## Full reference example - -If you're in a hurry, maybe you'd rather go through the [static](../reference/static-configuration.md) and the [dynamic](../reference/dynamic-configuration/kubernetes-crd.md) configuration references. - ## Further Also see the [full example](../user-guides/crd-acme/index.md) with Let's Encrypt. diff --git a/docs/content/user-guides/crd-acme/index.md b/docs/content/user-guides/crd-acme/index.md index 84c8db503..2956678b9 100644 --- a/docs/content/user-guides/crd-acme/index.md +++ b/docs/content/user-guides/crd-acme/index.md @@ -16,7 +16,7 @@ In the following, the Kubernetes resources defined in YAML configuration files c - the first, and usual way, is simply with the `kubectl apply` command. - the second, which can be used for this tutorial, is to directly place the files in the directory used by the k3s docker image for such inputs (`/var/lib/rancher/k3s/server/manifests`). -## k3s Docker-compose Configuration ## +## k3s Docker-compose Configuration Our starting point is the docker-compose configuration file, to start the k3s cluster. You can start it with: @@ -29,11 +29,11 @@ docker-compose -f k3s.yml up --8<-- "content/user-guides/crd-acme/k3s.yml" ``` -## Cluster Resources ## +## Cluster Resources Let's now have a look (in the order they should be applied, if using `kubectl apply`) at all the required resources for the full setup. -### IngressRoute Definition ### +### IngressRoute Definition First, the definition of the `IngressRoute` and the `Middleware` kinds. Also note the RBAC authorization resources; they'll be referenced through the `serviceAccountName` of the deployment, later on. @@ -42,7 +42,7 @@ Also note the RBAC authorization resources; they'll be referenced through the `s --8<-- "content/user-guides/crd-acme/01-crd.yml" ``` -### Services ### +### Services Then, the services. One for Traefik itself, and one for the app it routes for, i.e. in this case our demo HTTP server: [whoami](https://github.com/containous/whoami). @@ -50,7 +50,7 @@ Then, the services. One for Traefik itself, and one for the app it routes for, i --8<-- "content/user-guides/crd-acme/02-services.yml" ``` -### Deployments ### +### Deployments Next, the deployments, i.e. the actual pods behind the services. Again, one pod for Traefik, and one for the whoami app. @@ -59,7 +59,7 @@ Again, one pod for Traefik, and one for the whoami app. --8<-- "content/user-guides/crd-acme/03-deployments.yml" ``` -### Port Forwarding ### +### Port Forwarding Now, as an exception to what we said above, please note that you should not let the ingressRoute resources below be applied automatically to your cluster. The reason is, as soon as the ACME provider of Traefik detects we have TLS routers, it will try to generate the certificates for the corresponding domains. @@ -74,7 +74,7 @@ Also, and this is out of the scope if this guide, please note that because of th In which case you can use tricks such as elevating caps of `kubectl` with `setcaps`, or using `authbind`, or setting up a NAT between your host and the WAN. Look it up. -### Traefik Routers ### +### Traefik Routers We can now finally apply the actual ingressRoutes, with: