Terraform Stacks

Terraform Stacks は、従来の Terraform モジュール上に設定層を提供することで、インフラストラクチャのプロビジョニングと管理を大規模に簡素化します。Stacks を使用すると、環境、リージョン、クラウドアカウント全体で複数のコンポーネントの宣言的なオーケストレーションが可能になります。

Core Concepts

Stack: コンポーネントとデプロイメントで構成される、一体として管理できるインフラストラクチャの完全なユニット。

Component: インフラストラクチャのパーツを定義する Terraform モジュールの抽象化。各コンポーネントはソースモジュール、入力値、プロバイダーを指定します。

Deployment: Stack 内のすべてのコンポーネントのインスタンスで、特定の入力値を持つもの。異なる環境（dev/staging/prod）、リージョン、またはクラウドアカウント用にデプロイメントを使用します。

Stack Language: 通常の Terraform HCL ではなく、独立した HCL ベースの言語で、異なるブロックとファイル拡張子を持ちます。

File Structure

Terraform Stacks は特定のファイル拡張子を使用します：

• Component configuration: .tfcomponent.hcl
• Deployment configuration: .tfdeploy.hcl
• Provider lock file: .terraform.lock.hcl (CLI によって生成される)

すべての設定ファイルは Stack リポジトリのルートレベルに配置する必要があります。HCP Terraform は依存順にすべてのファイルを処理します。

Recommended File Organization

my-stack/
├── .terraform-version               # The required Terraform version for this Stack
├── variables.tfcomponent.hcl        # Variable declarations
├── providers.tfcomponent.hcl        # Provider configurations
├── components.tfcomponent.hcl       # Component definitions
├── outputs.tfcomponent.hcl          # Stack outputs
├── deployments.tfdeploy.hcl         # Deployment definitions
├── .terraform.lock.hcl              # Provider lock file (generated)
└── modules/                         # Local modules (optional - only if using local modules)
    ├── s3/
    └── compute/

Note: modules/ ディレクトリはローカルモジュールソースを使用している場合のみ必要です。コンポーネントは以下のソースからモジュールを参照できます：

• Local file paths: ./modules/vpc
• Public registry: terraform-aws-modules/vpc/aws
• Private registry: app.terraform.io/<org-name>/vpc/aws
• Git: git::https://github.com/org/repo.git//path?ref=v1.0.0

HCP Terraform は依存順にすべての .tfcomponent.hcl と .tfdeploy.hcl ファイルを処理します。

Required Terraform version (.terraform-version)

Stacks CLI プラグインにアクセスし、terraform stacks CLI コマンドを実行するには、Terraform v1.13.x 以降を使用してください。Stack のルートディレクトリに .terraform-version ファイルを追加して、Stack に必要な Terraform バージョンを指定することから始めます。たとえば、以下のファイルは Terraform v1.14.5 を指定します：

1.14.5

Component Configuration (.tfcomponent.hcl)

Variable Block

Stack 設定の入力変数を宣言します。変数は type フィールドを定義する必要があり、validation 引数はサポートされていません。

variable "aws_region" {
  type        = string
  description = "AWS region for deployments"
  default     = "us-west-1"
}

variable "identity_token" {
  type        = string
  description = "OIDC identity token"
  ephemeral   = true  # Does not persist to state file
}

variable "instance_count" {
  type     = number
  nullable = false
}

重要: 認証情報やトークン（アイデンティティトークン、API キー、パスワード）に対して ephemeral = true を使用して、状態ファイルへの永続化を防ぎます。ライセンスキーなど、実行間で永続化する必要がある長く存続する値には stable を使用します。

Required Providers Block

required_providers {
  aws = {
    source  = "hashicorp/aws"
    version = "~> 6.0"
  }
  random = {
    source  = "hashicorp/random"
    version = "~> 3.5.0"
  }
}

Provider Block

プロバイダーブロックは従来の Terraform とは異なります：

1. for_each メタ引数をサポート
2. ブロックヘッダーにエイリアスを定義（引数としてではなく）
3. config ブロックを使用して設定を受け入れる

Single Provider Configuration:

provider "aws" "this" {
  config {
    region = var.aws_region
    assume_role_with_web_identity {
      role_arn           = var.role_arn
      web_identity_token = var.identity_token
    }
  }
}

