Automating LetsEncrypt Wildcard Certificate Renewal with DNS Challenge

Hey there, Darian Vance here. As a Senior DevOps Engineer at TechResolve, I’ve seen my fair share of late-night pages for expired SSL certificates. I used to spend a couple of hours every month manually checking renewal logs, just to be safe. It felt like a necessary chore until I realized it was completely automatable. Setting up a robust, hands-off renewal system for wildcard certificates isn’t just a “nice-to-have”; it’s a core part of a reliable infrastructure.

Today, I’m going to walk you through my go-to setup for automating LetsEncrypt wildcard renewals using the DNS challenge. This method lets you secure `*.yourdomain.com` without needing to place verification files on any specific server, which is perfect for load-balanced environments or non-web services. Let’s build a system that lets you focus on bigger problems.

Prerequisites

Before we start, make sure you have the following ready:

• A domain name managed by a DNS provider with API access (e.g., Cloudflare, AWS Route 53, GoDaddy).
• API credentials (a token or key/secret pair) from that DNS provider with permissions to edit DNS records.
• A server or environment where you can run Python 3 and schedule tasks (like a cron job).

The Step-by-Step Guide

Step 1: Understanding the DNS-01 Challenge

First, a quick concept. To issue a wildcard certificate, LetsEncrypt needs to be absolutely sure you own the entire domain. The easiest way to prove this is the DNS-01 challenge. LetsEncrypt will ask you to create a specific TXT DNS record with a unique value. Once `certbot` creates that record via your provider’s API, LetsEncrypt’s servers check for it. If it’s there, they issue the certificate. Our script will automate this entire “API handshake.”

Step 2: Setting Up Your Environment

I’ll skip the standard project directory and virtualenv setup, as you probably have your own workflow for that. The important part is getting the right tools. You’ll need to use your package manager, pip, to install `certbot` and the specific DNS plugin for your provider. For example, if you use Cloudflare, you would install `certbot` and `certbot-dns-cloudflare`.

Next, we need a secure place for our API credentials. I recommend creating a file named `config.env` in your project directory. Never commit this file to version control. You’ll want to restrict its permissions so only your user can read it.

Here’s a template for what that `config.env` file should look like for Cloudflare. The variable names are specific to the certbot plugin, so check the documentation for your provider.

# Cloudflare credentials used by certbot
dns_cloudflare_api_token = "YOUR_CLOUDFLARE_API_TOKEN_HERE"

Pro Tip: Always create a dedicated API token for this purpose with the minimum required permissions. It should only have access to edit DNS records for the specific zone you’re securing. This is a key security practice I insist on in my production setups.

Step 3: The Python Automation Script

Instead of just running a raw `certbot` command in cron, I always wrap it in a small Python script. Why? It gives us much better control over error handling, logging, and notifications. If something goes wrong, you want to know immediately, not when a user reports a certificate error.

Let’s name our script `renew_certs.py`. Here is the logic:

import os
import subprocess
import requests

# --- Configuration ---
# Make sure to replace these with your actual details
YOUR_DOMAIN = "yourdomain.com"
YOUR_EMAIL = "your-email@yourdomain.com"
CREDENTIALS_FILE = "config.env" # The path to your credentials
SLACK_WEBHOOK_URL = "https://hooks.slack.com/services/YOUR/WEBHOOK/URL" # Optional: for notifications

def send_notification(message, is_error=False):
    """Sends a notification to a Slack webhook."""
    if not SLACK_WEBHOOK_URL.startswith("https://hooks.slack.com"):
        print("Slack webhook URL is not configured. Skipping notification.")
        return

    color = "#FF0000" if is_error else "#36A64F"
    payload = {
        "attachments": [
            {
                "fallback": message,
                "color": color,
                "title": "LetsEncrypt Renewal Status",
                "text": message,
                "footer": "Certificate Automation"
            }
        ]
    }
    try:
        response = requests.post(SLACK_WEBHOOK_URL, json=payload, timeout=5)
        response.raise_for_status()
    except requests.exceptions.RequestException as e:
        print(f"Failed to send notification: {e}")

