Installing Traefik on Kubernetes using Helm

🔔 Note: This post was translated from the original document and summarized based on technical content using Google’s AI model, Gemini.

Original Source: Traefik Official Documentation (Kubernetes Setup) https://doc.traefik.io/traefik/setup/kubernetes/

This guide provides an in-depth walkthrough on how to install and configure Traefik Proxy within a Kubernetes cluster using its official Helm chart. This guide covers:

• Configuring standard HTTP (web) and HTTPS (websecure) entrypoints
• Implementing automatic redirection from HTTP to HTTPS
• Securing the Traefik dashboard with Basic Authentication
• Deploying a demo application to test the setup
• Exploring other key configuration options

Prerequisites

• Kubernetes cluster
• Helm v3
• Kubectl

---

Cluster Creation

If you don’t already have a Kubernetes cluster, you can create one using 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 are used to access Traefik from the host, and port 8000 is left free for later demos. The Traefik built into k3s is disabled to prevent conflicts.

Verify the context

kubectl cluster-info --context k3d-traefik

You should see output similar to this:

Kubernetes control plane is running at CoreDNS is running at Metrics-server is running at

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

---

Add Chart Repository and Namespace

Helm simplifies Kubernetes application deployment. Helm packages applications as “charts,” which are collections of template files describing Kubernetes resources. We will use the official Traefik Helm chart for easy management and customization.

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

The first command registers a traefik repository alias pointing to the official chart location. The second command refreshes the local cache, ensuring that the latest chart list and versions from all configured repositories are available.

---

Generate Local Self-Signed TLS Secret

Whenever Traefik’s gateway listener uses the HTTPS protocol, a certificate is required. For local development, we will generate a one-time self-signed certificate and store it in a Kubernetes secret named local-selfsigned-tls. The gateway will reference this secret to terminate TLS on the websecure listener.

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

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

Why this is needed The gateway’s HTTPS listener references this secret via certificateRefs. Without it, Helm chart validation will fail, and the HTTP→HTTPS redirection chain will break.

Production Environment Tip The self-signed certificate above should only be used for local development. In a production environment, store certificates issued by your organization’s CA in a secret, or use automated issuance tools like cert-manager or Traefik’s ACME (Let’s Encrypt) to generate certificates as needed. Update the websecure listener’s certificateRefs or use traefik.io/tls.certresolver to ensure clients receive trusted certificates and avoid browser warnings.

---

Prepare Helm Chart Values

Create a values.yaml file with the following content:

# Configure network ports and entrypoints
# Entrypoints are network listeners for incoming traffic.
ports:
  # Define an HTTP entrypoint named 'web'
  web:
    port: 80
    nodePort: 30000
    # Instruct all traffic on this entrypoint to redirect to the 'websecure' entrypoint
    http:
      redirections:
        entryPoint:
          to: websecure
          scheme: https
          permanent: true

  # Define an HTTPS entrypoint named 'websecure'
  websecure:
    port: 443
    nodePort: 30001

# Enable 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

# Create BasicAuth middleware and secret for 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 your actual password
  - apiVersion: traefik.io/v1alpha1
    kind: Middleware
    metadata:
      name: dashboard-auth
    spec:
      basicAuth:
        secret: dashboard-auth-secret

# Route with Gateway API instead.
ingressClass:
  enabled: false

# Enable Gateway API provider and disable KubernetesIngress provider
# Providers tell Traefik where to find routing configurations.
providers:
  kubernetesIngress:
    enabled: false
  kubernetesGateway:
    enabled: true

## 게이트웨이 리스너
gateway:
  listeners:
    web: # HTTP listener matching entrypoint `web`
      port: 80
      protocol: HTTP
      namespacePolicy:
        from: All
    websecure: # HTTPS listener matching entrypoint `websecure`
      port: 443
      protocol: HTTPS # TLS is terminated inside Traefik
      namespacePolicy:
        from: All
      mode: Terminate
      certificateRefs:
        - kind: Secret
          name: local-selfsigned-tls # Secret created before installation
          group: ""

# Enable Observability
logs:
  general:
    level: INFO
  # Enable access logs, exporting them to Traefik's standard output by default.
  access:
    enabled: true

# Enable Prometheus for metrics
metrics:
  prometheus:
    enabled: true

---

Install Traefik using Helm Configuration

Now, apply the configuration using the Helm client.

# Install chart in 'traefik' namespace
helm install traefik traefik/traefik 
  --namespace traefik 
  --values values.yaml

Command Explanation:

• helm install traefik: Instructs Helm to install a new release named traefik.
• traefik/traefik: Specifies the chart to use (the traefik chart from the previously added traefik repository).
• –namespace traefik: Specifies the Kubernetes namespace for installation. Using a dedicated namespace is recommended.
• –values values.yaml: Applies custom configurations from the values.yaml file.

---

Accessing the Dashboard

With Traefik deployed, you can access the dashboard at . When you navigate to this link, your browser will prompt you for a username and password. Log in using the credentials you set in the values.yaml file. Upon successful login, the dashboard will be displayed.

---

Deploying a Demo Application

To test the setup, we will deploy the Traefik whoami application to your Kubernetes cluster. Create a whoami.yaml file and paste the following content:

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 create a Gateway API HTTPRoute to expose the application externally. Create a whoami-route.yaml file and paste the following content:

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: whoami
  namespace: traefik
spec:
  parentRefs:
    - name: traefik-gateway # Name of the Gateway created by Traefik when Gateway API provider is enabled
  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 applying the manifest, navigate to the Routes section of the Traefik dashboard, and you will see that the route has been created.

You can test the application using curl:

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

You can also access in your browser to see the service’s JSON dump.

---

Other Key Configuration Areas

While the above setup provides a secure foundation, Traefik offers many more features. Here’s a summary of some essential configurations using Helm values.yaml overrides:

TLS Certificate Management (Let’s Encrypt)

TLS is enabled by default on the websecure entrypoint, but currently, there is no valid certificate. Traefik can automatically obtain and renew TLS certificates from Let’s Encrypt using the ACME protocol.

Example values.yaml addition:

additionalArguments:
  - "--certificatesresolvers.le.acme.email=your-email@example.com"
  - "--certificatesresolvers.le.acme.storage=/data/acme.json"
  - "--certificatesresolvers.le.acme.httpchallenge.entrypoint=web"

persistence:
  enabled: true
  name: data
  size: 1Gi
  storageClass: ""

####

Let’s Encrypt in Production

Let’s Encrypt can only issue certificates for hostnames pointing to a public IP address accessible via port 80 (HTTP-01) or a DNS provider’s API (DNS-01). Replace the *.docker.localhost example with your actual owned domain and create DNS records.

Gateway API and ACME

Traefik’s built-in ACME integration works with IngressRoute and Ingress resources but does not issue certificates for Gateway API listeners. If you are using Gateway API, install cert-manager and reference the generated secret in gateway.listeners.websecure.certificateRefs.

####

Metrics (Prometheus)

Traefik can expose detailed metrics in Prometheus format, which are essential for performance and traffic monitoring.

Example values.yaml addition:

metrics:
  prometheus:
    entryPoint: metrics
    addRoutersLabels: true
    addServicesLabels: true

####

Tracing (OTel)

Distributed tracing helps understand the latency and flow of requests through your system, including Traefik itself.

Example values.yaml addition:

additionalArguments:
  - "--tracing.otel=true"
  - "--tracing.otel.grpcendpoint=otel-collector.observability:4317"

###

Conclusion

With this configuration, Traefik is set up with secure dashboard access, HTTPS redirection, and a foundation for observability and TLS enablement.