Multiple Provider Configurations with for_each:

provider "aws" "configurations" {
  for_each = var.regions

  config {
    region = each.value
    assume_role_with_web_identity {
      role_arn           = var.role_arn
      web_identity_token = var.identity_token
    }
  }
}

Authentication Best Practice: Stacks の認証方法として workload identity（OIDC）を推奨します。このアプローチは：

• 長寿命の静的認証情報を回避
• デプロイメント実行ごとに一時的でスコープされた認証情報を提供
• クラウドプロバイダーIAM（AWS IAM Roles、Azure Managed Identities、GCP Service Accounts）と統合
• プラットフォーム管理の環境変数の必要性を排除

Workload identity を設定するには、プロバイダー設定で identity_token ブロックと assume_role_with_web_identity を使用します。AWS、Azure、GCP の詳細なセットアップ手順については、https://developer.hashicorp.com/terraform/cloud-docs/dynamic-provider-credentials を参照してください。

Component Block

各 Stack には少なくとも 1 つのコンポーネントブロックが必要です。Stack に含める各モジュール用にコンポーネントを追加します。コンポーネントはローカルパス、レジストリ、または Git からモジュールを参照します。

component "vpc" {
  source  = "app.terraform.io/my-org/vpc/aws"  # Local, registry, or Git URL
  version = "2.1.0"          # For registry modules

  inputs = {
    cidr_block  = var.vpc_cidr
    name_prefix = var.name_prefix
  }

  providers = {
    aws = provider.aws.this
  }
}

依存関係、for_each、public registry モジュール、Git ソースなどの例については、references/component-blocks.md を参照してください。

Key Points:

• 参照出力: component.<name>.<output> または component.<name>[key].<output>（for_each の場合）
• 依存関係はコンポーネント参照から自動的に推論される
• for 式で集約: [for x in component.s3 : x.bucket_name]
• for_each を使用するコンポーネント場合、特定のインスタンスを参照: component.<name>[each.value].<output>
• プロバイダー参照は通常の値: provider.<type>.<alias> または provider.<type>.<alias>[each.value]

Output Block

出力には type 引数が必要で、preconditions はサポートされていません：

output "vpc_id" {
  type        = string
  description = "VPC ID"
  value       = component.vpc.vpc_id
}

output "endpoint_urls" {
  type      = map(string)
  value     = {
    for region, comp in component.api : region => comp.endpoint_url
  }
  sensitive = false
}

Locals Block

Locals ブロックは .tfcomponent.hcl と .tfdeploy.hcl ファイルの両方で同じように動作します：

locals {
  common_tags = {
    Environment = var.environment
    ManagedBy   = "Terraform Stacks"
    Project     = var.project_name
  }

  region_config = {
    for region in var.regions : region => {
      name_suffix = "${var.environment}-${region}"
    }
  }
}

Removed Block

Stack からコンポーネントを安全に削除するために使用します。HCP Terraform はコンポーネントを削除するためにそのプロバイダーを必要とします。

removed {
  from   = component.old_component
  source = "./modules/old-module"
  
  providers = {
    aws = provider.aws.this
  }
}

Deployment Configuration (.tfdeploy.hcl)

Identity Token Block

クラウドプロバイダーとの OIDC 認証用の JWT トークンを生成します：

identity_token "aws" {
  audience = ["aws.workload.identity"]
}

identity_token "azure" {
  audience = ["api://AzureADTokenExchange"]
}

identity_token.<name>.jwt を使用してデプロイメント内のトークンを参照します。

Store Block

Stack デプロイメント内で HCP Terraform 変数セットにアクセスします：

store "varset" "aws_credentials" {
  id       = "varset-ABC123"  # Alternatively use: name = "varset_name"
  source   = "tfc-cloud-shared"
  category = "terraform"      # Alternatively use: category = "env" for environment variables
}

deployment "production" {
  inputs = {
    aws_access_key = store.varset.aws_credentials.AWS_ACCESS_KEY_ID
  }
}

認証情報を一元化し、Stack 全体で変数を共有するために使用します。詳細については references/deployment-blocks.md を参照してください。

Deployment Block

デプロイメントインスタンスを定義します（Stack あたり最小 1 個、最大 20 個）：

