Learn Traefik - Wildcard Certificates & DNS Challenge

#Introduction

A wildcard certificate *.example.com protects all subdomains at once — one certificate, no need to register every name. Episode 16 covers how to get one through the DNS-01 challenge, the only challenge that supports wildcards, plus integration with DNS providers such as Cloudflare and Route53.

The challenge: DNS-01 requires the ability to write TXT records in your domain's DNS programmatically. Traefik does this through the lego library, which supports dozens of providers. In this episode we practice with Cloudflare as an example, complete with environment variable configuration and troubleshooting.

#Wildcard Certificates and DNS-01

#Why DNS-01 Is Required for Wildcards

The HTTP-01 and TLS-ALPN-01 challenges run per-domain: for *.example.com, there is no single host that represents the wildcard. DNS-01 works at the domain name level: Let's Encrypt asks you to place a token in the _acme-challenge.example.com TXT record. By controlling DNS, you prove ownership of the entire domain at once.

The complete flow:

1. Traefik requests a certificate for *.example.com.
2. Let's Encrypt gives a token.
3. Traefik (via lego) creates the _acme-challenge.example.com TXT record at the DNS provider.
4. Let's Encrypt checks that TXT record.
5. The wildcard certificate is issued; Traefik removes the TXT record.

Because no inbound connection is needed, DNS-01 can also be used for servers behind full NAT.

#Cloudflare Integration

#API Token and Environment Variables

To use the Cloudflare provider, create an API Token with Zone.DNS:Edit permission on the target zone. Store the token as an environment variable — never write it in a version-controlled configuration file:

services:
  traefik:
    image: traefik:v3
    environment:
      - CLOUDFLARE_DNS_API_TOKEN=${CLOUDFLARE_DNS_API_TOKEN}
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - ./config/traefik.yml:/etc/traefik/traefik.yml:ro
      - ./acme.json:/etc/traefik/acme.json

The token is taken from .env on the host during docker compose up. The resolver configuration uses DNS-01 with the Cloudflare provider:

certificatesResolvers:
  letsencrypt:
    acme:
      email: admin@example.com
      storage: /etc/traefik/acme.json
      dnsChallenge:
        provider: cloudflare
        resolvers:
          - "1.1.1.1:53"
          - "8.8.8.8:53"

• provider: cloudflare: tells lego which provider to use.
• resolvers: the DNS servers Let's Encrypt uses when verifying the TXT record — list servers that are reachable and accurate.

For other providers, the env var token differs but the pattern is the same: ROUTE53_ACCESS_KEY_ID, AZURE_CLIENT_SECRET, GANDI_API_KEY, and so on. The _acme-challenge record pattern is set automatically by lego.

#Certificates for Many Domains

#Main, SANs, and Mixed Wildcards

A single router can request a certificate with a combination of specific domains and wildcards at once:

services:
  portal:
    image: nginx:alpine
    labels:
      - traefik.enable=true
      - traefik.http.routers.portal.rule=HostRegexp(`{subdomain:[a-z]+}.example.com`)
      - traefik.http.routers.portal.entrypoints=websecure
      - traefik.http.routers.portal.tls.certresolver=letsencrypt
      - traefik.http.routers.portal.tls.domains[0].main=example.com
      - traefik.http.routers.portal.tls.domains[0].sans=*.example.com
      - traefik.http.routers.portal.service=portal-svc
      - traefik.http.services.portal-svc.loadbalancer.server.port=80

The HostRegexp rule makes all *.example.com subdomains enter this router. The tls.domains[0].main label requests a certificate for example.com plus the wildcard SAN *.example.com. Traefik merges requests from all routers using the same resolver, so overlapping domains are not issued as duplicates.

#DNS Troubleshooting

#Propagation Timeout

The most common DNS-01 error is a propagation timeout: the TXT record has been created, but the verification server has not seen it yet because DNS has not spread. Handling it:

• Raise dnsPropagationTimeout on dnsChallenge (60 seconds default for most providers) to 2-3 minutes.
• Make sure the _acme-challenge record TTL is low — if the TTL is 1 hour, verification can fail until the old record disappears.
• Check with dig whether the TXT record is visible from the internet perspective:

dig TXT _acme-challenge.example.com
dig TXT _acme-challenge.example.com @1.1.1.1

The first dig command uses the default resolver, the second forces resolver 1.1.1.1 — if the results differ, propagation is not complete yet.

#Resolvers and Zone Management

If resolvers is not filled in, lego uses built-in resolvers that may not see recent changes. Register trusted resolvers as above. For domains managed across many zones, make sure the token has permission on the correct zone — an unauthorized error is almost always a token scope problem, not a Traefik configuration problem.

#Closing

Key takeaways:

• Wildcard certificates are only possible through the DNS-01 challenge.
• DNS-01 writes a _acme-challenge TXT record at the DNS provider via lego.
• Cloudflare needs an API token scoped to Zone.DNS:Edit through an env var.
• Wildcard routers use HostRegexp plus tls.domains with main and sans.
• Propagation timeouts are handled by raising the timeout and checking via dig.
• Other providers follow the same env var pattern: Route53, Azure, Gandi, and more.

In episode 17 next we will cover custom certificates & mutual TLS — certificates from the file provider with hot reload, certificate stores and SNI routing, and mTLS for certificate-based client authentication. This is where Traefik turns from a public security guard into a trusted gateway for internal APIs.