翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

コードベースの構造と組織のベストプラクティス

大規模なチームや企業で Terraform の使用が増加するにつれて、適切なコードベース構造と組織ことが重要です。優れた設計のコードベースにより、大規模なコラボレーションが可能になり、保守性が向上します。

このセクションでは、品質と一貫性をサポートする Terraform のモジュール性、命名規則、ドキュメント、コーディング標準に関する推奨事項を提供します。

ガイダンスには、環境とコンポーネント別の再利用可能なモジュールへの設定の分割、プレフィックスとサフィックスを使用した命名規則の確立、モジュールの文書化と入出力の明確な説明、自動スタイルチェックを使用した一貫したフォーマットルールの適用が含まれます。

その他のベストプラクティスでは、モジュールとリソースを構造化階層に論理的に整理し、ドキュメントでパブリックモジュールとプライベートモジュールをカタログ化し、モジュールで不要な実装の詳細を抽象化して使用を簡素化します。

モジュール性、ドキュメント、標準、論理的な組織に関するコードベース構造のガイドラインを実装することで、組織全体に使用量が分散するにつれて Terraform を維持したまま、チーム間の広範なコラボレーションをサポートできます。規則と標準を適用することで、フラグメント化されたコードベースの複雑さを回避できます。

標準リポジトリ構造を実装する

次のリポジトリレイアウトを実装することをお勧めします。これらの整合性プラクティスをモジュール間で標準化することで、検出可能性、透明性、整理、信頼性が向上し、多くの Terraform 設定で再利用できます。

ルートモジュール構造

Terraform は常に単一のルートモジュールのコンテキストで実行されます。完全な Terraform 設定は、ルートモジュールと子モジュールのツリー (ルートモジュールによって呼び出されるモジュール、それらのモジュールによって呼び出されるモジュールなどを含む) で構成されます。

Terraform ルートモジュールレイアウトの基本的な例:

.
├── data.tf
├── envs
│   ├── dev
│   │   └── terraform.tfvars
│   ├── prod
│   │   └── terraform.tfvars
│   └── test
│       └── terraform.tfvars
├── locals.tf
├── main.tf
├── outputs.tf
├── providers.tf
├── README.md
├── terraform.tfvars
├── variables.tf
└── versions.tf

再利用可能なモジュール構造

再利用可能なモジュールは、ルートモジュールと同じ概念に従います。モジュールを定義するには、ルートモジュールを定義するのと同様に、新しいディレクトリを作成し、その中に.tfファイルを配置します。Terraform は、ローカル相対パスまたはリモートリポジトリからモジュールをロードできます。モジュールが多くの設定で再利用されることが予想される場合は、独自のバージョン管理リポジトリに配置します。さまざまな組み合わせでモジュールを簡単に再利用できるように、モジュールツリーを比較的平らに保つことが重要です。

Terraform 再利用可能なモジュールレイアウトの基本例:

.
├── data.tf
├── examples
│   ├── multi-az-new-vpc
│   │   ├── data.tf
│   │   ├── locals.tf
│   │   ├── main.tf
│   │   ├── outputs.tf
│   │   ├── providers.tf
│   │   ├── README.md
│   │   ├── terraform.tfvars
│   │   ├── variables.tf
│   │   ├── versions.tf
│   │   └── vpc.tf
│   └── single-az-existing-vpc
│   │   ├── data.tf
│   │   ├── locals.tf
│   │   ├── main.tf
│   │   ├── outputs.tf
│   │   ├── providers.tf
│   │   ├── README.md
│   │   ├── terraform.tfvars
│   │   ├── variables.tf
│   │   └── versions.tf
├── iam.tf
├── locals.tf
├── main.tf
├── outputs.tf
├── README.md
├── variables.tf
└── versions.tf

モジュール性の構造

原則として、任意のリソースやその他のコンストラクトをモジュールに結合できますが、ネストされた再利用可能なモジュールを過剰に使用すると、Terraform 設定全体の理解と維持が困難になる可能性があるため、これらのモジュールをモデレーションで使用します。

理にかなっている場合は、リソースタイプから構築されたアーキテクチャの新しい概念を記述することで、抽象化のレベルを高める再利用可能なモジュールに構成を分割します。

インフラストラクチャを再利用可能な定義にモジュール化する場合は、個々のコンポーネントや過度に複雑なコレクションではなく、リソースの論理セットを目指します。

単一のリソースをラップしない

他の単一のリソースタイプを囲む薄いラッパーのモジュールを作成しないでください。モジュール内のメインリソースタイプの名前とは異なるモジュールの名前を見つけられない場合、モジュールが新しい抽象化を作成していない可能性があります。不要な複雑さが発生しています。代わりに、呼び出し元のモジュールで リソースタイプを直接使用します。

