cert-manager Helm 安装中CRD问题的技术解析

问题背景

在cert-manager v1.15.0版本发布后，部分用户在使用Helm v3安装时遇到了CRD（Custom Resource Definition）无法正确安装的问题。这一问题主要出现在当用户尝试通过extraObjects配置项同时部署ClusterIssuer等自定义资源时。

技术原理分析

Helm与CRD的交互机制

Helm v3对于CRD的处理有其特定的工作流程。当使用Chart apiVersion v2时，Helm期望CRD文件存放在chart包的crds目录下，而不是作为模板渲染。这种设计是为了确保CRD能够在其他资源之前被安装到集群中。

cert-manager的特殊处理

cert-manager项目出于自身考虑，选择将CRD作为模板而非标准CRD文件打包。这种设计在v1.15.0版本前通过installCRDs参数实现，而在v1.15.0版本后改为使用crds.enabled参数控制。

问题复现场景

当用户同时配置以下内容时会出现问题：

1. 启用CRD安装（crds.enabled: true）
2. 在extraObjects中定义ClusterIssuer资源

Helm会先尝试验证ClusterIssuer资源的有效性，而此时CRD尚未安装到集群中，导致验证失败。

解决方案

推荐方案

1. 分步安装：先安装cert-manager及其CRD，待CRD就绪后再创建ClusterIssuer等资源
2. 使用Helm hooks：通过定义post-install hook确保CRD安装完成后再创建资源

配置示例

# 第一步：仅安装cert-manager
crds:
  enabled: true

# 第二步：单独应用ClusterIssuer
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-http01
spec:
  acme:
    email: [e-mail]
    secretKeyRef:
      name: letsencrypt-http01
    server: https://acme-v02.api.letsencrypt.org/directory
    solvers:
      - http01:
          ingress:
            class: nginx

深入理解

这个问题本质上反映了Kubernetes资源依赖管理的复杂性。CRD作为一种特殊的资源类型，需要先于其实例存在。Helm的设计哲学是"声明式"的，它期望所有资源都可以并行创建，这与CRD必须先行存在的刚性要求产生了矛盾。

cert-manager团队选择将CRD作为模板而非标准CRD文件打包，主要是出于对CRD生命周期管理的考虑。这种设计虽然带来了一些使用上的不便，但提供了更灵活的CRD管理能力。

最佳实践建议

1. 对于生产环境，建议将CRD安装与业务资源配置分离
2. 考虑使用Argo CD等GitOps工具实现更精细的资源部署顺序控制
3. 对于测试环境，可以使用kubectl wait命令确保CRD就绪后再创建相关资源

版本兼容性说明

需要注意的是，v1.15.0版本引入的这一变化是向后兼容的。从v1.14.6升级的用户需要将配置中的installCRDs参数迁移为crds.enabled参数，同时调整资源创建顺序。