hashicorp/postgres-nomad-demo

nomad-vault-integration 镜像文档

镜像概述和主要用途

nomad-vault-integration 镜像专为 Nomad 与 Vault 的集成场景设计，提供开箱即用的工具链和配置模板，帮助用户在 Nomad 集群中安全集成 Vault 密钥管理系统。其核心用途是简化 Nomad 任务对 Vault 中敏感信息（如密钥、证书、凭证）的访问流程，实现敏感数据的动态获取、自动轮换和安全分发，保障 Nomad 集群中服务的配置安全性。

核心功能和特性

• Vault Agent 集成：内置 Vault Agent，支持自动注入 Vault 密钥到 Nomad 任务，无需手动配置密钥获取逻辑。
• 动态密钥管理：支持通过 Vault 动态生成和轮换 Nomad 任务所需的数据库凭证、API 密钥等，降低静态密钥泄露风险。
• 策略适配：兼容 Vault 策略系统，可通过自定义策略控制 Nomad 任务对 Vault 路径的访问权限，实现最小权限原则。
• 多环境支持：适配开发、测试、生产等多环境配置，支持通过环境变量动态调整 Vault 连接参数和 Nomad 任务关联信息。
• 轻量级设计：基于 Alpine 基础镜像构建，体积小巧，启动速度快，适合容器化部署。

使用场景和适用范围

适用场景

• Nomad 集群敏感信息管理：替代传统静态配置文件，通过 Vault 集中管理 Nomad 任务的数据库密码、API 令牌等敏感信息。
• 微服务架构密钥分发：在 Nomad 编排的微服务集群中，为不同服务动态分发专属密钥，避免密钥跨服务共享。
• CI/CD 流程凭证注入：在 Nomad 任务中集成 CI/CD 流程时，通过 Vault 动态注入代码仓库凭证、镜像仓库密钥等，避免凭证硬编码。

适用范围

• Nomad 版本：兼容 Nomad 1.0+ 集群（支持任务驱动和服务发现功能）。
• Vault 版本：支持 Vault 1.5+（需启用 KV Secrets Engine v2 和动态密钥生成功能）。
• 部署环境：物理机、虚拟机、Kubernetes 集群或云服务器中的 Nomad 节点。

使用方法和配置说明

前提条件

1. 已部署 Nomad 集群（1.0+），并确保节点可访问外部网络（用于拉取镜像）。
2. 已部署 Vault 服务器（1.5+），并启用以下功能：
   • KV Secrets Engine v2（路径如 secret/）；
   • 为 Nomad 配置访问策略（允许读取指定路径的密钥）；
   • 生成具有对应策略权限的 Vault Token（或启用 AppRole 认证）。

拉取镜像

通过 Docker Hub 拉取最新版本镜像：

bash
docker pull hashicorp/nomad-vault-integration:latest  

Docker Run 示例

以下示例通过 docker run 启动容器，模拟 Nomad 任务通过镜像访问 Vault 并获取密钥：

bash
docker run -d \  
  --name nomad-vault-demo \  
  -e VAULT_ADDR="http://vault-server:8200" \  # Vault 服务器地址  
  -e VAULT_TOKEN="s.token.example123" \        # Vault 访问令牌（需具备对应策略权限）  
  -e NOMAD_JOB_NAME="web-service" \            # 关联的 Nomad 任务名称（用于动态生成密钥路径）  
  -e SECRET_PATH="secret/nomad/web" \          # Vault 中存储密钥的路径  
  --network nomad-vault-net \                  # 确保与 Nomad、Vault 网络连通  
  hashicorp/nomad-vault-integration:latest  

容器启动后，会自动通过 Vault Agent 从 secret/nomad/web 路径拉取密钥，并将其注入到 /vault/secrets 目录下的文件中，供 Nomad 任务读取。

Docker Compose 配置示例

通过 docker-compose.yml 编排 Nomad、Vault 和集成镜像，模拟完整集成环境：

yaml
version: '3.8'  

services:  
  vault:  
    image: hashicorp/vault:1.15.0  
    container_name: vault-server  
    ports:  
      - "8200:8200"  
    environment:  
      - VAULT_DEV_ROOT_TOKEN_ID=s.token.devroot  # 开发模式根令牌（生产环境禁用）  
    cap_add:  
      - IPC_LOCK  # 启用内存锁定，防止密钥泄露到磁盘  
    command: server -dev  # 开发模式（生产环境需配置持久化存储和 TLS）  

  nomad:  
    image: hashicorp/nomad:1.6.0  
    container_name: nomad-server  
    ports:  
      - "4646:4646"  # HTTP API 端口  
    command: agent -dev -bind 0.0.0.0  # 开发模式（单节点，生产环境需配置集群）  

  nomad-vault-integration:  
    image: hashicorp/nomad-vault-integration:latest  
    container_name: nomad-vault-demo  
    depends_on:  
      - vault  
      - nomad  
    environment:  
      - VAULT_ADDR="http://vault:8200"  
      - VAULT_TOKEN="s.token.devroot"  # 使用 Vault 开发模式根令牌  
      - NOMAD_JOB_NAME="demo-job"  
      - SECRET_PATH="secret/nomad/demo"  
    network_mode: "service:nomad"  # 共享 Nomad 容器网络命名空间  

启动服务：

bash
docker-compose up -d  

环境变量说明

注意事项

1. Vault 策略配置：需确保 VAULT_TOKEN 对应的 Vault 策略允许读取 SECRET_PATH 路径，策略示例：

   hcl
   path "secret/nomad/prod/*" {  
     capabilities = ["read"]  
   }  
   

2. 网络连通性：容器需与 Nomad 节点、Vault 服务器在同一网络，或通过端口映射确保 VAULT_ADDR 可访问。
3. 安全最佳实践：
   • 生产环境中禁用 VAULT_SKIP_VERIFY，配置有效的 TLS 证书；
   • 避免硬编码 VAULT_TOKEN，优先使用 Vault AppRole 或 Nomad 服务账户动态获取令牌；
   • 定期轮换 VAULT_TOKEN 和 Vault 中的密钥，降低泄露风险。