volcengine-iac

Volcengine IaC スキル

ユーザーが IaC を選択した場合、Terraform を使用して Volcengine のインフラストラクチャを生成、計画、適用します。アプリケーションのパッケージ化、ランタイムのロールアウト、ヘルスチェック、CLI のリソース台帳を使ったデプロイは、引き続き volcengine-deploy が担当します。

新しい例を作成するときは、Cloud Control プロバイダー volcengine/volcenginecc を優先してください。assets/examples/ にある検証済みの例から始め、対応する references/volcenginecc-*.md のメモを読んで、検証結果と注意点を確認します。ブロックされているリソースは references/volcenginecc-blocked.md で管理されています。assets/modules/ にある既存の再利用可能なモジュールは、各コンポーネントが volcenginecc で再検証されるまで、従来の volcengine/volcengine プロバイダーを使用します。

次のいずれかに該当する場合は、このスキルを使用してください。

• ユーザーが Terraform または IaC を求めている
• ユーザーがすでに Terraform の状態またはワークスペースを使用している
• plan／diff／ドリフト検出が重要である
• インフラストラクチャを長期にわたってチームで管理する予定で、ユーザーが IaC を選択している
• デプロイに VKE、マネージドデータベース／キャッシュ／ストレージ、ロードバランサー、ドメイン／証明書、IAM／KMS、ロギング、モニタリング、または Serverless トリガーが必要で、ユーザーが IaC を選択している

デプロイが長期にわたる、VKE ベースである、またはマネージド依存関係があるという理由だけで、このスキルを使用しないでください。適切な場合は IaC を推奨しますが、ユーザーに選択してもらってください。ユーザーが CLI、一時的なデモ／簡易検証、plan／diff／destroy の要件がない純粋な ECS 単一 VM サービスを求めている場合、または Terraform／プロバイダーのインストールがブロックされ、対象で CLI による代替が安全に使える場合は、このスキルを使用しないでください。

このスキルには、assets/examples/ にある検証済みの volcenginecc の例、assets/modules/ にある従来の再利用可能なモジュール、tfvars の生成、plan の要約、出力のエクスポート、ドリフトチェックを行うラッパースクリプトが含まれています。対象の構成が判明してからファイルを選択してください。小規模な Terraform の編集で、幅広いカタログをコンテキストに読み込まないでください。

従来の 6 つのモジュール以外のリソース（CLB／ALB、VKE、CR、データベース、キャッシュ、オブジェクトストレージ）は、まず検証済みの volcenginecc の例として追加し、インターフェースの安定性が繰り返しの使用で確認されてからラップしてください。

---

0. 前提条件

必須の環境変数：VOLCENGINE_ACCESS_KEY、VOLCENGINE_SECRET_KEY、VOLCENGINE_REGION。

必須ツール：terraform >= 1.5、jq、git、python3（gen_tfvars.py 用）。

任意：volcengine-prepare／volcengine-deploy が生成する .volcengine/deploy-choice.json。存在しない場合は、Terraform に関する質問をまとめて簡潔に尋ねてください。

このスキルは、デフォルトで .volcengine/terraform/ に Terraform の作業ファイルを書き込みます。ユーザーがリモート状態を希望する場合、状態には TOS S3 互換バックエンドを使用できます。詳しくは references/backend-tos.md を参照してください。ユーザーがそのトレードオフを受け入れる場合、小規模な単発の実験ではローカル状態を使用できます。

volcengine-deploy から呼び出された場合は、.volcengine/iac-outputs.json に出力を返し、deploy によるイメージのビルド／プッシュ、Cloud Assistant コマンド、Kubernetes マニフェスト、veFaaS のリリース、マイグレーション、ヘルスチェックの実行を続けてもらいます。

---

1. 生成フロー

パス A — .volcengine/deploy-choice.json に基づく場合

work_dir="${work_dir:-.volcengine/terraform}"
workload="${workload:-standard}"
mkdir -p "$work_dir"

python3 scripts/gen_tfvars.py \
  --input ".volcengine/deploy-choice.json" \
  --output "$work_dir/terraform.tfvars" \
  --workload "$workload"

gen_tfvars.py は、次の値を導出します。

• 選択ファイルと環境から project、region、AZ のペア
• 選択されたモードと既知の依存関係から enable_vke / enable_cr / enable_rds / enable_redis / enable_tos フラグ
• 大まかな --workload ティアからサイジング（インスタンスタイプ、ノード数、RDS 仕様、Redis 容量）

