hashicorp/vault-secrets-operator

Vault Secrets Operator 官方镜像

镜像概述与主要用途

Vault Secrets Operator（VSO）官方镜像是基于当前发布版本自动构建的容器镜像，用于在Kubernetes环境中实现Vault密钥与Kubernetes Secrets的原生同步。其核心用途是允许Kubernetes Pod通过Kubernetes Secrets间接消费Vault密钥，无需直接访问Vault服务，从而简化密钥管理流程并增强安全性。该镜像支持从Vault社区版、企业版及HCP Vault Secrets同步密钥。

核心功能与特性

1. 基于CRD的同步机制

通过监听Kubernetes集群中支持的自定义资源定义（CRD），触发Vault密钥到Kubernetes Secrets的同步操作，CRD中包含同步所需的配置规范。

2. 多源密钥支持

兼容多种Vault服务类型，包括Vault社区版、企业版以及HCP Vault Secrets，满足不同部署环境的需求。

3. 实时变更同步

将Vault中的源密钥数据直接写入Kubernetes目标Secret，并持续监控源密钥变更，确保目标Secret与源密钥实时保持一致。

4. 原生Kubernetes集成

应用Pod只需访问Kubernetes Secrets即可获取密钥数据，无需集成Vault SDK或直接调用Vault API，降低应用复杂度。

使用场景与适用范围

适用场景

• Kubernetes密钥集中管理：需将Vault作为密钥存储中心，同时通过Kubernetes Secrets向应用提供密钥的场景。
• 动态密钥同步：Vault密钥频繁更新（如数据库凭证自动轮换），需实时同步至Kubernetes Secrets的场景。
• 安全访问控制：希望限制应用直接访问Vault，通过Kubernetes RBAC控制密钥访问权限的场景。

适用范围

• 运行环境：Kubernetes集群（需支持CRD，建议版本1.21+）。
• 依赖服务：已部署Vault服务（社区版/企业版）或使用HCP Vault Secrets，且网络可互通。
• 目标用户：Kubernetes集群管理员、DevOps工程师、需要在K8s环境中安全管理密钥的开发团队。

使用方法与配置说明

部署前提

• Kubernetes集群（版本≥1.21），已启用CRD支持。
• Vault服务（社区版/企业版或HCP Vault Secrets）已部署并可访问，且已配置必要的访问策略（如创建角色、策略授权）。
• 集群内已安装kubectl工具，且用户具备集群管理员权限（用于部署CRD及Operator）。

Kubernetes部署示例（推荐）

VSO作为Kubernetes Operator，需部署至Kubernetes集群中，以下为基础部署流程：

1. 安装CRD

首先部署VSO所需的CRD：

bash
kubectl apply -f https://raw.githubusercontent.com/hashicorp/vault-secrets-operator/main/config/crd/bases/secret.hashicorp.com_vaultstaticsecrets.yaml
kubectl apply -f https://raw.githubusercontent.com/hashicorp/vault-secrets-operator/main/config/crd/bases/secret.hashicorp.com_vaultdynamicsecrets.yaml
# 其他CRD（如VaultAuth、VaultConnection等）根据实际需求部署，参考官方文档

2. 部署Operator

通过容器镜像部署VSO控制器（需替换<IMAGE_TAG>为实际版本，如1.0.0）：

yaml
# vault-secrets-operator-deploy.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: vault-secrets-operator
  namespace: vault-secrets-operator
spec:
  replicas: 1
  selector:
    matchLabels:
      app: vault-secrets-operator
  template:
    metadata:
      labels:
        app: vault-secrets-operator
    spec:
      containers:
      - name: vault-secrets-operator
        image: hashicorp/vault-secrets-operator:<IMAGE_TAG>
        args:
        - --leader-elect
        env:
        - name: POD_NAMESPACE
          valueFrom:
            fieldRef:
              fieldPath: metadata.namespace
        - name: VAULT_ADDR
          value: "https://vault.example.com:8200"  # Vault服务地址
        - name: VAULT_TOKEN
          valueFrom:
            secretKeyRef:
              name: vault-token
              key: token  # 存储Vault访问令牌的Secret

应用部署清单：

bash
kubectl create namespace vault-secrets-operator
kubectl apply -f vault-secrets-operator-deploy.yaml

3. 创建同步CRD示例

以同步Vault静态密钥为例，创建VaultStaticSecret CRD：

yaml
apiVersion: secret.hashicorp.com/v1beta1
kind: VaultStaticSecret
metadata:
  name: example-vault-static-secret
spec:
  vaultAuthRef: example-vault-auth  # 关联Vault认证配置（需提前创建）
  mount: kv-v2  # Vault密钥引擎挂载路径
  path: my-secret  # Vault密钥路径
  destination:
    name: k8s-secret  # 目标Kubernetes Secret名称
    create: true  # 自动创建目标Secret
  refreshAfter: 30s  # 同步间隔

应用CRD：

bash
kubectl apply -f example-vault-static-secret.yaml

Docker部署说明（非推荐）

VSO作为Kubernetes Operator，设计目标为运行在K8s集群中，直接通过docker run部署需手动配置K8s API访问，仅建议用于测试环境：

bash
docker run -d \
  --name vault-secrets-operator \
  -v /path/to/kubeconfig:/root/.kube/config \  # 挂载K8s配置以访问集群API
  -e VAULT_ADDR="https://vault.example.com:8200" \  # Vault服务地址
  -e VAULT_TOKEN="hvs.xxxx" \  # Vault访问令牌（测试用，生产环境建议用Vault Auth CRD）
  -e LOG_LEVEL="info" \  # 日志级别（debug/info/warn/error）
  hashicorp/vault-secrets-operator:<IMAGE_TAG>

配置参数与环境变量

VSO支持通过环境变量或CRD配置参数自定义行为，核心配置如下：

环境变量（Operator容器级）

CRD配置参数（密钥同步级）

通过VaultStaticSecret/VaultDynamicSecret等CRD的spec字段配置同步规则，核心参数包括：

• vaultAuthRef：关联Vault认证配置（如Kubernetes Auth、Token Auth等，需通过VaultAuth CRD定义）。
• mount：Vault密钥引擎的挂载路径（如kv-v2）。
• path：Vault密钥的完整路径（如myapp/database）。
• destination：目标Kubernetes Secret的名称及创建策略。
• refreshAfter：密钥同步间隔（如30s）。

参考文档

• Vault Secrets Operator 官方文档
• https://github.com/hashicorp/vault-secrets-operator/tree/main/config/crd/bases
• https://hub.docker.com/r/hashicorp/vault-secrets-operator