1. 项目概述:Kubernetes cert-manager的核心价值
在云原生环境中管理TLS证书一直是个令人头疼的问题。传统方式需要手动生成CSR、提交CA签名、下载证书再部署到集群,整个过程繁琐且容易出错。cert-manager作为Kubernetes原生的证书管理工具,彻底改变了这种状况。
我最早接触cert-manager是在2018年为一个金融项目搭建生产环境时。当时团队每周要处理上百张证书的轮换,手工操作不仅效率低下,还曾因证书过期导致服务中断。引入cert-manager后,证书生命周期实现了全自动化管理,运维效率提升超过80%。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 核心组件解析
2.1 cert-manager架构组成
cert-manager的核心组件采用典型的Kubernetes Operator模式:
- Certificate Controller:监视Certificate资源变更
- Issuer Controller:处理证书签发请求
- ACME Solver:专门处理Let's Encrypt挑战
这些组件通过CustomResourceDefinitions(CRDs)扩展Kubernetes API,主要定义了三种资源类型:
- Issuer/ClusterIssuer:证书颁发机构配置
- Certificate:证书申请规范
- Order/Challenge:ACME协议交互过程
2.2 签发器(Issuer)类型详解
签发器是cert-manager的核心概念,目前支持四种类型:
2.2.1 CA Issuer
使用本地CA证书签发,适合企业内网环境。需要预先生成CA证书并创建Secret:
yaml复制apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
name: ca-issuer
spec:
ca:
secretName: ca-key-pair
2.2.2 SelfSigned Issuer
生成自签名证书,主要用于测试场景。配置最简单但浏览器会报安全警告。
2.2.3 ACME Issuer
与Let's Encrypt等ACME协议CA集成,支持自动续期。生产环境推荐配置:
yaml复制spec:
acme:
server: https://acme-v02.api.letsencrypt.org/directory
email: admin@example.com
privateKeySecretRef:
name: letsencrypt-account-key
solvers:
- http01:
ingress:
class: nginx
2.2.4 Vault Issuer
集成HashiCorp Vault,适合已有Vault基础设施的企业。需要配置Vault角色和认证信息。
3. 生产级安装指南
3.1 前置条件检查
在开始安装前,需要确认:
- Kubernetes集群版本≥1.16
- 已安装kubectl并配置正确上下文
- 集群有互联网访问权限(如需使用ACME)
- 至少2个可用CPU和200MB内存
重要提示:生产环境建议使用cert-manager的webhook验证功能,需要在安装时额外配置
3.2 Helm安装最佳实践
推荐使用Helm 3进行安装,这是目前最稳定的方式:
- 添加jetstack仓库:
bash复制helm repo add jetstack https://charts.jetstack.io
helm repo update
- 创建独立命名空间:
bash复制kubectl create namespace cert-manager
- 安装cert-manager:
bash复制helm install cert-manager jetstack/cert-manager \
--namespace cert-manager \
--version v1.13.1 \
--set installCRDs=true \
--set prometheus.enabled=true \
--set webhook.timeoutSeconds=30
关键参数说明:
installCRDs=true:自动安装CRDprometheus.enabled=true:启用监控webhook.timeoutSeconds:调整webhook超时
3.3 安装验证
执行以下检查:
bash复制kubectl get pods -n cert-manager
应看到cert-manager、cainjector和webhook三个Pod都处于Running状态。
进一步验证签发功能:
bash复制kubectl apply -f - <<EOF
apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
name: test-selfsigned
namespace: default
spec:
selfSigned: {}
EOF
kubectl apply -f - <<EOF
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
name: selfsigned-cert
namespace: default
spec:
dnsNames:
- example.com
secretName: selfsigned-cert-tls
issuerRef:
name: test-selfsigned
EOF
检查证书是否生成:
bash复制kubectl get certificate -n default
4. 高级配置技巧
4.1 证书自动续期策略
cert-manager默认在证书到期前30天开始续期。可以通过Certificate资源调整:
yaml复制spec:
renewBefore: 720h # 提前30天
duration: 2160h # 90天有效期
注意:ACME证书受CA策略限制,Let's Encrypt最多90天
4.2 多集群管理方案
对于跨集群场景,推荐:
- 使用ClusterIssuer而非Namespace级别的Issuer
- 通过GitOps工具同步Certificate资源
- 集中监控所有集群的证书状态
监控配置示例:
yaml复制apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
name: cert-manager
namespace: cert-manager
spec:
endpoints:
- port: http-metrics
selector:
matchLabels:
app.kubernetes.io/instance: cert-manager
4.3 私有CA集成实践
企业内网集成私有CA的完整流程:
- 准备CA证书链:
bash复制openssl genrsa -out ca.key 2048
openssl req -x509 -new -nodes -key ca.key -days 3650 -out ca.crt
- 创建Kubernetes Secret:
bash复制kubectl create secret tls ca-key-pair \
--cert=ca.crt \
--key=ca.key \
--namespace=cert-manager
- 配置CA Issuer:
yaml复制apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
name: private-ca
spec:
ca:
secretName: ca-key-pair
crlDistributionPoints:
- "http://crl.example.com/ca.crl"
5. 故障排查手册
5.1 常见错误代码解析
| 错误代码 | 含义 | 解决方案 |
|---|---|---|
| ErrGetKeyPair | 密钥对获取失败 | 检查Secret是否存在且格式正确 |
| ErrInvalidKeyPair | 密钥对无效 | 验证证书和密钥是否匹配 |
| ErrRegisterACMEAccount | ACME注册失败 | 检查网络连接和邮箱配置 |
| ErrTypeNotSupported | 签发器类型不支持 | 确认API版本和签发器类型 |
5.2 日志分析技巧
查看cert-manager控制器日志:
bash复制kubectl logs -n cert-manager deploy/cert-manager
重点关注以下日志模式:
failed to reconcile certificate:证书签发失败rate limited:ACME请求被限速stored certificate is expired:证书过期未续期
5.3 证书签发状态检查
详细检查证书状态:
bash复制kubectl describe certificate my-cert
关键状态字段:
- Ready:是否可用
- Not After:过期时间
- Events:最近操作记录
6. 生产环境最佳实践
6.1 安全加固建议
- 启用资源配额限制:
yaml复制resources:
limits:
cpu: 500m
memory: 512Mi
- 配置Pod安全策略:
yaml复制securityContext:
runAsNonRoot: true
readOnlyRootFilesystem: true
- 定期轮换ACME账户密钥
6.2 性能优化方案
大规模集群优化建议:
- 为cert-manager配置单独的etcd存储
- 增加控制器并发数:
yaml复制args: - --concurrent-workers=10 - 使用高性能存储卷存放密钥
6.3 备份恢复策略
必须备份的关键数据:
- ACME账户私钥(存储在Secret中)
- 所有Issuer/ClusterIssuer定义
- 所有Certificate定义
推荐使用Velero进行全量备份:
bash复制velero backup create cert-manager-backup \
--include-namespaces cert-manager
7. 实际案例分享
7.1 电商平台证书管理
某跨境电商平台使用cert-manager管理超过500个域名的证书:
- 采用ACME DNS01挑战方式
- 按业务线划分Namespace
- 通过注解自动为Ingress创建证书
典型配置:
yaml复制apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
annotations:
cert-manager.io/cluster-issuer: letsencrypt-prod
spec:
tls:
- hosts:
- shop.example.com
secretName: shop-tls
7.2 混合云证书方案
某金融机构采用混合架构:
- 公网域名使用Let's Encrypt
- 内网服务使用私有CA
- 通过标签选择不同签发器
选择器配置示例:
yaml复制apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
labels:
env: internal
spec:
issuerRef:
name: private-ca
8. 版本升级指南
8.1 v0.16到v1.0迁移
主要变更点:
- API版本从v1alpha2升级到v1
- 默认启用Resource Validation
- 移除对Venafi TPP旧版API支持
迁移步骤:
- 备份所有资源
- 卸载旧版本
- 安装新版本
- 转换API版本:
bash复制
kubectl convert -f old-resources.yaml --output-version cert-manager.io/v1 > new-resources.yaml
8.2 最新版本特性
v1.13重要更新:
- 支持ECDSA P521密钥
- 改进ACME HTTP01挑战性能
- 新增Vault Kubernetes Auth方法
升级注意事项:
- 检查CRD兼容性
- 预留足够回滚时间
- 分阶段逐步升级