def run_certbot_renewal():
    """
    Executes the certbot command to renew wildcard certificates
    using the DNS challenge.
    """
    print("Starting certificate renewal process...")

    # We build the command as a list to avoid shell injection issues.
    command = [
        "certbot",
        "certonly",
        "--dns-cloudflare",
        "--dns-cloudflare-credentials", CREDENTIALS_FILE,
        "--dns-cloudflare-propagation-seconds", "60", # Give DNS time to propagate
        "--non-interactive",
        "--agree-tos",
        "--email", YOUR_EMAIL,
        "-d", f"*.{YOUR_DOMAIN}",
        "-d", YOUR_DOMAIN,
        #"--dry-run" # Uncomment for testing without issuing a real cert
    ]

    try:
        # Using subprocess.run is the modern and safer way to do this.
        result = subprocess.run(command, capture_output=True, text=True, check=False)

        if result.returncode == 0:
            success_message = f"Successfully renewed certificates for {YOUR_DOMAIN}."
            print(success_message)
            print("Certbot output:\n", result.stdout)
            send_notification(success_message)
        else:
            # If certbot fails, we capture the error and send a detailed notification.
            error_message = f"ERROR renewing certificates for {YOUR_DOMAIN}. Return code: {result.returncode}"
            print(error_message)
            print("Certbot error output:\n", result.stderr)
            full_log = f"{error_message}\n\nSTDOUT:\n{result.stdout}\n\nSTDERR:\n{result.stderr}"
            send_notification(full_log, is_error=True)
            return 1 # Indicate failure

    except FileNotFoundError:
        error_message = "ERROR: 'certbot' command not found. Is it installed and in your PATH?"
        print(error_message)
        send_notification(error_message, is_error=True)
        return 1
    
    return 0 # Indicate success

if __name__ == "__main__":
    run_certbot_renewal()

Step 4: Scheduling with Cron

With our script ready, the final step is to schedule it. LetsEncrypt certificates are valid for 90 days, so running the script once a week is more than enough. This gives you plenty of time to fix any issues that might pop up.

Here’s a safe, standard cron job entry that runs the script at 2:00 AM every Monday. Remember to run this from the directory containing your script and `config.env` file, or adjust the paths in the script itself.

0 2 * * 1 python3 script.py

Pro Tip: Before putting the real command in your cron, I highly recommend uncommenting the `–dry-run` flag in the script. This lets you test the entire process against LetsEncrypt’s staging environment without affecting your rate limits for real certificates. Once you see a dry run succeed, you’re ready for production.

Common Pitfalls (Where I Usually Mess Up)

Even with a solid plan, a few things can trip you up. Here are the ones I’ve run into most often:

• Incorrect API Token Permissions: The number one issue. The token needs permission to create and delete TXT records. A read-only token will always fail. Double-check your provider’s documentation.
• DNS Propagation Delay: Sometimes, your DNS provider takes a few minutes to make the new TXT record visible globally. The `–dns-cloudflare-propagation-seconds 60` flag helps, but if your provider is slow, you might need to increase this value.
• Rate Limits: If you’re testing, be careful. LetsEncrypt has strict rate limits. The `–dry-run` flag is your best friend here as it uses separate, more generous limits.
• Improperly Secured Credentials File: Leaving your `config.env` file with open permissions is a major security risk. Make sure only the user running the script can read it.

Conclusion

And that’s it. You now have a resilient, automated system that handles wildcard certificate renewals without you having to think about it. The initial setup takes maybe 30 minutes, but it saves countless hours of manual work and prevents stressful, customer-facing outages from expired certificates. This is the kind of foundational automation that separates a reactive team from a proactive one. Now, go deploy it and enjoy the peace of mind.

All the best,
Darian Vance

Darian Vance

Lead Cloud Architect & DevOps Strategist

With over 12 years in system architecture and automation, Darian specializes in simplifying complex cloud infrastructures. An advocate for open-source solutions, he founded TechResolve to provide engineers with actionable, battle-tested troubleshooting guides and robust software alternatives.

🤖 Frequently Asked Questions