Terraform Associate向け: providerメタ引数で実現する複数プロバイダ設定の基礎と実務

複数リージョンや複数アカウントを扱うとき、Terraformではproviderブロックのaliasと、resourceのproviderメタ引数、さらにmoduleのprovidersマップを正しく組み合わせます。

Associate試験では、デフォルト継承・リソース単位の切り替え・モジュール境界での引き渡しの違いと、configuration_aliasesの宣言有無が頻出です。

複数プロバイダ構成の前提と全体像

Terraformでは、同じプロバイダ種別に対して複数の設定を持てます。無名の設定がデフォルト、alias属性を持つ設定が別名付き設定です。resourceやdataは、providerメタ引数を指定しない場合はデフォルト設定を継承し、指定した場合は対応する別名設定を使います。

モジュール境界をまたぐときは、ルート側でmoduleブロックのprovidersマップを使って、子モジュールへ明示的にプロバイダ設定を渡せます。子モジュール側はterraform.required_providers内でconfiguration_aliasesを宣言して、受け取る別名を許可する必要があります。

ポイントは次の3層です。1) プロバイダ設定を定義する層、2) リソースでどの設定を使うか選ぶ層、3) モジュール間で設定を受け渡す層。これを混同しないことが安定運用と試験対策の近道です。

• デフォルト設定はproviderメタ引数未指定のリソースで自動使用される
• 別名設定はprovider "aws" { alias = "ue1" ... }のように定義する
• resourceのproviderメタ引数は aws.ue1 のように設定参照を書く（文字列ではない）
• モジュールへ渡すにはmoduleのprovidersマップと、子側のconfiguration_aliasesが必要

複数プロバイダ構成の流れ（デフォルト継承と別名受け渡し）

最小構成の例（デフォルトと別名、リソースでの切り替え）

terraform {
  required_providers {
    aws = {
      source = "hashicorp/aws"
    }
  }
}

provider "aws" {
  region = "us-east-1"
}

provider "aws" {
  alias  = "ue1"
  region = "us-east-1"
}

provider "aws" {
  alias  = "uw2"
  region = "us-west-2"
}

resource "aws_s3_bucket" "primary" {
  bucket = "example-primary-1234"
}

resource "aws_s3_bucket" "replica" {
  bucket   = "example-replica-1234"
  provider = aws.ue1
}

providerメタ引数の使い方（resource/data）

resourceやdataブロックでは、providerメタ引数で使用するプロバイダ設定を明示できます。書式は provider = <PROVIDER_ADDRESS>（例: aws.ue1）のように設定参照であり、文字列ではありません。

条件式で複数の設定を切り替えることも可能です。ただし、条件式の両側で参照されるプロバイダ設定は同一モジュール内で事前に定義されている必要があります。存在しない設定を参照すると計画段階でエラーになります。

注意点として、providerメタ引数はモジュールブロックには存在しません。モジュールへはprovidersマップで渡します。resourceやdataでproviderを指定する場合も、当該モジュール内に該当するプロバイダ設定が無ければなりません。

• 書式は provider = aws.alias のように参照で指定（文字列不可）
• 条件式で切替は可能だが、参照先の設定は事前定義が必須
• dataブロックでも同様に指定できる
• 指定しなければデフォルト設定を継承

条件でプロバイダを切り替える例

variable "primary_region_is_east" {
  type    = bool
  default = true
}

provider "aws" {
  region = "us-east-1"
}

provider "aws" {
  alias  = "uw2"
  region = "us-west-2"
}

resource "aws_kms_key" "example" {
  description = "Example KMS key"
  # eastを使うかwestを使うかを切り替え
  provider = var.primary_region_is_east ? aws : aws.uw2
}

モジュール境界とprovidersマップ（configuration_aliasesの必須性）

子モジュールに特定のプロバイダ設定（デフォルトや別名）を渡すには、ルート側でmoduleブロックのprovidersマップを使います。マップのキーは子モジュール側のプロバイダアドレス（aws、aws.replica等）、値はルート側の実際の設定（aws、aws.ue1等）です。

子モジュール側は、terraform.required_providersの該当プロバイダにconfiguration_aliasesを宣言することで、受け取る別名を明示します。これがないと「モジュールがその別名を宣言していない」というエラーになります。

子モジュール内部のresourceでproviderメタ引数を使って、aws.replicaのように受け取った別名を選択できます。

