hashicorp/vault-csi-provider

Vault CSI Provider 技术文档

镜像概述和主要用途

Vault CSI Provider 是 HashiCorp Vault 与 Kubernetes https://github.com/kubernetes-sigs/secrets-store-csi-driver 的原生集成组件。其核心功能是为 Kubernetes 用户提供安全、便捷的方式，实现从 Vault 检索敏感 secrets 并将其挂载到 Pod 中的能力，避免 secrets 以明文形式存储在 Kubernetes Secrets 中，增强敏感信息的生命周期管理和访问控制。

核心功能和特性

• 卷挂载方式挂载 Secrets：通过 CSI 卷挂载将 Vault 中的 secrets 直接挂载到 Pod 文件系统，无需暴露于 Kubernetes API。
• Vault Secrets 同步至 Kubernetes Secrets：支持将 Vault 中的 secrets 同步为 Kubernetes Secrets，满足依赖原生 K8s Secrets 的应用场景。
• 基于 Kubernetes 服务账户认证：使用请求资源的 Pod 所属服务账户（Service Account）向 Vault 发起认证请求，实现最小权限访问控制。
• 多值提取支持：可从单个 Vault Secret 中提取一个或多个键值对，灵活满足应用对多密钥的需求。
• TLS/mTLS 加密通信：与 Vault 服务之间通过 TLS 或 mTLS 加密通信，确保 secrets 在传输过程中的安全性。

使用场景和适用范围

使用场景

• 敏感信息安全挂载：应用需访问数据库密码、API 密钥、证书等敏感信息时，通过 Vault 管理并经 CSI 驱动安全挂载至 Pod。
• ** secrets 自动轮换**：结合 Vault 的动态 secrets 功能，实现密钥自动轮换后，通过 CSI 驱动实时更新挂载内容，无需重启 Pod。
• 最小权限访问控制：基于 Pod 服务账户粒度控制 Vault 访问权限，避免过度授权。
• 规避明文存储风险：替代传统 Kubernetes Secrets 明文存储（etcd 中加密仍存在风险），实现 secrets "使用时才解密" 的安全模型。

适用范围

• 运行 Kubernetes 1.16+ 且已部署 CSI Secret Store Driver 的集群。
• 使用 HashiCorp Vault 作为 secrets 管理平台的环境。
• 对敏感信息生命周期管理（创建、分发、轮换、销毁）有严格安全要求的应用。

安装与部署

推荐安装方式

官方推荐通过 https://github.com/hashicorp/vault-helm 安装，该 Chart 已集成 Vault CSI Provider 组件。

安装步骤

1. 添加 Helm 仓库

   bash
   helm repo add hashicorp https://helm.releases.hashicorp.com
   helm repo update
   

2. 安装 Vault Helm Chart
   启用 CSI Provider 组件（默认已启用，可通过参数确认）：

   bash
   helm install vault hashicorp/vault \
     --namespace vault \
     --create-namespace \
     --set "server.enabled=false" \  # 若已独立部署 Vault 服务，可禁用内置 Vault Server
     --set "injector.enabled=false" \  # 若无需 Sidecar 注入，可禁用
     --set "csi.enabled=true"  # 确保 CSI Provider 启用
   

3. 验证安装
   确认 CSI Provider DaemonSet 正常运行：

   bash
   kubectl get daemonset -n vault vault-csi-provider
   

部署示例（Kubernetes）

Vault CSI Provider 以 DaemonSet 形式运行在每个节点，以下为核心部署片段（由 Helm Chart 自动生成，供参考）：

yaml
# DaemonSet 示例（精简版）
apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: vault-csi-provider
  namespace: vault
spec:
  selector:
    matchLabels:
      app.kubernetes.io/name: vault-csi-provider
  template:
    metadata:
      labels:
        app.kubernetes.io/name: vault-csi-provider
    spec:
      containers:
      - name: vault-csi-provider
        image: hashicorp/vault-csi-provider:latest  # 建议指定具体版本号
        args:
          - --endpoint=unix:///csi/csi.sock
          - --log-level=info
        volumeMounts:
          - name: socket-dir
            mountPath: /csi
      volumes:
        - name: socket-dir
          hostPath:
            path: /var/lib/kubelet/plugins/csi-vault
            type: DirectoryOrCreate

配置说明

核心配置参数（Helm Chart 安装时可自定义）

使用方法

前提条件

1. Kubernetes 集群已部署 CSI Secret Store Driver。
2. Vault 服务已部署并配置 Kubernetes 认证（参考 Vault Kubernetes Auth）。

步骤 1：创建 SecretProviderClass

定义从 Vault 检索 secrets 的规则，示例：

yaml
apiVersion: secrets-store.csi.x-k8s.io/v1
kind: SecretProviderClass
metadata:
  name: vault-db-creds  # 自定义名称，供 Pod 引用
spec:
  provider: vault  # 固定为 "vault"
  parameters:
    vaultAddress: "https://vault.example.com:8200"  # Vault 服务地址
    vaultKubernetesMountPath: "kubernetes"  # Vault Kubernetes 认证挂载路径
    roleName: "db-app"  # Vault 中定义的角色（需绑定 Pod 服务账户）
    objects: |
      - objectName: "db-password"  # 挂载到 Pod 中的文件名
        objectType: "secret"  # Vault 秘密类型（secret/kv/transit 等）
        objectPath: "database/creds/my-app"  # Vault 秘密路径
        objectField: "password"  # 提取的字段名（若不指定则获取整个秘密）

步骤 2：在 Pod 中挂载 secrets

在 Pod 定义中引用 SecretProviderClass，通过 CSI 卷挂载 secrets：

yaml
apiVersion: v1
kind: Pod
metadata:
  name: app-with-vault-secret
spec:
  serviceAccountName: db-app-sa  # 需与 Vault 角色绑定的服务账户
  containers:
  - name: app
    image: nginx:alpine
    volumeMounts:
    - name: vault-secrets  # 卷名称，需与 volumes 中一致
      mountPath: "/mnt/secrets"  # 挂载路径
      readOnly: true  # 只读挂载，防止篡改
  volumes:
  - name: vault-secrets
    csi:
      driver: secrets-store.csi.k8s.io  # CSI Secret Store Driver 驱动名
      readOnly: true
      volumeAttributes:
        secretProviderClass: "vault-db-creds"  # 引用步骤 1 创建的 SecretProviderClass

验证挂载

进入 Pod 后，检查挂载路径下的 secrets 文件：

bash
kubectl exec -it app-with-vault-secret -- cat /mnt/secrets/db-password

输出应为 Vault 中 database/creds/my-app 路径下的 password 字段值。

参考文档

• 官方 Vault CSI Provider 文档
• https://github.com/hashicorp/vault-helm/blob/main/values.yaml
• CSI Secret Store Driver 文档