Ai Driven Temporal To Iac

🚀 Temporal Terraform Orchestrator

このプロジェクトは、Temporal ワークフローを用いた強力なインフラストラクチャコードオーケストレーションレイヤーを提供します。複数のワークスペース間でのTerraform操作を、依存関係解決、ワークスペース間の変数渡し、そしてAI駆動の自動化のためのMCPサーバー統合を通じて管理します。

🚀 クイックスタート

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 - PATHに設定されていること
• Temporal Server - デフォルトアドレス localhost:7233 で実行中（または TEMPORAL_ADDRESS を設定）
• AWS認証情報 - 実際のAWSリソースを使用する場合（サンプルではモック出力を使用）

💻 使用例

基本的な使用法

CLI Starterの使用

# デフォルト設定で実行
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 Serverの使用

list_workflows コマンド

# パラメーターなしで実行
go run ./cmd/mcp-server <<EOF
{
  "jsonrpc": "2.0",
  "method": "list_workflows",
  "params": {},
  "id": 1
}
EOF

応答例:

{
  "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 コマンド

go run ./cmd/mcp-server <<EOF
{
  "jsonrpc": "2.0",
  "method": "execute_workflow",
  "params": {
    "workflow_name": "ParentWorkflow",
    "config_path": "infra.yaml"
  },
  "id": 2
}
EOF

応答例:

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

get_workflow_status コマンド

go run ./cmd/mcp-server <<EOF
{
  "jsonrpc": "2.0",
  "method": "get_workflow_status",
  "params": {
    "workflow_id": "terraform-parent-workflow-12345"
  },
  "id": 3
}
EOF

応答例:

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

📚 ドキュメント

アーキテクチャ

ワークフローコンポーネント

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

  # 2番目のVPC - 独立しており、最初の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)

• 実行順序の制約を定義します。
• 複数の依存関係はAND条件を作成します（すべてが完了する必要があります）。
• 独立したワークスペース（空または 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 ./...

テストカバレッジ

• 設定検証：サイクル検出、重複する名前、欠落している依存関係、入力マッピングの検証。
• 親ワークフロー：実行順序、依存関係の待機、信号処理。
• アクティビティ：CLIの動作をシミュレートするシムTerraformバイナリを使用。

テストでは、以下の動作をする偽のTerraformバイナリを使用します。

• plan で終了コード2を返します（変更をシミュレート）。
• ディスク上に計画ファイルを作成します。
• output および show コマンドにモックJSONを返します。

リポジトリのレイアウト

.
├── activities/                 # Terraform CLIラッパーアクティビティ
│   ├── terraform_activities.go # Init, Plan, Validate, Apply, Output
│   └── 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 がPATHに設定されていることを確認してください。
• ワークスペースの dir パスが存在することを確認してください。
• ディレクトリ内のTerraform設定が有効であることを確認してください。
• AWSリソースを使用する場合は、認証情報が構成されていることを確認してください。

計画ファイルが見つからない

plan file not found for apply: ...

解決策：これは通常、terraform plan がサイレントに失敗したことを示しています。以下を確認してください。

• ディレクトリの権限。
• Terraformの初期化状態。
• プロバイダーの設定。

MCPサーバーが応答しない

解決策：MCPサーバーは標準入出力で動作します。クライアントがHTTPではなく標準入出力を介して通信するように構成されていることを確認してください。