postfinance/vault-kubernetes-synchronizer

vault-kubernetes-authenticator 镜像文档

镜像概述和主要用途

该镜像提供与Vault集成的工具，用于在Kubernetes环境中实现Vault认证、密钥同步及令牌管理。基于Seth Vargo的https://github.com/sethvargo/vault-kubernetes-authenticator%E9%A1%B9%E7%9B%AE%EF%BC%8C%E6%94%AF%E6%8C%81%E4%B8%89%E7%A7%8D%E6%A0%B8%E5%BF%83%E5%9C%BA%E6%99%AF%EF%BC%9A%E8%8E%B7%E5%8F%96%E4%B8%80%E6%AC%A1%E6%80%A7Vault%E4%BB%A4%E7%89%8C%E3%80%81%E5%90%8C%E6%AD%A5Vault%E5%AF%86%E9%92%A5%E8%87%B3Kubernetes%E5%AF%86%E9%92%A5%E3%80%81%E4%BB%A5%E5%8F%8A%E4%B8%BAPod%E7%94%9F%E5%91%BD%E5%91%A8%E6%9C%9F%E5%86%85%E6%8F%90%E4%BE%9B%E6%8C%81%E7%BB%AD%E6%9C%89%E6%95%88%E7%9A%84Vault%E4%BB%A4%E7%89%8C%E3%80%82

核心功能和特性

• 多场景支持：一次性令牌获取、密钥同步、令牌续期
• 灵活配置：通过环境变量配置Vault客户端、认证参数及密钥映射
• 密钥管理：自动同步Vault密钥至Kubernetes密钥，支持标签管理和过时密钥清理
• 错误处理：支持认证失败容忍，可配置失败后Pod继续运行或终止
• 安全可靠：基于Kubernetes服务账户认证，支持令牌自动续期

使用场景和适用范围

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

启动初始化容器vault-kubernetes-authenticator向Vault认证并获取令牌，该令牌将在指定TTL后过期，适用于一次性密钥访问场景。

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

先通过vault-kubernetes-authenticator认证获取令牌，再启动vault-kubernetes-synchronizer初始化容器，将Vault密钥同步至Kubernetes密钥，适用于需要在Kubernetes中持久化使用Vault密钥的场景。

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

通过vault-kubernetes-authenticator初始化容器获取令牌，再启动vault-kubernetes-token-renewer边车容器定期续期令牌，确保Pod运行期间令牌持续有效。

详细使用方法和配置说明

Vault客户端配置

通过以下环境变量配置Vault客户端，最小配置需包含VAULT_ADDR（建议配合VAULT_SKIP_VERIFY=true用于测试环境）：

• VAULT_ADDR：Vault服务地址
• VAULT_CACERT：CA证书路径
• VAULT_CAPATH：CA证书目录
• VAULT_CLIENT_CERT：客户端证书路径
• VAULT_CLIENT_KEY：客户端密钥路径
• VAULT_CLIENT_TIMEOUT：客户端超时时间
• VAULT_SKIP_VERIFY：是否跳过TLS验证（布尔值）
• VAULT_TLS_SERVER_NAME：TLS服务器名称
• VAULT_WRAP_TTL：包装令牌TTL
• VAULT_MAX_RETRIES：最大重试次数
• VAULT_TOKEN：Vault令牌
• VAULT_MFA：MFA配置
• VAULT_RATE_LIMIT：速率限制

初始化容器 vault-kubernetes-authenticator

用于向Vault认证并获取令牌，存储至指定路径供后续使用。

配置参数

• VAULT_ROLE：必填，用于认证的Vault角色名称
• VAULT_TOKEN_PATH：令牌存储路径（通常为共享卷）
• VAULT_AUTH_MOUNT_PATH：Kubernetes认证方法挂载路径（默认：kubernetes）
• SERVICE_ACCOUNT_TOKEN_PATH：Kubernetes服务账户JWT令牌路径（默认：/var/run/secrets/kubernetes.io/serviceaccount/token）
• ALLOW_FAIL：认证失败时是否允许容器成功终止（默认：false，需后续容器处理无令牌场景）

示例

