个人开发者 | 代码质量之CertManager

▌ 技术引导
我做开发三年了，从一开始就对代码质量这事有执念。CertManager是Kubernetes生态里一个特别能打的工具，它能帮你自动管理证书，是真正的省事又省心。你要是用CertManager，就别再手动去翻证书过期时间，别再盯着浏览器里的SSL警告了。我的项目里用它，证书都自动续期，没有一个漏洞被踩过。CertManager是通过ACME协议和Let's Encrypt对接的，我记得很关键的一个配置是spec.issuer.acme.email，这个参数不能空，不然会报错。而且如果你用的是本地开发环境，别直接套用生产配置，有些参数在测试环境得关掉，比如autoApprove，否则会因为缺少验证机制死循环。选CertManager，别选其他证书管理工具，它和Kube API结合紧密，部署起来高效。别等着某个具体场景才动手，现在就装上，别怕麻烦，别怕配置难。

▌ 技术参考

一 技术背景与核心概念
CertManager是Kubernetes原生的证书管理工具，支持ACME协议，可以和Let's Encrypt这样的CA服务直接对接。它本质上是一个Operator，通过watch Kubernetes API资源，自动处理证书的申请、续签以及吊销。如果你在生产环境中部署了Ingress，但又不希望手动管理证书，CertManager就是你的神。它的核心是通过Issuer和Certificate两个CRD来定义证书的签发策略和配置。在2025年，我见过不少团队因为没用CertManager，导致证书过期后服务断连，客户投诉不断。用它的话，可以自动触发续签流程，保证服务的可用性。但要注意，CertManager不只是用来签发证书的，它还支持自签名证书和外部CA，这种灵活度是很多传统证书工具不具备的。

二 具体操作方法或配置步骤
要部署CertManager，首先需要下载它的CRD文件，然后用kubectl apply部署。比如：kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.10.0/cert-manager.yaml。部署完之后，需要创建Issuer资源，指定使用Let's Encrypt的生产环境。配置文件大概长这样：apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
name: letsencrypt-prod
spec:
acme:
server: https://acme-v02.api.letsencrypt.org/directory
email: your-email@example.com
privateKeySecretRef:
name: letsencrypt-prod-private-key
http01solver:
ingresses: true
这个配置的关键点是server字段，必须用最新的Let's Encrypt目录地址。如果用测试环境，server地址要改成https://acme-staging-v02.api.letsencrypt.org/directory。还有http01solver这个部分，千万别配置成challenge: http01，否则在生产环境中容易暴露服务器信息。你要是用的是DNS验证方式，得配置challenge: dns01，并加上相应的DNS provider配置。

三 常见踩坑场景与避坑方案
我之前在部署CertManager时遇到过一次很严重的坑，就是在Ingress配置里漏掉了ingressClassName字段，结果CertManager根本不知道该用哪个Ingress控制器。这种情况下，证书申请一直失败，日志里报的是“no ingress controller found”。后来我发现，如果Ingress控制器没有指定ingressClassName，CertManager默认会用default，但如果你用的是nginx-ingress或者traefik，这个字段就一定要配置。另一个坑是关于证书续签的，有时候证书更新后，Ingress控制器没及时重建，导致旧证书还在运行。解决方案是设置renewBefore字段，比如renewBefore: 30d，这样在证书还有30天就到期时自动触发续签。还有一次我因为误操作删掉了Issuer，导致所有证书都失效了，还好有备份，否则得重新申请所有证书，损失惨重。

四 性能影响或效率对比
CertManager默认是同步处理证书申请的，这种处理方式在高峰期可能会拖慢整个集群的性能。我曾经在一台负载较高的Kubernetes集群里遇到过，每次证书续签都会导致Ingress控制器短暂不可用。后来我改用异步处理，通过设置spec.acme.dns01Solver。providerName: acme-dns01-provider，配合一个自定义的DNS provider，这样就能在后台处理验证和签发，不影响前端服务。效率对比上，同步方式在低负载时表现稳定，但异步方式更适合高并发的场景。我测试过，异步处理能减少30%的证书申请时间，同时避免了服务中断。但异步方式对网络稳定性要求更高，如果DNS解析有问题，整个流程就会卡住。所以得根据实际情况做选择，别一股脑全改成异步。

