design-deploy

カスタムインフラストラクチャの設計とデプロイのスキル

概要

このスキルでは、Google Cloud Platform（GCP）におけるインフラストラクチャのライフサイクル全体を対象とした、規範的で本番環境に対応したワークフローを提供します。自動化され内部処理が不透明な GAD の design_infra ツールを、モジュール化された Terraform とローカルの CLI 検証を活用するエージェントが制御する設計・検証ループに置き換えます。その後、デプロイとライフサイクル管理のために Application Design Center（ADC）レジストリと同期する前に、ベストプラクティスのシフトレフト型プランスキャンを実施します。

常にプリンシパルクラウドアーキテクトとしての役割を維持してください。ローカルの Terraform 構成を信頼できる情報源として扱い、クラウドレジストリにインポートする前に、設計がベストプラクティスに完全に準拠していることを確認してください。

---

目次

1. 前提条件：セットアップと確認
2. フェーズ 1：ローカルでのインフラストラクチャ設計と検証
3. フェーズ 2：シフトレフト型のベストプラクティス評価と反復的な修正
4. フェーズ 3：IaC を Application Design Center にインポート
5. フェーズ 4：アプリケーションのデプロイとモニタリング
6. フェーズ 5：デプロイ失敗のトラブルシューティング
7. フェーズ 6：検証と E2E テスト

---

前提条件：セットアップと確認

フェーズ 1 を実行する前に、以下のセットアップ手順を必ず実施してください。

1. 対象プロジェクトとロケーションの確認：

   • 対象となる GCP のプロジェクト IDとロケーション（リージョン）を、ユーザーに明示的に確認してください。

   • ユーザーがロケーションを指定しない場合は、デフォルトとして**us-central1**を使用してください。

   • ローカル環境でアクティブなプロジェクトが設定されていることを確認します。

     gcloud config set project <project_id>
     

---

フェーズ 1：ローカルインフラストラクチャの設計と検証

目標：ユーザーの要件とコードベースの特性を、ローカルで 100％ 検証済みかつ安全で、コンパイル可能な Terraform 設定に変換します。

1. design スキルを実行する：ユーザーのプロンプトに対して、 design で定義されている design スキルを呼び出して実行します。

   • design スキルは、専用のスクラッチディレクトリでコードベースの分析、 カタログレジストリへの問い合わせ、計画、HCL の生成、ローカル CLI 検証ループ（terraform init、validate、plan）を自律的に実行します。

2. 検証済みの HCL を特定する：design スキルが検証済みでコンパイル可能な Terraform ファイルを保存したスクラッチディレクトリ （例：scratch/tf_validate_<session_id>/）を特定します。

3. 引き継ぎを確認する（必須）：次に進む前に、design スキルのローカル検証 ループが、クリーンなプランで正常に完了したことを確認します。HCL を慎重に 調べ、次の点を確認してください。

   • シークレット保護ポリシー：平文の認証情報、パスワード、ハードコードされた シークレットが、terraform.tfvars または HCL のリソースブロックに記述されて いないことを確認します。機密性の高い入力はすべて GCP Secret Manager 経由で 渡す必要があります。
   • 状態分離ポリシー：HCL ファイルにリモートバックエンドブロック （例：backend "gcs" {}）がないことを確認します。検証中は状態をスクラッチ フォルダー内のローカルに保持し、インポート後のリモート状態レジストリには ADC が対応できるようにする必要があります。
   • 修正：違反が見つかった場合は、HCL を修正し、ローカル検証を再実行して、 もう一度確認します。未検証または安全でないコードで先に進まないでください。

4. Terraform プランを JSON にエクスポートする（必須）：スクラッチディレクトリで 次のコマンドを実行し、バイナリプランを生成して、整形された JSON 表現に変換します。

   terraform plan -out=tfplan && terraform show -json tfplan > tfplan.json
   

   tfplan.json ファイルがスクラッチディレクトリに正常に書き込まれたことを確認します。

