⚠️ Repo Archive Notice

As of Nov 13, 2020, charts in this repo will no longer be updated. For more information, see the Helm Charts Deprecation and Archive Notice, and Update.

Traefik

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

DEPRECATION NOTICE

This chart is deprecated and no longer supported.

Introduction

This chart bootstraps Traefik as a Kubernetes ingress controller with optional support for SSL and Let's Encrypt.

NOTE: Operators will typically wish to install this component into the kube-system namespace where that namespace's default service account will ensure adequate privileges to watch Ingress resources cluster-wide.

Prerequisites

• Kubernetes 1.4+ with Beta APIs enabled
• Kubernetes 1.6+ if you want to enable RBAC
• You are deploying the chart to a cluster with a cloud provider capable of provisioning an external load balancer (e.g. AWS or GKE)
• You control DNS for the domain(s) you intend to route through Traefik
• Suggested: PV provisioner support in the underlying infrastructure

A Quick Note on Versioning

Up until version 1.2.1-b of this chart, the semantic version of the chart was kept in-sync with the semantic version of the (default) version of Traefik installed by the chart. A dash and a letter were appended to Traefik's semantic version to indicate incrementally improved versions of the chart itself. For example, chart version 1.2.1-a and 1.2.1-b both provide Traefik 1.2.1, but 1.2.1-b is a chart that is incrementally improved in some way from its immediate predecessor-- 1.2.1-a.

This convention, in practice, suffered from a few problems, not the least of which was that it defied what was permitted by semver 2.0.0. This, in turn, lead to some difficulty in Helm understanding the versions of this chart.

Beginning with version 1.3.0 of this chart, the version references only the revision of the chart itself. The appVersion field in chart.yaml now conveys information regarding the revision of Traefik that the chart provides.

Installing the Chart

To install the chart with the release name my-release:

$ helm install stable/traefik --name my-release --namespace kube-system

After installing the chart, create DNS records for applicable domains to direct inbound traffic to the load balancer. You can use the commands below to find the load balancer's IP/hostname:

NOTE: It may take a few minutes for this to become available.

You can watch the status by running:

$ kubectl get svc my-release-traefik --namespace kube-system -w

Once EXTERNAL-IP is no longer <pending>:

$ kubectl describe service my-release-traefik -n kube-system | grep Ingress | awk '{print $3}'

NOTE: If ACME support is enabled, it is only after this step is complete that Traefik will be able to successfully use the ACME protocol to obtain certificates from Let's Encrypt.

Uninstalling the Chart

To uninstall/delete the my-release deployment:

$ helm delete my-release

The command removes all the Kubernetes components associated with the chart and deletes the release.

Configuration

The following table lists the configurable parameters of the Traefik chart and their default values.

Specify each parameter using the --set key=value[,key=value] argument to helm install. For example:

$ helm install --name my-release --namespace kube-system \
  --set dashboard.enabled=true,dashboard.domain=traefik.example.com stable/traefik

The above command enables the Traefik dashboard on the domain traefik.example.com.

Alternatively, a YAML file that specifies the values for the parameters can be provided while installing the chart. For example:

$ helm install --name my-release --namespace kube-system --values values.yaml stable/traefik

Clustering / High Availability

To enable cluster support, you need one of:

• etcd
• consul
• boltdb
• zookeeper

as kvprovider, especially when you are using Let's Encrypt. If you have already certificates stored as acme.json in an existing persistent volume claim, you can import it.

Given you have:

• a running etcd operator:
• you have created a master chart requiring this traefik chart
• an existing pvc with an acme.json called acme-certs-pvc
• you have an etcd template like:
  Copy

  apiVersion: "etcd.database.coreos.com/v1beta2"
  kind: "EtcdCluster"
  metadata:
    name: {{ .Values.etcdCluster.name }}
    labels:
       app: {{ .Values.etcdCluster.name }}
    annotations:
       etcd.database.coreos.com/scope: clusterwide
  spec:
    size: 3
    version: "3.1.8"
  

