密码学与证书 / 系统课时
部署 cert-manager 控制器
部署 cert-manager 控制器
这一课把 cert-manager 作为 Kubernetes 证书控制平面部署起来,并明确 CRD、控制器、Webhook 与 CA 注入组件各自负责什么。完成后,你能确认 API 已注册、核心 Deployment 已就绪,并知道哪些对象是命名空间级、哪些能力属于整个集群。
学习目标
- 使用 Helm 安装 cert-manager 并同时管理所需 CRD
- 解释 controller、webhook 与 cainjector 在控制循环中的职责
- 通过 CRD、Deployment 与 Pod 状态验证安装是否可用
先确认安装边界
cert-manager 通常部署在独立的 cert-manager 命名空间,但它并不是只为这个命名空间服务。Certificate、Issuer 等资源可以分布在业务命名空间中,而 ClusterIssuer、CRD 本身以及部分准入配置属于集群级资源,因此一个集群通常只部署一套 cert-manager。
它的核心不是“运行一个签证书的 Pod”,而是持续调谐 Kubernetes 对象:用户声明证书目标,控制器观察对象状态,创建后续请求并调用签发器;Webhook 负责准入校验与 API 转换,cainjector 则把受信 CA 数据注入需要校验 TLS 的 Kubernetes 资源。

安装 cert-manager
先确认当前上下文确实指向目标集群,并准备 Helm 3。生产环境应在变更前确认 Kubernetes 与 cert-manager 的兼容范围,并把版本固定在部署代码中,而不是长期追随浮动的 latest。
下面使用 OCI Chart 安装。将 <VERSION> 替换为经过验证的 cert-manager 版本;crds.enabled=true 让同一 Helm Release 管理 CRD。
helm upgrade --install cert-manager oci://quay.io/jetstack/charts/cert-manager \
--version <VERSION> \
--namespace cert-manager \
--create-namespace \
--set crds.enabled=true \
--wait \
--timeout 5m预期输出
NAME: cert-manager
NAMESPACE: cert-manager
STATUS: deployed首次安装时 Helm 可能额外显示“Release 不存在,正在安装”一类提示;Release 名称与最终 STATUS: deployed 才是这里需要确认的结果。
验证 CRD 与基础组件
安装完成后,先确认关键 API 类型存在,再检查三个基础 Deployment。下面的命令只验证控制平面就绪,不代表某个具体 CA 已经配置成功。
kubectl get crd certificates.cert-manager.io certificaterequests.cert-manager.io issuers.cert-manager.io clusterissuers.cert-manager.io
kubectl get deployment -n cert-manager cert-manager cert-manager-webhook cert-manager-cainjector预期输出
NAME CREATED AT
certificates.cert-manager.io <TIME>
certificaterequests.cert-manager.io <TIME>
issuers.cert-manager.io <TIME>
clusterissuers.cert-manager.io <TIME>
NAME READY UP-TO-DATE AVAILABLE AGE
cert-manager 1/1 1 1 <TIME>
cert-manager-webhook 1/1 1 1 <TIME>
cert-manager-cainjector 1/1 1 1 <TIME><TIME> 会随集群实际状态变化。若 CRD 不存在,后续创建 Certificate 或 Issuer 会直接报 API 类型不存在;若 webhook 尚未 Ready,创建或更新 cert-manager 资源时可能出现准入 Webhook 超时或连接失败。
看懂控制器如何工作
controller 采用 Kubernetes 常见的声明式调谐模型:它比较 spec 表达的期望状态与 status 记录的当前状态,并通过创建 CertificateRequest、Order、Challenge 或更新 Secret 等动作逐步逼近期望状态。对象短暂处于 Pending 并不等于失败,关键是观察 Condition、事件与下游对象是否持续推进。
Webhook 位于 API 写入路径上,主要承担校验、默认值和 API 版本转换;它不可用时,资源可能连“创建”都过不了。cainjector 不负责签发证书,它负责维护 CA bundle,使 Kubernetes 中依赖 TLS 校验的 Webhook 或扩展 API 能信任对应服务证书。
安装失败时按层定位
如果 Helm 已部署但资源不可用,优先按“CRD → Deployment/Pod → Webhook → 业务 CR”顺序排查,而不是直接重装。先看 kubectl get pods -n cert-manager 与 kubectl describe 的事件,再检查镜像拉取、RBAC、网络策略以及 API Server 到 webhook Service 的连通性。
当 CRD 已注册、三个基础 Deployment 都 Ready,且创建 cert-manager 资源不再触发准入错误时,控制平面才算具备进入签发器配置阶段的条件。