nomad-vault-integration 镜像文档

一、镜像概述和主要用途

镜像名称：nomad-vault-integration（示例名称，实际以官方为准）
主要用途：该镜像专为简化 Nomad 与 Vault 的集成流程设计，提供开箱即用的工具链、配置模板及示例，帮助用户快速实现 Nomad 集群与 Vault 密钥管理系统的安全集成。其核心目标是降低跨系统密钥注入、认证配置及权限管理的复杂度，适用于开发、测试及生产环境中 Nomad 任务的密钥安全管理场景。

二、核心功能和特性

2.1 核心功能

• 支持 Nomad 与 Vault 的双向认证配置（含 AppRole、Kubernetes、JWT 等 Vault 认证机制）
• 提供 Nomad 任务密钥注入模板，支持动态密钥挂载至任务容器
• 集成 Vault 策略生成工具，可根据 Nomad 任务角色自动生成最小权限策略
• 内置 Nomad 服务注册与 Vault 密钥路径映射的配置校验功能

2.2 关键特性

• 轻量级：基于 Alpine 基础镜像，镜像体积<100MB，资源占用低
• 兼容性：支持 Nomad 1.0+ 及 Vault 1.5+ 版本
• 自动化：内置初始化脚本，自动完成基础认证配置与连接测试
• 可扩展：支持自定义配置文件挂载，适配复杂企业级集成场景

三、使用场景和适用范围

3.1 典型使用场景

• Nomad 集群密钥管理：为 Nomad 任务（如数据库连接、API 密钥）提供安全的密钥注入能力，避免密钥硬编码
• 开发测试环境：快速搭建 Nomad-Vault 集成原型，验证密钥流转链路
• 生产环境配置标准化：通过镜像内置模板统一 Nomad 与 Vault 的集成规范，减少人工配置错误

3.2 适用范围

• 运行 Nomad 1.0+ 的容器编排集群
• 部署 Vault 1.5+ 的密钥管理系统
• 需要通过 Vault 管理动态密钥、静态密钥或证书的 Nomad 任务
• 开发、测试及生产环境的密钥安全集成需求

四、使用方法和配置说明

4.1 获取镜像

通过 Docker Hub 或私有仓库拉取镜像（示例命令）：

docker pull [仓库地址]/nomad-vault-integration:latest

4.2 基本使用（docker run 命令）

4.2.1 快速启动（默认配置）

docker run -d \
  --name nomad-vault-integration \
  -e NOMAD_ADDR="[***]" \
  -e VAULT_ADDR="[***]" \
  -e VAULT_AUTH_METHOD="approle" \
  -e VAULT_ROLE_ID="your-role-id" \
  -e VAULT_SECRET_ID="your-secret-id" \
  [仓库地址]/nomad-vault-integration:latest

4.2.2 带自定义策略配置

挂载本地策略文件至容器，覆盖默认策略：

docker run -d \
  --name nomad-vault-integration \
  -e NOMAD_ADDR="[***]" \
  -e VAULT_ADDR="[***]" \
  -v $(pwd)/custom-policy.hcl:/etc/vault/policy.hcl \  # 挂载自定义Vault策略
  -v $(pwd)/nomad-job-template.nomad:/etc/nomad/job.nomad \  # 挂载Nomad任务模板
  [仓库地址]/nomad-vault-integration:latest

4.3 环境变量配置

4.4 卷挂载说明

4.5 Docker Compose 部署示例

version: '3.8'

services:
  nomad-vault-integration:
    image: [仓库地址]/nomad-vault-integration:latest
    container_name: nomad-vault-integration
    environment:
      - NOMAD_ADDR=[***]
      - NOMAD_TOKEN=nomad-acl-token-xxxx
      - VAULT_ADDR=[***]
      - VAULT_AUTH_METHOD=approle
      - VAULT_ROLE_ID=role-id-xxxx
      - VAULT_SECRET_ID=secret-id-xxxx
      - LOG_LEVEL=debug
    volumes:
      - ./vault-policy.hcl:/etc/vault/policy.hcl
      - ./nomad-job.nomad:/etc/nomad/job.nomad
      - ./certs:/etc/certs:ro
    restart: unless-stopped
    networks:
      - nomad-vault-net

networks:
  nomad-vault-net:
    driver: bridge

五、注意事项

1. 生产环境中，VAULT_SECRET_ID 等敏感信息建议通过 Vault 自身或外部密钥管理系统注入，避免直接暴露在环境变量中。
2. 确保 Nomad 与 Vault 服务之间网络互通，且防火墙规则允许相关端口（Nomad 4646/tcp，Vault 8200/tcp）通信。
3. 镜像默认策略为最小权限示例，生产环境需根据实际业务需求调整 /etc/vault/policy.hcl。
4. 首次启动时，容器会自动执行集成测试（验证 Nomad-Vault 连接及认证），测试结果可通过 docker logs 查看。