From 40d2421db9305a7b4154894e218ff37f18f291c0 Mon Sep 17 00:00:00 2001 From: Maxence Moutoussamy Date: Tue, 9 Aug 2022 16:06:09 +0200 Subject: [PATCH] Add getting started guide for Kubernetes --- .../quick-start-with-kubernetes.md | 317 ++++++++++++++++++ docs/mkdocs.yml | 4 +- 2 files changed, 320 insertions(+), 1 deletion(-) create mode 100644 docs/content/getting-started/quick-start-with-kubernetes.md diff --git a/docs/content/getting-started/quick-start-with-kubernetes.md b/docs/content/getting-started/quick-start-with-kubernetes.md new file mode 100644 index 000000000..80e39ef09 --- /dev/null +++ b/docs/content/getting-started/quick-start-with-kubernetes.md @@ -0,0 +1,317 @@ +--- +title: "Traefik Getting Started With Kubernetes" +description: "Looking to get started with Traefik Proxy? Read the technical documentation to learn a simple use case that leverages Kubernetes." +--- + +# Quick Start + +A Simple Use Case of Traefik Proxy and Kubernetes +{: .subtitle } + +This guide is an introduction to using Traefik Proxy in a Kubernetes environment. +The objective is to learn how to run an application behind a Traefik reverse proxy in Kubernetes. +It presents and explains the basic blocks required to start with Traefik such as Ingress Controller, Ingresses, Deployments, static, and dynamic configuration. + +## Permissions and Accesses + +Traefik uses the Kubernetes API to discover running services. + +In order to use the Kubernetes API, Traefik needs some permissions. +This [permission mechanism](https://kubernetes.io/docs/reference/access-authn-authz/rbac/) is based on roles defined by the cluster administrator. +The role is then bound to an account used by an application, in this case, Traefik Proxy. + +The first step is to create the role. +The [`ClusterRole`](https://kubernetes.io/docs/reference/kubernetes-api/authorization-resources/cluster-role-v1/#ClusterRole) resource enumerates the resources and actions available for the role. +In a file called `00-role.yml`, put the following `ClusterRole`: + +```yaml tab="00-role.yml" +kind: ClusterRole +apiVersion: rbac.authorization.k8s.io/v1 +metadata: + name: traefik-role + +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 +``` + +!!! info "You can find the reference for this file [there](../../reference/dynamic-configuration/kubernetes-crd/#rbac)." + +The next step is to create a dedicated service account for Traefik. +In a file called `00-account.yml`, put the following [`ServiceAccount`](https://kubernetes.io/docs/reference/kubernetes-api/authentication-resources/service-account-v1/#ServiceAccount) resource: + +```yaml tab="00-account.yml" +apiVersion: v1 +kind: ServiceAccount +metadata: + name: traefik-account +``` + +And then, bind the role on the account to apply the permissions and rules on the latter. In a file called `01-role-binding.yml`, put the +following [`ClusterRoleBinding`](https://kubernetes.io/docs/reference/kubernetes-api/authorization-resources/cluster-role-binding-v1/#ClusterRoleBinding) resource: + +```yaml tab="01-role-binding.yml" +kind: ClusterRoleBinding +apiVersion: rbac.authorization.k8s.io/v1 +metadata: + name: traefik-role-binding + +roleRef: + apiGroup: rbac.authorization.k8s.io + kind: ClusterRole + name: traefik-role +subjects: + - kind: ServiceAccount + name: traefik-account + namespace: default # Using "default" because we did not specify a namespace when creating the ClusterAccount. +``` + +!!! info "`roleRef` is the Kubernetes reference to the role created in `00-role.yml`." + +!!! info "`subjects` is the list of accounts reference." + + In this guide, it only contains the account created in `00-account.yml` + +## Deployment and Exposition + +!!! info "This section can be managed with the help of the [Traefik Helm chart](../install-traefik/#use-the-helm-chart)." + +The [ingress controller](https://traefik.io/glossary/kubernetes-ingress-and-ingress-controller-101/#what-is-a-kubernetes-ingress-controller) +is a software that runs in the same way as any other application on a cluster. +To start Traefik on the Kubernetes cluster, +a [`Deployment`](https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/deployment-v1/) resource must exist to describe how to configure +and scale containers horizontally to support larger workloads. + +Start by creating a file called `02-traefik.yml` and paste the following `Deployment` resource: + +```yaml tab="02-traefik.yml" +kind: Deployment +apiVersion: apps/v1 +metadata: + name: traefik-deployment + labels: + app: traefik + +spec: + replicas: 1 + selector: + matchLabels: + app: traefik + template: + metadata: + labels: + app: traefik + spec: + serviceAccountName: traefik-account + containers: + - name: traefik + image: traefik:v2.8 + args: + - --api.insecure + - --providers.kubernetesingress + ports: + - name: web + containerPort: 80 + - name: dashboard + containerPort: 8080 +``` + +The deployment contains an important attribute for customizing Traefik: `args`. +These arguments are the static configuration for Traefik. +From here, it is possible to enable the dashboard, +configure entry points, +select dynamic configuration providers, +and [more](../reference/static-configuration/cli.md)... + +In this deployment, +the static configuration enables the Traefik dashboard, +and uses Kubernetes native Ingress resources as router definitions to route incoming requests. + +!!! info "When there is no entry point in the static configuration" + + Traefik creates a default one called `web` using the port `80` routing HTTP requests. + +!!! info "When enabling the [`api.insecure`](../../operations/api/#insecure) mode, Traefik exposes the dashboard on the port `8080`." + +A deployment manages scaling and then can create lots of containers, called [Pods](https://kubernetes.io/docs/concepts/workloads/pods/). +Each Pod is configured following the `spec` field in the deployment. +Given that, a Deployment can run multiple Traefik Proxy Pods, +a piece is required to forward the traffic to any of the instance: +namely a [`Service`](https://kubernetes.io/docs/reference/kubernetes-api/service-resources/service-v1/#Service). +Create a file called `02-traefik-services.yml` and insert the two `Service` resources: + +```yaml tab="02-traefik-services.yml" +apiVersion: v1 +kind: Service +metadata: + name: traefik-dashboard-service + +spec: + type: LoadBalancer + ports: + - port: 8080 + targetPort: dashboard + selector: + app: traefik +--- +apiVersion: v1 +kind: Service +metadata: + name: traefik-web-service + +spec: + type: LoadBalancer + ports: + - targetPort: web + port: 80 + selector: + app: traefik +``` + +!!! warning "It is possible to expose a service in different ways." + + Depending on your working environment and use case, the `spec.type` might change. + It is strongly recommended to understand the available [service types](https://kubernetes.io/docs/concepts/services-networking/service/#publishing-services-service-types) before proceeding to the next step. + +It is now time to apply those files on your cluster to start Traefik. + +```shell +kubectl apply -f 00-role.yml \ + -f 00-account.yml \ + -f 01-role-binding.yml \ + -f 02-traefik.yml \ + -f 02-traefik-services.yml +``` + +## Proxying applications + +The only part still missing is the business application behind the reverse proxy. +For this guide, we use the example application [traefik/whoami](https://github.com/traefik/whoami), +but the principles are applicable to any other application. + +The `whoami` application is a simple HTTP server running on port 80 which answers host-related information to the incoming requests. +As usual, start by creating a file called `03-whoami.yml` and paste the following `Deployment` resource: + +```yaml tab="03-whoami.yml" +kind: Deployment +apiVersion: apps/v1 +metadata: + name: whoami + labels: + app: whoami + +spec: + replicas: 1 + selector: + matchLabels: + app: whoami + template: + metadata: + labels: + app: whoami + spec: + containers: + - name: whoami + image: traefik/whoami + ports: + - name: web + containerPort: 80 +``` + +And continue by creating the following `Service` resource in a file called `03-whoami-services.yml`: + +```yaml tab="03-whoami-services.yml" +apiVersion: v1 +kind: Service +metadata: + name: whoami + +spec: + ports: + - name: web + port: 80 + targetPort: web + + selector: + app: whoami +``` + +Thanks to the Kubernetes API, +Traefik is notified when an Ingress resource is created, updated, or deleted. +This makes the process dynamic. +The ingresses are, in a way, the [dynamic configuration](../../providers/kubernetes-ingress/) for Traefik. + +!!! tip + + Find more information on [ingress controller](https://kubernetes.io/docs/concepts/services-networking/ingress-controllers/), + and [Ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/) in the official Kubernetes documentation. + +Create a file called `04-whoami-ingress.yml` and insert the `Ingress` resource: + +```yaml tab="04-whoami-ingress.yml" +apiVersion: networking.k8s.io/v1 +kind: Ingress +metadata: + name: whoami-ingress +spec: + rules: + - http: + paths: + - path: / + pathType: Prefix + backend: + service: + name: whoami + port: + name: web +``` + +This `Ingress` configures Traefik to redirect any incoming requests starting with `/` to the `whoami:80` service. + +At this point, all the configurations are ready. +It is time to apply those new files: + +```shell +kubectl apply -f 03-whoami.yml \ + -f 03-whoami-services.yml \ + -f 04-whoami-ingress.yml +``` + +Now you should be able to access the `whoami` application and the Traefik dashboard. +Load the dashboard on a web browser: [`http://localhost:8080`](http://localhost:8080). + +And now access the `whoami` application: + +```shell +curl -v http://localhost/ +``` + +!!! question "Going further" + + - [Filter the ingresses](../providers/kubernetes-ingress.md#ingressclass) to use with [IngressClass](https://kubernetes.io/docs/concepts/services-networking/ingress/#ingress-class) + - Use [IngressRoute CRD](../providers/kubernetes-crd.md) + - Protect [ingresses with TLS](../routing/providers/kubernetes-ingress.md#enabling-tls-via-annotations) diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 36240c18b..03a3f7f5e 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -66,7 +66,9 @@ nav: - 'Welcome': 'index.md' - 'Getting Started': - 'Concepts' : 'getting-started/concepts.md' - - 'Quick Start': 'getting-started/quick-start.md' + - 'Quick Start': + - 'Docker': 'getting-started/quick-start.md' + - 'Kubernetes': 'getting-started/quick-start-with-kubernetes.md' - 'Configuration Introduction': 'getting-started/configuration-overview.md' - 'Install Traefik': 'getting-started/install-traefik.md' - 'Frequently Asked Questions': 'getting-started/faq.md'