bash
# 查看容器日志
$ k logs vault-kubernetes-authenticator-5675d58d95-4wd8v -c vault-kubernetes-authenticator
2018/11/26 14:56:29 successfully authenticated to vault
2018/11/26 14:56:29 successfully stored vault token at /home/vault/.vault-token

# 验证令牌
$ k 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密钥，支持密钥映射、编码处理及标签管理。

密钥映射

Kubernetes中的标签/名称需符合https://tools.ietf.org/html/rfc1123%E8%A7%84%E8%8C%83%E3%80%82

编码处理

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

bash
# 创建Vault密钥（包含base64编码数据）
echo "base64:$(base64 -w0 filename)" | vault kv put secret/k8s/jks keystore=-

同步器会自动解码base64:前缀的内容，避免双重编码。

配置参数

• VAULT_TOKEN_PATH：令牌存储路径（与认证容器共享）
• VAULT_SECRETS：逗号分隔的Vault密钥路径列表（支持上述映射格式）
• SECRET_PREFIX：Kubernetes密钥名称前缀（如v3t_，则Vault密钥first同步为v3t_first）
• SYNCHRONIZER_ANNOTATION：用于标记同步器管理的密钥的注解（默认：vault-secret）
• SYNCHRONIZER_LABELS：添加到同步密钥的标签（格式：k1=v1,k2=v2，重复键会覆盖）

错误处理

• 若vault-kubernetes-authenticator认证失败且ALLOW_FAIL=true：
  • 检查所有VAULT_SECRETS对应的Kubernetes密钥是否已存在，存在则继续，缺失则失败
  • 同步器输出警告并成功终止

示例

Vault中存在两个密钥：

bash
$ vault kv get secret/k8s/first
====== Metadata ======
...
=== Data ===
Key    Value
---    -----
one    12345678
two    23456781

$ vault kv get secret/k8s/second
====== Metadata ======
...
===== Data =====
Key       Value
---       -----
green     lantern
poison    ivy

配置同步参数：

yaml
# deployment.yaml 片段
env:
- name: VAULT_SECRETS
  value: "secret/data/k8s/first,secret/data/k8s/second"

同步后验证：

bash
$ k get secrets | grep -e first -e second
first                                Opaque                                2      16m
second                               Opaque                                2      16m

$ k describe secret first
Name:         first
Namespace:    vault-test
Annotations:  vault-secret=secret/data/k8s/first
Type:  Opaque
Data
====
one:  8 bytes
two:  8 bytes

边车容器 vault-kubernetes-token-renewer

依赖vault-kubernetes-authenticator，定期续期Vault令牌，确保Pod生命周期内令牌有效。

配置参数

• VAULT_TOKEN_PATH：令牌存储路径（与认证容器共享）
• VAULT_REAUTH：令牌无效时是否重新认证（默认：false，需同时提供认证容器的环境变量）
• VAULT_TTL：请求的令牌TTL（Vault可能覆盖此值）

示例

bash
# 查看认证容器日志
$ k logs vault-kubernetes-token-renewer-844488f7bc-c6ztf -c vault-kubernetes-authenticator
2018/11/26 14:56:30 successfully authenticated to vault
2018/11/26 14:56:30 successfully stored vault token at /home/vault/.vault-token

# 查看边车容器日志
$ k logs vault-kubernetes-token-renewer-844488f7bc-c6ztf -c vault-kubernetes-token-renewer
2018/11/26 14:56:32 start renewer loop
2018/11/26 14:56:32 token renewed

常见问题

• 权限问题：同步器日志提示permission denied时，需为服务账户添加sys/mounts路径的read权限：

  hcl
  path "sys/mounts" {
    capabilities = ["read"]
  }
  

• KV引擎版本缺失：日志提示strconv.Atoi: parsing "": invalid syntax时，需启用KV引擎版本：

  bash
  vault secrets enable -version=2 kv  # 启用v2版本
  vault kv enable-versioning secret/  # 为现有路径启用版本控制
  

相关链接

• https://www.vaultproject.io/docs/auth/kubernetes.html
• https://kubernetes.io/docs/concepts/workloads/pods/init-containers
• https://github.com/postfinance/vault-kubernetes