• ルート: module.providersで子のプロバイダアドレスに実設定を割り当てる
• 子: required_providersでconfiguration_aliasesを宣言
• 子: resourceのproviderで受け取った別名を指定可能
• 名前不一致はよくあるエラーの原因

ルート→子モジュールの受け渡し（正しい最小例）

# ルート側
terraform {
  required_providers {
    aws = {
      source = "hashicorp/aws"
    }
  }
}

provider "aws" {
  region = "us-east-1"
}

provider "aws" {
  alias  = "ue1"
  region = "us-east-1"
}

module "app" {
  source = "./modules/app"
  providers = {
    aws         = aws       # 子のawsにデフォルトを割当て
    aws.replica = aws.ue1   # 子のaws.replicaに別名設定を割当て
  }
}

# 子モジュール側(./modules/app)
terraform {
  required_providers {
    aws = {
      source = "hashicorp/aws"
      configuration_aliases = [ aws.replica ]
    }
  }
}

resource "aws_iam_role" "main" {
  name = "example-app-role"
}

resource "aws_iam_role" "replica" {
  name     = "example-app-role-replica"
  provider = aws.replica
}

実務パターン（リージョン・アカウント・環境）

マルチリージョン: 同一アカウントの複数リージョンでは、aliasにリージョン名や役割を付けます。例: aws.primary、aws.dr、aws.reportingなど。リソース側は明示的にproviderを指定し、意図しないデフォルト継承を避けます。

マルチアカウント: assume_roleや認証情報プロファイルでアカウントを分け、alias名にアカウントの意味合い（prod、stg、opsなど）を持たせます。子モジュールにはprovidersマップで必要な組み合わせのみを渡し、誤用の余地を減らします。

環境分離: ルートモジュールで環境別にプロバイダ設定を宣言し、ワークスペースや変数により切替。条件式でproviderを分岐させる際は、どの分岐でも参照する設定を事前に定義しておきます。

• aliasは意味が一意に分かる短い名前（primary, dr, opsなど）
• デフォルト設定の無意識な継承を避けたい場合、全リソースでproviderを明示
• モジュール内部に閉じた切替より、providersマップで明示受け渡しを優先

別アカウントへのassume_role（典型例）

provider "aws" {
  region = "us-east-1"
}

provider "aws" {
  alias  = "ops"
  region = "us-east-1"
  assume_role {
    role_arn     = "arn:aws:iam::123456789012:role/ops-admin"
    session_name = "tf-ops"
  }
}

resource "aws_ssm_parameter" "managed_by_ops" {
  name     = "/ops/managed"
  type     = "String"
  value    = "true"
  provider = aws.ops
}

比較表：プロバイダ選択の手段

どこで選ぶかにより適用範囲と落とし穴が変わります。Associate試験では、用語と適用範囲の取り違えがよく出ます。以下で要点を整理します。

• デフォルト継承は簡単だが、規模が大きいと意図せぬ混在が起こりやすい
• リソース単位のprovider指定は明確だが、毎回の指定が手間
• モジュール受け渡しは再利用性が高い反面、alias名の不一致に注意

試験に出やすいひっかけ（宣言漏れの例）

# ルート
provider "aws" { region = "us-east-1" }
provider "aws" { alias = "ue1" region = "us-east-1" }

module "bad" {
  source = "./modules/bad"
  providers = {
    aws.replica = aws.ue1  # 子にaws.replicaを渡したい
  }
}

# 子(./modules/bad) — これだとNG: configuration_aliases未宣言
terraform {
  required_providers {
    aws = {
      source = "hashicorp/aws"
    }
  }
}

# → 典型的エラー: Module does not declare provider alias named "aws.replica".

検証とトラブルシュート（Associateで押さえる）

初期化と依存の可視化で早期に不一致を検出します。特にmodule.providersとconfiguration_aliasesの整合性を常に確認してください。

プロバイダの有無や割り当てはterraform providersコマンドで俯瞰できます。計画は小さく切って確認し、指定ミスを局所化します。

• terraform initでプロバイダ取得と設定の妥当性を確認
• terraform providersで構成と参照関係を一覧
• terraform plan -target=module.xなどで部分検証
• エラー文に出るproviderアドレス（例: aws.replica）と設定名の一致を必ず確認

チェックコマンド集

# 初期化
terraform init

# プロバイダの参照関係を確認
terraform providers

# 局所的に計画
terraform plan -target=module.app
terraform plan -target=aws_s3_bucket.replica

問題で確認

よくある質問