darranshepherd/acmeazure

AcmeAzure 镜像文档

镜像概述和主要用途

AcmeAzure是一个Docker容器，用于从Let's Encrypt请求SSL证书并自动安装到Azure WebApp。通过在Azure Container Instance中运行，容器利用托管服务身份（Managed Service Identity）登录Azure CLI，使用DNS挑战方式向Let's Encrypt发起证书请求，自动在Azure DNS Zone中创建所需的TXT记录，并将生成的证书上传至Azure WebApp并配置SSL绑定。通过将/etc/letsencrypt目录挂载到Azure Files共享，容器具备幂等性，仅在证书即将过期时才请求新证书。

核心功能和特性

• 自动证书请求：使用Certbot向Let's Encrypt发起SSL证书请求
• DNS挑战处理：自动在Azure DNS Zone中创建和清理TXT记录以完成DNS验证
• 证书部署：将生成的证书自动上传至Azure WebApp并配置SSL绑定
• 幂等性操作：通过Azure Files共享存储证书，仅在证书即将过期（<30天）时更新
• 通配符证书支持：可选择生成包含裸域和通配符域的证书（如example.com和*.example.com）
• 灵活配置：支持自定义ACME服务器URL（如测试环境）

使用场景和适用范围

适用于需要为Azure WebApp配置SSL证书的场景，尤其适合需要自动化证书申请、更新和部署的用户。例如：

• 为单个Azure WebApp配置HTTPS
• 为多个子域名（通过通配符证书）配置HTTPS
• 定期自动更新即将过期的SSL证书

使用方法和配置说明

环境变量

Docker部署示例（Azure Container Instance）

bash
az container create \
  --resource-group myResourceGroup \
  --name acmeazure \
  --image darranshepherd/acmeazure \
  --assign-identity $resourceID \
  --restart-policy Never \
 --azure-file-volume-account-name storageaccountname \
  --azure-file-volume-account-key storageaccountkey \
  --azure-file-volume-share-name certbot \
  --azure-file-volume-mount-path /etc/letsencrypt \
  --environment-variables EMAIL="foo@bar.com" DOMAIN=bar.com RESOURCE_GROUP=myResourceGroup ZONE_NAME=bar.com APP_SERVICE=appservice

手动运行步骤

1. 打开安装了Azure CLI的PowerShell终端
2. 创建托管服务身份（MSI）：

   bash
   az identity create --resource-group myResourceGroup --name letsencrypt
   

3. 运行Create-Certificate.ps1脚本，传入必要参数：

   powershell
   .\Create-Certificate.ps1 `
       -Email "foo@bar.com" `
       -ResourceGroup myResourceGroup `
       -Location "North Europe" `
       -IdentityName letsencrypt `
       -StorageAccount storageaccountname `
       -StorageKey aaaaaaaaaaaaaaaaaaaa== `
       -StorageShare sharename `
       -Domain bar.com `
       -ZoneName bar.com `
       -AppService appservice `
       -Wildcard "true" `
       -AcmeServer "https://acme-staging-v02.api.letsencrypt.org/directory"
   

自动运行说明

目前，Logic Apps连接器和Azure Automation中的Azure RM PowerShell cmdlet尚不支持为容器组启用MSI。待支持后，本文档将更新自动化运行容器的详细步骤。

工作原理

容器运行时执行acmeazure.sh脚本，流程如下：

1. 使用托管服务身份登录Azure CLI
2. 执行Certbot客户端，传入目标域名，请求DNS挑战，并指定钩子脚本处理DNS验证和证书部署
3. DNS挑战处理：azurednsauthenticator.sh在Azure DNS Zone中创建所需TXT记录；azurednscleanup.sh在验证完成后清理该记录
4. 证书部署：若证书已颁发或更新，Certbot调用azurewebappbind.sh，将证书链生成PKCS#12 (.pfx)文件，上传至WebApp并创建SSL绑定
5. 符号链接处理：由于Azure Files不支持符号链接（Certbot必需），/etc/letsencrypt目录的文件存储在tar归档中，容器首次运行时提取以保留符号链接

计划改进

• ✅ 安装最新版Certbot（原apk安装的0.19.0不支持ACME V2）
• ✅ 实现幂等性，仅在证书过期前<30天时更新
• ✅ 支持挂载持久卷用于/etc/letsencrypt
• ✅ 支持通配符证书
• 支持单证书多域名
• 支持单证书多WebApp
• 研究使用KeyVault部署证书至WebApp（参考Web App Certificate）
• 探索比资源组级别Contributor更受限的权限范围