shield_lock
金大哥
← 返回 MCP 目录
public公开dns本地运行

ai-driven-temporal-to-iac

基于Temporal的工作流编排系统，用于管理多工作区的Terraform部署，支持依赖解析、变量传递和MCP服务器集成实现AI驱动的自动化。

article

README

🚀 临时Terraform编排器

这是一个基于Temporal的工作流编排系统，用于管理多工作区的Terraform部署。它具备依赖解析、工作区之间的变量传递功能，还能与MCP服务器集成以实现AI驱动的自动化。

🚀 快速开始

  1. 安装依赖： 
    go mod tidy
  2. 启动Temporal（若尚未运行）： 
    temporal server start-dev
  3. 启动工作器： 
    go run ./cmd/worker
  4. 执行工作流： 
    go run ./cmd/starter -config infra.yaml
  5. 在Temporal Web UI（http://localhost:8233）中监控执行情况。

✨ 主要特性

  • 依赖管理：定义工作区依赖关系，系统会按正确顺序执行。
  • 输出传播：将一个工作区的Terraform输出作为依赖工作区的输入。
  • 并行执行：独立工作区可并发运行，加快部署速度。
  • 持久性：Temporal提供自动重试、状态持久化和故障恢复功能。
  • AI集成：MCP服务器使AI代理能够触发和监控基础设施部署。

📦 安装指南

前提条件

  • Go 1.23+
  • Terraform CLI >= 1.5 - 需添加到系统路径中
  • Temporal Server - 运行在默认地址 localhost:7233（或设置 TEMPORAL_ADDRESS）
  • AWS凭证 - 若使用真实AWS资源（示例使用模拟输出）

💻 使用示例

基础用法

CLI启动器

启动工作流执行：

go run ./cmd/starter [flags]

标志说明

| 标志 | 默认值 | 描述 | | -------------- | --------------------------- | --------------------------------------------- | | -config | infra.yaml | 基础设施配置文件的路径 | | -task-queue | terraform-task-queue | Temporal任务队列名称 | | -workflow-id | terraform-parent-workflow | 用于跟踪的自定义工作流ID |

示例

# 使用默认设置运行
go run ./cmd/starter

# 指定自定义配置文件
go run ./cmd/starter -config ./environments/production.yaml

# 使用自定义工作流ID进行跟踪
go run ./cmd/starter -config infra.yaml -workflow-id "deploy-prod-2024-01-15"

MCP服务器

启动MCP服务器：

go run ./cmd/mcp-server

可用工具

list_workflows

列出配置文件中可用的工作流和已配置的工作区。 参数： | 参数 | 类型 | 是否必需 | 默认值 | 描述 | |-----------|------|----------|---------|-------------| | config_path | string | 否 | infra.yaml | YAML配置文件的路径 | 响应示例：

{
  "config_path": "infra.yaml",
  "workspace_root": ".",
  "workflows": [
    {
      "name": "ParentWorkflow",
      "description": "Orchestrates terraform operations across multiple workspaces with dependencies",
      "configured_workspaces": [
        {
          "name": "vpc",
          "kind": "terraform",
          "dir": "/abs/path/vpc",
          "dependsOn": []
        },
        {
          "name": "subnets",
          "kind": "terraform",
          "dir": "/abs/path/subnets",
          "dependsOn": ["vpc"]
        }
      ],
      "workspace_count": 2
    }
  ]
}
execute_workflow

启动Terraform编排工作流。 参数： | 参数 | 类型 | 是否必需 | 描述 | |-----------|------|----------|-------------| | workflow_name | string | 是 | 必须为 ParentWorkflow | | config_path | string | 否* | YAML配置文件的路径 | | config | object | 否* | 内联配置负载（JSON） | *必须提供 config_path 或 config 中的一个。 响应示例：

Workflow started successfully.
WorkflowID: terraform-parent-workflow-12345
RunID: abc123-def456-ghi789
get_workflow_status

获取正在运行或已完成的工作流的状态。 参数： | 参数 | 类型 | 是否必需 | 描述 | |-----------|------|----------|-------------| | workflow_id | string | 是 | 要检查的工作流ID | 响应示例：

Workflow: terraform-parent-workflow-12345
Status: WORKFLOW_EXECUTION_STATUS_COMPLETED
Started At: 2024-01-15 10:30:00
Finished At: 2024-01-15 10:35:42

与AI代理集成

将MCP服务器添加到MCP配置中：

{
  "mcpServers": {
    "temporal-terraform": {
      "command": "/path/to/mcp-server",
      "args": []
    }
  }
}

📚 详细文档

架构

