Terraform Cloud Private Registry 実務と試験で押さえるポイント

Terraform Cloud/Enterprise の Private Registry は、組織内の標準モジュールやプライベートプロバイダを一元配布する仕組みです。VCS のタグからバージョンを検出し、terraform init がレジストリから解決する点は Public Registry と同様ですが、アクセス制御や発行フローに組織固有の要件が加わります。

本稿は Terraform のプロレベル試験を意識しつつ、現場でハマりやすい命名・タグ付け・認証・source 文字列・ロックファイルの扱いまで、安定した仕様に絞って解説します。

Private Registry の概要とアーキテクチャ

Terraform Cloud/Enterprise の Private Registry は、組織単位でモジュールとプライベートプロバイダを公開・検索・バージョン管理できる機能です。モジュールは主に VCS 連携で SemVer タグから登録され、プロバイダはレジストリ・プロトコルに沿ったバイナリ/署名/チェックサムをリリースとして登録します。

利用側は module ブロックや required_providers の source に組織ホスト名と名前空間を含むアドレスを指定します。terraform init は CLI 資格情報（ローカル実行）または Terraform Cloud の実行環境（リモート実行）を介して Private Registry にアクセスします。

• スコープ: 組織単位（同一組織内で共有）。
• バージョニング: SemVer のタグ vX.Y.Z をレジストリが検出（モジュール）。
• 参照: app.terraform.io/<org>/<module>/<provider>（モジュール）、required_providers の source に app.terraform.io/<org>/<provider>（プロバイダ）。
• 認証: terraform login によるトークン or 環境変数 TF_TOKEN_app_terraform_io（ローカル実行時）。

Private Registry の利用フロー（概念図）

モジュール公開の要件（命名・タグ・構成）

モジュールは VCS 連携で公開します。レジストリが自動検出できるよう、リポジトリ名とバージョンタグ、標準構成を満たす必要があります。特にリポジトリ名のプレフィックスと SemVer タグは、UI の候補一覧やバージョン解決に直結します。

安定仕様として、以下を守れば検出とドキュメント生成（README, Inputs/Outputs）が確実です。

• リポジトリ名: terraform-<name>-<provider>（例: terraform-vpc-aws）。
• SemVer タグ: vX.Y.Z 形式のみをバージョンとして認識（例: v1.2.0）。
• 構成: modules/ や main.tf, variables.tf, outputs.tf を標準的に配置。README.md をルートに置く。
• VCS 連携: Terraform Cloud の組織で VCS 接続（OAuth app など）を設定し、対象リポジトリを選択して公開。
• 互換性: 破壊的変更はメジャーアップ、後方互換の追加はマイナー/パッチでタグ。

参照方法とバージョン管理（source 文字列とロック）

Private Registry のモジュールは registry アドレスで参照します。依存の固定は required_providers の version 制約および module ブロックの version で行い、実際のハッシュや署名鍵情報は .terraform.lock.hcl に保存されます。ローカル実行では credentials.tfrc.json（もしくは TF_TOKEN_app_terraform_io）が必須です。

プロバイダは required_providers で source を app.terraform.io/<org>/<provider> と明示し、terraform init によりバイナリと署名が検証されます。ロックファイルはレジストリホスト名も含めて解決先を固定するため、チームで共有するのが推奨です。

• モジュール参照例: source = "app.terraform.io/my-org/vpc/aws", version = "~> 1.2"
• プロバイダ参照例: source = "app.terraform.io/my-org/mycloud", version = ">= 1.0, < 2.0"
• ローカル実行の認証: terraform login で作成されたトークン、または TF_TOKEN_app_terraform_io を使用
• .terraform.lock.hcl はプロバイダの署名鍵とチェックサムを固定（VCS で共有）

Private Registry の参照例（module と provider）＋ CLI 認証

# main.tf
terraform {
  required_version = ">= 1.3"
  required_providers {
    mycloud = {
      source  = "app.terraform.io/my-org/mycloud"
      version = "~> 1.4"
    }
  }
}

provider "mycloud" {}

module "vpc" {
  source  = "app.terraform.io/my-org/vpc/aws"
  version = "~> 1.2"
  name    = "prod-vpc"
}

# ローカル実行の認証（いずれか）
# 1) terraform login で作成される ~/.terraform.d/credentials.tfrc.json の例
# {
#   "credentials": {
#     "app.terraform.io": {"token": "<redacted>"}
#   }
# }
# 2) 環境変数: TF_TOKEN_app_terraform_io=<token>

プライベートプロバイダ配布の基礎（署名とリリース）

プライベートプロバイダは、Terraform のプロバイダ・レジストリ・プロトコルに準拠した成果物（OS/アーキテクチャ別のアーカイブ、SHA256SUMS、署名）を Private Registry に登録します。Terraform Cloud/Enterprise はレジストリ API を実装しており、UI または API でバージョンを公開できます。

利用側は required_providers で source に app.terraform.io/<org>/<provider> を指定します。初回 init 時に署名鍵とチェックサムが .terraform.lock.hcl に記録され、以降は復元性とサプライチェーンの一貫性が維持されます。公開時は SemVer を守り、破壊的変更を避けるためのプレリリース検証を十分に行ってからリリースするのが実務的です。

• UI でプロバイダを作成 → バージョンごとに成果物をアップロード（または API で自動化）。
• 署名/チェックサムは init 時に検証され、ロックファイルに固定される。
• source のホスト名を省略しない（app.terraform.io/... を必ず含める）。

アクセス制御・認証・運用ベストプラクティス

Private Registry の発行は権限が必要です。組織・チームに対して、モジュール/プロバイダの公開を許可する権限を付与し、利用者には読み取り権限を与えます。CI/CD からのローカル実行では、ユーザトークンあるいはチームトークンを安全に保管し、TF_TOKEN_app_terraform_io で供給します。

運用では、SemVer と CHANGELOG の厳守、破壊的変更の計画的リリース、README と I/O ドキュメントの整備、非推奨バージョンの明示、タグ保護（保護ブランチ/リリース権限の制御）を基本とします。

• 最小権限での発行フロー（レビューと自動テストを経てタグを作成）。
• トークンは環境変数または Vault/Secret Manager から注入し、平文保存を避ける。
• .terraform.lock.hcl をリポジトリで共有し、再現性を担保。
• モジュールの互換性ポリシーとサポート期間を明文化。

トラブルシュートと試験対策チェック

モジュールが UI に出ない場合は、リポジトリ名のプレフィックス（terraform-...）、SemVer タグ（vX.Y.Z）、VCS 連携の権限を確認します。terraform init で 401/403/404 が出る場合は、credentials.tfrc.json/TF_TOKEN_app_terraform_io、source のホスト名の有無、プロキシ越しのネットワーク制限を点検します。

試験対策としては、レジストリアドレスの構文、SemVer の要件、ロックファイルの役割、ローカルとリモート実行時の認証の違いを正確に説明できることが重要です。

• エラー: Provider not found → required_providers の source にホスト名がない可能性。
• エラー: Failed to retrieve modules → トークン未設定 or 組織権限不足。
• バージョン解決ミスマッチ → version 制約と存在するタグを再確認。

問題で確認

よくある質問