論理関係をカプセル化する

ネットワーク基盤、データ層、セキュリティコントロール、アプリケーションなどの関連リソースのグループセット。再利用可能なモジュールは、機能を有効にするために連携するインフラストラクチャ部分をカプセル化する必要があります。

継承を平らに保つ

モジュールをサブディレクトリにネストする場合は、1 つまたは 2 つのレベルを深くしないようにします。深くネストされた継承構造は、設定とトラブルシューティングを複雑にします。モジュールは他のモジュール上に構築する必要があります。それらを介してトンネルを構築しないでください。

アーキテクチャパターンを表す論理リソースグループに焦点を当てることで、チームは信頼性の高いインフラストラクチャ基盤をすばやく設定できます。過剰エンジニアリングや過剰簡素化なしで抽象化のバランスを取ります。

出力のリソースを参照する

再利用可能なモジュールで定義されているリソースごとに、リソースを参照する出力を少なくとも 1 つ含めます。変数と出力を使用すると、モジュールとリソース間の依存関係を推測できます。出力がないと、ユーザーは Terraform 設定に関連してモジュールを適切に注文できません。

環境の一貫性、目的主導のグループ化、エクスポートされたリソースリファレンスを提供する構造化されたモジュールにより、組織全体の Terraform コラボレーションを大規模に実現できます。チームは、再利用可能な構成要素からインフラストラクチャを組み立てることができます。

プロバイダーを設定しない

共有モジュールはモジュールの呼び出しからプロバイダーを継承しますが、モジュールはプロバイダー設定自体を設定しないでください。モジュールでプロバイダー設定ブロックを指定しないでください。この設定はグローバルに 1 回だけ宣言する必要があります。

必要なプロバイダーを宣言する

プロバイダー設定はモジュール間で共有されますが、共有モジュールは独自のプロバイダー要件も宣言する必要があります。この方法により、Terraform は、設定内のすべてのモジュールと互換性のあるプロバイダーの単一バージョンがあることを確認し、プロバイダーのグローバル (モジュールに依存しない) 識別子として機能するソースアドレスを指定できます。ただし、モジュール固有のプロバイダー要件では、 など、プロバイダーがどのリモートエンドポイントにアクセスするかを決定する設定は指定されません AWS リージョン。

バージョン要件を宣言し、ハードコードされたプロバイダー設定を回避することで、モジュールは共有プロバイダーを使用して Terraform 設定間で移植性と再利用性を提供します。

共有モジュールの場合、 の required_providers ブロックで最低限必要なプロバイダーバージョンを定義しますversions.tf。

モジュールが特定のバージョンの AWS プロバイダーを必要とすることを宣言するには、 required_providersブロック内で terraformブロックを使用します。

terraform {
  required_version = ">= 1.0.0"

  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = ">= 4.0.0"
    }
  }
}

共有モジュールが特定のバージョンの AWS プロバイダーのみをサポートしている場合は、悲観的制約演算子 (~>) を使用します。これにより、右端のバージョンコンポーネントのみが増分されます。

terraform {
  required_version = ">= 1.0.0"

  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 4.0"
    }
  }
}

この例では、 は 4.57.1と のインストール~> 4.0を許可します4.67.0が、 のインストールは許可しません5.0.0。詳細については、HashiCorp ドキュメントの「バージョン制約構文」を参照してください。

命名規則に従う

わかりやすいわかりやすい名前を使用すると、モジュール内のリソースと設定値の目的との関係を簡単に理解できます。スタイルガイドラインとの整合性により、モジュールユーザーとメンテナーの両方の読みやすさが向上します。

リソースの命名に関するガイドラインに従う

変数の命名に関するガイドラインに従う

アタッチメントリソースを使用する

一部のリソースには、擬似リソースが属性として埋め込まれています。可能であれば、これらの埋め込みリソース属性の使用を避け、代わりに一意のリソースを使用してその擬似リソースをアタッチする必要があります。これらのリソース関係は、リソースごとに固有のcause-and-effectの問題を引き起こす可能性があります。

