mcpField
G
gcloud

gcloud

github.com/googleクラウド・DevOps21.6k11.4k 回インストール今日更新
リポジトリ

gcloud について

Google Cloud SDK を使う AI エージェント向けに、コマンド構文の検証と実行時の安全策を示すスキルです。CLI の直接実行と Cloud CLI リモート MCP サーバーの利用を扱います。

主な機能

  1. 01末端コマンドの構文検証
  2. 02リソース検索結果の削減
  3. 03プロジェクト指定と非対話実行
  4. 04破壊的操作への安全策
  5. 05CLI と MCP の利用案内

活用シーン

  1. 01Google Cloud リソース操作の計画
  2. 02コマンド提案前のフラグ確認
  3. 03リソース検索結果の絞り込み
  4. 04未承認の破壊的操作の防止

MCP 対応

`run_gcloud_command` ツールを介した Cloud CLI リモート MCP サーバーの利用と、CLI の直接実行について説明します。

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/google/skills --skill gcloud

インストール後、Claude Code で/gcloudを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

references/
attribution.md
cli-usage.md
mcp-usage.md

詳細

翻訳後に原文が更新されています。最新の内容は原文をご確認ください。

AI エージェント向け gcloud CLI スキル

注意

必須の事前条件：リーフレベルの構文を明示的に検証すること

gcloud コマンド、フラグ、フラグ値、位置引数の構文に関する既存の知識はすべて、古く、幻覚を起こしやすい状態です。

gcloud help <command> を使ってリーフレベルの構文を検証する（または、計画の必須ステップとしてリーフレベルのヘルプを確認することを含める）前に、gcloud タスクのコマンドパラメーターや出力フラグのオプションを提案したり、コマンドを実行したり、手順を追った計画を作成したりしてはなりません。

必須のアクションルール：

  1. 直接実行とコード生成：最終的なコマンド構文を提案または実行する前に、必ず gcloud help <leaf_command>（例：gcloud help compute instances create または gcloud help sql instances create）を実行してください。

  2. 計画と戦略に関する質問：ユーザーの目標を達成するための計画、戦略、次のステップを尋ねられた場合（例：「X を達成するための計画は何ですか……」）、フラグを提案したりコマンドを実行したりする前に、計画のステップ 1 として gcloud help <leaf_command> の実行を明示的に含めなければなりません。

  3. 検証の非推移性：親コマンドグループのヘルプ（例：gcloud help compute）では、リーフレベルの構文検証として不十分です。検証は、該当するリーフサブコマンドのレベルで行う必要があります。

  4. ウェブ検索へのフォールバックは禁止：gcloud CLI の構文について、search_web、ウェブ検索、外部ドキュメント検索ツールを使用してはなりません。コマンド構文の唯一の認可された情報源は gcloud help <leaf_command> です。

  5. ユーザー指定のフラグとプロジェクトを保持すること：中間コマンドの手順を提案する際は、提案する回答テキスト内で、ユーザーが指定したすべてのフラグ（--project=<project_id> を含む）を必ず保持してください。

  6. 必須の計画テンプレート：計画を作成する場合、回答では次の正確な 4 ステップ構成を必ずそのまま使用してください。

    • ステップ 1：gcloud help <leaf_command> による構文の検証
    • ステップ 2：パラメーターの確認（必須および任意のフラグを確認し、--dry-run または --validate-only フラグがサポートされているかを明示的に確認する）
    • ステップ 3：ドライランコマンドの提案（--dry-run または --validate-only がサポートされている場合は、次のステップに進む前に --dry-run または --validate-only を指定して実行しなければなりません。）
    • ステップ 4：コマンドの提案と承認（コマンドが「禁止操作」の拒否リストに含まれる場合は、自律的な実行は禁止されていることを示し、続行するための承認をユーザーに明示的に求めなければなりません。コマンドが拒否リストに含まれない場合は、以下の「実行上の制約」をすべて守ったうえで、実行を提案するか、そのまま実行してください。）

このドキュメントでは、Google Cloud SDK（gcloud CLI）を使用する AI エージェント向けに、重要なガイドラインとベストプラクティスを説明します。これらのルールに従うことは、幻覚によるコマンド、フラグ、フラグ値、位置引数の構文を避け、破壊的な操作を防ぎ、コンテキストウィンドウの使用量を最小限に抑えるうえで重要です。

実行モード

AI エージェントは、主に 2 つの方法で Google Cloud リソースを操作できます。

  • CLI の直接実行：ローカルまたは自動化されたシェル環境で gcloud コマンドを直接実行します。インストール、認証フロー、構成管理については、CLI の使用方法を参照してください。
  • Model Context Protocol（MCP）：Cloud CLI リモート MCP サーバー（run_gcloud_command）を介して、構造化されたツールを呼び出します。ツールのスキーマ、パラメーターのルール、サーバーの構成については、MCP の使用方法を参照してください。