deployment "production" {
  inputs = {
    aws_region     = "us-west-1"
    instance_count = 3
    role_arn       = local.role_arn
    identity_token = identity_token.aws.jwt
  }
}

# Create multiple deployments for different environments
deployment "development" {
  inputs = {
    aws_region     = "us-east-1"
    instance_count = 1
    name_suffix    = "dev"
    role_arn       = local.role_arn
    identity_token = identity_token.aws.jwt
  }
}

デプロイメントを破棄するには: デプロイメントブロックで destroy = true を設定し、設定をアップロードして、HCP Terraform が破棄実行を作成します。詳細については references/deployment-blocks.md を参照してください。

Deployment Group Block

共有設定のためにデプロイメントをグループ化します（HCP Terraform Premium tier 機能）。Free/standard tiers は {deployment-name}_default という名前のデフォルトグループを使用します。

deployment_group "canary" {
  auto_approve_checks = [deployment_auto_approve.safe_changes]
}

deployment "dev" {
  inputs = { /* ... */ }
  deployment_group = deployment_group.canary
}

複数のデプロイメントが同じグループを参照できます。詳細については references/deployment-blocks.md を参照してください。

Deployment Auto-Approve Block

デプロイメントプランを自動的に承認するルールを定義します（HCP Terraform Premium tier 機能）：

deployment_auto_approve "safe_changes" {
  deployment_group = deployment_group.canary

  check {
    condition = context.plan.changes.remove == 0
    reason    = "Cannot auto-approve plans with resource deletions"
  }
}

利用可能なコンテキスト変数: context.plan.applyable、context.plan.changes.add/change/remove/total、context.success

Note: orchestrate ブロックは廃止予定です。代わりに deployment_group と deployment_auto_approve を使用してください。

すべてのコンテキスト変数とパターンについては references/deployment-blocks.md を参照してください。

Publish Output and Upstream Input Blocks

1 つの Stack から出力を発行し、別の Stack で消費することで、Stack をリンクします：

# In network Stack - publish outputs
publish_output "vpc_id_network" {
  type  = string
  value = deployment.network.vpc_id
}

# In application Stack - consume outputs
upstream_input "network_stack" {
  type   = "stack"
  source = "app.terraform.io/my-org/my-project/networking-stack"
}

deployment "app" {
  inputs = {
    vpc_id = upstream_input.network_stack.vpc_id_network
  }
}

完全なドキュメントと例については references/linked-stacks.md を参照してください。

Terraform Stacks CLI

Note: Terraform Stacks は Terraform CLI v1.13+ 時点で一般利用可能（GA）です。Stacks は HCP Terraform 課金の Resources Under Management（RUM）にカウントされるようになりました。

Initialize and Validate

terraform stacks init              # Download providers, modules, generate lock file
terraform stacks providers-lock    # Regenerate lock file (add platforms if needed)
terraform stacks validate          # Check syntax without uploading

Deployment Workflow

重要: plan または apply コマンドはありません。設定をアップロードするとデプロイメント実行が自動的にトリガーされます。

# 1. Upload configuration (triggers deployment runs)
terraform stacks configuration upload

# 2. Monitor deployments
terraform stacks deployment-run list                          # List runs (non-interactive)
terraform stacks deployment-group watch -deployment-group=... # Stream status updates

# 3. Approve deployments (if auto-approve not configured)
terraform stacks deployment-run approve-all-plans -deployment-run-id=...
terraform stacks deployment-group approve-all-plans -deployment-group=...
terraform stacks deployment-run cancel -deployment-run-id=...  # Cancel if needed

Configuration Management

terraform stacks configuration list                    # List configuration versions
terraform stacks configuration fetch -configuration-id=...  # Download configuration
terraform stacks configuration watch                   # Monitor upload status

Other Commands

terraform stacks create              # Create new Stack (interactive)
terraform stacks fmt                 # Format Stack files
terraform stacks list                # Show all Stacks
terraform stacks version             # Display version
terraform stacks deployment-group rerun -deployment-group=...  # Rerun deployment

Monitoring Deployments with HCP Terraform API

自動化、CI/CD、または非対話型環境（AI エージェントなど）での段階的な監視の場合は、CLI watch コマンドの代わりに HCP Terraform API を使用します。API は以下のエンドポイントを提供します：

