google-cloud-recipe-onboarding

Google Cloud のオンボーディング

このスキルでは、個人の開発者が Google Cloud を使い始めるための、簡潔で非対話型の「ハッピーパス」を提供します。環境の確認や認証から、プロジェクトの選択、請求先アカウントのリンク、後続の安全対策の適用までを網羅しています。

クレジット表記

このスキルを使用してコマンドを実行する際に必要な gcloud CLI、REST API、MCP のクレジット表記については、 Usage Attribution の手順に従ってください。

重要

このスキルを実行する自律型エージェントの場合：

1. 変更前の監査：プロジェクトや請求先に関する変更を提案または実行する前に、必ず実行前の状態を目立たない形で監査してください。
2. 質問は一度に1つ：対話形式で実行する際は、一度に尋ねる運用上のパラメーターまたは確認事項を必ず1つだけにしてください。
3. 非対話型の出力：すべての変更コマンドに非対話型のオーバーライド（--quiet、--format="json"）を追加し、決定論的で機械解析可能な出力を保証するとともに、ターミナルのハングを防いでください。
4. 最初のターンの対話ルール（トリガーターン）：開発者が一般的なオンボーディングの依頼（例：「Google Cloud を使い始めたい」）で初めてこのスキルを呼び出した場合：
   • 事前案内：Google Cloud アカウントの作成を案内する短い説明をあらかじめ含め（コンソールの https://console.cloud.google.com/ を案内してください）、すでにログイン済みと思われる場合でも、ワークステーションを認証するために gcloud auth login を実行するよう開発者に伝えてください。
   • 最初のターンでの質問は1つだけ：実行前の監査は目立たない形で行いますが、最初のターンではパラメーターの完全なサマリーテーブルを提示したり、最終確認を求めたりしないでください。代わりに、開発者に最初の運用上の質問を必ず1つだけ尋ねてください（例：「既存のアクティブなプロジェクトを再利用しますか、それとも新しいプロジェクトを作成しますか？」）。 注：開発者の最初のプロンプトで「オンボーディングの設定を承認します」「オンボーディングを進めましょう」と明示的に述べている場合、またはドライラン計画（例：「正確な計画またはドライラン用のコマンドを見せてください」）を求めている場合は、一般的な事前案内と最初の質問を省略し、要求された手順に直接進んでください。

---

概要

個人の開発者が Google Cloud を利用開始する際は、ローカルのターミナルツールを確認し、認証済みセッションを確立して、ワークスペース（プロジェクト）を選択または作成し、有効な請求先アカウントにリンクします。Google Cloud では、無料枠に加えて、初回利用者向けに300ドル分のクレジットが付与される無料トライアルを提供しています。詳しくはこちら。

---

前提条件

• 個人の Google アカウント（例：@gmail.com）または Google Workspace／Cloud Identity アカウント。
• 有効な支払い方法（クレジットカードまたは銀行口座）。これは本人確認と、概要で紹介した300ドル分の無料トライアルクレジットを有効にするために必要です。

---

手順

セクション1：ホストツールのセットアップを確認する

入力を求めたり変更を提案したりする前に、ホストシステムで有効なツールと環境の状態を目立たない形で監査してください。

1. gcloud CLI バイナリがインストールされ、アクセス可能かどうかを確認します。

   which gcloud
   

2. 認証済みのアクティブな ID セッションがあるかどうかを確認します。

   gcloud auth list --format="json"
   

3. 実行前の監査で which gcloud が有効なパスを返した場合は、セクション2「セッションを認証してルーティングする」に直接進みます。

4. バイナリが見つからない場合は、実行を中止し、gcloud スキルを使用して gcloud をインストールするようエージェントに指示します。認証の設定手順については、公式のGoogle Cloud CLI インストールガイドを開発者に案内してください。

---

セクション 2：認証とセッションのルーティング

開発者の Google アカウントを使用して、gcloud CLI に Google Cloud へのアクセスを許可し、そのアカウントが単独での開発者オンボーディングに適していることを確認します。

