Terraform Providers の基本 ─ プラグイン型アーキテクチャを正しく理解する

Provider は Terraform の外部サービス連携を担うプラグインで、計画・適用の各段階で API と対話します。Associate では宣言、インストール、バージョン管理、エイリアス、認証の基本を正確に押さえることが重要です。

本稿では、Terraform Core と Provider の分離という設計背景から、実務で外さない設定パターンと試験で問われやすい要点をまとめます。

Provider とは何か：責務と基本用語

Provider は Terraform Core から独立したプラグインで、各クラウドやSaaSの API へ接続し、resource と data source を実装します。リソースの作成・更新・削除や、読み取り専用のデータ取得を Provider が引き受け、Terraform Core は計画生成と状態管理に専念します。

Provider は source アドレスで一意に識別されます。例: registry.terraform.io/hashicorp/aws。required_providers でソースとバージョン制約を宣言し、terraform init により解決・取得されます。

• resource は実体を作成・変更・削除、data は読み取りのみ
• required_providers で source と version を明示
• terraform init が Provider プラグインの解決・インストールを行う
• Terraform Core と Provider は責務分離され、独立更新が可能

プラグイン型アーキテクチャの仕組み

Terraform Core は実行時に Provider プラグインを外部プロセスとして起動し、安定化されたプラグインプロトコル越しにやり取りします。Core は計画と状態の差分を計算し、Provider は個々のリソース操作を API に対して実行します。

この分離により、Provider ごとに独立して開発・配布・アップグレードが可能で、障害が一方に波及しにくく、機能追加の展開も容易になります。ネットワークアクセスは Provider 側で行われるため、Core は外部 API 認証情報を直接保持しません。

• Core は計画・状態、Provider は外部 API 操作を担当
• プラグインは別プロセスで起動され、障害分離が効く
• Provider の追加・更新は terraform init で解決
• 並列適用時、複数 Provider が同時に動作可能

Terraform Core と Provider プラグインの関係

インストールと宣言：required_providers と init

プロジェクトの terraform ブロックで required_providers を宣言し、source と version 制約を指定します。terraform init は Registry から Provider を解決し、署名とチェックサムを検証した上でローカルにインストールします。.terraform.lock.hcl は解決済みバージョンとチェックサムを固定し、チーム間での再現性を担保します。

アップグレードは version 制約を見直し、terraform init -upgrade を実行します。オフラインやミラー利用は CLI 設定ファイルの provider_installation で制御可能です。試験では、.terraform ディレクトリはコミットしないが .terraform.lock.hcl はコミットする、という基本がよく問われます。

• required_providers に source と version を宣言
• terraform init で取得・検証・ロックファイル作成
• .terraform.lock.hcl は原則コミットして再現性を確保
• アップグレードは terraform init -upgrade
• ミラーや社内レジストリは CLI 設定で指定可能

典型的な required_providers と Provider 設定

terraform {
  required_version = ">= 1.5.0"
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"
    }
    azurerm = {
      source  = "hashicorp/azurerm"
      version = ">= 3.0, < 4.0"
    }
  }
}

provider "aws" {
  region = var.aws_region
}

provider "azurerm" {
  features {}
}

variable "aws_region" {
  type        = string
  default     = "us-east-1"
  description = "AWS region"
}

認証と設定の優先順位：安全に渡す

Provider への認証情報は、一般に provider ブロックの明示的な引数、環境変数、共有認証ファイル、SDK のデフォルト探索順などが組み合わさって決まります。優先順位は Provider 実装に依存しますが、原則として provider ブロックで指定した値が最優先で、未指定の場合に環境変数や共有ファイルが用いられる形が一般的です。

機密情報は VCS に残さないことが基本です。変数の sensitive フラグや環境変数、Terraform Cloud/Enterprise の変数ストア等を活用し、平文での埋め込みは避けます。

• AWS 例: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_PROFILE
• GCP 例: GOOGLE_APPLICATION_CREDENTIALS（JSON キーファイルへのパス）
• Azure 例: ARM_CLIENT_ID, ARM_CLIENT_SECRET, ARM_TENANT_ID, ARM_SUBSCRIPTION_ID
• provider ブロックの明示設定が一般に最優先
• 資格情報は変数や環境変数で安全に注入

変数を使って認証情報を明示しない例（AWS）

variable "aws_profile" {
  type        = string
  default     = null
  description = "AWS named profile (optional)"
}

provider "aws" {
  region  = var.aws_region
  profile = var.aws_profile # 未指定なら SDK のデフォルト探索に委ねる
}

# 実行時に AWS_PROFILE を設定するか、var.aws_profile に値を渡す
# 例: AWS_PROFILE=dev terraform apply

複数 Provider・エイリアス・モジュール連携

同一種類の Provider を複数設定する場合は alias を使います。resource 側で provider = aws.east のように明示すると、そのリソースは該当の設定で作成されます。未指定の場合、同種類のデフォルト設定が使われます。

モジュールは Provider 設定を内包しません。呼び出し元が providers マップでモジュール内の Provider 参照に具体的な設定を割り当てます。これにより、同一モジュールを異なるアカウントやリージョンへ安全にデプロイできます。

• alias を付けた Provider は resource 側で provider メタ引数により選択
• デフォルト設定がないと resource はエラーになる
• モジュール呼び出し時は providers マップで紐付ける
• 動的に Provider を切り替える count/for_each 等は不可、明示が必要

エイリアスとモジュールへの Provider 受け渡し

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

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

resource "aws_s3_bucket" "west" {
  bucket   = "nlab-west-bucket"
  provider = aws
}

resource "aws_s3_bucket" "east" {
  bucket   = "nlab-east-bucket"
  provider = aws.east
}

module "network" {
  source = "./modules/vpc"
  # モジュール内は aws Provider を参照している前提
  providers = {
    aws = aws.east
  }
}

# modules/vpc 側の宣言例（抜粋）
# terraform {
#   required_providers {
#     aws = {
#       source = "hashicorp/aws"
#     }
#   }
# }
# resource "aws_vpc" "this" { ... }

トラブルシューティングとアップグレードの指針

バージョン更新は version 制約の見直しと terraform init -upgrade で行い、.terraform.lock.hcl の差分を確認します。terraform providers コマンドで現在の依存関係を可視化できます。署名・チェックサム検証は init 時に自動で実施されます。

不一致や適用失敗時は、計画出力でどの Provider/リソースが失敗しているかを特定し、環境変数や認証設定の漏れを確認します。必要に応じて TF_LOG を活用し、Provider 側ドキュメントの認証チェーンを参照します。既存リソースの Provider を切り替える場合、多くは再作成や import が必要で、単純な provider の差し替えでは対応できません。

• terraform providers で依存可視化、terraform init -upgrade で更新
• lock ファイルはチームで共有し再現性を担保
• 失敗時は認証・権限・リージョン・エンドポイントを再点検
• Provider 変更は原則置換や import が伴う点に注意

よく使う確認コマンド

# 依存している Provider とバージョン
terraform providers

# Provider のアップグレード
terraform init -upgrade

# 詳細ログ（一時的に）
TF_LOG=TRACE terraform plan

問題で確認

よくある質問