ユーザーは適用前に、任意の値を上書きできます。

パス B — 自然言語による入力

prepare レポートがない場合、ユーザーに質問をまとめて一度に尋ねてから、検証済みの例または従来のモジュールを使って Terraform の作業ディレクトリを作成し、対応する変数値を生成します。必要な回答は次のとおりです。

1. プロジェクト名（リソースのプレフィックス）
2. リージョン（例：cn-beijing）
3. VKE が必要か（はい／いいえ）
4. 必要なステートフル依存関係：MySQL？PostgreSQL？Redis？TOS バケット？
5. ワークロードのティア：light／standard／heavy

書き込まれるファイル

gen_tfvars.py が書き込むのは terraform.tfvars のみです。Terraform の構成ファイルは、assets/examples/ にある検証済みのサンプルをコピーするか、assets/modules/ から組み立てた小規模なルートモジュールを使用します。スクリプトが構成ファイルを生成すると想定せず、選択したスタックに合わせてそれらのファイルを編集してください。

ファイル	用途
main.tf / variables.tf	コピーまたは組み立てた Terraform 構成
terraform.tfvars	gen_tfvars.py で生成するか、手動で編集する具体的な値
backend.tf	TOS リモートステートを選択した場合にのみ生成します。それ以外の場合は省略してください

モジュールごとの変数スキーマ全体は references/modules.md にあります。新しい volcenginecc の作業では、ユーザーが古いプロバイダーを明示的に必要としていない限り、これらのレガシーモジュールではなく、assets/examples/ にある検証済みのサンプルから始めてください。

パス C — volcenginecc の検証済みサンプル

該当する検証済みサンプルをコピーし、同じ init／validate／plan の手順を実行してください。

cp -R "assets/examples/<example-name>" "$work_dir/<component>"
cd "$work_dir/<component>"
terraform init -backend=false -input=false
terraform validate
terraform plan -out=tfplan.binary -input=false

apply の前にプランの概要を提示し、ユーザーから明示的な確認を得てください。入力を変更したりリソースを破棄したりする前に、対応するリファレンスを読んでください。リファレンスには、フィールドの選択肢、検証に関する注意事項、インポート ID、プロバイダーに関する落とし穴が記載されています。

---

2. デプロイスタックの対応付け

デプロイの構成に応じて、少数の検証済みサンプルを選択してください。まずサンプルを使い、インターフェースが安定していることが繰り返しの使用で確認できた場合にのみ、再利用可能なモジュールでラップしてください。一般的なスタックの組み合わせは次のとおりです。

• ECS：volcenginecc-network、volcenginecc-ecs、必要に応じて TLS／CloudMonitor
• VKE：volcenginecc-network、volcenginecc-vke、volcenginecc-cr、CLB または ALB
• veFaaS：volcenginecc-vefaas、必要に応じて APIG／TLS
• ステートフルな Web アプリ：ランタイムスタックに加えて、RDS、Redis、必要に応じて TOS のサンプル
• プライベートサービス：ランタイムスタックに加えて、プライベート NAT またはネットワーク接続のサンプル
• ドメインのエントリーポイント：ランタイムスタックに加えて、DNS とロードバランサー証明書のサンプル

この対応付けはガイドであり、事前構築済みのモジュールが存在することを保証するものではありません。該当するサンプルを .volcengine/terraform/<component> にコピーし、plan／destroy の出力を読みやすく保てるよう、コンポーネントの境界を明確にしてください。

VKE プライベート CR nginx のエンドツーエンドのパスでは、assets/examples/volcengine-vke-cr-nginx/ を使用し、最初に references/volcengine-vke-cr-nginx.md を読んでください。このサンプルは、実際の実行で見つかった CR 認証情報アドオン、core-dns、CR トークンの有効期限、イメージのアーキテクチャに関する落とし穴に対応しています。

---

3. カタログ

カタログとしてファイルシステムを使用してください。デプロイの構成を選択したら、assets/examples/ のうち関連するディレクトリだけを一覧表示し、検証に関する注意事項、インポート ID、プロバイダーに関する注意事項を確認するため、対応する references/volcenginecc-*.md ファイルを読んでください。最初からすべてのサンプルをコンテキストに読み込まないでください。

一般的なサンプルファミリーは次のとおりです。