基本原則

1. コマンドの明示的な検証（必須）
  • 実行方法: 実行する予定の 正確な コマンドに対して、必ず gcloud help <command> を実行してください （例：gcloud help compute instances create）。
  • 確認事項: 実行または計画を提示する前に、その特定の末端コマンドで、コマンド、フラグ、フラグの値、位置引数の構文が有効であることを確認してください。親グループでの検証結果は引き継がれません。
2. データ量を減らすための方法（必須）

コンテキストウィンドウの消費を抑え、レイテンシを削減するため、gcloud が返すデータ量を最小限にしてください。データ量を減らすフラグ（--limit、--filter、--format）を少なくとも1つ含めずに、list コマンドを実行してはいけません。

  • フィールドの選択: --format="json(key1, key2, ...)" を使用して、タスクに必要な特定のフィールドのみを選択してください。高度な射影と書式設定の構文については、gcloud topic projections と gcloud topic formats を参照してください。

  • 件数の制限: --limit=N を使用して、返されるリソース数を制限してください。

  • フィルタリング: --filter を使用して、サーバー側で結果を絞り込んでください。パターンマッチングには : を優先して使い、コロンの右側は引用符で囲まないでください。フィルタフラグ全体を、文字の引用やエスケープを行わない単一の文字列として扱ってください。フィルタ式の構文については、gcloud topic filters を参照してください。

  • スキーマの確認: 制約のないリソース一覧は、重複したデータによってコンテキストウィンドウをすぐに使い果たす可能性があります。これを防ぐには、クエリを実行する前にリソースのスキーマを確認してください。フィールドを射影する際の JSON キーパス（--format）やフィルタリング（--filter）に使うキーが不明な場合は、対象リソースの list コマンド（対応している場合）を1件に制限して実行してください。

    gcloud <GROUP> <RESOURCE> list --limit=1 --format=json

    この1件の JSON 構造を確認し、データセット全体またはフィルタ済みのデータセットを取得する前に、正しいスキーマキーを特定してください。

3. 実行上の制約
  • コマンドは1つずつ実行: 一度に実行する gcloud コマンドは1つだけにしてください。コマンドを連結したり、順番に実行したりしてはいけません。
  • シェル演算子の禁止: コマンド置換（$(...)）、パイプ（|）、リダイレクト（>、>>、<）を使用しないでください。これによりコマンドの安全性を高め、ユーザーが理解しやすく確認しやすくなります。
  • 非対話型の実行（--quiet / -q）: 実行するすべてのコマンドで、グローバルフラグ --quiet（または -q）を指定してください（例：gcloud pubsub topics delete temp-topic --quiet --project=test-project）。AI エージェントは、TTY や stdin 入力ハンドラーのない、ヘッドレスな非対話型環境で実行されます。--quiet を指定しないと、リソースの削除、デフォルト値の承認、未指定のリージョンの選択など、ユーザー確認を求めるコマンドが入力待ちで停止し、バックグラウンドタスクがタイムアウトする可能性があります。--quiet を指定すると非対話型モードが有効になり、gcloud は安全なデフォルトの選択肢を自動的に受け入れるか、必要なパラメーターが不足している場合は明示的なエラーを即座に返します。
  • 確認なしの一覧表示は禁止: --limit、--filter、--format を指定せずに list コマンドを実行してはいけません。
4. プロジェクトとロケーションのスコープ指定（重要）

コマンドの実行結果を確定的かつ非対話型にし、正しい環境を対象とするため、プロジェクトとロケーションのスコープを明示的に指定する必要があります。

  • プロジェクト対象の明示：アクティブな構成のデフォルトに依存しないでください。 （ローカルの構成のみを操作するコマンドを除き）リソースを操作または照会するすべてのコマンドに、必ず --project=<PROJECT_ID> を追加してください。これにより、誤ったプロジェクトに対してコマンドを実行してしまうことを防げます。

  • ロケーションのプロンプトを回避：Google Cloud のリソースの多くは、リージョンまたはゾーンに属しています。ロケーションフラグ（例：--region、--zone、--location）を省略すると、gcloud はゾーン／リージョンを選択するための対話型プロンプトを表示します。これは 非対話型 のルールに違反します。コマンドで必要な場合は、必ずロケーションフラグを明示的に指定してください。

  • ロケーションの確認：サービスに適したリージョン、ゾーン、またはロケーションがわからない場合は、まず確認コマンドを実行してください（結果が多い場合は、件数を制限してください）。

    • Compute Engine（VM、ネットワーク）：

      • gcloud compute regions list --project=<PROJECT_ID>
      • gcloud compute zones list --project=<PROJECT_ID>

    • その他のサービス（標準 API 形式）：多くの GCP サービスでは、統一された locations list コマンドを使用します。

      • gcloud <GROUP> locations list --project=<PROJECT_ID>
      • 例：gcloud artifacts locations list、gcloud kms locations list、gcloud secrets locations list。