工作流组件

  • ParentWorkflow（编排器）：
    1. 验证并规范化配置。
    2. 构建依赖有向无环图（DAG）。
    3. 立即启动根工作区（无依赖的工作区）。
    4. 监听完成信号，准备好后启动依赖工作区。
    5. 根据输入映射在工作区之间传播输出。
  • TerraformWorkflow：为单个工作区执行Terraform操作：
    1. terraform init - 初始化工作区
    2. terraform plan - 创建执行计划（使用 -detailed-exitcode 检测更改）
    3. terraform show -json - 验证计划输出
    4. terraform apply - 应用更改（若未检测到更改则跳过）
    5. terraform output -json - 捕获下游工作区的输出
    6. 向ParentWorkflow发送完成信号
    7. 进入“托管模式”以生成嵌套依赖的子工作流

托管架构

子工作流作为其“宿主”工作流（最深层依赖）的嵌套子项生成。这形成了一个自然的层次结构：

  • 根工作区是ParentWorkflow的直接子项。
  • 依赖工作区成为其宿主工作流的子项。
  • 所有工作流都向ParentWorkflow编排器发送完成信号。

配置参考 (infra.yaml)

配置文件定义了基础设施工作区及其关系。

完整架构

# 解析相对目录的基本路径（可选）
workspace_root: '.'

# 要编排的工作区列表
workspaces:
  - name: string # 必需：唯一的工作区标识符
    kind: string # 可选："terraform"（默认且唯一支持的值）
    dir: string # 必需：Terraform目录的路径
    tfvars: string # 可选：.tfvars文件的路径
    dependsOn: [string] # 可选：此工作区依赖的工作区名称列表
    inputs: [InputMapping] # 可选：来自依赖项的变量映射
    operations: [string] # 可选：要运行的操作（默认：[init, validate, plan, apply]）
    taskQueue: string # 可选：覆盖Temporal任务队列

输入映射架构

inputs:
  - sourceWorkspace: string # 依赖工作区的名称
    sourceOutput: string # 要读取的Terraform输出的名称
    targetVar: string # 要设置的Terraform变量的名称

完整示例

workspace_root: .

workspaces:
  # VPC工作区 - 无依赖，首先运行
  - name: vpc
    kind: terraform
    dir: terraform/examples/vpc
    tfvars: terraform/examples/vpc/vpc.tfvars
    dependsOn: []
    taskQueue: terraform-task-queue

  # 第二个VPC - 独立，与第一个并行运行
  - name: vpc-2
    kind: terraform
    dir: terraform/examples/vpc-2
    tfvars: terraform/examples/vpc-2/vpc.tfvars
    dependsOn: []
    taskQueue: terraform-task-queue

  # 子网 - 依赖于VPC，接收vpc_id输出
  - name: subnets
    kind: terraform
    dir: terraform/examples/subnets
    tfvars: terraform/examples/subnets/subnets.tfvars
    dependsOn:
      - vpc
    inputs:
      - sourceWorkspace: vpc
        sourceOutput: vpc_id
        targetVar: vpc_id
    taskQueue: terraform-task-queue

  # EKS - 依赖于VPC和子网，接收两者的输出
  - name: eks
    kind: terraform
    dir: terraform/examples/eks
    tfvars: terraform/examples/eks/eks.tfvars
    dependsOn:
      - vpc
      - subnets
    inputs:
      - sourceWorkspace: vpc
        sourceOutput: vpc_id
        targetVar: vpc_id
      - sourceWorkspace: subnets
        sourceOutput: subnet_ids
        targetVar: subnet_ids

关键概念

  • 工作区依赖 (dependsOn)：
    • 定义执行顺序约束。
    • 多个依赖项创建“与”条件（所有依赖项必须完成）。
    • 独立工作区（空或无 dependsOn）并行运行。
    • 验证期间会检测并拒绝循环依赖。
  • 输出到输入传播 (inputs)： inputs 数组将依赖工作区的Terraform输出映射到当前工作区的变量： 
    # 在子网工作区配置中
inputs:
  - sourceWorkspace: vpc # 从 'vpc' 工作区获取输出
    sourceOutput: vpc_id # 读取 'vpc_id' 输出
    targetVar: vpc_id # 作为 -var vpc_id=<value> 传递
    这允许你：
    • 将基础设施组件链接在一起。
    • 在工作区之间传递资源ID。
    • 构建复杂的依赖图。
  • 传递依赖： 输入映射支持传递依赖。例如，如果 C 依赖于 B，而 B 依赖于 A，则 C 可以映射来自 B 和 A 的输出： 
    workspaces:
  - name: a
    dir: ./a

  - name: b
    dir: ./b
    dependsOn: [a]

  - name: c
    dir: ./c
    dependsOn: [b]
    inputs:
      - sourceWorkspace: a # 有效：'a' 是传递依赖
        sourceOutput: some_output
        targetVar: from_a
      - sourceWorkspace: b # 有效：'b' 是直接依赖
        sourceOutput: other_output
        targetVar: from_b
  • 操作控制： operations 字段允许对每个工作区运行的Terraform操作进行细粒度控制： 
    operations: [init, validate, plan, apply]  # 完整应用模式（默认）