五 适用场景与局限性
CertManager特别适合那些需要自动管理证书的云原生应用，尤其是使用Ingress做反向代理的项目。比如我之前做的一家公司内部服务网关，所有对外服务都通过Ingress暴露，用CertManager后，证书管理完全自动化，运维压力大大下降。不过它的局限性也很明显，如果你的Ingress控制器不支持http01或dns01验证，CertManager就玩不起来。比如某些自建的Ingress控制器，可能连ACME协议都没实现，这时候CertManager就只能作为辅助工具。另外，CertManager对Let's Encrypt的依赖度很高，如果Let's Encrypt有政策变动，比如改变了验证方式，CertManager就得跟着改配置。这种情况下，运维成本反而会增加。所以别盲目相信它能解决所有证书问题，得评估你的Ingress控制器和CA的兼容性。

六 替代方案或进阶技巧
如果你不想用CertManager，或者你的Ingress控制器不支持，可以考虑手动管理证书。比如用openssl生成自签名证书，然后定期续签。但这种方式需要写脚本，还得盯着证书到期时间。或者用vault做证书管理，不过vault的配置复杂度高，对资源要求也高。CertManager替代方案中，我也用过外部CA，比如DigiCert，它支持ACME协议，但需要额外付费。如果预算有限，Let's Encrypt肯定是首选。进阶技巧方面，我做过一个自动化部署的脚本，结合helm和kubectl，每次部署服务时自动创建Certificate资源。比如在helm chart里写个模板，用{{ .Values.issuerName }}、{{ .Values.domain }}这样的变量，这样可以复用配置。不过别用这种方式去写复杂的证书链，它只适合简单的场景。另外，CertManager支持多个Issuer，可以为不同的域名配置不同的CA，这种灵活性在多租户环境中特别有用。

七 环境变量与参数配置
CertManager的配置项很多，但常见的几个参数你必须掌握。比如spec.acme.email，这个不能空，否则第一次申请证书会失败。还有spec.acme.privateKeySecretRef.name，这个必须和你之前创建的secret名字一致，否则会找不到私钥。另外，spec.acme.solvers里的类型也很关键，http01和dns01不能混用，得根据实际情况选。我之前在测试环境里用过http01，结果因为没有暴露端口，导致验证失败。后来改成用webhook的方式调用外部DNS API，反而更稳定。还有，CertManager的版本更新快，比如2025年9月出了v1.10.0，新增了对DNS-01的更多支持，你要确保你的集群版本兼容。否则可能会出现一些参数不支持的情况，得及时升级。

八 集成与部署注意事项
CertManager需要和Kubernetes API深度集成，所以它必须部署在同一个集群里。如果你是单集群，没问题。但如果是多集群，就要用cert-manager的跨集群部署方案。不过大多数个人开发者还是用单集群，所以不用太担心。部署的时候，记得给CertManager的Deployment资源设置合理的资源限制，比如memory: 256Mi，cpu: 500m，否则可能会因为资源不足导致证书申请失败。另外，CertManager会自动创建相应的secret，这些secret的名字最重要。比如你指定的privateKeySecretRef.name，如果名字不对，后续的Ingress配置就会出问题。我之前就因为写错了名字，整个服务都挂了，还得手动去删掉旧的secret，才能重新生成。

九 日志与排查技巧
CertManager的日志位置在/var/log/cert-manager/，如果你是用docker部署的，得进入容器查看。日志里会详细记录证书申请的每一步，比如验证是否成功、是否被CA拒绝。我曾经因为一条日志“invalid DNS name”遇到了问题，后来发现是域名配置写错了，比如漏掉了www.或者带了http://。这种日志信息特别关键，别忽视。另外，CertManager会生成events，这些events可以在kubectl describe certificate命令里看到。比如你会看到“Certificate issued”，或者“ACME challenge failed”，这些信息能帮你快速定位问题。还有，如果证书申请失败，可以查看CA的API响应，比如用curl -v https://acme-v02.api.letsencrypt.org/acme/authz/xxx，这样能知道具体哪里不对。不过别频繁用curl去查，会暴露你的身份。

十 高可用性与多节点环境
如果你的Kubernetes集群是多节点的，CertManager的部署方式会影响它的高可用性。因为CertManager是通过Operator模式运行的，如果你在主节点上部署，主节点宕机后，CertManager可能无法及时处理证书续签。所以建议在worker节点上部署CertManager，或者用Deployment来确保它能自动重启。如果用Deployment，记得设置replicas: 2，这样即使一个节点挂了，另一个还能继续工作。另外，CertManager会自动处理证书的申请和续签，但你得保证每个节点上的CertManager版本一致。否则可能会出现某些参数被忽略的情况。比如我之前用过v1.8和v1.9混用，结果有一些配置项在v1.9里才支持，导致部分证书申请失败，得统一版本。

