Kubernetes

This guide provides an in-depth walkthrough for installing and configuring Traefik Proxy within a Kubernetes cluster using the official Helm chart. In this guide, we'll cover the following:

• Configure standard HTTP (web) and HTTPS (websecure) entry points,
• Implement automatic redirection from HTTP to HTTPS
• Secure the Traefik Dashboard using Basic Authentication.
• Deploy a demo application to test the setup
• Explore some other key configuration options

Prerequisites¶

• A Kubernetes cluster
• Helm v3,
• Kubectl

Create the Cluster¶

If you do not have a Kubernetes cluster already, you can spin up one with K3d:

k3d cluster create traefik \
  --port 80:80@loadbalancer \
  --port 443:443@loadbalancer \
  --port 8000:8000@loadbalancer \
  --k3s-arg "--disable=traefik@server:0"

Ports 80 and 443 reach Traefik from the host, while port 8000 remains free for later demos. The built-in Traefik shipped with k3s is disabled to avoid conflicts.

Check the context:

kubectl cluster-info --context k3d-traefik

You should see something like this:

Kubernetes control plane is running at https://0.0.0.0:56049
CoreDNS is running at https://0.0.0.0:56049/api/v1/namespaces/kube-system/services/kube-dns:dns/proxy
Metrics-server is running at https://0.0.0.0:56049/api/v1/namespaces/kube-system/services/https:metrics-server:https/proxy

To further debug and diagnose cluster problems, use 'kubectl cluster-info dump'.

Add the chart repo and namespace¶

Using Helm streamlines Kubernetes application deployment. Helm packages applications into "charts," which are collections of template files describing Kubernetes resources. We use the official Traefik Helm chart for a managed and customizable installation.

helm repo add traefik https://traefik.github.io/charts
helm repo update
kubectl create namespace traefik

The first command registers the traefik repository alias pointing to the official chart ___location. The second command refreshes your local cache to ensure you have the latest list of charts and versions available from all configured repositories.

Create a Local Self‑Signed TLS Secret¶

Traefik's Gateway listeners require a certificate whenever a listener uses protocol: HTTPS.

For local development create a throw‑away self‑signed certificate and store it in a Kubernetes Secret named local‑selfsigned‑tls.
The Gateway references this secret to terminate TLS on the websecure listener.

# 1) Generate a self‑signed certificate valid for *.docker.localhost
openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
  -keyout tls.key -out tls.crt \
  -subj "/CN=*.docker.localhost"

# 2) Create the TLS secret in the traefik namespace
kubectl create secret tls local-selfsigned-tls \
  --cert=tls.crt --key=tls.key \
  --namespace traefik

Why Do We Need To Do This¶

The Gateway's HTTPS listener references this secret via certificateRefs. Without it, the helm chart validation fails and the HTTP→HTTPS redirect chain breaks.

Prepare Helm Chart Configuration Values¶

Create a values.yaml file with the following content:

# Configure Network Ports and EntryPoints
# EntryPoints are the network listeners for incoming traffic.
ports:
  # Defines the HTTP entry point named 'web'
  web:
    port: 80
    nodePort: 30000
    # Instructs this entry point to redirect all traffic to the 'websecure' entry point
    redirections:
      entryPoint:
        to: websecure
        scheme: https
        permanent: true

  # Defines the HTTPS entry point named 'websecure'
  websecure:
    port: 443
    nodePort: 30001

# Enables the dashboard in Secure Mode
api:
  dashboard: true
  insecure: false

ingressRoute:
  dashboard:
    enabled: true
    matchRule: Host(`dashboard.docker.localhost`)
    entryPoints:
      - websecure
    middlewares:
      - name: dashboard-auth

# Creates a BasiAuth Middleware and Secret for the Dashboard Security
extraObjects:
  - apiVersion: v1
    kind: Secret
    metadata:
      name: dashboard-auth-secret
    type: kubernetes.io/basic-auth
    stringData:
      username: admin
      password: "P@ssw0rd"      # Replace with an Actual Password
  - apiVersion: traefik.io/v1alpha1
    kind: Middleware
    metadata:
      name: dashboard-auth
    spec:
      basicAuth:
        secret: dashboard-auth-secret

# We will route with Gateway API instead.
ingressClass:
  enabled: false

# Enable Gateway API Provider & Disables the KubernetesIngress provider
# Providers tell Traefik where to find routing configuration.
providers:
  kubernetesIngress:
     enabled: false
  kubernetesGateway:
     enabled: true

## Gateway Listeners
gateway:
  listeners:
    web:           # HTTP listener that matches entryPoint `web`
      port: 80
      protocol: HTTP
      namespacePolicy: All

    websecure:         # HTTPS listener that matches entryPoint `websecure`
      port: 443
      protocol: HTTPS  # TLS terminates inside Traefik
      namespacePolicy: All
      mode: Terminate
      certificateRefs:    
        - kind: Secret
          name: local-selfsigned-tls  # the Secret we created before the installation
          group: ""

# Enable Observability
logs:
  general:
    level: INFO
  # This enables access logs, outputting them to Traefik's standard output by default. The [Access Logs Documentation](https://doc.traefik.io/traefik/observability/access-logs/) covers formatting, filtering, and output options.
  access:
    enabled: true

# Enables Prometheus for Metrics
metrics:
  prometheus:
    enabled: true

Install the Traefik Using the Helm Values¶

Now, apply the configuration using the Helm client.

# Install the chart into the 'traefik' namespace
helm install traefik traefik/traefik \
  --namespace traefik \
  --values values.yaml

Command Breakdown:

