certmagicazureblob

certmagic-azureblob

Azure Blob Storage backend for CertMagic / Caddy. Enables distributed TLS certificate management across a Caddy cluster using Azure Blob Storage for persistence and Azure Blob Leases for distributed locking.

Features

• Distributed storage — certificates, keys, and ACME account data stored in Azure Blob Storage
• Distributed locking — Azure Blob Leases coordinate certificate renewals across cluster nodes
• Crash recovery — leases auto-expire (default 30s), so crashed nodes don't hold locks indefinitely
• Directory semantics — Exists, Stat, Delete, and List correctly handle both individual keys and directory prefixes
• Caddy module — registers as caddy.storage.azure_blob with full Caddyfile support

Installation

Build a custom Caddy binary with this plugin using xcaddy:

xcaddy build --with github.com/lnr0626/certmagic-azureblob

Configuration

Caddyfile

Using a connection string (account-level access)

{
    storage azure_blob {
        connection_string {env.AZURE_STORAGE_CONNECTION_STRING}
        encryption_key    {env.CADDY_CERT_ENCRYPTION_KEY}
        container          caddy-certs
        prefix             production
        lease_duration     30
        clean_lock_blobs
        create_container   false
    }
}

Using a container SAS URL (least-privilege, recommended)

{
    storage azure_blob {
        container_sas_url {env.CADDY_CERTS_SAS_URL}
        encryption_key    {env.CADDY_CERT_ENCRYPTION_KEY}
        prefix             production
        lease_duration     30
    }
}

The container_sas_url option restricts access to a single container with only the permissions granted by the SAS token. The container name is automatically extracted from the URL path — no separate container directive is needed.

Using a service principal (Azure AD)

{
    storage azure_blob {
        tenant_id      {env.AZURE_TENANT_ID}
        client_id      {env.AZURE_CLIENT_ID}
        client_secret  {env.AZURE_CLIENT_SECRET}
        account_url    https://caddycerts.blob.core.windows.net
        encryption_key {env.CADDY_CERT_ENCRYPTION_KEY}
        container      caddy-certs
        prefix         production
        lease_duration 30
        create_container false
    }
}

Service principal auth uses Azure AD client credentials. The account_url is the full blob service endpoint — this supports sovereign clouds (e.g. .blob.core.chinacloudapi.cn), private endpoints, and Azurite for local testing.

JSON config

{
  "storage": {
    "module": "azure_blob",
    "container_sas_url": "{env.CADDY_CERTS_SAS_URL}",
    "encryption_key": "{env.CADDY_CERT_ENCRYPTION_KEY}",
    "prefix": "production",
    "lease_duration": 30
  }
}

Options

How it works

Storage

CertMagic keys (e.g., certificates/acme-v02.api.letsencrypt.org-directory/example.com/example.com.crt) are mapped directly to Azure blob names within the configured container. An optional prefix namespaces all blobs.

Distributed locking

When CertMagic needs to acquire a lock (e.g., for certificate renewal), the plugin:

1. Creates a lock blob at locks/{name} (idempotent — skips if it already exists)
2. Acquires an Azure Blob Lease on the lock blob
3. Starts a background goroutine that renews the lease at 2/3 of the lease duration
4. On unlock, cancels the renewal goroutine and releases the lease

If a Caddy instance crashes, the lease expires automatically after lease_duration seconds, allowing another instance to acquire the lock.

Lease duration tradeoffs

Lock blob cleanup

The plugin creates empty blobs at locks/{name} to serve as lease targets. By default, these blobs are not deleted after the lease is released, which means they accumulate over time.

Two cleanup strategies are available:

Option 1: clean_lock_blobs (simple)

Set clean_lock_blobs in your Caddyfile or JSON config. The plugin will delete each lock blob immediately after releasing the lease. This adds one extra API call per unlock but keeps the container tidy.

Note: If a Caddy instance crashes before unlocking, the lock blob will remain. This is harmless — the lease expires automatically and the blob will be cleaned up on the next successful lock/unlock cycle for that name.