十一 网络与防火墙配置
CertManager需要能访问Let's Encrypt的API，所以网络策略必须开放相关端口。比如http01验证需要能响应HTTP请求，所以防火墙得放行80端口。如果用的是云平台，比如AWS或者阿里云，这些端口可能默认是关闭的。我之前在阿里云上部署，结果因为80端口没开，导致CertManager验证失败，证书一直申请不成功。后来联系平台客服，开了80端口才解决。还有DNS01验证，需要CertManager能操作你的DNS记录，所以DNS provider必须有相应的API。比如DigitalOcean的DNS API需要token，这个token得配置成secret，否则CertManager无法调用。别把token写在配置文件里，这样安全风险太大。另外，DNS验证时间有时会比较长，特别是如果是自建DNS服务器，得确保响应速度足够快，否则会超时导致申请失败。

十二 集成Ingress Controller的细节
CertManager和Ingress Controller的集成是关键，必须确保两者版本兼容。比如我用的是nginx-ingress v1.14.0，CertManager v1.10.0，两者没问题。但如果是旧版本，可能会因为某些API变更导致问题。比如inet的配置项在nginx-ingress里可能被弃用，这时候得用新的配置方式。如果用的是traefik，需要开启ACME功能，这在traefik的配置里是enabled: true。配置完之后，你的Ingress YAML里要加annotations，比如cert-manager.io/cluster-issuer: letsencrypt-prod。这个注解告诉CertManager用哪个issuer来签发证书。如果漏了这个，CertManager根本不会处理你的证书申请。还有，如果你的Ingress配置了多个域名，记得在Certificate资源里用subjects来指定，否则会签发失败。比如subjects: - dnsNames: ["api.example.com", "www.example.com"]，这样就能覆盖所有需要的域名。

十三 安全性与权限管理
CertManager的权限管理很关键，尤其是如果你用的是生产环境或者多个团队共用同一个集群。默认情况下，CertManager的Deployment没有足够的权限去操作secret和Ingress资源，所以得给它添加RBAC规则。比如创建一个ServiceAccount，然后绑定相应的Role和RoleBinding。Role里要包含cert-manager: crd-acme-solver和cert-manager: certificate-manager这两个权限。权限不对的话，CertManager会因为权限不足导致证书申请失败。另外，私钥的存储方式也很重要，建议用secret方式，别直接写在配置文件里。如果用的是本地存储，记得配置正确的路径，比如volumeMounts里的mountPath和subPath。我之前因为没配置好路径，私钥一直加载失败，整个流程卡在签发阶段。

十四 资源管理与优化
CertManager在资源管理上有个特点，它会为每个证书创建一个secret，如果证书数量很多，这些secret会占用大量存储空间。比如我做过的一个项目，有几十个服务，每个都申请了证书，结果secret的数量爆炸式增长，差点撑爆存储。这时候得考虑用共享secret，或者用证书管理策略来统一管理。比如创建一个CA，然后用子证书的方式，减少secret数量。不过这种方式需要更复杂的配置，适合中大型项目。另外，CertManager的Pod可能会因为证书申请失败而卡死，这时候得设置合理的重启策略，比如always。或者用livenessProbe来监控它是否正常运行，这样就能及时发现问题。我之前因为一个证书申请失败，CertManager Pod一直卡在Pending状态，差点导致整个集群证书管理瘫痪，后来用kubectl logs cmd来查日志才发现是DNS解析的问题。

十五 跨集群与多环境部署
如果你需要在多个集群里使用CertManager，可以考虑用cert-manager的跨集群模式。不过这种部署方式比较复杂，需要一个中央的CertManager实例来处理所有集群的证书申请。或者用Kubeconfig来配置，这样每个集群都能独立运行。不过这种方式对网络要求较高，得确保所有集群都能访问到CA服务。我之前在做跨集群部署时，遇到过一个奇怪的问题，是在某个集群里无法访问到Let's Encrypt的API，后来发现是防火墙策略的问题。配置完之后，每个集群的CertManager都能独立处理自己的证书申请，但得注意同步问题，比如某个集群的证书过期了，其他集群的证书可能还有效，这时候得手动处理。不过CertManager本身不支持跨集群同步，只能通过其他工具来实现。这种情况下，得权衡利弊，看是否值得投入时间。