---

フェーズ 2：シフトレフトのベストプラクティス評価と反復的な修正

目標：ネイティブの ADC プラン評価 API を使用して、クラウドレジストリにインポートする前に、ローカルプランがセキュリティ、コスト、信頼性のベンチマークに適合していることを検証します。

1. スペース ID の検出（必須）：評価の実行やテンプレートの作成を行う前に、対象のロケーションでアクティブな ADC スペース ID を動的に検出する必要があります。

   • スペースの一覧表示：次のコマンドを実行します。

     gcloud design-center spaces list --project=<project_id> --location=<location>
     

   • スペースの選択：出力を解析して、アクティブなスペース（例： test-deploy または googlespace）を特定します。スペースが複数ある場合は、ユーザーに確認します。スペースが存在しない場合は、ユーザーに確認するか、次のコマンドで作成します。

     gcloud design-center spaces create <space_id> --project=<project_id> --location=<location>
     

2. gcloud でのプラン評価の実行：検出したスペース ID とエクスポート済みの tfplan.json ファイルを使用して、プランベースの評価を実行します。ターミナルでコマンドを直接実行します。

   gcloud design-center spaces generate-terraform-assessment-report <space_id> \
       --location=<location> \
       --project=<project_id> \
       --terraform-plan="<scratch_directory_path>/tfplan.json" \
       --format=json
   

3. 検出結果の分析：具体的な違反事項、リソースの範囲、関連する重大度を明記し、すべての検出結果を見やすい表形式でユーザーに提示します。

4. ローカルでの修正ループ：

   • 安全でないコードをインポートまたはコミットしようとしないでください。

   • 報告された違反を修正するため、スクラッチディレクトリ内のローカル HCL ファイルを編集します（例：暗号化キーの追加、OS Login の有効化、IAM のスコープの制限）。

   • フェーズ 1 のローカル検証とプランのエクスポートを再実行します。

     terraform validate && terraform plan -out=tfplan && terraform show -json tfplan > tfplan.json
     

   • ステップ 2 に記載されたプラン評価コマンドを再実行します。

5. 終了条件：

   • 重大または高リスクの検出結果がすべて解決されているか、許容可能なトレードオフが文書化されていること。
   • 反復回数が最大 3 回に達していること。問題が解消されるか、許容可能な状態になったら、フェーズ 3 に進みます。

---

フェーズ 3：IaC の Application Design Center へのインポート

目標：完全に検証され、ベストプラクティスに準拠したローカル HCL 構成を ADC クラウドレジストリと同期し、デプロイ可能なテンプレートリソースを確立します。

1. アプリケーションテンプレートの確認または作成（必須）：HCL をインポートする前に、検出した ADC スペースに親となるアプリケーションテンプレートリソースが存在することを確認する必要があります。

   • 存在の確認：gcloud design-center spaces application-templates describe <template_id> --space=<space_id> --project=<project_id> --location=<location> を実行し、テンプレートが存在するか確認します。

   • 存在しない場合は作成：describe コマンドが NOT_FOUND エラーを返した場合は、次のコマンドを実行して、先にテンプレートリソースを作成します。

     gcloud design-center spaces application-templates create <template_id> --space=<space_id> --project=<project_id> --location=<location> --display-name="<Name>" --description="<Description>"
     

2. 厳格な HCL パーサー制約（重大）：インポート操作を呼び出す前に、ローカル HCL が ADC レジストリの厳格な取り込みルールに準拠していることを確認します。

   • 純粋モジュールポリシー（リソースブロックなし）： ADC パーサーは、インポートする HCL 内の resource ブロックを一切禁止しています。使用できるのは module、variable、output、provider ブロックのみです。リソースが必要な場合（例：Private Service Access のピアリング）に、カタログに登録された単独のモジュールがない場合は、既存の登録済みモジュール内で組み込み設定オプションとしてサポートされているか必ず確認してください（例：module "vpc" 内で private_service_access_config を設定する）。
   • 厳密な文字列型指定： ADC パーサーは、ブール値から文字列への暗黙的な型変換を行いません。たとえば、サブネットのプライベートアクセスはリテラル文字列として宣言する必要があります。subnet_private_access = "true" のように指定し、ブール値の true は使用しないでください。
   • Terraform ブロックなし： パーサーは terraform {} のバージョン制約ブロックを厳密に禁止しています。providers.tf または main.tf から完全に省略してください。

