中文
devexamples
← Recipes

阅读中文版本

Issue a Wildcard Certificate with DNS-01

Use the ACME DNS-01 challenge with a provider API token to obtain wildcard certificates, and automate renewal before expiry.

~40 mintlsacmeautomation

Task

Obtain and renew a wildcard TLS certificate without exposing the service to the internet.

When to use this

A service needs a wildcard certificate but the HTTP-01 challenge cannot be used because the host is internal or behind a proxy.

Prerequisites

  • An ACME client such as certbot
  • A DNS provider with an API for TXT records

Steps

1. Configure the ACME client with DNS provider credentials and the wildcard domain.

Expected output: The client can create challenge TXT records.

2. Run the issuance so the client creates and cleans up the TXT record.

Expected output: Ownership is proven via DNS.

3. Install the resulting certificate and set a renewal timer.

Expected output: The certificate is deployed and renews automatically.

4. Verify the certificate covers the wildcard and the base domain.

certbot certonly --dns-cloudflare --dns-cloudflare-credentials ~/.secrets/cf.ini -d "*.example.com" -d example.com

Expected output: Both names are present in the SAN.

Troubleshooting

Problem

DNS propagation delays fail the challenge

Solution

Increase propagation wait and use the provider hook that waits for the record to be visible.

Problem

Renewal silently fails

Solution

Monitor certificate expiry and renewal logs; a broken DNS token causes a silent lapse.

Limitations

  • DNS-01 requires API access to the DNS zone, which is a powerful credential to guard.
  • Wildcard certificates share one key for many hosts, so a compromise has a broad blast radius.

Context

Obtain and renew a wildcard TLS certificate without exposing the service to the internet. A service needs a wildcard certificate but the HTTP-01 challenge cannot be used because the host is internal or behind a proxy.

Steps

  1. Configure the ACME client with DNS provider credentials and the wildcard domain. Expected: The client can create challenge TXT records.
  2. Run the issuance so the client creates and cleans up the TXT record. Expected: Ownership is proven via DNS.
  3. Install the resulting certificate and set a renewal timer. Expected: The certificate is deployed and renews automatically.
  4. Verify the certificate covers the wildcard and the base domain. Expected: Both names are present in the SAN.
certbot certonly --dns-cloudflare \
  --dns-cloudflare-credentials ~/.secrets/cf.ini \
  --dns-cloudflare-propagation-seconds 60 \
  -d "*.example.com" -d example.com

Verify

  • The client can create challenge TXT records.
  • Ownership is proven via DNS.
  • The certificate is deployed and renews automatically.
  • Both names are present in the SAN.

Limits

  • DNS-01 requires API access to the DNS zone, which is a powerful credential to guard.
  • Wildcard certificates share one key for many hosts, so a compromise has a broad blast radius.