Option 2: Azure Blob lifecycle management policy (recommended for production)

Use an Azure lifecycle management policy to automatically delete old lock blobs. This handles crash-orphaned blobs without any plugin-side logic:

az storage account management-policy create \
  --account-name caddycerts \
  --resource-group mygroup \
  --policy '{
    "rules": [{
      "enabled": true,
      "name": "cleanup-lock-blobs",
      "type": "Lifecycle",
      "definition": {
        "filters": {
          "blobTypes": ["blockBlob"],
          "prefixMatch": ["caddy-certs/locks/"]
        },
        "actions": {
          "baseBlob": {
            "delete": {
              "daysAfterModificationGreaterThan": 30
            }
          }
        }
      }
    }]
  }'

Adjust prefixMatch to include your container name and any configured prefix (e.g., caddy-certs/production/locks/).

Azure setup

Create a storage account

az storage account create \
  --name caddycerts \
  --resource-group mygroup \
  --location eastus \
  --sku Standard_LRS

# Get the connection string
az storage account show-connection-string \
  --name caddycerts \
  --resource-group mygroup \
  --output tsv

Permissions

Connection string

The connection string provides account-level access. If create_container is true (the default), the identity also needs permission to create containers. For tighter RBAC, pre-create the container and set create_container false.

Container SAS URL (recommended)

A container SAS URL restricts access to a single container. Required SAS permissions:

• Read (r) — load certificates, keys, and lock blobs
• Write (w) — store certificates/keys, acquire/renew blob leases
• Delete (d) — delete certificates/keys, break blob leases
• List (l) — list blobs for directory semantics

Generate a SAS with a stored access policy for revocability:

# Create a stored access policy
az storage container policy create \
  --container-name caddy-certs \
  --account-name caddycerts \
  --name caddy-rw \
  --permissions rwdl \
  --expiry "$(date -u -v+2y '+%Y-%m-%dT%H:%M:%SZ')"

# Generate a SAS URL from the policy
ACCOUNT="caddycerts"
CONTAINER="caddy-certs"
SAS=$(az storage container generate-sas \
  --account-name "$ACCOUNT" \
  --name "$CONTAINER" \
  --policy-name caddy-rw \
  --https-only \
  -o tsv)
echo "https://${ACCOUNT}.blob.core.windows.net/${CONTAINER}?${SAS}"

Pre-create the container since SAS tokens can't create containers:

az storage container create \
  --name caddy-certs \
  --account-name caddycerts \
  --auth-mode login

Service principal

Create an Azure AD app registration and assign the Storage Blob Data Contributor role on the storage account (or container, for tighter scoping):

# Create the app registration and service principal
az ad app create --display-name caddy-certs-sp
APP_ID=$(az ad app list --display-name caddy-certs-sp --query '[0].appId' -o tsv)
az ad sp create --id "$APP_ID"

# Create a client secret
az ad app credential reset --id "$APP_ID" --query password -o tsv

# Assign Storage Blob Data Contributor on the storage account
SUBSCRIPTION_ID=$(az account show --query id -o tsv)
az role assignment create \
  --assignee "$APP_ID" \
  --role "Storage Blob Data Contributor" \
  --scope "/subscriptions/${SUBSCRIPTION_ID}/resourceGroups/mygroup/providers/Microsoft.Storage/storageAccounts/caddycerts"

If create_container is true, the principal also needs container-create permission (included in Storage Blob Data Contributor). For tighter RBAC, pre-create the container and set create_container false.

Testing

Unit tests

go test -v ./...

Integration tests (requires Azurite)

# Start Azurite
docker run -d -p 10000:10000 mcr.microsoft.com/azure-storage/azurite azurite-blob --blobHost 0.0.0.0

# Run integration tests
go test -tags integration -v ./...

Or with a real Azure Storage account:

AZURE_STORAGE_CONNECTION_STRING="..." go test -tags integration -v ./...

License

MIT