• helm install traefik: Instructs Helm to install a new release named traefik.
• traefik/traefik: Specifies the chart to use (traefik chart from the traefik repository added earlier).
• --namespace traefik: Specifies the Kubernetes namespace to install into. Using a dedicated namespace is recommended practice.
• --values values.yaml: Applies the custom configuration from your values.yaml file.

Accessing the Dashboard¶

Now that Traefik is deployed, you can access its dashboard at https://dashboard.docker.localhost/. When you access this link, your browser will prompt for the username and password. Ensure you use the credentials set in the values.yaml file to log in. Upon successful login, the dashboard will be displayed as shown below:

Deploy a Demo Application¶

To test the setup, deploy the Traefik whoami application in the Kubernetes cluster. Create a file named whoami.yaml and paste the following:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: whoami
  namespace: traefik
spec:
  replicas: 2
  selector:
    matchLabels:
      app: whoami
  template:
    metadata:
      labels:
        app: whoami
    spec:
      containers:
        - name: whoami
          image: traefik/whoami
          ports:
            - containerPort: 80
---
apiVersion: v1
kind: Service
metadata:
  name: whoami
  namespace: traefik
spec:
  selector:
    app: whoami
  ports:
    - port: 80

Apply the manifest:

kubectl apply -f whoami.yaml

After deploying the application, you can expose the application by creating a Gateway API HTTPRoute. To do this, create a file named whoami-route.yaml and paste the following:

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: whoami
  namespace: traefik
spec:
  parentRefs:
    - name: traefik-gateway # Name of the Gateway that Traefik creates when you enable the Gateway API provider
  hostnames:
    - "whoami.docker.localhost"
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /
      backendRefs:
        - name: whoami
          port: 80

Apply the manifest:

kubectl apply -f whoami-route.yaml

After you apply the manifest, navigate to the Routes in the Traefik Dashboard; you’ll see that the https://whoami.docker.localhost route has been created.

You can test the application using curl:

curl -k https://whoami.docker.localhost/

Hostname: whoami-76c9859cfc-k7jzs
IP: 127.0.0.1
IP: ::1
IP: 10.42.0.59
IP: fe80::50d7:a2ff:fed5:2530
RemoteAddr: 10.42.0.60:54148
GET / HTTP/1.1
Host: whoami.docker.localhost
User-Agent: curl/8.7.1
Accept: */*
Accept-Encoding: gzip
X-Forwarded-For: 10.42.0.1
X-Forwarded-Host: whoami.docker.localhost
X-Forwarded-Port: 443
X-Forwarded-Proto: https
X-Forwarded-Server: traefik-644b7c67d9-f2tn9
X-Real-Ip: 10.42.0.1

You can also open a browser and navigate to https://whoami.docker.localhost to see a JSON dump from the service.

Other Key Configuration Areas¶

The above setup provides a secure base, but Traefik offers much more. Here's a brief overview of other essential configurations, with minimal examples using Helm values.yaml overrides.

These examples illustrate how to enable features; consult the main documentation for detailed options.

TLS Certificate Management (Let's Encrypt)¶

On the websecure entry point TLS is enabled by default. However, it currently lacks a valid certificate. Traefik can automatically obtain and renew TLS certificates from Let's Encrypt using the ACME protocol.

Example values.yaml addition:

additionalArguments:
  - "[email protected]"
  - "--certificatesresolvers.le.acme.storage=/data/acme.json"
  - "--certificatesresolvers.le.acme.httpchallenge.entrypoint=web"
  # - "--certificatesresolvers.le.acme.dnschallenge.provider=your-dns-provider" # Requires provider-specific config, adjust if you control your DNS provider

# Enable persistence for ACME data (certificates, account) to ensure it survives pod restarts:
persistence:
  enabled: true
  name: data
  size: 1Gi
  storageClass: ""

This enables a certificate resolver named le, configures the mandatory email and storage file, and sets up the HTTP challenge (requires port 80 access). Refer to the HTTPS/TLS Documentation and Let's Encrypt Documentation for full details, including DNS challenge configuration.

Gateway API & ACME¶

Traefik’s built‑in ACME/Let’s Encrypt integration works for IngressRoute and Ingress resources, but it does not issue certificates for Gateway API listeners. If you’re using the Gateway API, install cert‑manager (or another certificate controller) and reference the secret it creates in gateway.listeners.websecure.certificateRefs.

Metrics (Prometheus)¶

Traefik can expose detailed metrics in Prometheus format, essential for monitoring its performance and the traffic it handles.

Example values.yaml addition:

# Enable metrics endpoint
metrics:
  prometheus:
    # The entry point metrics will be available on (usually internal/admin)
    entryPoint: metrics
    # Add standard Prometheus metrics
    addRoutersLabels: true
    addServicesLabels: true
    # ... other options available

This enables the Prometheus endpoint on a dedicated metrics entry point (port 9100). See the Metrics Documentation for configuration details and available metrics.

Tracing (OTel)¶

Distributed tracing helps understand request latency and flow through your system, including Traefik itself.

Example values.yaml addition:

additionalArguments:
  - "--tracing.otel=true"
  - "--tracing.otel.grpcendpoint=otel-collector.observability:4317" # Adjust endpoint as needed
  - "--tracing.otel.httpendpoint=otel-collector.observability:4318" # Adjust endpoint as needed

This enables OTel tracing and specifies the collector endpoint. Consult the Tracing Documentation for details on OTel tracing.

Conclusion¶

This setup establishes Traefik with secure dashboard access and HTTPS redirection, along with pointers to enable observability & TLS.