1. 認証情報の認証を実行する：

   gcloud auth login
   

   重要

   新規ユーザー／未認証ユーザー向けのガイダンス： 実行前の状態監査またはコマンドの失敗から、開発者が未認証であることが確認された場合（例：gcloud auth list が空、または有効な認証情報が存在しない場合）：

   1. Google Cloud Console に移動して、Google Cloud アカウントを作成するよう案内します。
   2. ローカルのワークステーションのターミナルセッションを認証するために、gcloud auth login コマンドを実行するよう指示します。
   3. 認証が正常に完了するまで、プロジェクトの作成やリソースの設定を試みないでください。

2. アクティブな ID を確認する：

   gcloud config get-value account --format="json"
   

3. プログラムによるエンタープライズルーティングのガードレール： 続行する前に、アカウントが企業組織に紐づいているかどうかを確認します。エンタープライズ環境では、異なるアーキテクチャに従う必要があります。

   gcloud organizations list --format="json"
   

   • 新規の Free Trial アカウントには、自動的に Self-Owned Organization（SOO）が付与される点に注意してください。個人の Free Trial アカウントとエンタープライズ組織を区別するには、JSON 出力を確認します。
     • エンタープライズ組織（実行を中止）：出力リストに owner.directoryCustomerId が存在する組織ノードが含まれている場合（ドメインが確認済みの Google Workspace または Cloud Identity 組織であることを示します）、またはユーザーのプロンプトで企業のランディングゾーンやマルチテナントのプロジェクト構成が明示されている場合：
       • このスキルの実行を直ちに中止します。
       • 開発者を公式のGoogle Cloud Setup ガイド付きフローに案内します。
     • 個人アカウント／Free Trial SOO（続行）：出力リストが空の [] である場合、または Self-Owned Organization（owner.directoryCustomerId がなく、displayName が確認済みドメイン名ではないもの）が含まれている場合は、「セクション 3：Google Cloud プロジェクトの選択または作成」に進みます。

---

セクション 3：Google Cloud プロジェクトを選択または作成する

Google Cloud リソースは プロジェクト 単位で管理されます。開発者がコンソールから無料トライアルに申し込むと、Google Cloud によってデフォルトのプロジェクト（例：「My First Project」）が自動的に作成されます。既存のプロジェクトを再利用し、トークンを浪費する競合エラーを防ぐため、まず現在の環境を必ず確認してください。

1. バックグラウンドでのプロジェクト検出： 利用可能なアクティブなプロジェクトを一覧表示します（コンテキストウィンドウの超過を防ぐため、数を制限します）。

   gcloud projects list --filter="lifecycleState=ACTIVE" --limit=20 --format="json"
   

2. 既存のプロジェクトを再利用する（推奨）： 一覧にアクティブなプロジェクトがあれば、開発者に提示し、デフォルトの作業プロジェクトとして設定することを提案します。

   gcloud config set project {PROJECT_ID} --quiet
   

3. カスタムプロジェクトを作成する： プロジェクトが存在しない場合、または開発者が新しいワークスペースを明示的にリクエストした場合：

   • 開発者にカスタムの PROJECT_ID と PROJECT_NAME を尋ねます（質問は一度に 1 つまで）。

   • 構造化された確認と同意のゲート（必須）： プロジェクト作成または課金の関連付けに関するコマンドを実行する前に、エージェントは対象パラメーターをまとめた構造化された Markdown テーブルを必ず提示します。

     パラメーター	値
     対象プロジェクト ID	{PROJECT_ID}
     対象プロジェクト名	{PROJECT_NAME}
     アクティブな ID アカウント	{ACCOUNT}
     対象の課金アカウント ID	{BILLING_ACCOUNT_ID}

     ユーザーに次の同意確認をそのまま尋ねます。 "Google Cloud プロジェクトを初期化し、課金を関連付ける準備ができました。続行してもよろしいですか？"

     重要：このターン中に、エージェントは gcloud projects create または課金の関連付けコマンドを実行してはいけません。このテーブルを表示し、同意確認をそのまま尋ねた後、ユーザーの肯定的な回答を待つために必ず停止してください。

   • プロジェクト ID の競合時のサフィックス復旧：PROJECT_ID がグローバルで既に使用されているためプロジェクト作成コマンドが失敗し（PROJECT_ID_COLLISION または ALREADY_EXISTS エラーが返された場合）：

     • 4 桁のランダムなサフィックスを自動的に追加します（例：my-project を my-project-8472 に変更）。
     • この新しい利用可能なプロジェクト ID を開発者に提案し、再試行する前に改めて同意を求めます。

   • プロジェクトの作成を実行する：ユーザーの明示的な同意を確認した後、次を実行します。

     gcloud projects create {PROJECT_ID} --name="{PROJECT_NAME}" --quiet --format="json"
     

   • アクティブな作業プロジェクトを設定します。

     gcloud config set project {PROJECT_ID} --quiet
     