• Configuration status and validation
• Deployment group summaries
• Deployment run status
• Deployment step details (plan/apply)
• Error diagnostics with file locations and code snippets
• Stack outputs via artifacts endpoint

Key points:

• CLI watch コマンドは無限にストリーミングされ、自動化では機能しません
• Stack 出力を取得するには artifacts エンドポイントを使用: GET /api/v2/stack-deployment-steps/{step-id}/artifacts?name=apply-description
• Diagnostics エンドポイントには stack_deployment_step_id クエリパラメータが必要です
• Artifacts エンドポイントは HTTP 307 リダイレクトを返します（curl -L を使用）

完全な API ワークフロー、認証、ポーリングベストプラクティス、サンプルスクリプトについては references/api-monitoring.md を参照してください。

Common Patterns

Component Dependencies: 1 つのコンポーネントが別のコンポーネントの出力を参照する場合（例：subnet_ids = component.vpc.private_subnet_ids）、依存関係は自動的に推論されます。

Multi-Region Deployment: プロバイダーとコンポーネントで for_each を使用して、複数のリージョンにデプロイします。各リージョンは独自のプロバイダー設定とコンポーネントインスタンスを取得します。

Deferred Changes: Stacks は遅延変更をサポートして、apply 後にのみ値が既知の依存関係を処理します。これは、一部のリソースが他のコンポーネント（クラスターエンドポイント、生成されたパスワードなど）からのランタイム値に依存する複雑なマルチコンポーネントデプロイメントを実現します。

マルチリージョンデプロイメント、コンポーネント依存関係、遅延変更パターン、リンクされた Stack を含む完全な例については references/examples.md を参照してください。

Best Practices

1. Component Granularity: ライフサイクルを共有する論理的なインフラストラクチャユニット用のコンポーネントを作成します
2. Module Compatibility:
   • Stacks で使用されるモジュールはプロバイダーブロックを含めることはできません（Stack 設定でプロバイダーを設定）
   • 本番環境で使用する前に public registry モジュールをテストしてください - 一部のモジュールに互換性の問題がある場合があります
   • モジュール互換性が不確実な場合は、重要なインフラストラクチャに対して未処理のリソースの使用を検討してください
   • 例: 一部の terraform-aws-modules バージョンは Stacks との互換性の問題が見つかっています（ALB および ECS モジュールなど）
3. State Isolation: 各デプロイメントは独立した状態を持ちます
4. Input Variables: デプロイメント全体で異なる値に変数を使用します。共有値には locals を使用します
5. Provider Lock Files: 常に .terraform.lock.hcl を生成してバージョン管理にコミットします
6. Naming Conventions: コンポーネントとデプロイメントに説明的な名前を使用します
7. Deployment Groups: デプロイメントを deployment groups に整理できます。Deployment groups は自動承認ルール、論理的な整理、スケーリングの基盤を提供します。Deployment groups は HCP Terraform Premium tier 機能です
8. Testing: 本番環境の前に dev/staging デプロイメントで Stack 設定をテストします

Troubleshooting

Circular Dependencies: 循環参照を解除するためにリファクタリングするか、中間コンポーネントを使用します。

Deployment Destruction: UI からは破棄できません。デプロイメントブロックで destroy = true を設定し、設定をアップロードして、HCP Terraform が破棄実行を作成します。

Empty Diagnostics: diagnostics API リクエストに必須の stack_deployment_step_id クエリパラメータを追加します。

Module Compatibility: 本番環境使用前に public registry モジュールをテストしてください。一部のモジュールは Stacks との互換性の問題がある場合があります。

References

詳細なドキュメントについては、以下を参照してください：

• references/component-blocks.md - すべての引数と構文を含む完全なコンポーネントブロック参照
• references/deployment-blocks.md - すべての設定オプションを含む完全なデプロイメントブロック参照
• references/linked-stacks.md - Stack をリンクするための発行出力と上流入力
• references/examples.md - マルチリージョンとコンポーネント依存関係の完全に機能する例
• references/api-monitoring.md - プログラム監視と自動化の完全な API ワークフロー
• references/troubleshooting.md - 一般的な問題と解決策の詳細なトラブルシューティングガイド