再利用可能なモジュールのベストプラクティス

このドキュメントでは、再利用可能な Terraform モジュールを使用する際に考慮すべきガイドラインと推奨事項について説明します。

このガイドでは Terraform の概要は説明しません。 Google Cloudで Terraform を使用する方法については、Terraform を使ってみるをご覧ください。

モジュールで必要な API を有効にする

Terraform モジュールは、google_project_service リソースまたは project_services モジュールを使用して、必要なサービスを有効にできます。API の有効化を含めることで、デモが容易になります。

API の有効化をモジュールに含める場合は、デフォルトが true の enable_apis 変数を公開することで、API の有効化を無効にする必要があります。

API の有効化がモジュールに含まれている場合、API の有効化で disable_services_on_destroy を false に設定する必要があります。これは、この属性によりモジュールのマルチインスタンスで問題が発生するためです。

次に例を示します。

module "project-services" {
  source  = "terraform-google-modules/project-factory/google//modules/project_services"
  version = "~> 12.0"

  project_id  = var.project_id
  enable_apis = var.enable_apis

  activate_apis = [
    "compute.googleapis.com",
    "pubsub.googleapis.com",
  ]
  disable_services_on_destroy = false
}

オーナーファイルを含める

すべての共有モジュールについて、誰がモジュールの責任者かを明らかにする OWNERS ファイルを含めます（GitHub では CODEOWNERS）。pull リクエストがマージされる前に、オーナーが承認する必要があります。

タグ付きバージョンをリリースする

モジュールによっては互換性を損なう変更が必要になる場合があります。ユーザーが特定のバージョンに構成を固定できるよう、その影響をユーザーに通知する必要があります。

新しいバージョンがタグ付けまたはリリースされたときに、共有モジュールが必ず SemVer v2.0.0 に準拠するようにします。

モジュールを参照する場合は、バージョンの制約を使用して、メジャーバージョンに固定します。例:

module "gke" {
  source  = "terraform-google-modules/kubernetes-engine/google"
  version = "~> 20.0"
}

プロバイダやバックエンドを構成しない

共有モジュールでプロバイダやバックエンドを構成することはできません。代わりに、ルートモジュールでプロバイダとバックエンドを構成します。

共有モジュールの場合は、次のように required_providers ブロックでプロバイダの最低必要バージョンを定義します。

terraform {
  required_providers {
    google = {
      source  = "hashicorp/google"
      version = ">= 4.0.0"
    }
  }
}

動作しないと証明されていない限り、新しいプロバイダバージョンは動作すると想定します。

ラベルを変数として公開する

モジュールのインターフェースを使用して、リソースのラベル付けを柔軟に行えるようにします。次のように、空のマップのデフォルト値で labels 変数を指定することを検討してください。

variable "labels" {
  description = "A map of labels to apply to contained resources."
  default     = {}
  type        = "map"
}

すべてのリソースの出力を公開する

変数と出力によって、モジュールとリソース間の依存関係を推測できます。出力がないと、ユーザーは Terraform 構成に関連してモジュールを適切に順序付けできません。

共有モジュールで定義されているリソースごとに、そのリソースを参照する出力を少なくとも 1 つ含めます。

複雑なロジックにインラインサブモジュールを使用する

インラインモジュールを使用すると、複雑な Terraform モジュールを小さなユニットに整理したり、共通リソースの重複を排除できます。
インラインモジュールは modules/$modulename に配置します。
インラインモジュールは、共有モジュールのドキュメントで特に明記されていない限り、外部モジュールで使用されないように非公開として扱います。
Terraform は、リファクタリングされたリソースを追跡しません。最上位モジュールの複数のリソースをサブモジュールに push した場合、Terraform はリファクタリングされたすべてのリソースの再作成を試みます。この問題を緩和するには、リファクタリング時に moved ブロックを使用します。
内部モジュールによって定義された出力は自動的に公開されません。内部モジュールからの出力を共有するには、それらを再度エクスポートします。

再利用可能なモジュールのベスト プラクティス コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。