rancher/storage-secrets

Rancher Secrets 卷驱动镜像文档

一、镜像概述和主要用途

概述

本镜像为 Docker 卷驱动（Volume Driver），专为 Rancher 平台的 Secrets 功能设计，用于在容器中安全挂载和访问 Rancher 管理的敏感信息（如密码、API 密钥、证书等）。通过该驱动，容器可通过 Docker 卷的方式透明地获取 Rancher Secrets 中存储的密钥，无需直接暴露密钥内容到镜像或容器配置中。

主要用途

• 实现 Rancher Secrets 与 Docker 卷的集成，将 Rancher 管理的密钥安全传递至容器内部
• 提供密钥的隔离和权限控制，避免敏感信息通过环境变量、镜像层等不安全方式暴露
• 简化容器对密钥的访问流程，统一通过卷挂载方式管理密钥生命周期

二、核心功能和特性

核心功能

1. Rancher Secrets 原生集成
   与 Rancher Secrets 功能深度集成，支持直接引用 Rancher 中创建的 Secrets 资源，无需额外配置密钥同步机制。

2. 安全挂载控制

   • 支持以只读（read-only）方式挂载密钥，防止容器内意外修改
   • 可配置密钥文件的权限（如 0400，仅容器内 root 用户可读），符合最小权限原则

3. 动态更新支持
   当 Rancher Secrets 中的密钥内容更新后，驱动可自动同步最新密钥至已挂载的卷，容器无需重启即可访问更新后的密钥（需驱动支持动态刷新机制）。

4. 多容器共享
   同一密钥卷可被多个容器挂载，实现密钥在多实例应用中的共享，同时保持权限隔离。

三、使用场景和适用范围

典型使用场景

• 容器敏感信息注入：需在容器中使用数据库密码、API 密钥、OAuth 令牌等敏感信息的场景（如数据库客户端、API 服务端）
• 密钥动态更新需求：密钥需定期轮换（如每月更新密码），且应用需实时获取最新密钥的场景
• Rancher 平台标准化部署：基于 Rancher 进行应用编排，需统一管理密钥生命周期的场景

适用范围

• 环境要求：仅适用于 Rancher 管理的容器平台（支持 Rancher v2.x 及以上版本）
• Docker 兼容性：需 Docker 17.06+ 或 containerd 1.2+（支持卷驱动插件机制）
• 应用类型：无状态/有状态应用均可，尤其适合对密钥安全性要求高的业务（如***、支付、企业内部系统）

四、使用方法和配置说明

前提条件

1. 已部署 Rancher 平台（v2.x+），并在集群中启用 Secrets 功能
2. 节点已安装 Docker/containerd，且支持卷驱动插件
3. 已在 Rancher 中创建目标 Secrets（如 db-password、api-token）

1. 安装卷驱动

通常，Rancher 平台会自动部署该驱动（若未部署，可通过 Rancher 应用商店或手动安装驱动插件）。验证驱动是否安装：

bash
docker info | grep "Volume Drivers"  # 应包含 "rancher-secrets" 驱动

2. 创建密钥卷

使用 docker volume create 命令创建关联 Rancher Secrets 的卷，需指定驱动为 rancher-secrets，并通过 driver_opts 配置 Secrets 名称、挂载路径等参数。

命令示例：

bash
docker volume create \
  --driver rancher-secrets \
  --opt secrets=db-password,api-token  # 逗号分隔多个 Rancher Secrets 名称 \
  --opt file-mode=0400 \  # 密钥文件权限（默认 0400，仅 root 可读） \
  --opt dir-mode=0700 \   # 挂载目录权限（默认 0700） \
  my-secret-volume  # 卷名称

参数说明：

3. 在容器中挂载密钥卷

创建容器时，通过 -v 参数挂载已创建的密钥卷，容器即可在指定路径访问密钥文件（文件名与 Rancher Secrets 名称一致）。

Docker Run 示例：

bash
docker run -d \
  --name my-app \
  -v my-secret-volume:/app/secrets:ro  # 挂载卷至 /app/secrets，只读模式 \
  my-app-image  # 业务镜像

容器内密钥访问：
挂载后，容器内 /app/secrets 目录下会生成与 Rancher Secrets 同名的文件，内容为密钥值：

bash
# 容器内执行
cat /app/secrets/db-password  # 输出 Rancher Secrets "db-password" 的值
cat /app/secrets/api-token    # 输出 Rancher Secrets "api-token" 的值

4. Docker Compose 配置示例

在 docker-compose.yml 中定义使用该驱动的卷，并挂载至服务：

yaml
version: '3.8'

volumes:
  my-secret-volume:
    driver: rancher-secrets
    driver_opts:
      secrets: "db-password,api-token"  # 关联的 Rancher Secrets 名称
      file-mode: "0400"
      dir-mode: "0700"

services:
  app:
    image: my-app-image
    volumes:
      - my-secret-volume:/app/secrets:ro  # 只读挂载密钥卷
    restart: always

五、注意事项

1. 权限控制：密钥文件默认权限为 0400（仅 root 可读），建议容器内以非 root 用户运行时，通过 file-mode 调整权限（如 0440），并确保用户组权限匹配。
2. 动态更新：若 Rancher Secrets 内容更新，驱动会自动同步至卷（同步延迟取决于 Rancher 配置，通常 < 30s），容器需通过信号（如 SIGHUP）或轮询机制重新读取文件以获取最新值。
3. 安全性：密钥卷仅存储在内存或节点本地临时存储（非持久化），且通过 Rancher 加密传输，避免持久化敏感信息。
4. 兼容性：不支持非 Rancher 环境（如独立 Docker 主机），需确保节点已加入 Rancher 集群并正常通信。