• and these values in your values.yaml
  Copy

  etcdCluster:
    name: traefik-etcd-cluster
  
  traefik:
    replicas: 3
    acme:
      persistence:
        enabled: true
        existingClaim: acme-certs-pvc
    kvprovider:
      storeAcme: true
      importAcme: true
      etcd:
        endpoint: "traefik-etcd-cluster-client:2379"
        useAPIV3: false
        watch: true
        prefix: traefik
  

Then you are good to migrate your old certs into the kvprovider and run traefik in HA/Cluster-Mode.

Dashboard Basic Auth

Basic auth can be specified via dashboard.auth.basic as a map of usernames to passwords as below. See the linked Traefik documentation for accepted passwords encodings. It is advised to single quote passwords to avoid issues with special characters:

$ helm install --name my-release --namespace kube-system \
  --set dashboard.enabled=true,dashboard.auth.basic.test='$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/' \
  stable/traefik

Alternatively in YAML form:

dashboard:
  enabled: true
  domain: traefik.example.com
  auth:
    basic:
      test: $apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/

Let's Encrypt domain verification using DNS challenge

When obtaining an ACME (Let's Encrypt) certificate, sometimes it's more desirable to do DNS challenge, for example, if the server you want to obtain a certificate for does not have a public IP address.

First, check if your DNS provider is supported by lego(the ACME library that Traefik is using). Next, you will need to configure the Traefik chart to use DNS challenge. In the ACME section:

acme:
  enabled: true
  challengeType: "dns-01"
  dnsProvider:
    name:  # name of the dns provider to use
    $name: # the configuration of the dns provider. See the following section for an example
      # variables that the specific dns provider requires

Let's Encrypt wildcard certificate

To obtain an ACME (Let's Encrypt) wildcard certificate you must use a DNS challenge as explained above. Then you need to specify the wildcard domain name in the acme.domains section like this :

acme:
  enabled: true
  challengeType: "dns-01"
  dnsProvider:
    name:  # name of the dns provider to use
    $name: # the configuration of the dns provider. See the following section for an example
      # variables that the specific dns provider requires
  domains:
    enabled: true
    domainsList:
      - main: "*.example.com" # name of the wildcard domain name for the certificate
      - sans:
        - "example.com" # OPTIONAL: Alternative name(s) for the certificate, if you want the same certificate for the root of the domain name for example
      - main: "*.example2.com" # name of the wildcard domain name for the certificate

Example: AWS Route 53

Using route53 as DNS provider requires the following configuration variables to be set:

• AWS_ACCESS_KEY_ID
• AWS_SECRET_ACCESS_KEY
• AWS_REGION

The configuration would look like this:

acme:
  enabled: true
  dnsProvider:
    name: route53
    route53:
      AWS_ACCESS_KEY_ID: ...
      AWS_SECRET_ACCESS_KEY: ...
      AWS_REGION: us-east-1

Example: Google Cloud DNS

Using gcloud as DNS provider requires the following configuration variables to be set:

• GCE_PROJECT
• GCE_SERVICE_ACCOUNT_FILE

The configuration would look like this:

secretFiles:
  gcloud-credentials.json: '{"type":"service_account","project_id":"<projectName>","private_key_id":"<hash>",...}'

acme:
  enabled: true
  dnsProvider:
    name: gcloud
    gcloud:
      GCE_PROJECT: <projectName>
      GCE_SERVICE_ACCOUNT_FILE: /secrets/gcloud-credentials.json

Proxy Protocol

In situations where Traefik lives behind an Internet-facing loadbalancer (like an AWS ELB) and you still want it to see the actual source IP of the visitor instead of the internal IP of the loadbalancer, you can enable the loadbalancer to use the Proxy protocol to talk to Traefik. This effectively makes the loadbalancer transparent, as Traefik will still get the actual visitor IP address for each request. This only works if Traefik knows it's receiving traffic via the Proxy Protocol and the loadbalancer IP addresses need to be whitelisted as well.

How to set this up on AWS is described in the Kubernetes documentation here, it can easily be done by adding an annotation to the Service definition.

Caution

If only one of the components (either the loadbalancer or Traefik) is set to use the Proxy protocol and the other is not, this will break badly as they will not be able to communicate with each other.