Azure Verified Modules (AVM) 要件

このガイドでは、Azure Verified Modules 認定の必須要件について説明します。これらの要件により、Azure Terraform モジュール全体の一貫性、品質、および保守性を確保します。

参照:

• Azure Verified Modules
• AVM Terraform 要件

目次

• モジュール相互参照
• Azure プロバイダー要件
• コードスタイル標準
• 変数要件
• 出力要件
• ローカル値標準
• Terraform 設定要件
• テスト要件
• ドキュメント要件
• 破壊的変更と機能管理
• 貢献標準
• コンプライアンスチェックリスト

---

モジュール相互参照

重大度: MUST | 要件: TFFR1

Resource または Pattern モジュール構築時、モジュールオーナーは他のモジュールを相互参照する場合があります。ただし:

• モジュールは HashiCorp Terraform レジストリへの参照でピン留めされたバージョンを使用して参照しなければならない
  • 例: source = "Azure/xxx/azurerm" と version = "1.2.3"
• モジュールは git 参照 (例: git::https://xxx.yyy/xxx.git または github.com/xxx/yyy) を使用してはいけない
• モジュールは AVM 以外のモジュールへの参照を含めてはならない**(MUST NOT)**

---

Azure プロバイダー要件

重大度: MUST | 要件: TFFR3

オーサーは以下の Azure プロバイダーのみを使用しなければならない:

プロバイダー	最小バージョン	最大バージョン
azapi	>= 2.0	< 3.0
azurerm	>= 4.0	< 5.0

要件:

• オーサーは Azurerm、Azapi、またはその両方を選択できます
• プロバイダーバージョンを強制するために required_providers ブロックを使用しなければならない
• 悲観的バージョン制約演算子 (~>) を使用することが望ましい

例:

terraform {
  required_providers {
    azurerm = {
      source  = "hashicorp/azurerm"
      version = "~> 4.0"
    }
    azapi = {
      source  = "Azure/azapi"
      version = "~> 2.0"
    }
  }
}

---

コードスタイル標準

小文字のスネークケース

重大度: MUST | 要件: TFNFR4

以下に対して小文字のスネークケースを使用しなければならない:

• Locals
• Variables
• Outputs
• Resources (シンボリック名)
• Modules (シンボリック名)

例: snake_casing_example

Resource とデータソースの順序

重大度: SHOULD | 要件: TFNFR6

• 依存されるリソースは最初に来ることが望ましい
• 依存関係を持つリソースは互いに近く定義されることが望ましい

Count と for_each の使用

重大度: MUST | 要件: TFNFR7

• 条件付きリソース作成に count を使用
• map(xxx) または set(xxx) をリソースの for_each コレクションとして使用しなければならない
• マップのキーまたはセットの要素は静的リテラルでなければならない

例:

resource "azurerm_subnet" "pair" {
  for_each             = var.subnet_map  # map(string)
  name                 = "${each.value}-pair"
  resource_group_name  = azurerm_resource_group.example.name
  virtual_network_name = azurerm_virtual_network.example.name
  address_prefixes     = ["10.0.1.0/24"]
}

Resource とデータブロック内部の順序

重大度: SHOULD | 要件: TFNFR8

resource/data ブロック内での順序:

1. メタ引数 (上):

   • provider
   • count
   • for_each

2. 引数/ブロック (中央、アルファベット順):

   • 必須の引数
   • オプションの引数
   • 必須のネストされたブロック
   • オプションのネストされたブロック

3. メタ引数 (下):

   • depends_on
   • lifecycle (サブ順序: create_before_destroy, ignore_changes, prevent_destroy)

セクションを空白行で区切る。

モジュールブロックの順序

重大度: SHOULD | 要件: TFNFR9

モジュールブロック内での順序:

1. 上部のメタ引数:

   • source
   • version
   • count
   • for_each

2. 引数 (アルファベット順):

   • 必須の引数
   • オプションの引数

3. 下部のメタ引数:

   • depends_on
   • providers

Lifecycle ignore_changes 構文

重大度: MUST | 要件: TFNFR10

ignore_changes 属性は二重引用符で囲まれてはならない**(MUST NOT)**。

良い例:

lifecycle {
  ignore_changes = [tags]
}

悪い例:

lifecycle {
  ignore_changes = ["tags"]
}

条件付き作成のための Null 比較

重大度: SHOULD | 要件: TFNFR11

条件付きリソース作成が必要なパラメーターについては、plan ステージ中の「known after apply」問題を回避するために object 型でラップすること。

推奨:

variable "security_group" {
  type = object({
    id = string
  })
  default = null
}

オプションのネストされたオブジェクトの動的ブロック

重大度: MUST | 要件: TFNFR12

条件付きのネストされたブロックは以下のパターンを使用しなければならない:

dynamic "identity" {
  for_each = <condition> ? [<some_item>] : []

  content {
    # ブロック内容
  }
}

coalesce/try によるデフォルト値

重大度: SHOULD | 要件: TFNFR13

良い例:

coalesce(var.new_network_security_group_name, "${var.subnet_name}-nsg")

悪い例:

var.new_network_security_group_name == null ? "${var.subnet_name}-nsg" : var.new_network_security_group_name

モジュール内のプロバイダー宣言

重大度: MUST | 要件: TFNFR27

• provider はモジュール内で宣言してはならない**(MUST NOT)** (configuration_aliases を除く)
• モジュール内の provider ブロックは alias のみを使用しなければならない
• プロバイダー設定はモジュールユーザーによって渡されるべき

---

変数要件

許可されていない変数

重大度: MUST | 要件: TFNFR14

モジュールオーナーは、モジュール全体の操作を制御するために enabled や module_depends_on などの変数を追加してはいけない。特定のリソース用のブール機能トグルは許容される。

変数定義の順序

重大度: SHOULD | 要件: TFNFR15

変数は以下の順序に従うことが望ましい:

1. すべての必須フィールド (アルファベット順)
2. すべてのオプションフィールド (アルファベット順)

変数命名ルール

重大度: SHOULD | 要件: TFNFR16

• HashiCorp の命名ルールに従う
• 機能スイッチは肯定的なステートメントを使用することが望ましい: xxx_disabled の代わりに xxx_enabled

説明付きの変数

重大度: SHOULD | 要件: TFNFR17

• description はパラメーターの目的と想定されるデータ型を正確に説明することが望ましい
• 対象ユーザーはモジュールユーザーであり、開発者ではない
• object 型の場合は HEREDOC 形式を使用

型付きの変数

重大度: MUST | 要件: TFNFR18

• すべての変数に type を定義しなければならない
• type はできるだけ正確であることが望ましい
• any は適切な理由がある場合のみ使用できます
• true/false 値には string/number の代わりに bool を使用
• map(any) の代わりに具体的な object を使用

機密データ変数

重大度: SHOULD | 要件: TFNFR19

変数の型が object で機密フィールドを含む場合、変数全体に sensitive = true を設定するか、機密フィールドを別の変数に抽出することが望ましい。

コレクション用の Null ではないデフォルト

重大度: SHOULD | 要件: TFNFR20

ループで使用する場合、コレクション値 (セット、マップ、リスト) に対して nullable を false に設定することが望ましい。スカラー値の場合、null は意味を持つ可能性がある。

デフォルトで Null 許容を回避

重大度: MUST | 要件: TFNFR21

null 値の具体的な意味的ニーズがない限り、nullable = true を避けなければならない。

sensitive = false の回避

重大度: MUST | 要件: TFNFR22

sensitive = false を避けなければならない (これがデフォルト)。

機密デフォルト値の条件

重大度: MUST | 要件: TFNFR23

機密入力 (デフォルトパスワードなど) にはデフォルト値を設定してはいけない。

廃止された変数の処理

重大度: MUST | 要件: TFNFR24

• 廃止された変数を deprecated_variables.tf に移動
• 説明の冒頭に DEPRECATED で注釈を付ける
• 置き換え先の名前を宣言
• メジャーバージョンリリース時にクリーンアップ

---

出力要件

追加の Terraform 出力

重大度: SHOULD | 要件: TFFR2

オーサーはリソースオブジェクト全体を出力してはいけない。これは機密データを含む可能性があり、スキーマは API またはプロバイダーバージョンで変わる可能性がある。

ベストプラクティス:

• リソースの計算属性を個別の出力として出力 (アンチコラプション層パターン)
• すでに入力されている値を出力してはいけない (除: name)
• 機密属性には sensitive = true を使用
• for_each で展開されたリソースについては、計算属性をマップ構造で出力

例:

# 単一リソースの計算属性
output "foo" {
  description = "MyResource foo 属性"
  value       = azurerm_resource_myresource.foo
}

# for_each リソース
output "childresource_foos" {
  description = "MyResource 子要素の foo 属性"
  value = {
    for key, value in azurerm_resource_mychildresource : key => value.foo
  }
}

# 機密出力
output "bar" {
  description = "MyResource bar 属性"
  value       = azurerm_resource_myresource.bar
  sensitive   = true
}

機密データ出力

重大度: MUST | 要件: TFNFR29

機密データを含む出力は sensitive = true で宣言しなければならない。

廃止された出力の処理

重大度: MUST | 要件: TFNFR30

• 廃止された出力を deprecated_outputs.tf に移動
• 新しい出力を outputs.tf で定義
• メジャーバージョンリリース時にクリーンアップ

---

ローカル値標準

locals.tf の構成

重大度: MAY | 要件: TFNFR31

• locals.tf は locals ブロックのみを含むべき**(SHOULD)**
• 高度なシナリオでは、リソースの隣で locals ブロックを宣言できます

アルファベット順ローカル配置

重大度: MUST | 要件: TFNFR32

locals ブロック内の式はアルファベット順に配置しなければならない。

正確なローカル型

重大度: SHOULD | 要件: TFNFR33

正確な型を使用することが望ましい (例: string ではなく年齢には number)。

---

Terraform 設定要件

Terraform バージョン要件

重大度: MUST | 要件: TFNFR25

terraform.tf 要件:

• terraform ブロックを 1 つだけ含むしなければならない
• 最初の行は required_version を定義しなければならない
• 最小バージョン制約を含むしなければならない
• 最大メジャーバージョン制約を含むしなければならない
• ~> #.# または >= #.#.#, < #.#.# 形式を使用することが望ましい

例:

terraform {
  required_version = "~> 1.6"
  required_providers {
    azurerm = {
      source  = "hashicorp/azurerm"
      version = "~> 4.0"
    }
  }
}

required_providers 内のプロバイダー

重大度: MUST | 要件: TFNFR26

• terraform ブロックは required_providers ブロックを含むしなければならない
• 各プロバイダーは source と version を指定しなければならない
• プロバイダーはアルファベット順にソートされることが望ましい
• 直接必要なプロバイダーのみを含める
• source は namespace/name 形式でなければならない
• version は最小および最大メジャーバージョン制約を含むしなければならない
• ~> #.# または >= #.#.#, < #.#.# 形式を使用することが望ましい

---

テスト要件

テストツール

重大度: MUST | 要件: TFNFR5

AVM の必須テストツール:

• Terraform (terraform validate/fmt/test)
• terrafmt
• Checkov
• tflint (azurerm ルールセット付き)
• Go (カスタムテスト用オプション)

テストプロバイダー設定

重大度: SHOULD | 要件: TFNFR36

堅牢なテストのため、prevent_deletion_if_contains_resources をテストプロバイダー設定で明示的に false に設定することが望ましい。

---

ドキュメント要件

モジュールドキュメント生成

重大度: MUST | 要件: TFNFR2

• ドキュメントは Terraform Docs を通じて自動生成しなければならない
• .terraform-docs.yml ファイルはモジュールルートに存在しなければならない

---

破壊的変更と機能管理

機能トグルの使用

重大度: MUST | 要件: TFNFR34

マイナーバージョン/パッチバージョンで追加された新しいリソースはトグル変数を持つしなければならない。デフォルトでは作成されません:

variable "create_route_table" {
  type     = bool
  default  = false
  nullable = false
}

resource "azurerm_route_table" "this" {
  count = var.create_route_table ? 1 : 0
  # ...
}

潜在的な破壊的変更のレビュー

重大度: MUST | 要件: TFNFR35

注意を要する破壊的変更:

リソースブロック:

1. 条件付き作成なしの新しいリソースの追加
2. デフォルト値ではない引数の追加
3. dynamic ブロックなしのネストされたブロックの追加
4. moved ブロックなしのリソース名前変更
5. count から for_each へのまたはその逆への変更

変数/出力ブロック:

1. 変数の削除/名前変更
2. 変数 type の変更
3. 変数 default 値の変更
4. nullable を false に変更
5. sensitive を false から true に変更
6. default なしで変数を追加
7. 出力の削除
8. 出力 value の変更
9. 出力 sensitive 値の変更

---

貢献標準

GitHub リポジトリブランチ保護

重大度: MUST | 要件: TFNFR3

モジュールオーナーはデフォルトブランチ (通常は main) にブランチ保護ポリシーを設定しなければならない:

1. マージ前にプルリクエストを要求
2. 最新の確認可能なプッシュの承認を要求
3. 新しいコミットがプッシュされたときに古いプルリクエスト承認を却下
4. 線形履歴を要求
5. フォースプッシュを防止
6. 削除を許可しない
7. CODEOWNERS レビューを要求
8. 設定を回避できない
9. 管理者に適用を強制

---

コンプライアンスチェックリスト

Azure Verified Modules を開発またはレビューするときに、このチェックリストを使用してください:

モジュール構造

• モジュール相互参照がレジストリソースをピン留めされたバージョンで使用
• Azure プロバイダー (azurerm/azapi) バージョンが AVM 要件を満たしている
• .terraform-docs.yml がモジュールルートに存在
• CODEOWNERS ファイルが存在

コードスタイル

• すべての名前が小文字スネークケースを使用
• リソースが依存関係優先で順序付けられている
• for_each が静的キーを持つ map() または set() を使用
• resource/data/module ブロックが適切な内部順序に従う
• ignore_changes が引用されていない
• 条件付きネストされたオブジェクトに動的ブロックを使用
• デフォルト値に coalesce() または try() を使用

変数

• enabled または module_depends_on 変数がない
• 変数が順序付けられている: 必須 (アルファベット順) その後オプション (アルファベット順)
• すべての変数が正確な型を持つ (any を回避)
• すべての変数が説明を持つ
• コレクションが nullable = false を持つ
• sensitive = false 宣言がない
• 機密入力にデフォルト値がない
• 廃止された変数が deprecated_variables.tf に移動されている

出力

• 出力がアンチコラプション層パターン (個別属性) を使用
• 機密出力が sensitive = true でマーク
• 廃止された出力が deprecated_outputs.tf に移動されている

Terraform 設定

• terraform.tf がバージョン制約 (~> 形式) を持つ
• required_providers ブロックがすべてのプロバイダーで存在
• モジュール内に provider 宣言がない (エイリアスを除く)
• Locals がアルファベット順で配置

テストと品質

• 必須テストツールが設定されている
• 新しいリソースが機能トグルを持つ
• 破壊的変更がレビューおよびドキュメント化されている

---

統計サマリー

• 機能要件: 3
• 非機能要件: 34
• 総要件: 37

重大度別

• MUST: 21 要件
• SHOULD: 14 要件
• MAY: 2 要件

---

参照先: Azure Verified Modules - Terraform 要件