Quick Start

A Simple Use Case of Traefik Proxy and Kubernetes

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 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 resource enumerates the resources and actions available for the role. In a file called 00-role.yml, put the following ClusterRole:

00-role.yml

  1. kind: ClusterRole
  2. apiVersion: rbac.authorization.k8s.io/v1
  3. metadata:
  4.   name: traefik-role
  6. rules:
  7.   - apiGroups:
  8.       - ""
  9.     resources:
  10.       - services
  11.       - endpoints
  12.       - secrets
  13.     verbs:
  14.       - get
  15.       - list
  16.       - watch
  17.   - apiGroups:
  18.       - extensions
  19.       - networking.k8s.io
  20.     resources:
  21.       - ingresses
  22.       - ingressclasses
  23.     verbs:
  24.       - get
  25.       - list
  26.       - watch
  27.   - apiGroups:
  28.       - extensions
  29.       - networking.k8s.io
  30.     resources:
  31.       - ingresses/status
  32.     verbs:
  33.       - update

You can find the reference for this file there.

The next step is to create a dedicated service account for Traefik. In a file called 00-account.yml, put the following ServiceAccount resource:

00-account.yml

  1. apiVersion: v1
  2. kind: ServiceAccount
  3. metadata:
  4.   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 resource:

01-role-binding.yml

  1. kind: ClusterRoleBinding
  2. apiVersion: rbac.authorization.k8s.io/v1
  3. metadata:
  4.   name: traefik-role-binding
  6. roleRef:
  7.   apiGroup: rbac.authorization.k8s.io
  8.   kind: ClusterRole
  9.   name: traefik-role
  10. subjects:
  11.   - kind: ServiceAccount
  12.     name: traefik-account
  13.     namespace: default # Using "default" because we did not specify a namespace when creating the ClusterAccount.

roleRef is the Kubernetes reference to the role created in 00-role.yml.

subjects is the list of accounts reference.

In this guide, it only contains the account created in 00-account.yml

Deployment and Exposition

This section can be managed with the help of the Traefik Helm chart.

The 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 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:

02-traefik.yml

  1. kind: Deployment
  2. apiVersion: apps/v1
  3. metadata:
  4.   name: traefik-deployment
  5.   labels:
  6.     app: traefik
  8. spec:
  9.   replicas: 1
  10.   selector:
  11.     matchLabels:
  12.       app: traefik
  13.   template:
  14.     metadata:
  15.       labels:
  16.         app: traefik
  17.     spec:
  18.       serviceAccountName: traefik-account
  19.       containers:
  20.         - name: traefik
  21.           image: traefik:v2.8
  22.           args:
  23.             - --api.insecure
  24.             - --providers.kubernetesingress
  25.           ports:
  26.             - name: web
  27.               containerPort: 80
  28.             - name: dashboard
  29.               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…

In this deployment, the static configuration enables the Traefik dashboard, and uses Kubernetes native Ingress resources as router definitions to route incoming requests.

When there is no entry point in the static configuration

Traefik creates a default one called web using the port 80 routing HTTP requests.

When enabling the api.insecure mode, Traefik exposes the dashboard on the port 8080.

A deployment manages scaling and then can create lots of containers, called 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. Create a file called 02-traefik-services.yml and insert the two Service resources:

02-traefik-services.yml

  1. apiVersion: v1
  2. kind: Service
  3. metadata:
  4.   name: traefik-dashboard-service
  6. spec:
  7.   type: LoadBalancer
  8.   ports:
  9.     - port: 8080
  10.       targetPort: dashboard
  11.   selector:
  12.     app: traefik
  13. ---
  14. apiVersion: v1
  15. kind: Service
  16. metadata:
  17.   name: traefik-web-service
  19. spec:
  20.   type: LoadBalancer
  21.   ports:
  22.     - targetPort: web
  23.       port: 80
  24.   selector:
  25.     app: traefik

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 before proceeding to the next step.

It is now time to apply those files on your cluster to start Traefik.

  1. kubectl apply -f 00-role.yml \
  2.               -f 00-account.yml \
  3.               -f 01-role-binding.yml \
  4.               -f 02-traefik.yml \
  5.               -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, 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:

03-whoami.yml

  1. kind: Deployment
  2. apiVersion: apps/v1
  3. metadata:
  4.   name: whoami
  5.   labels:
  6.     app: whoami
  8. spec:
  9.   replicas: 1
  10.   selector:
  11.     matchLabels:
  12.       app: whoami
  13.   template:
  14.     metadata:
  15.       labels:
  16.         app: whoami
  17.     spec:
  18.       containers:
  19.         - name: whoami
  20.           image: traefik/whoami
  21.           ports:
  22.             - name: web
  23.               containerPort: 80

And continue by creating the following Service resource in a file called 03-whoami-services.yml:

03-whoami-services.yml

  1. apiVersion: v1
  2. kind: Service
  3. metadata:
  4.   name: whoami
  6. spec:
  7.   ports:
  8.     - name: web
  9.       port: 80
  10.       targetPort: web
  12.   selector:
  13.     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 for Traefik.

Tip

Find more information on ingress controller, and Ingress in the official Kubernetes documentation.

Create a file called 04-whoami-ingress.yml and insert the Ingress resource:

04-whoami-ingress.yml

  1. apiVersion: networking.k8s.io/v1
  2. kind: Ingress
  3. metadata:
  4.   name: whoami-ingress
  5. spec:
  6.   rules:
  7.   - http:
  8.       paths:
  9.       - path: /
  10.         pathType: Prefix
  11.         backend:
  12.           service:
  13.             name: whoami
  14.             port:
  15.               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:

  1. kubectl apply -f 03-whoami.yml \
  2.               -f 03-whoami-services.yml \
  3.               -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.

And now access the whoami application:

  1. curl -v http://localhost/

Going further