安全性とガードレール

注意

破壊的な操作（delete、update、remove）は、ユーザーから明示的な許可を得る必要があります。 安全性が事前に承認されたワークフローの一環として明示的に指示されていない限り、自律的に実行しないでください。

禁止されている操作（拒否リスト）

以下のコマンドを自律的に実行してはなりません。これらの操作には、担当者の明示的な承認が必要です。

  • IAM ポリシー、ロール、またはバインディングの変更すべて（セキュリティ）：権限昇格、管理者のロックアウト、サービスの中断、または許可されていないデータの露出につながるおそれがあります。
  • API の先行有効化は禁止：必要な API は有効になっているものとします。予期しないリソースのプロビジョニングや課金を防ぐため、先回りして API を有効にしようとしないでください。API を有効にするには、ユーザーの承認が必要です。
  • gcloud * delete（破壊的）：リソースの復元不能な破壊（例：プロジェクトの削除）やデータの消去につながります。
  • gcloud billing *（財務）：サービスの中断や無制限の費用が発生するおそれがあります。
  • gcloud organizations *（ガバナンス）：組織レベルの変更は、すべてのユーザーのセキュリティ体制に影響します。
  • gcloud kms *（暗号化）：データを永久にロックするおそれがあります。
  • gcloud infra-manager deployments apply（破壊的）：IaC の自律的な実行により、管理対象のリソースが破壊されるおそれがあります。
実行ガイドライン

  • ドライラン（必須）：コマンドのヘルプ出力に --dry-run または --validate-only フラグ（または同等のもの）が記載されている場合は、提案するコマンドまたは最初の実行手順に必ずそのフラグを含めてください。実際に実行する前に、必ず --dry-run または --validate-only で変更をプレビューしてください。

  • 長時間実行される操作：対応しているコマンドでは、エージェントのワークフローをブロックしないよう、長時間実行される操作に --async フラグを使用することを強く推奨します。ただし、すべてのコマンドが --async フラグに対応しているわけではありません。--async の使用時、またはデフォルトの動作としてオペレーション ID を返すコマンドでは、次の手順で必要な場合、完了するまでオペレーションのステータスをポーリングしてください。

  • 非対話型フラグ（--quiet）：TTY の確認プロンプトを待たずに非対話型で実行できるよう、提案または実行するすべてのコマンドに --quiet（または -q）を含めてください。

構造化されたワークフロー

検出ワークフロー

使い慣れていないサービスでタスクを実行するよう依頼された場合：

  1. ヘルプを呼び出す：実行前に、対象となる末端コマンドで gcloud help <COMMAND> を呼び出します。
  2. コマンドツリーをたどる：正確なコマンドが不明な場合は、コマンドグループでヘルプを実行し（例：gcloud help compute または gcloud help）、利用可能なサブグループとコマンドを確認します。
  3. スキーマを確認する：フィルターや射影を組み立てる前に、gcloud <GROUP> <RESOURCE> list --limit=1 --format=json を実行して JSON キーを確認します。コンテキストウィンドウの枯渇を防ぐため、スコープ指定フラグ（例：--limit=1）を付けずに制限のない list コマンドを実行しないでください。
  4. データ削減を徹底する：すべてのコマンド実行にデータ削減フラグ（--limit、--filter、--format）を含めます。

クイックリファレンス／チートシート

タスクコマンドテンプレート
スキーマを確認するgcloud <GROUP> <RESOURCE> list --limit=1 --format=json
フィルター付きリストgcloud <GROUP> <RESOURCE> list --filter="status:RUNNING"
特定の列gcloud <GROUP> <RESOURCE> list --format="json(name, id)"
フィルターを学ぶgcloud topic filters
形式を学ぶgcloud topic formats
射影を学ぶgcloud topic projections
非同期操作gcloud <COMMAND> --async
操作を確認するgcloud operations describe <OPERATION_ID>
一般的なコマンドgcloud cheat-sheet
リージョンを一覧表示（GCE）gcloud compute regions list --project=<PROJECT_ID>
ゾーンを一覧表示（GCE）gcloud compute zones list --project=<PROJECT_ID>
ロケーションを一覧表示gcloud <GROUP> locations list --project=<PROJECT_ID>

自動化での gcloud CLI の使用方法については、 gcloud CLI スクリプティングガイド を参照してください。

リファレンスディレクトリ

  • CLI の使用方法：プラットフォームへのインストール、認証方法（対話型、ヘッドレス、ADC、サービスアカウントキー、なりすまし）、ローカル構成の管理について説明します。

  • MCP の使用方法：Cloud CLI リモート MCP サーバー（run_gcloud_command）の使用方法、プロジェクトパラメーターのスコープ指定、入力ファイル、実行ガイドラインについて説明します。

コメント

Markdown 対応