---

セクション 4：課金を確認して関連付ける

Google Cloud にリソースをデプロイするには、プロジェクトをアクティブな Cloud Billing アカウントに関連付ける必要があります。

1. 課金ステータスを確認する： アクティブなプロジェクトが既に課金アカウントに関連付けられているか確認します。

   gcloud billing projects describe {PROJECT_ID} --format="json"
   

2. 出力に "billingEnabled": true が含まれている場合は、関連付けを省略して、直ちにセクション 5「スキルチェーン（支出制御とワークロード）」に進みます。

3. 利用可能な課金アカウントを検出する： プロジェクトが関連付けられていない場合は、認証済みユーザー ID に関連付けられた利用可能な課金アカウントの識別情報を照会します。

   gcloud billing accounts list --format="json"
   

4. 課金アカウントを関連付ける： 検出された課金アカウント ID へのプロジェクトの関連付けを提案し、次を実行します。

   gcloud billing projects link {PROJECT_ID} --billing-account={BILLING_ACCOUNT_ID} --format="json"
   

---

セクション 5：スキルの連携（支出管理とワークロード）

オンボーディングの設定が完了しました。環境を保護し、ワークロードをデプロイするには、後続の専門スキルを連携できます。

1. 請求の支出管理： 意図しないコスト超過を防ぐため、請求を自動的に無効化するプログラム制御の設定をご検討ください。請求を無効にすると、プロジェクト内のすべての Google Cloud サービスと利用が終了し、それ以上のコストが発生しなくなります。

• 費用がプロジェクトの予算を超えたときに請求を自動的に停止する方法が詳しく説明されている、公式の通知を使用した請求利用の無効化ガイドを開発者に案内してください。

2. ワークロードのデプロイ：最初のリソースをデプロイするには、対象アプリケーションに対応する後続の専門スキル（例： cloud-run-basics または bigquery-basics）を実行します。専門スキルがローカルで利用できない場合は、 Cloud Run コンテナのデプロイに関するクイックスタートなど、該当する公式クイックスタートを開発者に案内してください。 注：後続の専門スキルはそれぞれ、実行中に必要なサービス API（例： run.googleapis.com）を動的に有効化する責任を負います。

---

検証ロジック

オンボーディングの手順を完了した後、以下の診断コマンドを使用して、環境の状態が整っていることをプログラムで検証します。

1. CLI のインストールを確認：

   which gcloud
   

2. 認証済みの ID を確認：

   gcloud config get-value account
   

3. プロジェクトのワークスペースの存在を確認：

   gcloud projects describe {PROJECT_ID} --format="json"
   

4. 請求のリンクを確認（JSON 出力に "billingEnabled": true が含まれていることを確認）：

   gcloud billing projects describe {PROJECT_ID} --format="json"
   

---

追加リソース

• Google Cloud の利用開始ページ
• Google Cloud の概要
• Google Cloud 無料プログラム
• Google Cloud セットアップの概要
• Google Cloud セットアップ：本番環境向けの高度な基盤
• 利用状況の帰属：gcloud CLI、REST API、MCP リクエスト向けの標準化された利用状況の帰属タグです。