Kubebuilder 中使用 cert-manager 为 Webhook 提供证书与 CA 注入完整指南

原创2026-09-24 22:51:541,394 阅读
文章标签:云原生容器编排代码生成开发工具CLI插件系统Web框架

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 生态中有两个关键组件参与证书生命周期管理:

  1. 证书管理器(Certificate Controller):根据 Certificate CR 的声明式描述(域名、签发者、Secret 名称等)自动向指定的 Issuer 申请证书,并将签发好的证书与私钥写入 Secret,且会在证书到期前自动续期。
  2. 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:

  1. 依次构建 certmanager.Certificate、certmanager.Issuer、certmanager.MetricsCertificate、certmanager.Kustomization、certmanager.KustomizeConfig 等模板并写入磁盘(第 87–97 行);
  2. 调用 enableWebhookDefaults() 取消 ../certmanager、manager_webhook_patch.yaml、replacements: 及相关替换块的注释(第 336–444 行);
  3. 根据 Webhook 类型调用 uncommentCodeForValidationWebhooks / uncommentCodeForDefaultWebhooks(默认/校验),以及 uncommentCodeForConversionWebhooks(转换,同时打开 CRD 的 cainjection 配置);
  4. 若检测到旧版脚手架遗留的 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 基于最新版本重新生成项目后移植业务代码。
登录后查看全文
kubebuilder