ebrianne/cert-manager-webhook-duckdns

ACME webhook for DuckDNS (cert-manager-webhook-duckdns)

cert-manager-webhook-duckdns是cert-manager的ACME webhook组件。它为cert-manager提供ACME（即Let's Encrypt）webhook功能，支持通过DuckDNS执行DNS-01挑战。这允许为Kubernetes中的非HTTP服务协议提供Let's Encrypt证书，还可申请通配符证书。其内部通过DuckDNS API与DuckDNS进行通信。

引用[ACME DNS-01挑战]的说明：

此挑战要求您通过在域名下的TXT记录中放置特定值来证明您控制该域名的DNS。它比HTTP-01配置更复杂，但可在HTTP-01无法使用的场景中工作，还允许签发通配符证书。Let's Encrypt向ACME客户端提供令牌后，客户端会根据该令牌和账户密钥生成TXT记录，并将其放在_acme-challenge.<您的域名>。然后Let's Encrypt会查询DNS系统中的该记录，若匹配则可继续签发证书！

镜像概述

该镜像提供了与cert-manager集成的webhook服务，用于处理DuckDNS的DNS-01挑战，实现Kubernetes环境中证书的自动化管理。

核心功能与特性

• 与cert-manager无缝集成，支持ACME DNS-01挑战
• 通过DuckDNS API自动管理DNS TXT记录
• 支持为非HTTP服务（如HTTPS、SSH等）获取证书
• 支持申请通配符证书
• 提供Helm图表便于在Kubernetes中部署

兼容性

已在cert-manager v1.0.1和Kubernetes v0.17.x（amd64架构）上测试。理论上支持其他硬件平台，但未经过验证。

镜像信息

预构建镜像托管于Docker Hub：

ebrianne/cert-manager-webhook-duckdns

https://hub.docker.com/repository/docker/ebrianne/cert-manager-webhook-duckdns可在Docker Hub查看。

使用场景

• Kubernetes集群中需要为非HTTP服务（如数据库、消息队列）配置TLS证书
• 需要使用通配符证书保护多个子域名
• 无法通过HTTP-01挑战（如服务未暴露HTTP端口或位于防火墙后）的场景

使用方法

前提条件

• 已安装Kubernetes集群
• 已安装Helm
• 拥有DuckDNS账户、域名及API令牌

安装步骤

1. 安装cert-manager

使用Helm添加cert-manager仓库并安装：

shell
helm repo add jetstack https://charts.jetstack.io
helm repo update

helm install \
cert-manager jetstack/cert-manager \
--namespace cert-manager \
--version v1.2.0 \
--set 'extraArgs={--dns01-recursive-nameservers=8.8.8.8:53\,1.1.1.1:53}' \
--create-namespace \
--set installCRDs=true

# 监控pod状态
kubectl get pods --namespace cert-manager --watch

注意：extraArgs中的DNS服务器配置需参考官方文档
注意：确保cert-manager的CRD版本与Helm图表的应用版本匹配，可通过helm search repo jetstack查看

2. 部署webhook

可通过本地构建或Helm仓库部署：

本地构建部署：

shell
helm install cert-manager-webhook-duckdns \
    --namespace cert-manager \
    --set duckdns.token='<您的DuckDNS令牌>' \
    --set clusterIssuer.production.create=true \
    --set clusterIssuer.staging.create=true \
    --set clusterIssuer.email=<您的邮箱> \
    --set logLevel=2 \
    ./deploy/cert-manager-webhook-duckdns

Helm仓库部署（使用https://github.com/ebrianne/helm-charts仓库）：

shell
helm install cert-manager-webhook-duckdns \
    --namespace cert-manager \
    --set duckdns.token='<您的DuckDNS令牌>' \
    --set clusterIssuer.production.create=true \
    --set clusterIssuer.staging.create=true \
    --set clusterIssuer.email=<您的邮箱> \
    --set logLevel=2 \
    ebrianne.github.io/cert-manager-webhook-duckdns

验证部署：

shell
# 查看pod状态
kubectl get pods -n cert-manager --watch
# 查看日志（替换XYZ为实际pod名称）
kubectl logs -n cert-manager cert-manager-webhook-duckdns-XYZ

3. 申请证书

为目标域名创建Certificate资源：

shell
DOMAIN="example.duckdns.org"  # 替换为您的DuckDNS域名
cat << EOF | sed "s/example.duckdns.org/$DOMAIN/" | kubectl apply -f -
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: $DOMAIN
  namespace: services
spec:
  dnsNames:
  - '$DOMAIN'
  issuerRef:
    name: cert-manager-webhook-duckdns-production
    kind: ClusterIssuer
  secretName: $DOMAIN-tls
EOF

验证证书状态：

shell
# 查看证书详情
kubectl describe certificate $DOMAIN -n services
# 查看证书密钥信息
kubectl get secret $DOMAIN-tls -n services -o yaml

卸载步骤

卸载webhook

shell
helm uninstall cert-manager-webhook-duckdns --namespace cert-manager
kubectl delete duckdns-credentials

卸载cert-manager

参考官方卸载文档。

一致性测试

该测试并非传统单元测试，而是在类Kubernetes环境中调用webhook，实际与DuckDNS API交互，创建并验证TXT记录。

测试步骤

1. 准备测试配置：

shell
cp testdata/duckdns/api-key.yml.sample testdata/duckdns/api-key.yml
# 将DuckDNS令牌base64编码后填入api-key.yml
echo -n $YOUR_DUCKDNS_TOKEN | base64  # 复制输出结果
$EDITOR testdata/duckdns/api-key.yml  # 将复制的base64值填入apiKey字段

2. 获取测试工具：

shell
./scripts/fetch-test-binaries.sh

3. 运行测试（替换example.com为您的DuckDNS域名）：

shell
TEST_ZONE_NAME=example.com. DNS_NAME=example.com go test -v .

注意：测试会实际操作DuckDNS DNS记录，需确保拥有该域名的管理权限。