3. ADC テンプレートへのインポート：テンプレートリソースの存在を確認し、上記の制約に照らして HCL を検証したら、ホストされている application_design_center:manage_application_template MCP ツールを APPLICATION_TEMPLATE_OPERATION_IMPORT_IAC オペレーションで呼び出します。

   • 引数：

     • project：対象プロジェクト ID。

     • location：GCP デプロイリージョン（例：us-central1）。

     • spaceId：検出した ADC スペース ID。

     • applicationTemplateId：アプリケーションテンプレートの一意な名前。

     • operation：APPLICATION_TEMPLATE_OPERATION_IMPORT_IAC

     • iacModule：ファイルリストを含む構造化オブジェクト：

       {
         "files": [
           { "name": "main.tf", "content": "<content of main.tf>" },
           { "name": "variables.tf", "content": "<content of variables.tf>" },
           { "name": "terraform.tfvars", "content": "<content of terraform.tfvars>" }
         ]
       }
       

   • 耐障害性と再試行（必須）：

     • 一時的なエラー（例：502 Bad Gateway、504 Gateway Timeout、429 Rate Limit）が原因で IMPORT_IAC の呼び出しに失敗した場合、すぐに再試行しないでください。
     • ジッターを加えた指数バックオフを使用してください（例：2 秒、4 秒、8 秒に加えて、1 秒未満のランダムな時間だけ待機）。
     • 再試行前にリビジョンを確認：タイムアウトが発生した場合は、まず gcloud alpha design-center spaces application-templates describe を呼び出し、インポートがバックグラウンドで実際に成功したかを確認してください。テンプレートが更新されていない場合に限り、再試行してください。

4. テンプレート URI の取得：成功すると、スペース内にテンプレートリソースが作成されます。次のパターンで applicationTemplateUri を構築してください。 projects/{project}/locations/{location}/spaces/{spaceId}/applicationTemplates/{applicationTemplateId}

---

フェーズ 4：アプリケーションのデプロイとモニタリング

目標：検証済みでベストプラクティスに準拠したアプリケーションテンプレートを GCP 環境にデプロイします。

1. アプリケーションのデプロイ：ホストされた application_design_center:manage_application MCP ツールを APPLICATION_OPERATION_DEPLOY オペレーションで呼び出します。
   • 引数：
     • project：対象プロジェクト ID。
     • location：対象のデプロイ先ロケーション。
     • spaceId：対象スペース ID。
     • applicationId：デプロイするアプリケーションインスタンスの一意の ID。
     • applicationTemplateUri：フェーズ 3 で確定した URI。
     • serviceAccount：デプロイ用サービスアカウント。
   • レジリエンスと再試行（必須）：
     • DEPLOY オペレーションが一時的なネットワークエラーまたはゲートウェイエラー（例：502、504）で失敗した場合は、再試行する前にジッターを伴う指数バックオフを適用します。
     • デプロイ LRO がタイムアウトした場合、または状態の競合で失敗した場合は、gcloud design-center spaces applications describe を使用してアプリケーションのステータスを確認してからデプロイ呼び出しを再試行し、同時に実行される競合したデプロイを回避します。
2. LRO の積極的なモニタリング：
   • ツールは長時間実行オペレーション（LRO）を返します。デプロイが開始されたことをユーザーに伝えます。
   • デプロイ状況のポーリング中はスリープしないでください。コマンド gcloud design-center operations describe <operation_name> を使用して、done: true になるまで 30～60 秒ごとに LRO を積極的にポーリングします。
