baarde/cert-manager-webhook-ovh

OVH Webhook for Cert Manager 镜像文档

1. 镜像概述

OVH Webhook for Cert Manager是Cert Manager的扩展组件，专为集成OVH DNS服务设计，通过ACME DNS-01挑战验证机制实现SSL/TLS证书的自动化签发与管理。该镜像作为Cert Manager的Webhook接口，桥接ACME证书颁发机构（如Let's Encrypt）与OVH DNS服务，实现域名所有权验证及证书生命周期的全自动化管理。

2. 核心功能与特性

• ACME DNS-01验证支持：通过OVH DNS服务自动创建和清理_acme-challenge验证记录，完成域名所有权验证
• OVH API深度集成：安全对接OVH DNS API，支持域名解析记录的动态管理
• 证书生命周期自动化：自动处理证书申请、签发、续期及替换流程，避免人工干预
• 多场景证书支持：兼容单域名、多域名及通配符域名证书（如*.example.com）
• 灵活配置：支持自定义OVH API端点、权限范围及证书参数，适配不同OVH服务区域
• 高可靠性：与Cert Manager原生接口兼容，支持故障重试与状态监控

3. 使用场景与适用范围

• 基于OVH DNS的Kubernetes集群：在使用OVH DNS服务的K8s环境中实现证书自动化管理
• 多域名Web服务：需为多个子域名或通配符域名统一管理证书的企业网站、电商平台
• DevOps自动化流程：集成到CI/CD pipeline，实现应用部署时的证书自动配置
• 合规性要求场景：需满足HTTPS强制要求的***、政务等对证书有效期敏感的业务系统
• 高可用架构：需避免证书过期导致服务中断的核心生产环境

4. 使用方法与配置说明

4.1 前置条件

