wjiec/alidns-webhook

Alidns-Webhook

[![Go Report Card] ] [![GitHub license] ]

概述

alidns-webhook 是一个适用于 [cert-manager] 的通用 ACME 求解器，用于通过阿里云 DNS 完成 ACME DNS01 验证。

快速开始

以下步骤详细说明如何配置并在集群中部署该 webhook，以对接阿里云 DNS。

安装 webhook

前置条件

安装前请确保已正确部署 cert-manager。若未安装，可参考 [cert-manager 官方安装文档][1]。

部署命令

使用 Helm 部署 alidns-webhook：

bash
helm upgrade --install alidns-webhook alidns-webhook \
    --repo [] \
    --namespace cert-manager --create-namespace \
    --set groupName=acme.yourcompany.com  # 替换为自定义域名（如 acme.example.com）

注意：若通过 bitnami 仓库安装 cert-manager，需额外添加参数 --set certManager.serviceAccountName=cert-manager-controller 以指定正确的 ServiceAccount。

配置 Issuer

创建访问凭证 Secret

先创建存储阿里云 AccessKey 的 Secret，用于 API 调用鉴权：

yaml
# alidns-secret.yaml
apiVersion: v1
kind: Secret
metadata:
  name: alidns-secret
  namespace: cert-manager
stringData:
  access-key-id: "你的阿里云 AccessKey ID"       # 替换为实际 AccessKey ID
  access-key-secret: "你的阿里云 AccessKey Secret" # 替换为实际 AccessKey Secret

创建 ClusterIssuer

创建 ACME 集群级 Issuer，配置 DNS01 验证器对接 alidns-webhook：

yaml
# example-cluster-issuer.yaml
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: example-acme-issuer
spec:
  acme:
    server: []  # Let's Encrypt 生产环境
    # server: []  # 测试环境（推荐先测试）
    email: [邮箱已删除]  # 替换为管理员邮箱（用于证书过期通知）
    privateKeySecretRef:
      name: example-acme-account-key  # 存储 ACME 账户私钥的 Secret 名称
    solvers:
      - dns01:
          webhook:
            groupName: acme.yourcompany.com  # 必须与 Helm 部署时的 groupName 一致
            solverName: alidns
            config:
              region: "cn-hangzhou"  # 可选，默认 cn-hangzhou
              accessKeyIdRef:
                name: alidns-secret  # 引用上述创建的 Secret 名称
                key: access-key-id
              accessKeySecretRef:
                name: alidns-secret
                key: access-key-secret

应用配置

执行以下命令创建资源：

bash
kubectl apply -f alidns-secret.yaml
kubectl apply -f example-cluster-issuer.yaml

申请证书

可通过两种方式使用上述 Issuer 申请证书：直接在 Ingress 中配置，或创建独立的 Certificate 资源。

方式一：通过 Ingress 自动签发

在 Ingress 资源中添加 cert-manager 注解，自动触发证书签发：

yaml
# example-ingress.yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: example-ingress
  annotations:
    cert-manager.io/cluster-issuer: "example-acme-issuer"  # 引用上述 ClusterIssuer 名称
spec:
  tls:
  - hosts:
    - foo.example.com  # 替换为实际域名
    secretName: foo-example-tls  # 存储证书的 Secret 名称（自动创建）
  rules:
  - host: foo.example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: your-backend-service  # 替换为实际后端服务名称
            port:
              number: 80

方式二：创建独立 Certificate 资源

手动定义 Certificate 资源，显式指定域名和签发配置：

yaml
# example-certificate.yaml
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: example-com-cert
spec:
  secretName: example-com-tls  # 证书存储 Secret 名称
  commonName: example.com
  dnsNames:
    - example.com
    - "*.example.com"  # 支持泛域名
  issuerRef:
    name: example-acme-issuer
    kind: ClusterIssuer  # 若使用命名空间级 Issuer，此处改为 Issuer 并指定 namespace

创建后，cert-manager 会自动向 Let's Encrypt 申请证书，并将结果存储在指定的 Secret 中，后续可在 Ingress 或 Service 中引用该 Secret。

版本兼容性

许可证

本项目基于 [MIT 许可证] 开源。

[1]: []]: []