3. 結果の処理：
   • 成功：done が true で、error フィールドがない場合は、フェーズ 6 に進みます。
   • 失敗：error フィールドがある場合は、エラーの種類を分析してフェーズ 5 に進みます。

---

フェーズ 5：デプロイの失敗をトラブルシューティングする

目標：専用のトラブルシューティングスキルと確立されたクラウド解決パターンを使用して、デプロイの失敗を段階的に診断し、修正します。

1. 反復的なクラウド解決パターン（重要）：デプロイが REVISION_FAILED または TERRAFORM エラーで失敗した場合は、次のような一般的なリソース競合がないか確認します。

   • サービスアカウントの 409 競合（alreadyExists）：モジュールが生成したサービスアカウント（例：frontend-service-us-central-sa）がプロジェクト内にすでに存在するためにデプロイが失敗する場合は、サービスアカウントの作成を無効にし、既存のアカウントを参照するようにローカルの HCL を修正します。

     create_service_account = false
     service_account        = "<existing_service_account_email>"
     

   • コンテナイメージの 404 NotFound：コンテナイメージが見つからないためにデプロイが失敗する場合は、イメージがレジストリに存在することを確認します。テストや hello-world のデプロイには、Google 公式のパブリック hello-world イメージを使用します。 us-docker.pkg.dev/cloudrun/container/hello

2. トラブルシューティングスキルに委任する：デプロイが失敗し、上記のパターンに該当しない場合は、専用の infra-deployment-debugging スキル（infra-deployment-debugging にあります）を呼び出して実行します。

3. トラブルシューティングのコンテキストを選択する：

   • ローカル検証エラーの場合（フェーズ 1／2）：トラブルシューティングスキルの ケース B：生の Terraform デプロイの手順に従い、構文、コンパイル、プラン作成時の検証エラーを切り分けます。
   • クラウドデプロイの失敗の場合（フェーズ 4）：トラブルシューティングスキルの ケース A：ADC アプリケーションのデプロイの手順に従い、LRO エラーを分析し、サービスログを取得して、クラウド環境の問題を診断します。

4. ローカル優先で修正する：

   • トラブルシューティングスキルの修正ガイドに従って、解決策を作成します。

   • 必須：スクラッチディレクトリ内のローカル HCL ファイルに直接修正を適用し、ローカル検証を再実行して HCL を再インポートし、新たなデプロイを開始します。

   • フェーズ 1 のローカル検証とプランのエクスポートを再実行します。

     terraform validate && terraform plan -out=tfplan && terraform show -json tfplan > tfplan.json
     

   • プランの評価（フェーズ 2）を再実行し、新たな違反が発生していないことを確認します。

   • 修正した HCL を APPLICATION_TEMPLATE_OPERATION_IMPORT_IAC を使用して ADC に再インポートします。

   • APPLICATION_OPERATION_DEPLOY を使用して新たなデプロイを開始します。

5. 反復回数の上限：トラブルシューティング、検証、インポート、再デプロイのサイクルを最大 5 回繰り返します。それでも失敗する場合は、すべての履歴と診断情報をユーザーに報告します。

---

フェーズ 6：検証と E2E テスト

目標：デプロイ済みのサービスが正常に動作し、完全に機能することを確認します。

1. デプロイ済みリソースを取得する：ホストされている application_design_center:manage_application MCP ツールを APPLICATION_OPERATION_GET オペレーションとともに呼び出し、リソースの詳細、公開エンドポイント、出力パラメータを取得します。
2. ヘルスチェック：すべてのサービスが正しいコンテナイメージ URL を使用し、実行時のステータスが正常であることを確認します。
3. E2E 検証：簡単なデモテスト（公開 HTTP エンドポイントの確認やドライラン取引の実行など）を行い、E2E 機能を確認します。タスクの完了にあたり、結果と公開 URL をユーザーに提示します。

問題の報告

このスキルのバグや改善点は、Google Skills Issues で報告してください。