zendesk/samson_secret_puller

Secret puller

镜像概述和主要用途

Secret puller是一个在Kubernetes init容器中运行的应用，用于向容器化应用发布密钥，无需使用不安全的进程环境变量（不安全原因）。该工具适用于https://github.com/zendesk/samson%EF%BC%8C%E5%B9%B6%E6%8F%90%E4%BE%9B%E5%A4%9A%E7%A7%8D%E8%AF%AD%E8%A8%80%E7%9A%84%E5%BA%93%EF%BC%8C%E4%BB%A5%E4%BE%BF%E5%BA%94%E7%94%A8%E4%BB%8E%E7%A3%81%E7%9B%98%E8%AF%BB%E5%8F%96%E8%BF%99%E4%BA%9B%E5%AF%86%E9%92%A5%E3%80%82

环境变量

init容器支持以下环境变量配置：

VAULT_ADDR: 必填，Vault的URL
VAULT_AUTH_FILE: 可选，磁盘上挂载的Vault令牌/PEM文件路径，默认'/vault-auth/authsecret'
VAULT_AUTH_TYPE: 可选，认证类型，默认'token'
VAULT_AUTH_PATH: 可选，自定义Vault认证路径，默认$VAULT_AUTH_TYPE
VAULT_AUTH_ROLE: 可选，Vault登录时使用的角色（当VAULT_AUTH_TYPE=kubernetes时必填）
VAULT_TLS_VERIFY: 可选，与Vault通信时是否验证SSL，默认false
VAULT_KV_V2: 可选，是否为Vault KV v2，默认false
VAULT_MOUNT: 可选，使用的挂载点，默认"secret"
VAULT_PREFIX: 可选，使用的前缀，默认"apps"
SIDECAR_SECRET_PATH: 可选，密钥在磁盘上的存储路径，默认'/secrets'
SECRET_ANNOTATIONS: 可选，读取注解的位置，默认'/secretkeys/annotations'
SERVICEACCOUNT_DIR: 可选，ServiceAccount的路径，默认'/var/run/secrets/kubernetes.io/serviceaccount/'
POD_IP: 可选，Kubernetes Pod的IP地址
POD_HOSTNAME: 可选，Kubernetes Pod的主机名
LOG_LEVEL: 可选，日志级别，默认"info"；调试时设为"debug"

注：仓库中的密钥仅用于测试。

示例配置：

• kubernetes/vault-auth-secret.yml
• kubernetes/vault-auth-token.yml

支持的认证类型

VAULT_AUTH_TYPE=token（默认）

VAULT_AUTH_FILE指定的文件路径将被读取，并直接用作Vault令牌。令牌通过Vault的lookup-self API进行验证。

VAULT_AUTH_TYPE=cert

VAULT_AUTH_FILE指定的文件路径将被读取，并用作X509证书，通过Vault的TLS Certificate Auth后端进行认证。

如果后端挂载路径不是/auth/cert，可通过VAULT_AUTH_PATH环境变量自定义。

VAULT_AUTH_TYPE=kubernetes

使用挂载到init容器中的Kubernetes ServiceAccount，通过Vault的Kubernetes Auth后端进行认证。登录使用的角色通过VAULT_AUTH_ROLE设置。

如果后端挂载路径不是/auth/kubernetes，可通过VAULT_AUTH_PATH环境变量自定义。

示例工作流

Init容器读取注解secret/BAR=foo/bar/baz/foo，并在SIDECAR_SECRET_PATH路径下生成名为BAR的文件，文件内容为从Vault读取secret/apps/foo/bar/baz/foo的结果（目前secret/apps前缀为硬编码）。

在宿主应用中，可通过samson_secret_puller gem加载密钥：

ruby
gem 'samson_secret_puller'

require 'samson_secret_puller'

SamsonSecretPuller.replace_ENV!

# 从/secrets/FOO读取，若不存在则回退到原ENV['FOO']
ENV['FOO']

PKI工作流示例

Init容器读取以pki/开头的注解。PKI注解格式为pki/{name}={vault_path}?{parameters}。

注解键中的“name”用于输出文件的路径；注解值包含用于请求证书签发的Vault URI路径，注解值中的URL风格路径参数将转换为签发证书请求的 payload。

例如：init容器读取注解pki/example.com=pki/issue/example-com?common_name=example.com，并在${SIDECAR_SECRET_PATH}/pki/example.com目录下生成证书文件。注解值中的URL风格参数（common_name=example.com）将被编组为Vault的Generate Certificate请求的payload（详见该文档的可能参数）。

根据PKI后端配置，以下文件将生成在SIDECAR_SECRET_PATH目录下：

${SIDECAR_SECRET_PATH}/pki/example.com/certificate.pem
${SIDECAR_SECRET_PATH}/pki/example.com/private_key.pem
${SIDECAR_SECRET_PATH}/pki/example.com/issuing_ca.pem
${SIDECAR_SECRET_PATH}/pki/example.com/chain_ca.pem
${SIDECAR_SECRET_PATH}/pki/example.com/serial_number
${SIDECAR_SECRET_PATH}/pki/example.com/private_key_type
${SIDECAR_SECRET_PATH}/pki/example.com/expiration

特殊注解参数：

• ?pod_hostname_as_cn=true：将Pod主机名设为通用名称，覆盖common_name参数（若提供）
• ?pod_hostname_as_san=true：将Pod主机名包含为主题备用名称
• ?pod_ip_as_san=true：将Pod IP包含为主题备用名称

调试

• 使用专用Pod在集群内调试，详见[kubernetes/debug.yml]
• 容器内无bash，使用sh
• 设置环境变量LOG_LEVEL=debug获取调试日志

测试

bash
bundle && bundle exec rake

发布到https://hub.docker.com/r/zendesk/samson_secret_puller/

• 合并PR后，docker pull zendesk/samson_secret_puller可获取最新镜像
• 分支镜像：使用rake build构建后，手动标记并推送
• 对于Zendesk内部：https://github.com/zendesk/zendesk_samson_secret_puller%E6%8B%89%E5%8F%96%E6%9C%80%E6%96%B0%E9%95%9C%E5%83%8F%E5%B9%B6%E6%8E%A8%E9%80%81%E5%A4%9A%E6%9E%B6%E6%9E%84%E9%95%9C%E5%83%8F%E5%88%B0GCR

Ruby Gem

详见gem Readme.md

Elixir

详见elixir README.md