alibabacloud-terraform-code-generation

Alibaba Cloud Terraform コード生成

自然言語で記述された Alibaba Cloud インフラストラクチャの要件を、現在の aliyun/alicloud プロバイダー向けの検証済み Terraform に変換します。リソース情報は生成時にプロバイダー自身のドキュメントから取得するため、ローカルで模範例を管理する必要はありません。

絶対に守るべきルール（例外なし）

1. 認証情報 — 漏えいさせない、要求しない

AK/SK の値は、HCL、コメント、環境変数の宣言、シェル出力、ログを含め、どこでも読み取ったり、表示したり、要求したり、書き込んだりしてはいけません。alicloud プロバイダーは、7 つの方法（環境変数の AK/SK、共有 config.json、ECS インスタンスの RAM ロール、Assume Role、OIDC/RRSA、サイドカー URI、静的 HCL）で認証情報を解決します。詳細な流れは references/auth-and-network.md を参照してください。これらはすべてプロバイダー自身が読み取り、このスキルでは読み取りません。非推奨の ALICLOUD_* ／ ALIBABACLOUD_*（アンダースコアなし）の環境変数名は推奨しないでください。現在の名前は ALIBABA_CLOUD_ACCESS_KEY_ID ／ _ACCESS_KEY_SECRET ／ _SECURITY_TOKEN です。

2. 正確な報告 — 実行していないステップを実行したと主張しない

該当するコマンドが実際に実行され、そのステータスが返されていない限り、fmt: ok ／ validate: ok ／ plan: ok と報告してはいけません。ステップをスキップした場合（ツールがない、ユーザーがオプトアウトしたなど）は、理由とともに "SKIPPED"（または "FAILED"）と明記してください。実際の出力を言い換えるのは問題ありませんが、捏造してはいけません。

3. terraform apply は実行禁止

このスキルは terraform apply を絶対に実行しません。plan はオプトインです（Step 8）。apply は必ずユーザー自身が実行してください。

環境（推奨事項）

• Terraform ≥ 1.5 を推奨します。Terraform を自動的にインストールまたはダウンロードしないでください。Step 6 では、terraform が PATH 上にあるか確認し、実際の検証ステータスを報告します。
• ネットワークが必要です — Step 4.2 では、各リソースのプロバイダードキュメントを WebFetch で取得します。

ワークフロー

Step 1. 要件を解析する

以下を抽出します。

• region — デフォルトは cn-hangzhou です。
• resources[] — { alicloud_type, quantity, attributes }。
• 非機能要件：マルチ AZ、暗号化、バックアップ、高可用性、IOPS。

曖昧な場合（例：「データベースを構築して」）は、確認の質問を最大 1 つだけ行います。

Step 2. 対象ディレクトリを解決する

ユーザーのリクエストから <target-dir> を抽出します（myshop-infra/ のような明示的なパス、または指定がなければ現在の作業ディレクトリ）。以降の fmt ／ init ／ validate コマンドはすべてこのディレクトリで実行します。

.tf ファイルを書き込む前に、必ずディレクトリを作成します。

mkdir -p <target-dir>

すべてのファイル書き込みで、パスの先頭に <target-dir>/ を付けてください。現在の作業ディレクトリに直接書き込んだり、汎用の outputs/ 親ディレクトリに書き込んだりしてはいけません。生成完了後、構成を確認してください。

ls -R <target-dir>

Step 3. アーキテクチャを概略設計する

HCL を記述する前に、リソースごとに 1 行の依存関係テーブルを作成します。

リソース	依存関係	AZ ／配置

• resources[] を、暗黙的に必要となるインフラストラクチャ（VPC → VSwitch → SecurityGroup → ワークロード）で拡張します。ユーザーの要件解析では、これらが省略されることがよくあります。
• 拡張した一覧を Step 4 のゲートへの入力とします。

Step 4. HCL 作成前のゲート（必須）

