Traefik

Traefik is a modern HTTP reverse proxy and load balancer made to deploy microservices with ease.

Introduction

This chart bootstraps Traefik version 2 as a Kubernetes ingress controller, using Custom Resources IngressRoute: https://docs.traefik.io/providers/kubernetes-crd/.

It's now possible to use this chart with Traefik v3 (current tested with beta3). Helm will auto detect which version is used based on image.tag. Set image.tag to a semver higher than 3.0, e.g. "v3.0.0-beta3". See Migration guide from v2 to v3 and upgrading section of this chart on CRDs.

Philosophy

The Traefik HelmChart is focused on Traefik deployment configuration.

To keep this HelmChart as generic as possible we tend to avoid integrating any third party solutions nor any specific use cases.

Accordingly, the encouraged approach to fulfill your needs:

1. Override the default Traefik configuration values (yaml file or cli)
2. Append your own configurations (kubectl apply -f myconf.yaml)

If needed, one may use extraObjects or extend this HelmChart as a Subchart. In the examples, one can see how to use this Chart as a dependency.

Installing

Prerequisites

1. Helm v3 > 3.9.0 installed: helm version
2. Traefik's chart repository: helm repo add traefik https://traefik.github.io/charts

Kubernetes Version Support

Due to changes in CRD version support, the following versions of the chart are usable and supported on the following Kubernetes versions:

CRDs Support of Traefik Proxy

Due to changes in API Group of Traefik CRDs from containo.us to traefik.io, this Chart install the two CRDs API Group on the following versions:

Deploying Traefik

helm install traefik traefik/traefik

You can customize the install with a values file. There are some EXAMPLES provided. Complete documentation on all available parameters is in the default file.

helm install -f myvalues.yaml traefik traefik/traefik

🛂 Warning: Helm v2 support was removed in the chart version 10.0.0.

Upgrading

One can check what has changed in the Changelog.

# Update repository
helm repo update
# See current Chart & Traefik version
helm search repo traefik/traefik
# Upgrade Traefik
helm upgrade traefik traefik/traefik

New major version indicates that there is an incompatible breaking change.

Upgrading CRDs

🛂 Warning: Traefik v3 totally removes the crd support for traefik.containo.us CRDs. By default this helm installs the CRDs compatible with v2 also, but Traefik v3 will no longer monitor them. There is no support for deprecation errors, so your existing resources may silently fail to work after upgrade to Traefik v3. See Migration guide from v2 to v3 for more details.

With Helm v3, CRDs created by this chart can not be updated, cf the Helm Documentation on CRDs. Please read carefully release notes of this chart before upgrading CRDs.

kubectl apply --server-side --force-conflicts -k https://github.com/traefik/traefik-helm-chart/traefik/crds/

Upgrading after 18.X+

It's detailed in release notes.

Upgrading from 17.x to 18.x

Since v18.x, this chart by default merges TCP and UDP ports into a single (LoadBalancer) Service. Load balancers with mixed protocols are available since v1.20 and in beta as of Kubernetes v1.24. Availability may depend on your Kubernetes provider.

To retain the old default behavior, set service.single to false in your values.

When using TCP and UDP with a single service, you may encounter this issue from Kubernetes.

On HTTP/3, if you want to avoid this issue, you can set ports.websecure.http3.advertisedPort to an other value than 443

If you were previously using HTTP/3, you should update your values as follows:

• Replace the old value (true) of ports.websecure.http3 with a key enabled: true
• Remove experimental.http3.enabled=true entry

Upgrading from 16.x to 17.x

Since v17.x, this chart provides unified labels following Kubernetes recommendation.

This version needs to change an immutable field, which is not supported by Kubernetes and Helm, see this issue for more details. So you will have to delete your Service, Deployment or DaemonSet in order to be able to upgrade.

You may also upgrade by deploying another Traefik to a different namespace and removing after your first Traefik.

Alternatively, since version 20.3.0 of this chart, you may set instanceLabelOverride to the previous value of that label. This will override the new Release.Name-Release.Namespace pattern to avoid any (longer) downtime.

Contributing

If you want to contribute to this chart, please read the Contributing Guide.

Thanks to all the people who have already contributed!