埋め込み属性の使用 (このパターンは避けてください）。

resource "aws_security_group" "allow_tls" {
  ...
  ingress {
    description      = "TLS from VPC"
    from_port        = 443
    to_port          = 443
    protocol         = "tcp"
    cidr_blocks      = [aws_vpc.main.cidr_block]
    ipv6_cidr_blocks = [aws_vpc.main.ipv6_cidr_block]
  }

  egress {
    from_port        = 0
    to_port          = 0
    protocol         = "-1"
    cidr_blocks      = ["0.0.0.0/0"]
    ipv6_cidr_blocks = ["::/0"]
  }
}

アタッチメントリソースの使用 (推奨):

resource "aws_security_group" "allow_tls" {
  ...
}

resource "aws_security_group_rule" "example" {
  type              = "ingress"
  description      = "TLS from VPC"
  from_port        = 443
  to_port          = 443
  protocol         = "tcp"
  cidr_blocks      = [aws_vpc.main.cidr_block]
  ipv6_cidr_blocks = [aws_vpc.main.ipv6_cidr_block]
  security_group_id = aws_security_group.allow_tls.id
}

デフォルトのタグを使用する

タグを受け入れることができるすべてのリソースにタグを割り当てます。Terraform AWS プロバイダーには、ルートモジュール内で使用する必要がある aws_default_tags データソースがあります。

Terraform モジュールによって作成されたすべてのリソースに必要なタグを追加することを検討してください。アタッチできるタグのリストを次に示します。

Terraform レジストリ要件を満たす

モジュールリポジトリは、Terraform レジストリに発行できるように、以下のすべての要件を満たしている必要があります。

短期的にモジュールをレジストリに公開する予定がない場合でも、常にこれらの要件に従う必要があります。これにより、リポジトリの設定と構造を変更することなく、後でモジュールをレジストリに発行できます。

詳細については、Terraform ドキュメントの「モジュールリポジトリの準備」を参照してください。

推奨されるモジュールソースを使用する

Terraform は、モジュールブロックの source引数を使用して、子モジュールのソースコードを検索およびダウンロードします。

繰り返しコード要素を除外することを主な目的とする密接に関連するモジュールにはローカルパスを使用し、複数の設定で共有することが意図されているモジュールにはネイティブの Terraform モジュールレジストリまたは VCS プロバイダーを使用することをお勧めします。

次の例は、モジュールを共有するための最も一般的なソースタイプと推奨されるソースタイプを示しています。レジストリモジュールはバージョニングをサポートしています。次の例に示すように、常に特定のバージョンを指定する必要があります。

レジストリ

Terraform レジストリ:

module "lambda" {
  source = "github.com/terraform-aws-modules/terraform-aws-lambda.git?ref=e78cdf1f82944897ca6e30d6489f43cf24539374" #--> v4.18.0

  ...

}

コミットハッシュを固定することで、サプライチェーン攻撃に対して脆弱なパブリックレジストリからのドリフトを回避できます。

HCP Terraform:

module "eks_karpenter" {
  source = "app.terraform.io/my-org/eks/aws"
  version = "1.1.0"

  ...

  enable_karpenter = true
}

Terraform Enterprise:

module "eks_karpenter" {
  source = "terraform.mydomain.com/my-org/eks/aws"
  version = "1.1.0"

  ...

  enable_karpenter = true
}

VCS プロバイダー

VCS プロバイダーは、次の例に示すように、特定のリビジョンを選択するための ref引数をサポートしています。

GitHub (HTTPS):

module "eks_karpenter" {
  source = "github.com/my-org/terraform-aws-eks.git?ref=v1.1.0"

  ...

  enable_karpenter = true
}

汎用 Git リポジトリ (HTTPS):

module "eks_karpenter" {
  source = "git::https://example.com/terraform-aws-eks.git?ref=v1.1.0"

  ...

  enable_karpenter = true
}

汎用 Git リポジトリ (SSH):

module "eks_karpenter" {
  source = "git::ssh://username@example.com/terraform-aws-eks.git?ref=v1.1.0"

  ...

  enable_karpenter = true
}

コーディング標準に従う

すべての設定ファイルに一貫した Terraform フォーマットルールとスタイルを適用します。CI/CD パイプラインで自動スタイルチェックを使用して標準を適用します。コーディングのベストプラクティスをチームワークフローに埋め込むと、組織全体で使用が広く普及するにつれて、設定は読みやすく、保守可能で、共同作業性が維持されます。

スタイルガイドラインに従う

事前コミットフックを設定する

コミットを許可する前にterraform fmt、、tflintcheckov、、およびその他のコードスキャンとスタイルチェックを実行するクライアント側の事前コミットフックを設定します。このプラクティスは、開発者ワークフローの早い段階で標準への準拠を検証するのに役立ちます。

事前コミットなどの事前コミットフレームワークを使用して、Terraform リンティング、フォーマット、コードスキャンをローカルマシンのフックとして追加します。フックは各 Git コミットで実行され、チェックに合格しなかった場合はコミットに失敗します。

スタイルチェックと品質チェックをローカルのコミット前フックに移動すると、変更が導入される前に開発者に迅速なフィードバックが提供されます。標準はコーディングワークフローの一部になります。