• Kubernetes集群（v1.19+）
• Cert Manager（v1.0+）已部署至集群
• OVH API凭证（包含Application Key、Application Secret、Consumer Key），需具备以下权限：
  • GET /domain/zone/*（读取DNS区域）
  • POST /domain/zone/*（创建DNS记录）
  • DELETE /domain/zone/*（删除DNS记录）

4.2 获取OVH API凭证

1. 登录OVH开发者控制台
2. 创建应用并获取Application Key和Application Secret
3. 生成Consumer Key，设置权限范围为上述DNS操作权限，记录生成的凭证

4.3 部署Webhook

4.3.1 Helm部署（推荐）

bash
# 添加Helm仓库
helm repo add ovh-webhook https://ovh.github.io/cert-manager-webhook-ovh
helm repo update

# 部署Webhook
helm install ovh-webhook ovh-webhook/cert-manager-webhook-ovh \
  --namespace cert-manager \
  --create-namespace \
  --set groupName=acme.yourdomain.com  # 自定义API组名称，需与后续Issuer配置一致

4.3.2 手动部署（Docker镜像直接使用）

bash
# 拉取镜像
docker pull ovhcom/cert-manager-webhook-ovh:latest

# 运行容器（仅用于测试，生产环境建议通过K8s Deployment部署）
docker run -d \
  --name ovh-webhook \
  -p 443:443 \
  -e GROUP_NAME=acme.yourdomain.com \
  -e METRICS_ADDR=:8080 \
  -e HEALTH_ADDR=:8081 \
  ovhcom/cert-manager-webhook-ovh:latest

4.4 配置OVH凭证Secret

创建存储OVH API凭证的Kubernetes Secret：

yaml
apiVersion: v1
kind: Secret
metadata:
  name: ovh-credentials
  namespace: cert-manager  # 需与Cert Manager同命名空间
type: Opaque
data:
  application-key: <base64编码的Application Key>  # 示例：echo -n "your-key" | base64
  application-secret: <base64编码的Application Secret>
  consumer-key: <base64编码的Consumer Key>
  endpoint: <base64编码的OVH API端点>  # 可选值：ovh-eu/ovh-ca/ovh-us

4.5 配置Issuer/ClusterIssuer

创建ACME证书颁发者配置，指定OVH Webhook作为DNS验证器：

yaml
apiVersion: cert-manager.io/v1
kind: ClusterIssuer  # 集群级颁发者，适用于多命名空间
metadata:
  name: ovh-acme-issuer
spec:
  acme:
    server: https://acme-v02.api.letsencrypt.org/directory  # 生产环境
    # server: https://acme-staging-v02.api.letsencrypt.org/directory  # 测试环境（无速率限制）
    email: admin@example.com  # 证书过期通知邮箱
    privateKeySecretRef:
      name: ovh-acme-issuer-private-key  # 存储ACME账户私钥的Secret名称
    solvers:
    - dns01:
        webhook:
          groupName: acme.yourdomain.com  # 需与Webhook部署时的GROUP_NAME一致
          solverName: ovh  # 固定值，对应Webhook solver名称
          config:
            ovhSecretRef:
              name: ovh-credentials  # 引用4.4节创建的Secret
              key: application-key
              secretKey: application-secret
              consumerKey: consumer-key
              endpoint: endpoint
            zoneName: example.com  # OVH域名根 zone（如管理子域名，填写父域名）

4.6 申请证书

创建Certificate资源申请证书：

yaml
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: example-com-cert
  namespace: default  # 目标应用所在命名空间
spec:
  secretName: example-com-tls  # 存储证书的Secret名称（应用需挂载此Secret）
  issuerRef:
    name: ovh-acme-issuer    # 引用4.5节创建的Issuer/ClusterIssuer
    kind: ClusterIssuer
  dnsNames:                  # 需签发证书的域名列表
  - example.com
  - www.example.com
  - "*.example.com"          # 通配符域名（需配合DNS-01验证）
  duration: 2160h            # 证书有效期（默认90天）
  renewBefore: 360h          # 提前续期时间（默认30天）

4.7 验证部署

检查证书状态

bash
kubectl get certificate example-com-cert -n default

输出示例（就绪状态）：

NAME               READY   SECRET             ISSUER              STATUS                                          AGE
example-com-cert   True    example-com-tls    ovh-acme-issuer     Certificate is up to date and has not expired   10m

检查Secret内容

bash
kubectl describe secret example-com-tls -n default

确认包含tls.crt（证书）和tls.key（私钥）字段。

5. 配置参数说明

5.1 OVH API凭证参数

5.2 Webhook运行参数

6. 常见问题排查

6.1 证书申请失败（Pending状态）

• 排查步骤：
  1. 检查Cert Manager日志：kubectl logs -n cert-manager deploy/cert-manager -f
  2. 检查Webhook日志：kubectl logs -n cert-manager deploy/ovh-webhook -f
  3. 验证OVH API凭证权限：通过OVH API测试工具确认凭证是否具备DNS记录读写权限

6.2 Webhook服务不可达

• 可能原因：
  • Webhook Deployment未正常运行：kubectl get pods -n cert-manager
  • 网络策略限制：检查是否有NetworkPolicy阻止Cert Manager访问Webhook服务（默认端口443）
  • 证书问题：Webhook TLS证书无效或未正确挂载

6.3 OVH API调用失败

• 常见错误：
  • 403 Forbidden：检查Consumer Key权限是否包含GET /domain/zone/*和POST /domain/zone/*
  • 404 Not Found：确认zoneName配置与OVH域名一致（需填写根域名，如example.com而非sub.example.com）
  • 503 Service Unavailable：OVH API服务暂时不可用，可稍后重试或切换API端点

6.4 证书续期失败

• 排查方向：
  • 检查证书renewBefore配置是否早于证书有效期的1/3
  • 确认OVH API凭证未过期（Consumer Key默认有效期可配置）
  • 检查集群时间同步（NTP服务异常可能导致时间戳验证失败）