Learn Traefik - TLS Configuration

#Introduction

Episode 14 marks a big transition: from plaintext HTTP to HTTPS. This TLS phase contains four episodes that successively strengthen transport security. In this episode, we build the basic understanding of TLS in Traefik: what TLS termination is, what passthrough is, how to configure versions and cipher suites, where certificates come from, and how SNI determines which certificate is used.

The most important concept here: TLS termination is Traefik's default. Traefik holds the certificate, handles the handshake with the client, then forwards the request in plaintext (or re-encrypted) to the backend. This centralizes all certificate management in one place — one of the reasons Traefik is so well liked.

#TLS Termination vs. Passthrough

#Termination

In TLS termination, the TLS handshake happens at Traefik. Traefik holds the private key, decrypts traffic, and can route based on the request. Because traffic is already decrypted, all HTTP middlewares — headers, rate limit, auth — work normally. This is the default mode.

#Passthrough

In TLS passthrough, Traefik only passes the intact TLS connection to the backend without decrypting. Traefik only sees SNI for routing and cannot apply HTTP middlewares. The backend holds its own certificate. This is used for non-HTTP protocols or end-to-end encryption requirements.

tcp:
  routers:
    db-tcp:
      rule: "HostSNI(`db.example.com`)"
      entrypoints:
        - db
      service: db-svc
      tls:
        passthrough: true
  services:
    db-svc:
      loadBalancer:
        servers:
          - address: "10.0.0.60:5432"

TLS passthrough on a TCP router opens a direct connection to the database without Traefik ever seeing its contents. We dissect TCP routing deeper in episode 18.

#TLSOption

#TLS Versions and Cipher Suites

TLSOption is the resource that governs TLS behavior: minimum and maximum versions, cipher suites, curve preferences, and client authentication. An example of a safe standard:

http:
  tlsOptions:
    hardened:
      minVersion: VersionTLS12
      maxVersion: VersionTLS13
      cipherSuites:
        - TLS_AES_128_GCM_SHA256
        - TLS_AES_256_GCM_SHA384
      curvePreferences:
        - CurveP256
        - CurveP384
      sniStrict: true

• minVersion: VersionTLS12: rejects obsolete TLS 1.0 and 1.1.
• cipherSuites: restricts the accepted encryption algorithms. For TLS 1.3, only AEAD suites are available.
• curvePreferences: the preferred ordering of elliptic curves.
• sniStrict: true: rejects connections whose SNI does not match any certificate.

A TLSOption is attached to a router by name:

http:
  routers:
    app:
      rule: "Host(`app.example.com`)"
      entrypoints:
        - websecure
      service: app-svc
      tls:
        options: hardened

#Certificate Sources

#Three Main Sources

Certificates for Traefik can come from three sources:

• File provider: manual certificates in files — covered in episode 17.
• Let's Encrypt (ACME): automatic certificates via a certificate resolver — covered deeply in episode 15.
• Custom CA: certificates from an internal Certificate Authority, e.g. for internal environments.

All certificates are stored in the certificate store named default. When a request arrives, Traefik matches the client's SNI against the available certificates. If nothing matches, Traefik uses the default certificate as a fallback.

#Default Certificate

The default certificate is a safety net: if Traefik cannot find a certificate matching the SNI, it sends this default certificate. Without any settings, Traefik uses an internally generated self-signed certificate. For production, define your own:

tls:
  stores:
    default:
      defaultCertificate:
        certFile: /certs/default.crt
        keyFile: /certs/default.key

#SNI and Certificate Selection

#Server Name Indication

SNI is the TLS extension where the client states the host name it wants before the handshake completes. This is what allows Traefik to serve many domains from one IP: the client says "I want app.example.com", Traefik selects the app.example.com certificate.

openssl s_client -connect app.example.com:443 -servername app.example.com -showcerts

The openssl s_client command above shows the full certificate chain Traefik sends based on SNI. Use a different -servername to verify that each domain receives the correct certificate — standard debugging for multi-domain TLS issues.

#Closing

Key takeaways:

• TLS termination: Traefik holds the certificate and decrypts traffic.
• TLS passthrough: Traefik only passes the TLS connection through without decrypting.
• TLSOption configures TLS versions, cipher suites, and curve preferences.
• Certificate sources: file provider, ACME, and custom CA.
• The default certificate is the fallback when SNI does not match.
• SNI determines which certificate is served for each domain.

In episode 15 next we will cover Let's Encrypt & ACME — the ACME protocol, certificate resolver configuration with email and storage, the three challenge types, and certificate lifecycle management including automatic renewal. This is the feature that makes HTTPS in Traefik almost effortless.