Step 3 のすべての個別の alicloud_* タイプ（リソースおよびデータソース）について、4.1 → 4.2 → 4.3 を実行します。タイプごとの呼び出しは独立しているため、タイプ間で並列に実行してください。

4.1 事前のドキュメント確認（カタログ＋パターンを並行して確認）

WebFetch に進む前に、2 つのローカル確認を並行して実行します。

(a) カタログ確認 — リソースが存在することと、非推奨かどうかを確認します。 カタログ（references/alicloud-providers.md）は約 2600 行あります。全体を Read しないでください。必要な行だけを取得する grep を使います。

grep "alicloud_<name>" references/alicloud-providers.md

結果は次の 3 通りです。

• 行が見つかり、ステータス列が空 → 行に記載されている [doc](<url>) を控え、 4.2 に進みます。
• **行が見つかり、ステータスが ⚠️ 弃用 → <new_name>** → 計画を <new_name>に切り替え、再確認します。非推奨の名前は絶対に出力しないでください。よくある例：alicloud_fc_function→alicloud_fcv3_function`。
• 行が見つからない → 中止します。その名前が誤記かどうかをユーザーに尋ねてください。 alicloud_<guess> を作り出してはいけません。

(b) パターン確認（条件付き）— ユーザーの要件が references/resource-patterns.md に記載されている製品固有のイディオム（例： RDS のクロス AZ HA、OSS の noncurrent ライフサイクル、VPC ピアリング）に当てはまる場合は、該当するセクションを読みます。 これらのイディオムはプロバイダーのドキュメントの Required リストには記載されていませんが、ユーザーが実際に必要としているものです（例：RDS HA の zone_id_slave_a はドキュメントでは任意ですが、実際に AZ をまたいで配置するには必須です）。 これらが欠けていると、「検証は通るが、気付かないまま誤った」出力になります。

該当するパターンセクションが見つかった場合、そのセクションの「Required attributes」表に記載されているすべての属性を、生成する HCL に含める必要があります。 プロバイダーのドキュメントで Optional とされていても、必須として扱います。

# Quick check whether a relevant pattern exists, then Read only the section:
grep -in "<keyword>" references/resource-patterns.md

4.2 プロバイダーのドキュメントを取得する（WebFetch）

4.1 のドキュメント URL を WebFetch します。失敗した場合、または有用な内容が返されない場合は、カタログ行の doc URL から raw URL を直接構築します。 カタログの種類を維持してください。リソースには website/docs/r/、データソースには website/docs/d/ を使用します。

https://raw.githubusercontent.com/aliyun/terraform-provider-alicloud/master/website/docs/{r|d}/<doc_name>.html.markdown

両方とも失敗した場合は、references/alicloud-providers.md のローカルカタログ行を代わりに使用します。読み上げヘッダーの先頭に doc unreachable: used local catalog を付けてください。ほかの URL を取得してはいけません。 信頼できる情報源は、上記の 2 つの URL またはローカルカタログのみです。

4.3 読み上げる（読み取りの証明）

HCL を書く前に、リソースごとの概要を完全に提示し、検証します。

• Required パラメーター（ドキュメントのリストをそのまま記載。4.2 でフォールバックした場合はローカルカタログから記載）
• ユーザーの要件に関連する、重要な Optional パラメーターを 2～5 個
• ドキュメントの「Example Usage」から抜粋した最小限の HCL スニペット（フォールバックした場合に限り、no example available という注記を付けて省略可能）

Required または Optional パラメーターが不足している場合は、4.2 に戻ります。読み上げを省略したり、一部だけを提示したりすることは重大な失敗です。WebFetch に失敗した場合は、記憶に頼らず、4.2 のフォールバックを使用します。

Step 5. 生成

5.1 記憶ではなく、読み上げた内容に基づいて HCL を記述する

4.3 で確認したパラメーターのみを使用します。読み上げた概要にないパラメーターが必要な場合は、4.2 でより詳しく再取得し、推測してはいけません。

フィールドを記述する前に、references/deprecated-fields.md でリソースを確認します（4 種類の行とそれぞれの扱いについては §5.6 を参照）。

grep '`alicloud_<resource>`' references/deprecated-fields.md

ユーザーの要件が特定の使用パターンを持つ製品（例：RDS のクロス AZ HA、VPC ピアリング、OSS ライフサイクル）に関わる場合は、見落としやすい属性について references/resource-patterns.md も確認してください。

5.2 データソースの適用（必須 — ID をハードコードしない）

リテラル値ではなく、data ブロックを使って解決します。これらも Step 4 の条件を満たします。

• zone_id → data "alicloud_zones"（available_resource_creation でフィルターします）。
• image_id → data "alicloud_images"（name_regex、owners = "system"、most_recent = true でフィルターします）。
• instance_type → data "alicloud_instance_types"（cpu_core_count、memory_size、AZ でフィルターします）。

5.4 プロバイダーブロック（内容の契約）

プロジェクト内の *.tf ファイルのどこかに、Terraform ブロックが 2 つ必要です。Terraform はディレクトリ内のすべての *.tf をマージするため、ファイル構成はスタイル上の選択であり、契約ではありません。下記の「ファイル構成」を参照してください。

ブロック 1 — terraform { required_providers {} }：

terraform {
  required_version = ">= 1.5"
  required_providers {
    alicloud = {
      source  = "aliyun/alicloud"
      version = "~> 1.274"
    }
  }
}

• プロバイダーのバージョン：公開済みの安定版 aliyun/alicloud 1.x の最新バージョンを確認し、悲観的なマイナー制約を記述します（1.278.0 -> ~> 1.278）。 確認先は次の順です。
  1. https://registry.terraform.io/v1/providers/aliyun/alicloud/versions
  2. https://registry.terraform.io/providers/aliyun/alicloud/latest
  3. https://github.com/aliyun/terraform-provider-alicloud/releases または https://github.com/aliyun/terraform-provider-alicloud/tags
• 確認に失敗した場合は、~> 1.274 を使用します。使用できる形式は、公開済みの 1.x リリースであることを確認したうえでの ~> 1.<minor> です。オープンエンドの制約（>= 1.x、>= 1.239.0）や、バージョン文字列だけの指定は絶対に記述しないでください。

ブロック 2 — provider "alicloud" {}。region = var.region と configuration_source の両方が必要です。

provider "alicloud" {
  region               = var.region
  configuration_source = "AlibabaCloud-Agent-Skills/alibabacloud-terraform-code-generation"
}

• configuration_source は帰属を示す署名であり、必須です。
• region はハードコードした値ではなく、必ず var.region を参照してください。

ファイル構成（推奨、必須ではありません）：一般的な分割方法は、terraform.tf（ブロック 1）と providers.tf（ブロック 2）です。両方のブロックを 1 つの versions.tf に含める方法や、いずれかのブロックを main.tf の先頭に置く方法も使用できます。プロジェクトに合った方法を選んでください。Terraform はすべての *.tf を同等にマージします。ファイル名のチェックは追加せず、代わりに以下の内容チェックを実行してください。

生成後の検証（複数ファイルを対象とした内容の grep）：

# 1. required_providers has aliyun/alicloud with a ~> 1.<minor> version
awk '
  /required_providers[[:space:]]*{/ { in_req=1 }
  in_req && /alicloud[[:space:]]*=[[:space:]]*{/ { in_ali=1 }
  in_ali && /source[[:space:]]*=[[:space:]]*"aliyun\/alicloud"/ { source=1 }
  in_ali && /version[[:space:]]*=[[:space:]]*"~>[[:space:]]*1\.[0-9]+"/ { version=1 }
  in_ali && /^[[:space:]]*}/ { in_ali=0 }
  END { exit(source && version ? 0 : 1) }
' <target-dir>/*.tf \
  && echo OK_VERSION || echo BAD_OR_MISSING_VERSION

# 2. configuration_source attribution present somewhere
grep -Rq 'configuration_source = "AlibabaCloud-Agent-Skills/alibabacloud-terraform-code-generation"' \
  <target-dir>/*.tf \
  && echo OK_CFG_SOURCE || echo MISSING_CFG_SOURCE

# 3. region uses variable, not hardcoded
grep -Rq 'region\s*=\s*var\.region' <target-dir>/*.tf \
  && echo OK_REGION_VAR || echo HARDCODED_REGION

3 つすべてが OK を返す必要があります。いずれかが失敗した場合は、該当する内容を修正して再実行してください。失敗したままステップ 6 に進んではいけません。

5.5 スタイルの基本

• インデントは 2 スペースとし、ブロック内で = の位置を揃えます。リソースラベルには、意味の分かる snake_case を使用します（vsw1 ではなく alicloud_vswitch.app_a）。
• タグに対応するすべてのリソースに、運用上の衛生管理のため、空でない tags ブロックを指定してください。シナリオに合ったキーを選びます（よく使われるキー：ManagedBy、Project、Environment、CreatedBy）。Skill では、特定のタグキーや値を指定しません。

5.6 非推奨フィールドの監査 — 静的 grep パス（必須）

terraform が必要になる前に実行してください。これは、直前に作成した HCL に対する純粋な grep パスです。この世代で作成したすべてのリソースについて、プロジェクトを references/deprecated-fields.md と照合して grep し、各行の種類に応じて対応してください。

• rename 行 → 古いフィールド名が直前に作成した HCL に含まれている場合は、新しいフィールド名に置き換えてください。よく見られる例：
  • alicloud_ram_role：name → role_name、 document → assume_role_policy_document
  • alicloud_security_group：name → security_group_name
  • alicloud_db_database：name → data_base_name
• split / soft-split 行 → 親リソースにインラインフィールドを記述しないでください。その機能がユーザーの要件に必要な場合、または references/resource-patterns.md にサブリソースの明示的な安全なデフォルトが記載されている場合に限り、代替のサブリソースを宣言してください。例：OSS バケットでは、alicloud_oss_bucket_acl のデフォルトは private ですが、ユーザーが機能を求めない限り、ロギング／CORS／ウェブサイトのサブリソースは省略します。
• deprecated-no-replacement 行 → 代替手段を使わず、そのフィールドの使用を停止してください。

この世代で作成したファイルにのみ適用します。変更を依頼されていない既存のユーザーファイルはリファクタリングしないでください。

監査後の検証（bash grep — すべて OK が返ること）：

# Walk deprecated-fields.md row by row and check whether any deprecated
# field that applies to a generated resource is still in use.
# Uses awk to extract individual resource blocks before field matching,
# so that short field names (name, document) don't falsely match
# substrings in compound field names (role_name, policy_document).
grep '| `alicloud_' references/deprecated-fields.md | while IFS='|' read _ resource field kind _; do
  resource=$(echo "$resource" | tr -d ' `')
  field=$(echo "$field" | tr -d ' ')
  kind=$(echo "$kind" | tr -d ' ')
  # Only check if this resource exists in the generated HCL
  if grep -Rq "resource \"$resource\"" <target-dir>/*.tf; then
    case "$kind" in
      rename|deprecated-no-replacement)
        awk -v res="$resource" -v fld="$field" '
          $0 ~ "resource \"" res "\"" { in_block=1; next }
          in_block && /^}/ { in_block=0 }
          in_block && $0 ~ "(^|[^_[:alnum:]])" fld "([^_[:alnum:]]|$)" { found=1; exit }
          END { exit found ? 0 : 1 }
        ' <target-dir>/*.tf \
          && echo "DEPRECATED: $resource.$field" || echo "OK: $resource.$field"
        ;;
      split|soft-split)
        grep -q "\b$field\b\s*=" <target-dir>/*.tf \
          && echo "DEPRECATED: $resource.$field (inline — use standalone sub-resource)" \
          || echo "OK: $resource.$field (not inline)"
        ;;
    esac
  fi
done

厳格なゲート：ステップ 6 の前に必ず合格すること — 上記のスクリプトが DEPRECATED: 行を出力した場合：

1. 各 DEPRECATED: 行を確認してください。リソースとフィールドが記載されています。
2. references/deprecated-fields.md で該当するリソースとフィールドを調べ、Action 列（変更先、分割先のサブリソースなど）を確認してください。
3. HCL に修正を適用してください。
4. 検証スクリプトを再実行してください。
5. すべての行が OK: を返すまで繰り返してください。これはブロッキングゲートです。DEPRECATED: の出力がある状態でステップ 6 に進まないでください。スクリプトがすべて OK: を出力しない限り、「検証済み」と主張しないでください。

ステップ 6. 検証とプロバイダーの非推奨検出

terraform が PATH にある場合：

(cd <target-dir> \
  && terraform fmt -recursive \
  && terraform init -backend=false \
  && terraform validate -json)

両方の条件が満たされるまでループします（修正の試行は最大 3 回まで）：

1. validate -json を解析します。エラーがある場合 → 該当ファイルを修正し、ステップ 3 に進みます。
2. validate -json の diagnostics[].summary に [DEPRECATED] 文字列がないかスキャンします。プロバイダーは、権威ある非推奨の注釈を出力します（例："document": "[DEPRECATED] … New field 'assume_role_policy_document' instead."）。見つかった場合 → 該当フィールドを修正し、ステップ 3 に進みます。
3. cd <target-dir> && terraform validate -json を再実行し、ステップ 1 に戻ります。

validate でエラーも [DEPRECATED] 診断もない場合にのみ、ループを終了します。この状態に達しないまま 3 回試行した場合は、Validation: FAILED (<diagnostic excerpt>) としてステップ 7 に進み、任意の注記に失敗した HCL をそのまま含めてください。

init がネットワークエラーで失敗した場合（registry.terraform.io に到達できない場合）： 設定の不具合ではありません。references/auth-and-network.md のミラーソース設定をユーザーに案内してから、ステップ 7 に進んでください。Summary では必ず Validation: SKIPPED (init failed — network/unreachable) を使用してください。むやみに再試行せず、自分で ~/.terraformrc を書き込まないでください。

terraform がない場合：このステップをスキップし、ステップ 7 のサマリーでその事実を示してください（ハードルール §2）。Validation: SKIPPED (terraform binary not on PATH) を使用してください。

ステップ 7. カバレッジを確認して要約する

必須 — 生成の結果にかかわらず実行します。 それ以前のステップが中断されていても（初期化時のネットワーク障害、検証ループの上限到達、terraform が PATH にない場合など）、このステップは必ず実行してください。Files written: と Validation: の行は後続の評価処理に対する最終的な契約です。これらを省略すると重大な失敗になります。

カバレッジの確認。 生成された HCL 内のリソースブロックを列挙し、ステップ 3 のスケッチと比較します。スケッチの行が欠けている場合は、ステップ 5 に戻って追加してください。「ユーザーが明示的に指定していない」という理由で行を省略してはいけません。

要約テンプレート — ユーザーの言語で、必ず以下の構造どおりに出力してください（<bracketed> のプレースホルダーを埋め、2 つの行ラベル Files written: と Validation: はそのままにします）。

Files written:
<path/to/file1>
<path/to/file2>
...

Validation: <one-of-four-exact-strings-below>

Deprecation routing: <If re-routed: `<original_name>` → `<new_name>`; else: None>

<optional: architecture notes, design decisions, deploy hints — free-form
here is fine, but NOT inside the lines above>

Validation: の行は、ステップ 6 で実際に起きたことに基づいて、以下の正確な文字列のいずれかにしなければなりません。言い換えたり、文章に含めたりしてはいけません。

• Validation: terraform fmt+validate: ok
• Validation: SKIPPED (terraform binary not on PATH)
• Validation: SKIPPED (<reason>)
• Validation: FAILED (<diagnostic excerpt>) — 3 回の再試行後、上限に達した場合

例外ケース：

• 初期化がタイムアウトした場合 → Validation: FAILED (init timed out — provider installation exceeded time limit)
• 初期化時にネットワークへ接続できなかった場合 → Validation: SKIPPED (init failed — network/unreachable)
• fmt が成功した後に初期化が失敗した場合 → 複合ステータスではなく、上記の根本原因文字列を使用してください。

ステップ 8（任意）。terraform plan

ユーザーが求めた場合に限ります。事前チェックでは、値を読み取らずに references/auth-and-network.md に記載された7 つすべての認証情報パスを確認します。

(
  [[ -n "${ALIBABA_CLOUD_ACCESS_KEY_ID:-}" ]] && [[ -n "${ALIBABA_CLOUD_ACCESS_KEY_SECRET:-}" ]] && echo "ready:env-ak-sk"
  [[ -f "$HOME/.aliyun/config.json" ]]                                                           && echo "ready:shared-config"
  { [[ -n "${ALIBABA_CLOUD_CREDENTIALS_FILE:-}" ]] && [[ -f "${ALIBABA_CLOUD_CREDENTIALS_FILE}" ]]; } && echo "ready:custom-credentials-file"
  [[ -n "${ALIBABA_CLOUD_ECS_METADATA:-}" ]]                                                      && echo "ready:ecs-ram-role"
  [[ -n "${ALIBABA_CLOUD_ROLE_ARN:-}" ]]                                                          && echo "ready:assume-role"
  [[ -n "${ALIBABA_CLOUD_CREDENTIALS_URI:-}" ]]                                                   && echo "ready:sidecar"
) | head -1

• 出力が 1 行でもある場合 → 利用可能な認証情報パスがあります。 (cd <target-dir> && terraform init && terraform plan -out=tfplan) を実行し、出力を提示してください。
• 出力が空の場合 → NO_CREDENTIALS。利用可能なすべてのパス（環境変数 AK/SK、共有 ~/.aliyun/config.json と ALIBABA_CLOUD_PROFILE、ECS インスタンス RAM ロール、Assume Role チェーン、OIDC/RRSA、サイドカー URI）をユーザーに伝えてください。環境変数 AK/SK だけを勧めてはいけません。詳しい設定については references/auth-and-network.md を参照するよう案内してください。その後は終了します。シークレット値を読み取ったり、出力したりしてはいけません。

参考資料

ソース	読み込むタイミング
references/alicloud-providers.md（ローカル）	ステップ 4.1 — リソースの有無、非推奨マーク、ドキュメント URL
プロバイダーのドキュメント（4.1 の URL を WebFetch）	ステップ 4.2 — 各リソースの必須／任意項目に関する正式な情報
references/deprecated-fields.md（ローカル）	ステップ 5.1 — terraform validate では検出されない、既知のフィールド名変更
references/resource-patterns.md（ローカル）	ステップ 5.1 — プロバイダーのドキュメントで強調されていない、製品固有の慣例（RDS HA など）
references/auth-and-network.md（ローカル）	ステップ 6 の失敗時 — ミラーソースの設定。ステップ 8 の事前チェック — 認証情報チェーン全体

ローカルカタログは、各 alicloud_* リソースおよびデータソースにつき 1 行の Markdown テーブルです。[doc](<url>) のセルがあり、非推奨の項目には ⚠️ 弃用 → <new_name>`` マーカーが付いています。これは上流のプロバイダーリポジトリから scripts/build_alicloud_providers.py で生成されます。新しい aliyun/alicloud リリースで非推奨項目が追加または変更された場合は、そのスクリプトを再実行してください。