cert-manager：Kubernetes 集群证书自动签发续期管理部署指南

cert-manager 在 Kubernetes 集群中把证书和证书颁发者（Issuer）作为资源类型引入，简化了获取、续期和使用 TLS 证书的全过程。它支持从多种来源签发证书，包括 Let's Encrypt（ACME）、HashiCorp Vault、CyberArk Certificate Manager，以及集群内部本地签发。它还会在证书到期前的合适时间自动尝试续期，降低中断风险。

一、项目官方信息

项目	信息
GitHub 仓库	https://github.com/cert-manager/cert-manager
官方网站	https://cert-manager.io
开源协议	Apache-2.0
主要语言	Go（约 95.7%）
Star 数	约 14.0k
项目性质	CNCF 项目

cert-manager 可保证证书始终有效、最新，自动在到期前择机续期，免去人工维护的重复劳动。它松耦合地基于 kube-lego 的工作，并借鉴了 kube-cert-manager 等同类项目的经验。

二、官方图片

cert-manager 项目 Logo：

cert-manager 高层架构概览图：

cert-manager 高层架构

三、环境要求

一个可用的 Kubernetes 集群（社区版/云厂商托管均可）。
kubectl 已配置好对集群的访问权限。
网络能访问 quay.io / ghcr.io 镜像仓库与 GitHub Releases。
若用 Let's Encrypt HTTP-01 验证，Ingress 需暴露 80/443；若用 DNS-01，需配置对应 DNS 服务商凭据。

四、完整部署步骤

1. 用 kubectl 安装（官方推荐方式之一）

从 GitHub Releases 下载与你版本对应的 manifest 并直接应用：

# 安装最新稳定版（生产环境建议替换为具体版本号）
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/latest/download/cert-manager.yaml

该 manifest 会创建 cert-manager 命名空间，以及 cert-manager、webhook、cainjector 等组件。

2. 确认组件就绪

kubectl get pods -n cert-manager

等待全部 Pod 变为 Running：

NAME                                      READY   STATUS    RESTARTS   AGE
cert-manager-xxxxxxxxxx-xxxxx             1/1     Running   0          60s
cert-manager-cainjector-xxxxxxxxxx-xxxxx  1/1     Running   0          60s
cert-manager-webhook-xxxxxxxxxx-xxxxx     1/1     Running   0          60s

3. 创建 Issuer（证书颁发者）

以 Let's Encrypt 为例，先创建一个 ClusterIssuer（分两块：staging 测试与正式环境）。新建 cluster-issuer.yaml：

apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-prod
spec:
  acme:
    server: https://acme-v02.api.letsencrypt.org/directory
    email: your@email.org
    privateKeySecretRef:
      name: letsencrypt-prod
    solvers:
    - http01:
        ingress:
          class: nginx

应用：

kubectl apply -f cluster-issuer.yaml

4. 为 Ingress 自动签发证书

cert-manager 最常见的用法是给 Ingress 自动签发 TLS 证书。给 Ingress 加上注解即可：

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: example-ingress
  annotations:
    cert-manager.io/cluster-issuer: "letsencrypt-prod"
spec:
  ingressClassName: nginx
  tls:
  - hosts:
    - example.com
    secretName: example-tls
  rules:
  - host: example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: example-service
            port:
              number: 80

应用后，cert-manager 会自动通过 ACME 验证域名，并把证书写入 example-tls Secret。

5. 验证证书状态

kubectl get certificates
kubectl describe certificate example-tls

当 READY 为 True 且证书包含你的域名时，说明签发成功。

五、使用方法

直接创建 Certificate 资源

除了给 Ingress 加注解，也可以显式创建 Certificate 资源：

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: example-com
spec:
  secretName: example-tls
  issuerRef:
    name: letsencrypt-prod
    kind: ClusterIssuer
  dnsNames:
  - example.com
  - www.example.com

支持的颁发者类型

Let's Encrypt（ACME）：最常用，支持 http01 与 dns01 两种 solver。
HashiCorp Vault：对接内部 Vault PKI。
CyberArk Certificate Manager：企业级证书管理。
集群内自签名/CA 签发：用于内部服务。

开发与构建

cert-manager 支持 Linux 与 macOS 开发环境，构建要求见官方文档 "Building cert-manager"；macOS 有额外工具要求。注意：cert-manager 不提供 Go module 兼容性保证，pkg/ 下代码即使小版本之间也可能发生 breaking 变更；1.8 及以后导入路径为 github.com/cert-manager/cert-manager，之前版本为 github.com/jetstack/cert-manager。

六、常见问题 FAQ

1. Certificate 一直不变成 Ready 怎么办？ 先用 kubectl describe certificate <name> 查看 Events，常见原因是 80 端口未放行导致 http01 验证失败、域名未正确解析、或触发了 Let's Encrypt 速率限制。调试时可先用 staging 的 Issuer 验证。

2. 如何避免触发 Let's Encrypt 速率限制？ 在正式签发前，先用 staging 环境（https://acme-staging-v02.api.letsencrypt.org/directory）测试，确认无误后再切到正式环境。

3. Ingress 注解写了为什么没签发？ 确认注解写法是 cert-manager.io/cluster-issuer: <issuer-name>，且对应的 ClusterIssuer/Issuer 已存在、名称一致；同时 Ingress 里 tls 段的 hosts 要与域名匹配。

4. 想签泛域名证书或内网 DNS 域名怎么办？ http01 无法签泛域名，需要改用 dns01 solver，并在 Issuer 里配置对应 DNS 服务商的凭据 Secret。

5. cert-manager 会自动续期吗？ 会。cert-manager 会在证书到期前的合适时间自动发起续期，把新证书写入同一个 Secret，无需人工干预。

6. 组件起不来怎么办？ 先 kubectl get pods -n cert-manager 看状态，再 kubectl logs 查日志。官方提供完整的 troubleshooting 指南（cert-manager.io/docs/faq/troubleshooting/）和 Kubernetes Slack 的 #cert-manager 频道。

七、跳转链接

GitHub 仓库：https://github.com/cert-manager/cert-manager
官方文档：https://cert-manager.io/docs/
安装指南：https://cert-manager.io/docs/installation/
Nginx Ingress 快速上手：https://cert-manager.io/docs/tutorials/acme/nginx-ingress/