Terraform CloudのAgent設定ガイド — オンプレ・VPC内リソースへの接続

1. 概要

• Terraform Cloud Agentとは（Self-hosted Agentの概要）
• AgentがVPC内やオンプレ環境へのアクセスを可能にする仕組み
• AgentのデプロイとAgentPoolの設定方法
• WorkspaceへのAgent割り当て

Terraform Cloud Agentは、オンプレミスやVPC内のプライベート環境にデプロイするself-hostedの実行エージェントです。Terraform CloudのRunをAgentが受け取り、VPC内のリソースに直接アクセスしてplan/applyを実行できます。BusinessプランのTerraform Cloudで利用可能です。

---

2. Agentの仕組み

Terraform Cloud
  │ Runをキュー → AgentPoolへ転送
  ↓
Self-hosted Agent（VPC内 or オンプレ）
  │ Runを受け取りplan/apply実行
  │ プライベートAPIへアクセス（例: オンプレDB・VPC内EKS）
  ↓
プライベートリソース

AgentはTerraform Cloudに対してアウトバウンド接続（ポーリング）するだけです。インバウンド通信は不要なため、ファイアウォールルールが最小限で済みます。

---

3. AgentをEC2でデプロイするTerraform例

# agent_infra/main.tf
terraform {
  required_version = ">= 1.9"
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"
    }
  }
}

provider "aws" {
  region = "ap-northeast-1"
}

variable "environment" {
  description = "環境名"
  type        = string
  default     = "dev"
}

variable "tfc_agent_token" {
  description = "Terraform Cloud Agentトークン"
  type        = string
  sensitive   = true
}

data "aws_ami" "amazon_linux_2023" {
  most_recent = true
  owners      = ["amazon"]
  filter {
    name   = "name"
    values = ["al2023-ami-*-x86_64"]
  }
}

data "aws_vpc" "main" {
  filter {
    name   = "tag:Name"
    values = ["${var.environment}-vpc"]
  }
}

data "aws_subnets" "private" {
  filter {
    name   = "vpc-id"
    values = [data.aws_vpc.main.id]
  }
  filter {
    name   = "tag:Tier"
    values = ["private"]
  }
}

resource "aws_instance" "tfc_agent" {
  ami           = data.aws_ami.amazon_linux_2023.id
  instance_type = "t3.micro"
  subnet_id     = data.aws_subnets.private.ids[0]

  user_data = base64encode(<<-EOF
    #!/bin/bash
    # Docker インストール
    dnf install -y docker
    systemctl start docker
    systemctl enable docker

    # TFC Agent 起動
    docker run -d       --restart=always       --name tfc-agent       -e TFC_AGENT_TOKEN="${var.tfc_agent_token}"       -e TFC_AGENT_NAME="${var.environment}-agent"       hashicorp/tfc-agent:latest
  EOF
  )

  root_block_device {
    volume_size = 20
    volume_type = "gp3"
    encrypted   = true
  }

  tags = {
    Name        = "${var.environment}-tfc-agent"
    Environment = var.environment
    ManagedBy   = "terraform"
  }
}

---

4. Agentのセットアップ手順

Step 1: AgentPoolを作成

Terraform Cloud → Settings → Agents → Create an Agent Pool

AgentPool名を設定し、Agentトークンを発行します。

Step 2: Agentを起動

EC2 / コンテナ / Kubernetes Pod等にAgentをデプロイします。上記のTerraformコードを参照してください。

# 手動で動かす場合
export TFC_AGENT_TOKEN="your-agent-token"
export TFC_AGENT_NAME="my-agent"
docker run -e TFC_AGENT_TOKEN -e TFC_AGENT_NAME hashicorp/tfc-agent:latest

Step 3: WorkspaceにAgentPoolを割り当て

Workspace → Settings → Execution Mode → Agent → AgentPoolを選択

---

5. Agent vs Remote実行 vs Local実行

比較軸	Remote実行	Local実行	Agent実行
実行場所	TF Cloud Runner	ローカルマシン	Self-hosted Agent
VPC内リソースへのアクセス	❌	✅	✅
実行ログ（TF Cloud上）	✅	❌	✅
プラン	Free〜	Free〜	Business
インバウンド接続	不要	不要	不要（Agentがポーリング）

---

6. ユースケース

• オンプレDB・VMへのTerraform apply: プライベートネットワーク内のvSphere・Nexus等をTerraformで管理
• EKS/k8s Providerでのクラスター管理: k8sのAPIサーバーにVPC内からしかアクセスできない場合
• データセンター内のネットワーク機器: Cisco・Palo Alto等のプロバイダーでネットワーク機器を管理
• AWS PrivateLinkを使ったサービス: パブリックエンドポイントがないプライベートサービスへのアクセス

---

7. 関連記事

• Terraform Cloud remote実行 vs local実行 — 実行モード比較
• Terraform Cloudは無料でどこまで使える？ — Businessプランが必要
• Terraform CloudのVCS連携設定ガイド — VCS連携
• Terraform Cloud vs Jenkins — エンタープライズ選定ガイド — オンプレ対応の比較
• sensitive変数 — 機密値のマスクとstateへの記録 — Agentトークンの管理
• Atlantis vs Terraform Cloud — OSSとSaaSの使い分け — セルフホスト代替

---

8. まとめ

• Terraform Cloud AgentはVPC内やオンプレにデプロイしてplan/applyを実行するself-hostedエージェント
• AgentはTerraform Cloudにアウトバウンド接続（ポーリング）するだけでインバウンドは不要
• Businessプランで利用可能。AgentPool → Agentトークン → EC2等にデプロイ → Workspaceに割り当てる
• プライベートAPIへのアクセスが必要なエンタープライズ環境で特に有用

---

対象バージョン: Terraform Cloud Business / tfc-agent (2024) 公式ドキュメント: https://developer.hashicorp.com/terraform/cloud-docs/agents

---