Kubebuilder 中使用 cert-manager 为 Webhook 提供证书与 CA 注入完整指南
Kubebuilder 中使用 cert-manager 为 Webhook 提供证书与 CA 注入完整指南
导读:在 Kubebuilder 生成的控制器项目中,Webhook 服务器必须以 HTTPS 对外提供服务,因此需要一套可信证书颁发与 CA 注入机制。本指南围绕 docs/book/src/cronjob-tutorial/cert-manager.md 展开,讲解如何用 cert-manager 自动签发并轮换 Webhook 证书、通过 CA Injector 与
cert-manager.io/inject-ca-from注解把 CA 注入到MutatingWebhookConfiguration/ValidatingWebhookConfiguration,并结合仓库源码剖析 Kubebuilder 脚手架生成的config/certmanager目录与 kustomize 配置。读完你将掌握从安装 cert-manager 到启用 CA 注入的完整实战流程。
为什么 Webhook 需要证书管理
Kubebuilder 生成的 Webhook(准入控制器)以 HTTPS 服务的形式运行在控制器的 Manager 进程中。Kubernetes API Server 在调用 Webhook 时,会校验服务端证书:
- 证书的
dnsNames必须包含 Webhook Service 的域名(如webhook-service.<namespace>.svc及其.cluster.local形式); - 证书必须由集群信任的 CA 签发,且
caBundle必须被注入到MutatingWebhookConfiguration/ValidatingWebhookConfiguration的clientConfig.caBundle字段中。
手动生成、挂载并轮换这些证书繁琐且易出错,因此 Kubebuilder 官方文档明确推荐使用 cert-manager 来为 Webhook 服务器供给证书。文档同时指出:只要能把证书放到期望的位置,其他方案也可以工作,但 cert-manager 是 Kubebuilder 脚手架默认集成、文档与测试覆盖最完整的方案。
cert-manager 与 CA Injector 的工作原理
cert-manager 生态中有两个关键组件参与证书生命周期管理:
- 证书管理器(Certificate Controller):根据
CertificateCR 的声明式描述(域名、签发者、Secret 名称等)自动向指定的Issuer申请证书,并将签发好的证书与私钥写入 Secret,且会在证书到期前自动续期。 - CA Injector(cainjector):负责把 CA 证书包注入到各种对象中。对 Webhook 而言,它把 CA bundle 注入到
MutatingWebhookConfiguration/ValidatingWebhookConfiguration(以及CustomResourceDefinition)的clientConfig.caBundle字段,替换原先占位符或空的caBundle。
要触发 CA Injector 的注入行为,需要在 Webhook 配置对象上使用 cert-manager.io/inject-ca-from 注解,其值为一个已存在的 Certificate(证书请求实例)的引用,格式为:
<certificate-namespace>/<certificate-name>
例如 Kubebuilder 脚手架生成的证书 CR 位于 system 命名空间、名为 serving-cert,则注解值为:
cert-manager.io/inject-ca-from: system/serving-cert
CA Injector 读取该注解,定位到对应的 Certificate,从其存储 Secret 中提取 CA 数据,写入目标对象的 caBundle。下图描述了完整链路:
Certificate CR (serving-cert)
│ 签发证书、写 Secret
▼
Secret (webhook-server-cert)
│ CA Injector 读取注解 cert-manager.io/inject-ca-from: system/serving-cert
▼
MutatingWebhookConfiguration / ValidatingWebhookConfiguration
└─ clientConfig.caBundle 被注入 CA
Kubebuilder 脚手架生成的 cert-manager 资源
当你通过 Kubebuilder 创建 Webhook(如 kubebuilder create webhook --group crew --version v1 --kind Admiral --defaulting --programmatic-validation)后,kustomize/v2 插件会在项目中生成 config/certmanager 目录下的 5 个文件。它们由以下源码模板产生:
| 生成文件 | 模板源码 |
|---|---|
config/certmanager/certificate-webhook.yaml |
certificate_webhook.go |
config/certmanager/certificate-metrics.yaml |
certificate_metrics.go |
config/certmanager/issuer.yaml |
issuer.go |
config/certmanager/kustomization.yaml |
kustomization.go |
config/certmanager/kustomizeconfig.yaml |
kustomizeconfig.go |
这些模板的 SetTemplateDefaults 实现均将 IfExistsAction 设为 machinery.SkipFile,即:若文件已存在(例如之前创建过 Webhook),则跳过生成,不会覆盖用户已有配置。
签发者(Issuer):自签名根
issuer.yaml 定义了一个自签名签发者:
apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
name: selfsigned-issuer
namespace: system
spec:
selfSigned: {}
selfSigned: {}表示这是一个自签名签发者,会生成自签名根证书作为 CA;- 它是整个证书链的信任锚点,Webhook 证书由此 CA 签发;
- 模板注释提醒:目标版本为 CertManager v1.0+,升级时需查阅 cert-manager 官方升级说明中的破坏性变更。
Webhook 服务证书
certificate-webhook.yaml 定义了 Webhook 使用的证书:
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
name: serving-cert # 此名称需与 kustomizeconfig.yaml 中出现的名称保持一致
namespace: system
spec:
dnsNames:
- SERVICE_NAME.SERVICE_NAMESPACE.svc
- SERVICE_NAME.SERVICE_NAMESPACE.svc.cluster.local
issuerRef:
kind: Issuer
name: selfsigned-issuer
secretName: webhook-server-cert
关键点:
- 名称
serving-cert:与 kustomizeconfig.yaml 中的 nameReference 以及config/default/kustomization.yaml中replacements的 select 条件强一致,改名会导致注入失败; dnsNames是占位符:SERVICE_NAME与SERVICE_NAMESPACE会在 kustomize 渲染时被config/default/kustomization.yaml中的 replacements 用真实 Service 名(webhook-service)与命名空间(<project>-system)替换;secretName: webhook-server-cert:签发结果落入该 Secret,Manager 部署通过 manager_webhook_patch.go 将其挂载到/tmp/k8s-webhook-server/serving-certs供 Webhook 服务器使用。
指标服务证书(可选)
certificate-metrics.yaml 定义了名为 metrics-certs 的证书,secretName 为 metrics-server-cert,用于保护开启 --metrics-bind-address 的 metrics 端点。其 dnsNames 同样是占位符,由 replacements 注入 controller-manager-metrics-service 的名称与命名空间。启用它需要同时在 config/default/kustomization.yaml 中取消 cert_metrics_manager_patch.yaml 与 metrics 相关 replacements 的注释。
连接 Issuer 与 Certificate:kustomize 名称引用配置
config/certmanager/kustomizeconfig.yaml 教导 kustomize 如何在 nameReference 替换时更新 Certificate 的 spec.issuerRef.name:
nameReference:
- kind: Issuer
group: cert-manager.io
fieldSpecs:
- kind: Certificate
group: cert-manager.io
path: spec/issuerRef/name
config/certmanager/kustomization.yaml 将上述资源汇总:
resources:
- issuer.yaml
- certificate-webhook.yaml
- certificate-metrics.yaml
configurations:
- kustomizeconfig.yaml
这样 issuer.yaml、两份 Certificate 与名称引用配置便被组织成可独立渲染的 kustomize 资源集合。完整的渲染结果可参考仓库测试数据 testdata/project-v4/config/certmanager/kustomization.yaml。
在 config/default 中启用 cert-manager 并注入 CA
脚手架在 config/default/kustomization.yaml 中默认将 cert-manager 相关段落注释掉(模板源码见 kustomization.go,实际渲染结果见 testdata/project-v4/config/default/kustomization.yaml)。启用分为三步:
1. 引入 certmanager 资源
在 resources: 下取消注释:
# [CERTMANAGER] To enable cert-manager, uncomment all sections with 'CERTMANAGER'. 'WEBHOOK' components are required.
- ../certmanager
同时确保 - ../webhook 已取消注释(cert-manager 段依赖 Webhook 组件)。
2. 挂载 Webhook 证书到 Manager 部署
在 patches: 下取消注释:
# [WEBHOOK] To enable webhook, uncomment all the sections with [WEBHOOK] prefix including the one in
# crd/kustomization.yaml
- path: manager_webhook_patch.yaml
target:
kind: Deployment
该 patch 将 webhook-server-cert Secret 挂载为 /tmp/k8s-webhook-server/serving-certs。
3. 配置 replacements 注入 CA 与 DNS 名称
在 replacements: 下取消注释对应段落。脚手架按 Webhook 类型生成四种替换块,其模板与自动化逻辑可在 webhook.go 的 enableWebhookDefaults、uncommentCodeForDefaultWebhooks、uncommentCodeForValidationWebhooks、uncommentCodeForConversionWebhooks 中看到——kubebuilder create webhook 会根据 --defaulting、--programmatic-validation、--conversion 选项自动取消对应注释。
A. 任意 Webhook 都需要的 DNS 名称替换(把 Service 名称/命名空间写入 serving-cert 的 spec.dnsNames):
- source: # Uncomment the following block if you have any webhook
kind: Service
version: v1
name: webhook-service
fieldPath: .metadata.name # Name of the service
targets:
- select:
kind: Certificate
group: cert-manager.io
version: v1
name: serving-cert
fieldPaths:
- .spec.dnsNames.0
- .spec.dnsNames.1
options:
delimiter: '.'
index: 0
create: true
- source:
kind: Service
version: v1
name: webhook-service
fieldPath: .metadata.namespace # Namespace of the service
targets:
- select:
kind: Certificate
group: cert-manager.io
version: v1
name: serving-cert
fieldPaths:
- .spec.dnsNames.0
- .spec.dnsNames.1
options:
delimiter: '.'
index: 1
create: true
B. ValidatingWebhook 的 CA 注入(--programmatic-validation):
- source: # Uncomment the following block if you have a ValidatingWebhook (--programmatic-validation)
kind: Certificate
group: cert-manager.io
version: v1
name: serving-cert # This name should match the one in certificate.yaml
fieldPath: .metadata.namespace # Namespace of the certificate CR
targets:
- select:
kind: ValidatingWebhookConfiguration
fieldPaths:
- .metadata.annotations.[cert-manager.io/inject-ca-from]
options:
delimiter: '/'
index: 0
create: true
- source:
kind: Certificate
group: cert-manager.io
version: v1
name: serving-cert
fieldPath: .metadata.name
targets:
- select:
kind: ValidatingWebhookConfiguration
fieldPaths:
- .metadata.annotations.[cert-manager.io/inject-ca-from]
options:
delimiter: '/'
index: 1
create: true
C. DefaultingWebhook 的 CA 注入(--defaulting):结构同 B,但 targets 的 select 目标是 MutatingWebhookConfiguration。
D. ConversionWebhook 的 CA 注入(--conversion):目标为 CustomResourceDefinition,同时需要在 config/crd/kustomization.yaml 中取消 configurations: - kustomizeconfig.yaml 的注释,让 CRD 的 CA 注入 patch(见 enablecainjection_patch.go)生效。
注解值是如何拼装出来的
上面的 replacements 用两个 source 分别取 Certificate 的 namespace(index 0)与 name(index 1),再用 delimiter: '/' 将它们拼成 <certificate-namespace>/<certificate-name>——这正是文档所要求的 cert-manager.io/inject-ca-from 注解格式。create: true 表示若目标对象上不存在该注解字段则自动创建。
与源码脚手架流程的对照
从源码看,Kubebuilder 生成 cert-manager 配置的完整流程位于 pkg/plugins/common/kustomize/v2/scaffolds/webhook.go 的 webhookScaffolder.Scaffold:
- 依次构建
certmanager.Certificate、certmanager.Issuer、certmanager.MetricsCertificate、certmanager.Kustomization、certmanager.KustomizeConfig等模板并写入磁盘(第 87–97 行); - 调用
enableWebhookDefaults()取消../certmanager、manager_webhook_patch.yaml、replacements:及相关替换块的注释(第 336–444 行); - 根据 Webhook 类型调用
uncommentCodeForValidationWebhooks/uncommentCodeForDefaultWebhooks(默认/校验),以及uncommentCodeForConversionWebhooks(转换,同时打开 CRD 的 cainjection 配置); - 若检测到旧版脚手架遗留的
crdkustomizecainjectionpatch标记,会输出迁移指引(validateScaffoldedProject)。
安装 cert-manager 与启用验证
cert-manager 的安装请遵循其官方安装文档。由于 Webhook 证书需要 CA Injector 正常工作,安装时务必确保 cainjector 组件已就绪。
启用后可通过以下方式验证链路:
# 1. 确认证书已签发(Secret 已生成)
kubectl -n <project>-system get certificate,secret
# 2. 确认 Webhook 配置的 caBundle 与注解已注入
kubectl get mutatingwebhookconfiguration mutating-webhook-configuration -o yaml
kubectl get validatingwebhookconfiguration validating-webhook-configuration -o yaml
# 3. 观察 cainjector 日志确认注入成功
kubectl -n cert-manager logs deployment/cert-manager-cainjector
常见问题与排查要点
- 注解值为空或格式错误:检查
replacements中 source 的fieldPath(.metadata.namespace/.metadata.name)与options.delimiter: '/'、index是否被正确取消注释;注解最终形态必须是<namespace>/<name>。 - 证书名称不匹配:
serving-cert的名称需在certificate-webhook.yaml、kustomizeconfig.yaml、config/default/kustomization.yaml三处一致。 - 证书未签发:确认
Issuer已就绪且Certificate的issuerRef正确指向selfsigned-issuer,同时config/certmanager已作为资源被config/default/kustomization.yaml引入。 - Manager 无法启动或 TLS 握手失败:确认 Secret
webhook-server-cert已挂载到/tmp/k8s-webhook-server/serving-certs,且dnsNames的替换已生效(查看生成的serving-cert是否包含webhook-service.<project>-system.svc域名)。 - 旧项目迁移:若脚手架早期版本生成了多余的 CRD cainjection patch,参考
webhook.go中validateScaffoldedProject输出的清理指引,或使用alpha generate基于最新版本重新生成项目后移植业务代码。