vault-kubernetes 工具集

概述

vault-kubernetes 是一套用于在Kubernetes环境中与HashiCorp Vault交互的工具集，包含初始化容器（vault-kubernetes-authenticator、vault-kubernetes-synchronizer）和边车容器（vault-kubernetes-token-renewer），支持身份验证获取Vault令牌、同步Vault密钥到Kubernetes密钥以及令牌续期等核心功能，满足不同密钥管理场景需求。

credits

基于Seth Vargo的工作开发。

应用场景

场景1 - 获取一次性使用的Vault令牌

启动初始化容器vault-kubernetes-authenticator，向Vault进行身份验证并获取Vault令牌。该令牌将在指定TTL（生存时间）后过期，适用于一次性密钥访问场景。

场景2 - 将Vault密钥同步到Kubernetes密钥

首先启动初始化容器vault-kubernetes-authenticator进行身份验证获取令牌，随后启动初始化容器vault-kubernetes-synchronizer，将Vault中的密钥同步到Kubernetes密钥中，支持密钥映射和编码处理。

场景3 - 获取Pod生命周期内使用的Vault令牌

启动初始化容器vault-kubernetes-authenticator获取Vault令牌，再启动边车容器vault-kubernetes-token-renewer，定期续期令牌，确保令牌在Pod整个生命周期内有效。

问题说明

• 令牌续期失败处理：若边车容器vault-kubernetes-token-renewer续期失败（如令牌已过期），容器将重启（需设置restartPolicy=always）。此时可通过两种方式恢复：1）利用Kubernetes的进程命名空间共享和容器生命周期钩子，让Pod终止并重启，由初始化容器重新获取令牌；2）启用VAULT_REAUTH=true，让续期容器重新身份验证并更新令牌，应用需监听令牌文件变化。
• 依赖问题：因Go版本与k8s.io/client-go兼容性问题，仓库中已移除go.sum文件。

Vault客户端配置

工具集通过以下环境变量配置Vault客户端，最小配置需设置VAULT_ADDR（Vault地址），若禁用TLS验证需添加VAULT_SKIP_VERIFY=true：

详细配置说明参见：Vault API文档

初始化容器 vault-kubernetes-authenticator

用于向Vault进行身份验证并获取令牌，存储到指定路径供其他容器使用。

配置参数

使用示例

Pod日志输出：

$ kubectl logs vault-kubernetes-authenticator-5675d58d95-4wd8v -c vault-kubernetes-authenticator
2018/11/26 14:56:29 成功向Vault进行身份验证
2018/11/26 14:56:29 成功将Vault令牌存储到 /home/vault/.vault-token

获取令牌：

$ kubectl exec -ti vault-kubernetes-authenticator-5675d58d95-4wd8v sh
~ $ VAULT_TOKEN=$(cat /home/vault/.vault-token)
~ $ echo $VAULT_TOKEN
8Pj0EzFLWQv8uWcjbP9hF1MB

初始化容器 vault-kubernetes-synchronizer

依赖vault-kubernetes-authenticator获取的令牌，将Vault密钥同步到Kubernetes密钥，支持密钥映射、编码处理及标签管理。

密钥映射

支持以下映射规则（Vault密钥路径 → Kubernetes密钥名称）：

Kubernetes密钥名称和标签需符合RFC-1123规范。

编码处理

若Vault中存储的是二进制数据（如Java KeyStore），需使用Base64编码并添加前缀base64:。例如，创建Vault密钥：

echo "base64:$(base64 -w0 filename)" | vault kv put secret/path key=-

同步时工具集会自动解码，避免双重编码。

配置参数

错误处理

• 身份验证失败：若vault-kubernetes-authenticator设置ALLOW_FAIL=true，且身份验证失败：
  • 若所有需同步的密钥已存在于Kubernetes中，工具集输出警告并成功退出；
  • 若存在密钥不存在，工具集失败退出。
• 同步失败：常见原因为权限不足（需为服务账户添加sys/mounts的read权限）或Vault KV引擎版本未配置（需启用版本控制，如vault kv enable-versioning secret/）。

使用示例

Vault密钥准备：

# 创建Vault密钥
vault kv put secret/k8s/first one=*** two=23456781
vault kv put secret/k8s/second green=*** poison=ivy

Kubernetes部署配置（片段）：

spec:
  initContainers:
  - name: vault-kubernetes-authenticator
    image: postfinance/vault-kubernetes-authenticator
    env:
    - name: VAULT_ADDR
      value: "[***]"
    - name: VAULT_ROLE
      value: "my-vault-role"
    - name: VAULT_TOKEN_PATH
      value: "/vault/token"
    volumeMounts:
    - name: vault-token
      mountPath: "/vault"
  - name: vault-kubernetes-synchronizer
    image: postfinance/vault-kubernetes-synchronizer
    env:
    - name: VAULT_ADDR
      value: "[***]"
    - name: VAULT_TOKEN_PATH
      value: "/vault/token"
    - name: VAULT_SECRETS
      value: "secret/data/k8s/first,secret/data/k8s/second"
    volumeMounts:
    - name: vault-token
      mountPath: "/vault"
  volumes:
  - name: vault-token
    emptyDir: {}

同步结果验证：

# 查看生成的Kubernetes密钥
kubectl get secrets | grep -e first -e second

# 查看密钥详情
kubectl describe secret first
# 输出包含注解：vault-secret=secret/data/k8s/first，数据包含one和two字段

边车容器 vault-kubernetes-token-renewer

用于定期续期Vault令牌，确保Pod生命周期内令牌有效。

配置参数

使用示例

Kubernetes部署配置（片段）：

spec:
  initContainers:
  - name: vault-kubernetes-authenticator
    image: postfinance/vault-kubernetes-authenticator
    env:
    - name: VAULT_ADDR
      value: "[***]"
    - name: VAULT_ROLE
      value: "my-vault-role"
    - name: VAULT_TOKEN_PATH
      value: "/vault/token"
    volumeMounts:
    - name: vault-token
      mountPath: "/vault"
  containers:
  - name: vault-kubernetes-token-renewer
    image: postfinance/vault-kubernetes-token-renewer
    env:
    - name: VAULT_ADDR
      value: "[***]"
    - name: VAULT_TOKEN_PATH
      value: "/vault/token"
    - name: VAULT_REAUTH
      value: "true"
    - name: VAULT_ROLE
      value: "my-vault-role"
    volumeMounts:
    - name: vault-token
      mountPath: "/vault"
  volumes:
  - name: vault-token
    emptyDir: {}

日志验证：

kubectl logs <pod-name> -c vault-kubernetes-token-renewer
# 输出包含：2018/11/26 14:56:32 start renewer loop，2018/11/26 14:56:32 token renewed

构建

1. 安装 mage 构建工具。
2. 配置环境变量：

   export GO111MODULE=on
   export DOCKER_TARGET="registry.example.com/repopath"  # 镜像仓库地址（可选，用于推送）
   

3. 构建镜像：

   mage buildAllImages
   

演示

1. 编辑demo/profile文件配置环境。
2. 部署演示环境：

   cd demo
   ./deploy.sh profile
   

3. 清理环境：

   ./delete.sh namespace
   

链接

• HashiCorp Vault与Kubernetes集成（Cloud Next '18）
• GitHub - vault-kubernetes-authenticator
• Vault - Kubernetes认证方法
• Kubernetes - 初始化容器