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。