jkroepke/kube-webhook-certgen

kube-webhook-certgen

镜像概述和主要用途

kube-webhook-certgen是一个用于Kubernetes环境的自签名证书生成与Webhook配置修补工具。它能够生成CA（证书颁发机构）和叶子证书（有效期长达100年），并自动修补Kubernetes准入Webhook（包括ValidatingWebhookConfiguration和MutatingWebhookConfiguration）的caBundle字段，将生成的CA证书注入其中。此外，该工具还支持修补Webhook的failurePolicy设置，特别适用于Helm图表在部署过程中同时配置资源和Webhook的场景，通常作为Kubernetes Job通过pre-install和post-install钩子执行。

核心功能和特性

• 证书生成：自动生成CA证书和服务器证书（叶子证书），并存储到Kubernetes Secret中
• Webhook修补：读取Secret中的CA证书，自动更新Webhook配置的caBundle字段
• 策略配置：支持修补Webhook的failurePolicy（可选值：Ignore或Fail）
• 灵活部署：优化适配Helm部署流程，可作为Kubernetes Job执行
• 多Webhook支持：同时支持ValidatingWebhookConfiguration和MutatingWebhookConfiguration
• 可配置性：支持自定义证书文件名称、Secret名称及命名空间

使用场景和适用范围

• Kubernetes测试环境：快速部署准入Webhook时生成自签名证书
• Helm图表部署：在Helm部署过程中通过pre-install/post-install钩子自动配置Webhook证书
• 开发环境：简化本地或开发环境中Webhook的证书配置流程
• 临时部署：需要快速搭建Webhook功能而无需完整PKI基础设施的场景

安全注意事项：该工具可能不适用于所有安全环境。如需更完善的证书管理方案，建议考虑https://github.com/jetstack/cert-manager%E7%AD%89%E6%9B%BF%E4%BB%A3%E6%96%B9%E6%A1%88%E3%80%82

详细使用方法和配置说明

命令行选项概览

kube-webhook-certgen [flags]
kube-webhook-certgen [command]

可用命令:
  create      生成CA和服务器证书+密钥，并存储到指定命名空间的Secret中
  help        帮助信息
  patch       使用Secret中的CA证书修补Webhook配置
  version     打印CLI版本信息

全局标志:
      --kubeconfig string   kubeconfig文件路径 (例如: ~/.kube/kind-config-kind)
      --log-format string   日志格式: text|json (默认: "text")
      --log-level string    日志级别: panic|fatal|error|warn|info|debug|trace (默认: "info")
  -h, --help                帮助信息

create子命令

生成CA和服务器证书，并存储到指定的Kubernetes Secret中。

用法:
  kube-webhook-certgen create [flags]

标志:
      --cert-name string     Secret中证书文件的名称 (默认: "cert")
  -h, --help                 帮助信息
      --host string          生成证书的主机名和IP，逗号分隔
      --key-name string      Secret中密钥文件的名称 (默认: "key")
      --namespace string     存储证书的Secret所在命名空间
      --secret-name string   存储证书的Secret名称

全局标志:
      --kubeconfig string   kubeconfig文件路径
      --log-format string   日志格式: text|json (默认: "json")
      --log-level string    日志级别 (默认: "info")

patch子命令

使用指定Secret中的CA证书修补Webhook配置的caBundle字段。

用法:
  kube-webhook-certgen patch [flags]

标志:
  -h, --help                          帮助信息
      --namespace string              读取CA证书的Secret所在命名空间
      --patch-failure-policy string   修补Webhook的failurePolicy (可选值: Ignore或Fail)
      --patch-mutating                是否修补MutatingWebhookConfiguration (默认: true)
      --patch-validating              是否修补ValidatingWebhookConfiguration (默认: true)
      --secret-name string            存储CA证书的Secret名称
      --webhook-name string           要更新的Webhook配置名称

全局标志:
      --kubeconfig string   kubeconfig文件路径
      --log-format string   日志格式: text|json (默认: "text")
      --log-level string    日志级别 (默认: "info")

部署示例

Kubernetes Job示例（生成证书）

yaml
apiVersion: batch/v1
kind: Job
metadata:
  name: generate-webhook-cert
  namespace: default
spec:
  template:
    spec:
      containers:
      - name: certgen
        image: jkroepke/kube-webhook-certgen:latest
        command: ["kube-webhook-certgen", "create"]
        args:
          - --host=my-webhook.default.svc,my-webhook.default.svc.cluster.local
          - --namespace=default
          - --secret-name=webhook-tls
      restartPolicy: Never
  backoffLimit: 1

Kubernetes Job示例（修补Webhook）

yaml
apiVersion: batch/v1
kind: Job
metadata:
  name: patch-webhook-config
  namespace: default
spec:
  template:
    spec:
      containers:
      - name: certgen
        image: jkroepke/kube-webhook-certgen:latest
        command: ["kube-webhook-certgen", "patch"]
        args:
          - --webhook-name=my-webhook-config
          - --namespace=default
          - --secret-name=webhook-tls
          - --patch-failure-policy=Fail
      restartPolicy: Never
  backoffLimit: 1

Docker运行示例（本地测试）

bash
# 生成证书并存储到Secret（需提前配置kubeconfig）
docker run --rm -v ~/.kube/config:/kubeconfig jkroepke/kube-webhook-certgen:latest \
  create --kubeconfig=/kubeconfig \
  --host=my-webhook.default.svc \
  --namespace=default \
  --secret-name=webhook-tls

# 修补Webhook配置
docker run --rm -v ~/.kube/config:/kubeconfig jkroepke/kube-webhook-certgen:latest \
  patch --kubeconfig=/kubeconfig \
  --webhook-name=my-webhook-config \
  --namespace=default \
  --secret-name=webhook-tls

已知用户

• https://github.com/prometheus-community/helm-charts/tree/main/charts/kube-prometheus-stack Helm图表