operations: [init, validate, plan]         # 仅计划模式（不应用）
    有效操作：
    • init - 初始化Terraform工作区（必需）
    • validate - 验证Terraform配置（必需）
    • plan - 生成执行计划
    • apply - 将更改应用到基础设施 要求：
    • init 和 validate 始终是必需的。
    • 操作必须按顺序指定：init → validate → plan → apply。
    • apply 需要 plan 存在。 用例：
    • 仅计划模式：设置 operations: [init, validate, plan] 用于审核/批准工作流。
    • 完整应用模式：设置 operations: [init, validate, plan, apply] 用于自动部署（默认）。
  • 路径解析：
    • workspace_root：解析相对路径的基本路径。
    • dir 和 tfvars 中的相对路径与 workspace_root 连接。
    • 绝对路径按原样使用。
    • 如果 workspace_root 为空，则使用当前工作目录。

🔧 技术细节

测试

运行所有测试：

go test ./...

测试覆盖范围

  • 配置验证：循环检测、重复名称、缺失依赖项、输入映射验证。
  • 父工作流：执行顺序、依赖等待、信号处理。
  • 活动：使用模拟Terraform二进制文件模拟CLI行为。 测试使用的假Terraform二进制文件：
  • 为 plan 返回退出代码2（模拟更改）。
  • 在磁盘上创建计划文件。
  • 为 output 和 show 命令返回模拟JSON。

仓库布局

.
├── activities/                 # Terraform CLI包装活动
│   ├── terraform_activities.go # 初始化、计划、验证、应用、输出
│   └── terraform_activities_test.go
├── cmd/
│   ├── mcp-server/            # 用于AI集成的MCP服务器
│   ├── starter/               # 启动工作流的CLI
│   └── worker/                # Temporal工作器进程
├── terraform/examples/        # 示例Terraform工作区
│   ├── vpc/
│   ├── vpc-2/
│   ├── subnets/
│   └── eks/
├── utils/                     # 共享常量
├── workflow/                  # Temporal工作流定义
│   ├── config.go              # 配置类型和验证
│   ├── parent_workflow.go     # 编排器工作流
│   └── terraform_workflow.go  # 每个工作区的工作流
├── go.mod
├── go.sum
├── infra.yaml                 # 示例配置
└── README.md

📄 故障排除

工作器连接问题

Unable to create client: ...

解决方案：确保Temporal服务器正在运行且可访问。如果使用非默认位置，请检查 TEMPORAL_ADDRESS。

工作流立即失败

Invalid config: ...

解决方案：验证你的 infra.yaml：

  • 检查是否有重复的工作区名称。
  • 确保所有 dependsOn 引用存在。
  • 验证是否没有循环依赖。
  • 确认 inputs 引用有效的依赖项。

Terraform错误

terraform init failed: ...

解决方案：

  • 确保 terraform 在系统路径中。
  • 验证工作区 dir 路径存在。
  • 检查目录中是否有有效的Terraform配置。
  • 对于AWS资源，确保已配置凭证。

未找到计划文件

plan file not found for apply: ...

解决方案：这通常表示 terraform plan 无声失败。检查：

  • 目录权限。
  • Terraform初始化状态。
  • 提供程序配置。

MCP服务器无响应

解决方案：MCP服务器在标准输入输出上运行。确保你的客户端配置为通过标准输入/输出进行通信，而不是HTTP。

help

运行方式说明

cloud

托管运行

托管运行通常表示这个 MCP Server 由服务方环境承载，用户一般按页面提供的连接方式或授权流程接入，不需要在本地长期启动一个 MCP 进程

  1. 打开服务方连接页
  2. 完成授权或复制端点
  3. 在 MCP 客户端中连接
terminal

本地运行 / 其它方式

本地运行通常需要用户在自己的电脑或服务器上安装依赖，把 server_config 复制到 MCP 客户端，并按 env_schema 补齐环境变量、密钥或其它配置

  1. 复制 server_config
  2. 安装所需依赖
  3. 补齐环境变量后重启客户端