• volcenginecc-network、VPC 拡張、NAT、VPN、DirectConnect、CEN、TransitRouter、PrivateLink、DNS、PrivateZone
• volcenginecc-ecs、ECS 拡張、起動テンプレートのバージョン、EBS スナップショット、Auto Scaling
• volcenginecc-vke、volcenginecc-cr、CLB／ALB エントリーポイント、APIG、veFaaS
• volcenginecc-rdsmysql、volcenginecc-rdspostgresql、volcenginecc-rdsmssql、Redis、Kafka 許可リスト
• volcenginecc-tos、TOS 通知、TLS、CloudMonitor、IAM、FileNAS、EFS

レガシーの volcengine モジュールは引き続き assets/modules/ で利用できます。使用する前に references/modules.md を読んでください。

レガシーモジュールは現在、network、vke、cr、rds-mysql、redis、tos をカバーしています。ECS と CLB／ALB は、ワークロードの構成が多様すぎて、単一の安定したモジュールインターフェースにまとめられないため、検証済みのサンプルとして提供しています。

---

4. 初期化とバックエンド

cd "$work_dir"

# Map Volcengine creds to the Terraform s3 backend's required env variable names.
export AWS_ACCESS_KEY_ID="$VOLCENGINE_ACCESS_KEY"
export AWS_SECRET_ACCESS_KEY="$VOLCENGINE_SECRET_KEY"
export AWS_EC2_METADATA_DISABLED=true

terraform init -input=false
tf_workspace="${tf_workspace:-default}"
terraform workspace select "$tf_workspace" || \
  terraform workspace new "$tf_workspace"

リモート状態が要求された場合は、references/backend-tos.md から backend.tf を生成します。検証済みの TOS バックエンド設定では、skip_requesting_account_id = true が必須であり、force_path_style または use_path_style を設定してはいけません。

プロバイダーのダウンロード（初回は約30～60秒）は registry.terraform.io 経由で行われます。中国のネットワークでは、ブロックされたり遅くなったりする場合があります。パブリックレジストリへのアクセスに失敗してもユーザーが IaC を希望する場合は、Terraform の provider_installation をファイルシステムまたは内部ミラーで設定してください。それ以外の場合は volcengine-deploy に戻り、CLI リソース台帳を使用するかどうかを確認してください。

TOS バケットの前提条件（init の前に存在している必要があります）については、references/backend-tos.md を参照してください。TOS バケットがない場合は backend.tf を省略し、Terraform がローカル状態にフォールバックするようにしてください。

---

5. プラン

terraform plan -out=tfplan.binary -input=false
terraform show -json tfplan.binary > tfplan.json
bash scripts/plan_summary.sh tfplan.json

plan_summary.sh は変更をアクション（CREATE／UPDATE／DELETE／REPLACE）ごとにまとめ、最後に1行の概要を表示します。apply を実行する前に、これをユーザーに提示してください。

次の点に注意してください。

• 依頼されていない DELETE — 通常、ドリフトまたは誤って削除されたモジュール呼び出しの兆候です
• 状態を持つリソースの REPLACE — RDS／Redis の置き換えはデータ損失につながります。中止して terraform show tfplan.binary で差分を確認してください

---

6. 適用

必ずユーザーの明示的な確認を求めてください。 -auto-approve を渡してはいけません。次の手順に従います。

The plan above will create N resources, change M, destroy K. Approve apply? [yes/no]

はいの場合：

terraform apply tfplan.binary

VKE クラスターの作成には約10～15分かかります。RDS HA インスタンスには約20分かかります。処理が停止したと思われないよう、apply の開始時に長時間実行される旨を一度ユーザーに伝えてください。

apply が成功したら、export_outputs.sh を自動的に実行します。

bash scripts/export_outputs.sh
echo "Resources ready. .volcengine/iac-outputs.json now contains downstream consumption keys."

---

7. 下流で使用する出力

export_outputs.sh は terraform output -json を .volcengine/iac-outputs.json にモード 0600 で書き込みます。下流のスキルでは通常、VPC／サブネット／セキュリティグループの ID、VKE kubeconfig、CR リポジトリデータ、RDS／Redis のエンドポイントまたは ID、TOS バケット名を使用します。一部のキーは有効にした例やモジュールによって条件付きで出力されるため、利用側では防御的な jq のデフォルト値を使用する必要があります。

---

8. 破棄

# Show what will be destroyed first
terraform plan -destroy -out=destroy.binary
terraform show -json destroy.binary | bash scripts/plan_summary.sh

その後：

This will permanently delete N resources including RDS / Redis / TOS bucket data. Confirm? [yes/no]

はいの場合：

terraform destroy
# Note: provider does not accept -auto-approve=false; we rely on the agent-level prompt above.

