The most surprising thing about Traefik’s ACME DNS challenge is that it’s often less about Traefik and more about your DNS provider’s API.
Let’s see Traefik handle a wildcard certificate request using the DNS challenge. Imagine we’ve got a few services running behind Traefik, and we want *.example.com to be covered by a single Let’s Encrypt certificate.
# Traefik static configuration
entryPoints:
websecure:
address: ":443"
certificatesResolvers:
le:
acme:
email: "admin@example.com"
storage: "/etc/traefik/acme.json"
dnsChallenge:
provider: "cloudflare"
# Cloudflare API Token
# Make sure this token has Zone:DNS:Edit permissions for your zone
cloudflare:
apiToken: "your_cloudflare_api_token_here"
When Traefik needs to issue a certificate for *.example.com, it first tells Let’s Encrypt, "Hey, I need a cert for this wildcard." Let’s Encrypt responds by asking Traefik to prove ownership of the domain. For the DNS challenge, this means creating a specific TXT record. Let’s Encrypt will tell Traefik something like: "Okay, create a TXT record named _acme-challenge.example.com with the value some_unique_verification_string."
Now, Traefik doesn’t directly log into your DNS provider. Instead, it uses a provider plugin (like cloudflare in the example above) to interact with your DNS provider’s API. Traefik will call the Cloudflare API (or your provider’s API) to create the TXT record. For a wildcard, it’s crucial that Traefik knows how to add the TXT record for the specific subdomain Let’s Encrypt requests. The _acme-challenge prefix is essential.
Once Traefik successfully creates the TXT record via the DNS provider’s API, it tells Let’s Encrypt, "I’ve put the record in place." Let’s Encrypt then queries DNS servers to find that TXT record. If it finds it, the challenge is passed, and Let’s Encrypt issues the certificate. Traefik then downloads this certificate and stores it in acme.json.
The apiToken (or equivalent credentials for other providers) is the key. It needs the correct permissions to create and delete TXT records within your domain’s zone. Without these permissions, Traefik can’t complete the challenge, and the certificate issuance will fail.
The dnsChallenge block in Traefik’s configuration tells it how to talk to your DNS provider. You specify the provider (e.g., cloudflare, route53, digitalocean), and then provide the necessary authentication credentials for that provider. For Cloudflare, it’s apiToken. For AWS Route 53, it might be IAM credentials. The specific configuration details vary per provider.
The actual TXT record that Let’s Encrypt asks for will look something like _acme-challenge.yourdomain.com. When you request a wildcard certificate for *.example.com, Let’s Encrypt will initially ask for a TXT record at _acme-challenge.example.com. However, to validate all subdomains under example.com, it might also issue challenges for specific subdomains like _acme-challenge.app.example.com. Traefik, using its DNS provider integration, needs to correctly create these TXT records for both the base domain and any requested subdomains.
The most common point of failure isn’t Traefik’s ACME logic, but the DNS provider’s API integration. If your API token is invalid, lacks the necessary DNS:Edit permissions, or if there’s a network issue preventing Traefik from reaching the API, the challenge will fail. Traefik will retry, but it will eventually give up. Always check the logs for specific errors related to the DNS provider API calls.
When Traefik successfully obtains the wildcard certificate, it will automatically renew it before it expires. The storage: "/etc/traefik/acme.json" line ensures that the certificate is persisted across Traefik restarts and is available for automatic renewal.
Once your wildcard certificate is working, the next thing you’ll likely want to configure is how Traefik routes traffic to your services using that certificate, often involving dynamic configuration and routing rules.