patoarvizu/vault-agent-auto-inject-webhook

Vault agent auto-inject webhook

概述

Vault agent auto-inject webhook是一个Kubernetes Mutating Webhook，可作为https://github.com/patoarvizu/vault-dynamic-configuration-operator%E7%9A%84%E9%85%8D%E5%A5%97%E5%B7%A5%E5%85%B7%EF%BC%8C%E4%B9%9F%E5%8F%AF%E7%8B%AC%E7%AB%8B%E9%83%A8%E7%BD%B2%E3%80%82%E5%AE%83%E8%83%BD%E5%A4%9F%E4%BF%AE%E6%94%B9Pod%E4%BB%A5%E8%87%AA%E5%8A%A8%E6%B3%A8%E5%85%A5Vault agent边车容器，包括从对应服务身份的ConfigMap中获取并渲染配置模板，同时修改Pod中所有容器的环境变量，注入指向边车代理的VAULT_ADDR环境变量。通过为工作负载（Deployment、StatefulSet、DaemonSet等）添加注解vault.patoarvizu.dev/agent-auto-inject: sidecar，即可在Pod创建时触发webhook进行修改。

核心功能和特性

• 自动注入Vault agent：支持边车容器（sidecar）和初始化容器（init-container）两种模式
• 配置模板渲染：使用ConfigMap中的Go模板结合gomplate动态生成Vault agent配置
• 环境变量注入：自动为Pod中所有容器添加VAULT_ADDR环境变量
• CA证书管理：支持自动挂载CA证书到Vault agent容器
• 证书热重载：监控并自动重载TLS证书，支持证书自动轮换
• 资源控制：可配置Vault agent容器的CPU和内存资源请求与限制
• 指标暴露：提供Prometheus风格指标，便于监控webhook运行状态
• 多架构支持：提供多架构镜像，适配不同硬件平台

使用场景和适用范围

• 长期运行的服务：通过边车容器模式为Deployment、StatefulSet等提供持续的Vault凭证管理
• 短期任务：通过初始化容器模式为Job、CronJob等短期工作负载提供一次性凭证获取
• Kubernetes环境中的Vault集成：简化应用与Vault的集成过程，无需手动配置Vault agent
• 需要动态配置的场景：通过ConfigMap模板实现不同服务的个性化Vault agent配置

使用方法和配置说明

运行webhook

webhook可作为Deployment部署在Kubernetes集群中，需暴露为Service并接受TLS连接。以下是Deployment示例：

yaml
kind: Deployment
...
      containers:
        - name: vault-agent-auto-inject-webhook
          image: patoarvizu/vault-agent-auto-inject-webhook:latest
          command:
          - /vault-agent-auto-inject-webhook
          - -tls-cert-file
          - /tls/tls.crt
          - -tls-key-file
          - /tls/tls.key
          ports:
          - name: https
            containerPort: 4443
          volumeMounts:
            - name: tls
              mountPath: /tls
      volumes:
      - name: tls
        secret:
          secretName: vault-agent-auto-inject-webhook

上述配置假设存在名为vault-agent-auto-inject-webhook的Secret，其中包含tls.crt和tls.key文件。推荐使用https://github.com/jetstack/cert-manager/%E7%94%9F%E6%88%90%E6%AD%A4%E7%B1%BB%E8%AF%81%E4%B9%A6Secret%E3%80%82

配置webhook

需部署MutatingWebhookConfiguration资源，示例如下：

yaml
apiVersion: admissionregistration.k8s.io/v1beta1
kind: MutatingWebhookConfiguration
metadata:
  name: vault-agent-auto-inject-webhook
  labels:
    app: vault-agent-auto-inject-webhook
webhooks:
  - name: vault.patoarvizu.dev
    rules:
      - apiGroups:
          - ""
        apiVersions:
          - v1
        operations:
          - CREATE
          - UPDATE
        resources:
          - pods
    failurePolicy: Ignore
    clientConfig:
      caBundle: ${CA_BUNDLE}
      service:
        name: vault-agent-auto-inject-webhook
        namespace: default
        path: /

