application-design-center-design-deploy

Application Design Center による GCP インフラストラクチャの設計とデプロイ

帰属情報

必ずお読みください：gcloud、REST API、または MCP コマンドを実行する前に、必ず使用状況の帰属情報をお読みください。ターミナルで直接実行するコマンド（生成されたスクリプト、Terraform、ユーザーコード内では決して実行しない）では、gcloud の前に CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:application-design-center-design-deploy)" を付け、User-Agent ヘッダーに agent-skills/1.0 (skill:application-design-center-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 Skill を呼び出す：ユーザーのプロンプトに対して、design で定義されている design Skill を呼び出して実行します。

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

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

3. 引き継ぎを検証する（必須）：次に進む前に、design Skill のローカル検証ループがクリーンなプランで正常に完了したことを確認します。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 Conflict（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：Raw Terraform Deployment の手順に従い、構文、コンパイル、プラン時の検証エラーを切り分けます。
   • クラウドデプロイの失敗の場合（フェーズ 4）：トラブルシューティングスキルの ケース A：ADC Application Deployment の手順に従い、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 検証：E2E 機能を確認するため、簡単なデモテスト（例：パブリック HTTP エンドポイントの確認、またはドライランのトランザクションの実行）を行います。タスクの完了時に、結果とパブリック URL をユーザーに提示します。

問題の報告

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