vault-kubernetes-authenticator 镜像文档

概述

vault-kubernetes-authenticator是一个用于Kubernetes环境与Vault集成的工具镜像，提供初始化容器（Init Container）和Sidecar容器，实现Vault令牌获取、Vault密钥同步至Kubernetes密钥以及令牌续期功能，保障Pod在生命周期内安全访问Vault资源。

核心功能与特性

• 令牌获取：通过初始化容器vault-kubernetes-authenticator向Vault进行身份验证，获取一次性使用的Vault令牌。
• 密钥同步：通过初始化容器vault-kubernetes-synchronizer将Vault密钥同步至Kubernetes密钥，并支持标签管理和过期密钥清理。
• 令牌续期：通过Sidecar容器vault-kubernetes-token-renewer定期续期Vault令牌，确保Pod生命周期内令牌有效。
• 灵活配置：支持Vault客户端环境变量配置、密钥映射规则、编码处理及自定义标签和注解。

使用场景

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

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

场景2 - 同步Vault密钥至Kubernetes密钥

先通过vault-kubernetes-authenticator获取Vault令牌，再启动vault-kubernetes-synchronizer将指定Vault密钥同步为Kubernetes密钥，支持密钥映射、编码处理及标签管理。

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

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

问题说明

• 当vault-kubernetes-token-renewer续期失败时（restartPolicy=always），容器将重启。若令牌已过期无法续期，需重启Pod由vault-kubernetes-authenticator重新获取令牌。
• 若启用VAULT_REAUTH=true，令牌续期失败时将重新认证，此时需确保提供vault-kubernetes-authenticator所需的所有认证环境变量，且令牌消费者需支持重新读取令牌文件。

Vault客户端配置

支持通过环境变量配置Vault客户端，常用变量如下：

• VAULT_ADDR：Vault服务器地址
• VAULT_CACERT：CA证书路径
• VAULT_SKIP_VERIFY：是否跳过TLS验证（默认false）
• VAULT_TOKEN：Vault令牌
• VAULT_ROLE：用于身份验证的Vault角色名称

最小配置需设置VAULT_ADDR，若未配置TLS验证，需设置VAULT_SKIP_VERIFY=true。

初始化容器：vault-kubernetes-authenticator

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

配置

示例

# 容器日志示例
$ 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密钥名称和标签需符合RFC-1123规范。

编码处理

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

# 生成Vault密钥内容
echo "base64:$(base64 -w0 filename)"

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

配置

错误处理

• 若vault-kubernetes-authenticator身份验证失败且ALLOW_FAIL=true：
  • 检查所有VAULT_SECRETS对应的Kubernetes密钥是否已存在，存在则警告后成功退出；
  • 若任一密钥不存在，则同步失败。

示例

Vault中存在两个密钥：

$ vault kv get secret/k8s/first
=== Data ===
Key    Value
---    -----
one    ***
two    23456781

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

部署配置：

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

同步结果：

$ 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

Sidecar容器：vault-kubernetes-token-renewer

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

配置

示例

# 初始化容器日志
$ 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

# Sidecar容器日志
$ 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

credits

基于Seth Vargo的工作。

相关链接

• Vault Kubernetes认证方法
• Kubernetes初始化容器
• 使用HashiCorp Vault与Kubernetes (Cloud Next '18)