厳守事項：prod ワークスペースでは、2回目の確認なしに破棄してはいけません。エージェントは明示的に再確認してください。

Workspace = prod. Re-confirm destroy by typing 'destroy prod':

---

9. ドリフト検出

bash scripts/check_drift.sh

戻り値：

• 0 と {"drift": false, ...} — ドリフトなし
• 2 と {"drift": true, "changed_resources": N, ...} — N 個のリソースが Terraform 外で変更されました
• 1 と {"drift": "error", ...} — refresh-only プランでエラーが発生しました

次の用途で使用します。

• 既知の手動介入後（コンソールからノードプールのサイズを変更した場合など）
• CI ジョブとして定期的に実行（毎週）
• ベースラインが状態と一致していることを確認するため、重要な apply の前に実行

---

10. 既存リソースのインポート

ユーザーが volcengine-cli またはコンソールで作成したリソースを管理対象にしたい場合は、terraform import を使用します。インポート ID はリソースごとに異なるため、インポート前に該当する references/volcenginecc-*.md または references/modules.md を読んでください。インポート後に terraform plan を実行し、状態ではなく設定を編集して調整してください。

---

11. 安全規則

• ~/.volcengine/config.json は平文の AK／SK が含まれている可能性があるため、絶対に読み取らないでください。
• terraform.tfstate* または .volcengine/iac-outputs.json を絶対にコミットしないでください。
• terraform apply または terraform destroy に -auto-approve を絶対に渡さないでください。
• 共有環境では、apply の前に必ず check_drift.sh を実行してください。
• kubeconfig またはシークレットを含むファイルのモードは 0600 に設定してください。
• すべてのモジュール／例でプロバイダーのバージョンを固定してください。

スクリプトは可能な限りファイル権限を適用します。apply と destroy のゲート管理はエージェントの責任です。

---

12. トラブルシューティング

正確なエラー文字列で検索し、無関係なレイヤーを疑う前に、対応する原因に対処してください。

症状	原因	修正方法
terraform init：「Failed to query available provider packages」	registry.terraform.io へのアウトバウンド通信がブロックされています	provider_installation をファイルシステムまたは内部ミラーで設定し、init を再実行してください。それができない場合は volcengine-deploy に戻り、CLI によるリソース台帳のプロビジョニングが許容されるか確認してください
terraform init：TOS バックエンドで「InvalidAccessKeyId」	s3 バックエンドの環境変数がエクスポートされていません	AWS_ACCESS_KEY_ID="$VOLCENGINE_ACCESS_KEY"、AWS_SECRET_ACCESS_KEY="$VOLCENGINE_SECRET_KEY"、AWS_EC2_METADATA_DISABLED=true をエクスポートしてください
terraform init：TOS バックエンドが InvalidPathAccess を返す	パス形式のアクセス、またはサポートされていないワークスペースのプレフィックスです	references/backend-tos.md の検証済みテンプレートを使用してください。skip_requesting_account_id = true はそのままにし、force_path_style／use_path_style は削除してください
VPC の apply は成功するものの、サブネットで InvalidVpc.InvalidStatus が発生する	VPC がまだ Available ではありません（整合性が取れるまでの時間）	depends_on = [volcengine_vpc.main] を追加してください（ネットワークモジュールにはすでに設定されています）
VKE クラスターが Creating のまま 20 分以上経過する	クォータまたは AZ のキャパシティが原因です	ve vke ListClusters --body '{"Filter":{"Ids":["..."]}}' | jq .Result.Items[0].Status を実行して、本当の原因を確認してください
redis の出力にエンドポイントがない	プロバイダーがエンドポイントをエクスポートしません	ve redis DescribeDBInstanceDetail --InstanceId $(jq -r '.redis_instance_id.value' .volcengine/iac-outputs.json) で解決してください
変更していないのに terraform plan に予期しない変更が表示される	ドリフト、またはプロバイダーのパッチバージョン更新によってデフォルト値がひそかに変更されています	check_drift.sh を実行し、tfplan.json を確認して、変更を受け入れるか元に戻すかを判断してください
2 人のエンジニアによる apply が競合する	TOS バックエンドには DynamoDB 形式のロック機能がありません	手動で調整してください。詳細は references/backend-tos.md を参照してください
リソース固有の apply／インポートでドリフトが発生する	該当リソースに関するプロバイダーの注意事項です	設定を編集する前に、対応する references/volcenginecc-*.md の注記を読んでください