clientConfig需与前面创建的Service匹配。caBundle字段需填入签名webhook TLS证书的CA公钥的base64编码值。若使用cert-manager，可通过cert-manager.io/inject-ca-from注解自动注入CA证书。

Webhook命令行标志

ConfigMap配置

webhook要求在目标Pod的命名空间（非webhook所在命名空间）中存在ConfigMap（默认名称为vault-agent-config，可通过-default-config-map-name修改），该ConfigMap需包含vault-agent-config.hcl键，其值为使用Go template编写的Vault agent配置模板，通过https://github.com/hairyhenderson/gomplate%E6%B8%B2%E6%9F%93%E3%80%82%E6%A8%A1%E6%9D%BF%E5%8F%AF%E4%BD%BF%E7%94%A8%E4%BB%A5%E4%B8%8B%E7%8E%AF%E5%A2%83%E5%8F%98%E9%87%8F%EF%BC%9A

自动挂载CA证书

启用-mount-ca-cert-secret标志后，webhook会从-ca-cert-secret-name指定的Secret创建卷，并仅挂载到Vault agent容器的/opt/vault/certs/路径。此时vault-agent-config.hcl可使用Vault配置中的ca_cert字段，无需设置tls_skip_verify = true。

初始化容器模式

对于Job、CronJob等短期工作负载，可通过注解vault.patoarvizu.dev/agent-auto-inject: init-container将Vault agent注入为初始化容器。此时配置需包含exit_after_auth = true以确保认证后容器退出，并至少配置一个文件sink。webhook会自动为容器添加/vault-agent挂载卷作为文件sink路径。

若默认ConfigMap不适用于特定应用，可通过注解vault.patoarvizu.dev/agent-config-map指定目标命名空间中的其他ConfigMap名称。

指标

webhook在-metrics-addr指定的地址（默认:8081）暴露Prometheus风格指标，包括：

• admission_reviews_total：总准入审查次数
• admission_review_errors_total：准入审查错误次数
• admission_review_duration_seconds：准入审查持续时间

自动重载证书

服务器会监控-tls-cert-file指定的TLS证书文件变化，当文件修改时自动热重载证书。这通过https://github.com/radovskyb/watcher%E5%BA%93%E5%AE%9E%E7%8E%B0%EF%BC%8C%E9%80%82%E7%94%A8%E4%BA%8Ecert-manager%E7%AD%89%E8%87%AA%E5%8A%A8%E8%AF%81%E4%B9%A6%E8%BD%AE%E6%8D%A2%E5%B7%A5%E5%85%B7%E3%80%82

安全相关说明

注意：由于Notary客户端技术问题，自2023年1月4日起，新镜像不再进行签名。镜像仍为多架构构建，并包含Git和GPG元数据，但启用Docker Content Trust时无法通过验证。

Docker镜像标签元数据

镜像包含以下Docker标签，可用于验证镜像内容与Git提交的一致性：

• AUTHOR_EMAIL：作者***
• COMMIT_TIMESTAMP：提交时间戳
• GIT_COMMIT：Git提交ID
• GIT_TAG：Git标签（如有）
• SIGNATURE_KEY：GPG签名密钥ID

可通过docker inspect命令查看这些标签，例如：

bash
docker inspect patoarvizu/vault-agent-auto-inject-webhook:c1201e30e90d9d8fd2f2f65f2552236013cdcbe8 | jq -r '.[0].ContainerConfig.Labels'

多架构镜像

使用语义化版本标签（如patoarvizu/vault-agent-auto-inject-webhook:v0.5.0）及latest标签的镜像是多架构清单列表。此外，还有架构特定标签，格式为<版本>-<架构后缀>，例如v0.15.0-amd64。支持的架构及对应后缀：

• linux/amd64：-amd64
• linux/arm64：-arm64
• linux/arm/v7：-arm7

贡献说明

欢迎提交Issues或Pull Requests，包括但不限于拼写错误、问题咨询等。