hashicorp/vault-plugin-database-mongodbatlas

Vault MongoDB Atlas 数据库插件 Docker 镜像文档

一、镜像概述和主要用途

1.1 概述

Vault MongoDB Atlas 数据库插件是 HashiCorp Vault 的官方后端插件，旨在为 MongoDB Atlas 项目提供动态数据库凭证管理能力。该 Docker 镜像封装了插件的运行环境，支持在容器化部署中集成至 Vault 生态系统。

1.2 主要用途

• 程序化生成 MongoDB Atlas 数据库的临时、唯一用户凭证
• 实现 MongoDB Atlas 访问凭证的自动轮换与生命周期管理
• 通过 Vault 统一管控 MongoDB Atlas 的数据库访问权限
• 支持在容器环境中快速部署和运行插件

二、核心功能和特性

2.1 动态凭证管理

• 自动生成：通过 Vault API 或 CLI 动态生成 MongoDB Atlas 用户凭证
• 临时有效：凭证具有可配置的生命周期，到期自动失效
• 最小权限：支持基于角色的权限粒度控制，仅授予必要访问权限

2.2 安全增强

• 唯一性：每个凭证关联独立用户，避免共享凭证风险
• 自动轮换：支持定时或按需轮换凭证，降低凭证泄露风险
• 审计追踪：通过 Vault 审计日志记录所有凭证生成与使用行为

2.3 集成能力

• MongoDB Atlas 原生支持：通过 MongoDB Atlas Admin API 实现凭证管理
• Vault 生态兼容：无缝集成 Vault 的策略系统、身份认证和机密管理能力
• 容器化部署：轻量级镜像设计，支持 Kubernetes、Docker Compose 等容器编排平台

2.4 运行环境约束

• 仅支持运行在 Linux 操作系统的 Vault 服务器
• 兼容 Docker 19.03+ 及容器运行时

三、使用场景和适用范围

3.1 典型使用场景

• 多环境数据库访问：开发、测试、生产环境的 MongoDB Atlas 动态凭证隔离
• CI/CD 流水线集成：为自动化流程生成临时数据库访问凭证，避免硬编码凭证
• 第三方服务访问：向外部服务授予临时数据库权限，到期自动回收

3.2 适用范围

• 已部署 HashiCorp Vault 的企业级架构
• 使用 MongoDB Atlas 托管数据库服务的场景
• 对数据库访问安全有严格合规要求的组织（如***、***等）
• 需要实现最小权限原则和凭证自动轮换的环境

四、使用方法和配置说明

4.1 前置条件

• Vault 服务器（v1.6+），运行于 Linux 操作系统
• Docker 环境（19.03+）或容器运行时（如 containerd）
• MongoDB Atlas 账号及 API 凭证（需具备 Project Owner 或 Database Access Admin 权限）
• 网络连通性：Vault 服务器可访问 MongoDB Atlas API（https://cloud.mongodb.com）

4.2 获取镜像

通过 Docker Hub 或 HashiCorp 容器仓库拉取官方镜像：

bash
docker pull hashicorp/vault-plugin-database-mongodbatlas:latest

4.3 Docker 运行配置

4.3.1 基础运行命令

bash
docker run -d \
  --name vault-mongodbatlas-plugin \
  --restart unless-stopped \
  -v /etc/vault/plugins:/vault/plugins \
  hashicorp/vault-plugin-database-mongodbatlas:latest

4.3.2 参数说明

4.4 Vault 配置流程

4.4.1 启用数据库机密引擎

bash
vault secrets enable database

4.4.2 注册插件至 Vault

bash
# 获取插件 SHA256 校验和（需替换为实际镜像内插件二进制路径）
PLUGIN_SHA256=$(sha256sum /vault/plugins/vault-plugin-database-mongodbatlas | awk '{print $1}')

# 注册插件
vault plugin register -sha256="$PLUGIN_SHA256" database mongodbatlas-database-plugin

4.4.3 配置 MongoDB Atlas 连接

bash
vault write database/config/mongodbatlas \
  plugin_name="mongodbatlas-database-plugin" \
  allowed_roles="readonly,readwrite" \
  public_key="ATLAS_PUBLIC_KEY" \          # MongoDB Atlas API 公钥
  private_key="ATLAS_PRIVATE_KEY" \        # MongoDB Atlas API 私钥
  project_id="ATLAS_PROJECT_ID" \          # MongoDB Atlas 项目 ID
  base_url="https://cloud.mongodb.com"     # API 基础地址（默认值）

4.4.4 创建访问角色

bash
# 创建只读角色（示例）
vault write database/roles/readonly \
  db_name="mongodbatlas" \
  creation_statements='{
    "database_name": "admin",
    "roles": [{"roleName": "read", "databaseName": "myappdb"}]
  }' \
  default_ttl="1h" \
  max_ttl="24h"

五、配置参数说明

5.1 Vault 配置参数（database/config/mongodbatlas）

5.2 角色创建参数（database/roles/<role-name>）

六、Docker 部署方案示例

6.1 Docker Run 命令

bash
# 运行插件容器并挂载至 Vault 插件目录
docker run -d \
  --name vault-mongodbatlas-plugin \
  --restart unless-stopped \
  -v /opt/vault/plugins:/plugins \  # 宿主机 Vault 插件目录（需与 Vault 配置一致）
  hashicorp/vault-plugin-database-mongodbatlas:latest

6.2 Docker Compose 配置

yaml
version: "3.8"

services:
  vault-plugin:
    image: hashicorp/vault-plugin-database-mongodbatlas:latest
    container_name: vault-mongodbatlas-plugin
    restart: unless-stopped
    volumes:
      - /opt/vault/plugins:/plugins  # 挂载至 Vault 可访问的插件目录
    networks:
      - vault-network  # 确保与 Vault 容器在同一网络

networks:
  vault-network:
    external: true  # 假设已存在 Vault 网络

七、使用示例

7.1 生成临时凭证

bash
vault read database/creds/readonly

输出示例：

Key                Value
---                -----
lease_id           database/creds/readonly/abc123...
lease_duration     1h
lease_renewable    true
password           vauLt-abcdef123456...
username           v-token-readonly-xyz789...

7.2 使用凭证访问 MongoDB Atlas

bash
# 使用生成的用户名/密码连接 MongoDB Atlas
mongo "mongodb+srv://<username>:<password>@cluster0.mongodb.net/myappdb" --authenticationDatabase admin

7.3 验证凭证权限

javascript
// 在 MongoDB Shell 中验证权限
db.runCommand({ connectionStatus: 1 })  // 确认连接成功
db.getRoles({ showPrivileges: true })   // 验证已分配的只读权限

八、注意事项

1. 环境兼容性：仅支持运行在 Linux 操作系统的 Vault 服务器，不支持 Windows 或 macOS 环境。
2. 权限控制：MongoDB Atlas API 凭证需具备 Project Owner 或 Database Access Admin 权限，否则无法创建/管理用户。
3. 网络安全：确保 Vault 服务器与 MongoDB Atlas API 之间网络通畅，建议通过 VPC peering 或 IP 白名单限制访问。
4. 镜像更新：定期更新插件镜像以获取安全补丁和功能更新，推荐使用具体版本标签（如 v1.2.0）而非 latest。
5. 凭证轮换：通过 Vault 策略配置 default_ttl 和 max_ttl，建议根据业务需求设置合理的轮换周期（如生产环境 default_ttl=15m）。

九、参考链接

• https://github.com/hashicorp/vault-plugin-database-mongodbatlas
• MongoDB Atlas API 文档
• Vault 数据库机密引擎文档