Ai Driven Temporal To Iac

🚀 临时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]

标志说明

示例

# 使用默认设置运行
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": "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 started successfully.
WorkflowID: terraform-parent-workflow-12345
RunID: abc123-def456-ghi789

get_workflow_status

获取正在运行或已完成的工作流的状态。 参数：

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。