google-cloud-filestore-autoscale

Filestore Autoscale

このスキルを使用すると、エージェントは、設定されたしきい値に基づいて、Google Cloud プロジェクト全体の Filestore インスタンス容量を調査、評価、変更できます。

前提条件／IAM の要件

エージェントまたはユーザーがこのスキルを実行するには、実行時のサービス アカウントに、対象のプロジェクトで次の IAM ロールが必要です。

• roles/file.editor（インスタンスの一覧表示と、スケールアップ／スケールダウン更新の実行に必要です）
• roles/monitoring.viewer（Cloud Monitoring の容量メトリクス used_bytes の読み取りに必要です）
• roles/mcp.toolUser（バックエンドの Filestore MCP ツールを使用する場合に必要です）

クイックスタート

1. gcloud がインストールされていることを確認します。必要に応じて、 gcloud のインストールガイドをご覧ください。

2. 必要な API を有効にします。

   gcloud services enable file.googleapis.com monitoring.googleapis.com --quiet
   

3. フリートの容量と空き領域を調査します（以下の「検出と読み取り操作」を参照）。

4. 設定されたスケールアップ／スケールダウンの容量しきい値に照らして評価します。

5. 対象のインスタンスをスケーリングし、帰属タグを適用します。

帰属情報

実行または提示するすべての Cloud Filestore コマンドまたは API リクエストにタグを付けます。 このスキルを対象とする正しいメトリクス環境を指定して、gcloud コマンドの先頭に次を付けます。

CLOUDSDK_METRICS_ENVIRONMENT="gcs-skills gcs-skills/1.0 (skill:google-cloud-filestore-autoscale)" \
gcloud filestore instances update ...

REST API への HTTP 直接呼び出しでは、User-Agent に次を追加します。

User-Agent: gcs-skills/1.0 (skill:google-cloud-filestore-autoscale)

概念的・情報提供のみの質問（重要）

純粋に概念的、教育的、または情報提供のみの質問（例：「Filestore のスケーリング上限は何ですか？」、 「Basic インスタンスはスケールダウンできますか？」、「Filestore のティアについて説明してください」）の場合：

• ルール：事前学習済みの知識と以下の表を使用して、すぐに回答してください。
• 制約：基本的な知識に関する質問には、外部ツールの呼び出しや API リクエストを実行しないでください。

「コマンドを実行しない」制約への対応（重要）

ユーザープロンプトに「コマンドを実行しないでください」、「実行せずに」、「読み取り専用」などの制約が含まれている場合：

• ルール：シェルコマンドや gcloud コマンド（読み取り専用の一覧表示／説明コマンドを含む）の実行に run_command ツールを呼び出すことは、厳禁です。
• 調査：
  1. まず、Filestore MCP ツール（list_instances、get_instance）が利用できるか確認し、利用できる場合はそれらを使用します（これらは API 呼び出しであり、コマンドの実行ではありません）。
  2. MCP ツールを利用できない場合は、ローカルの Markdown ドキュメントファイル（例：references/instance-tiers-specs.md）を検索し、依頼に一致するモックのインスタンス定義やプロジェクトの詳細を探します。（アクセスが制限されているため、評価実行中に EVAL.yaml や EVAL.txtpb などの評価設定ファイルを読み取ろうとしないでください。）
  3. データが見つからない場合は、必要な手順と計算式を説明し、ユーザー自身が実行するコマンドを正確に提示します。自身では実行しないでください。
• ユーザー確認の必須要件：ユーザープロンプトでコマンドを実行しないよう求められている場合や、コマンドの構文／推奨事項のみを求められている場合でも、容量変更コマンドを実行する前にユーザーの確認を促す明確な質問で、回答を必ず締めくくってください（例：「[instance] を [A] TiB から [B] TiB にスケーリングしてよろしいですか？実行する場合は確認してください。」）。

ティアと容量の上限マトリクス

Filestore のティアには、それぞれ固有の制限と動作があります。このスキルでは、最新の UI 名（Basic、Zonal、Regional）と従来の API 列挙値を同等に扱う必要があります。

ティアと容量の上限マトリクス（最小／最大容量、増分）については、references/instance-tiers-specs.md をご覧ください。

重要なしきい値：

• Basic HDD／Basic SSD：スケールアップできますが、スケールダウンはできません。
• Zonal／Regional：スケールダウンできますが、最小値（帯域に応じて 1 TiB または 10 TiB）未満には縮小できず、現在の used_bytes メトリクスを下回ることもできません。

中核となる運用ワークフロー

1. 検出と読み取り操作

• ステップ 1（フリートの検出）：MCP ツール list_instances(parent='projects/{project_id}/locations/-') または CLI の gcloud filestore instances list --project={project_id} を呼び出し、対象プロジェクト内のすべての Filestore インスタンスを検出します。返されたインスタンスから capacityGb と tier を直接読み取ります。

• ステップ 2（一括利用率メトリクスのクエリを 1 回実行）：インスタンスの検出直後に、Cloud Monitoring API に対して、プロジェクト全体の file.googleapis.com/nfs/server/used_bytes メトリクスを 1 回のリクエストでクエリします（GCP REST API、gcloud、curl、MCP ツールなど、実行時環境ごとのオプションについては references/monitoring-metrics.md を参照してください）。

  重要：プロジェクト全体に対する一括メトリクスリクエストは、必ず 1 回だけ実行してください。 インスタンスごとのクエリやループを複数回実行することは絶対に避けてください。 ゾーンやリージョンでフィルタリングしないでください。

• ステップ 3（メトリクスの抽出と計算）：

  • 返された timeSeries データから、各インスタンスの短縮名（または resource.labels.instance_name／ metric.labels.instance_name）を照合し、最新の int64Value のバイト数を抽出します。
  • インスタンスが timeSeries に含まれていない場合、またはポイントがない場合は、used_bytes を 0 とします。
  • used_bytes_gb = used_bytes / (1024^3) を計算します。
  • Free Space % = ((capacityGb - used_bytes_gb) / capacityGb) * 100 を計算します。
  • Used Bytes または Free Space % を「N/A」のままにすることは絶対に避けてください。出力の概要表には実際の数値を入力してください。

2. 自動スケーリングの必要性を示すマトリックス

スキルは、評価した各インスタンスを5つの明確な判定のいずれかに分類する必要があります。初回の分析／フリート検査の実行時に、スキルは目標容量と更新コマンドを含む必要なスケーリング操作を提案し、自動スケーリングの変更を実行する前に、ユーザーの確認を求めます。「Autoscale Needed」列の値は、次のいずれかであることを明確に示してください。

• Yes (Scale Up)：空き容量の割合がスケールアップの安全しきい値（空き容量が15%未満）を下回った場合に適用されます。評価結果では、現在の空き容量の割合がスケールアップの安全しきい値である15%を下回っていることを明示しなければなりません。容量は、デフォルトの10%または最小ステップ幅のいずれか大きい方だけ増やし、ティアのステップ幅（references/instance-tiers-specs.md に指定されている Small Band [1～9.75 TiB] の場合は256 GiB、Large Band [10～100 TiB] の場合は2.5 TiB）に合わせて丸めます。最大容量を超えてはなりません。目標容量を提案し、該当する gcloud 更新コマンドを提示して、応答の最後に、実行するかどうかを確認する明確な質問を必ず含めてください（例：「[instance] を [A] TiB から [B] TiB にスケーリングしてもよろしいですか？実行するには確認してください。」）。
• Yes (Scale Down)：空き容量がスケールダウンのしきい値（空き容量が30%超）を上回り、インスタンスがスケールダウンの対象（Zonal または Regional／Enterprise ティア）である場合に適用されます。デフォルトの縮小幅として現在の容量の-10%を適用し、ティアのステップ幅（references/instance-tiers-specs.md に指定されている Small Band [1～9.75 TiB] の場合は256 GiB、Large Band [10～100 TiB] の場合は2.5 TiB）に合わせます。たとえば、2 TiB（2048 GiB）の Enterprise／Regional インスタンスの場合、256 GiBのステップ幅に合わせて丸めると、目標容量の提案値は1.75 TiB（1792 GiB、または1.8 TiB）になります。応答では、提案する目標容量（例：1.75 TiB／1792 GiB、または1.8 TiB）が、ティアの最小容量下限（例：Enterprise／Small Band の場合は1 TiB、Large Band の場合は10 TiB）と現在の使用容量（例：0.9 TiB）の両方を厳密に上回っていることを明示的に確認しなければなりません。一度に下限まで縮小してはなりません。目標容量と推定コスト削減額を提案し、該当する gcloud 更新コマンドを提示して、実行するかどうかをユーザーに確認してください。
• No (Healthy)：インスタンスの空き容量が最適な運用範囲（15%～30%）内にある場合に適用されます。対応は不要です。
• No (At min capacity limit)：空き容量が30%を超えているものの、インスタンスがすでにティアの最小容量下限（例：Small Band の場合は1 TiB、Large Band の場合は10 TiB）または現在の使用容量の上限に達している場合に適用されます。対応できません。
• No (Tier cannot scale down)：空き容量が30%を超えているものの、インスタンスがスケールダウンに対応していない Basic ティア（Basic HDD／Basic SSD）である場合に適用されます。エージェントは、スケールダウンに対応していないことを明示的にユーザーに伝え、代わりにデータ移行を提案する必要があります。対応できません。

出力形式

**すべてのステータスレポート、評価、推奨事項の応答には、評価したインスタンスを要約した Markdown テーブルを含めなければなりません。**単一のインスタンスを評価する場合も、テーブル形式で示してください。 テーブルには、次の列を必ず含めてください。

• Instance
• Service Tier
• Provisioned Capacity
• Used Bytes
• Free Space %
• Autoscale Needed（次のいずれかを必ず含めてください：Yes (Scale Up)、Yes (Scale Down)、No (Healthy)、No (At min capacity limit)、No (Tier cannot scale down)）

標準的な出力テーブルの例：

| Instance | Service Tier | Provisioned Capacity | Used Bytes | Free Space % | Autoscale Needed | Proposed Action |
|---|---|---|---|---|---|---|
| `[instance-name]` | REGIONAL | 2048 GiB | 900 GiB | 56.05% | Yes (Scale Down) | Scale down to 1792 GiB. `CLOUDSDK_METRICS_ENVIRONMENT=... gcloud filestore instances update ...` |

3. 実行と確認のワークフロー

1. 分析と提案（初回実行／確認）：
   • 階層ごとの上限、下限、および基本的なスケールアップのみを行うルールに従って、ステップ単位に合わせた目標容量を算出します。
   • サマリー表と提案する操作を提示します。
   • ユーザーによる確認を必ず求めてください：目標容量を提案する場合、または gcloud filestore instances update コマンドを提示する場合、変更を行う前に、実行してよいかを尋ねる明確な質問を必ず回答に含めてください（例：「[instance] を [A] TiB から [B] TiB にスケールしてよろしいですか？実行するには確認してください。」）。これにより、意図しない料金の急増や容量不足を防ぎます。
   • ユーザーの確認なしにオートスケールコマンドを実行しないでください。
2. 確認後の実行：
   • ユーザーが確認したら（例：「はい、スケールしてください」、「インスタンス X をスケールして」）、確認済みのインスタンスに対して、該当する gcloud filestore instances update コマンドを実行します。
3. フォールバック：
   • Prod の変更制限により実行に失敗した場合は、失敗の理由を出力し、ユーザーが手動で実行できるよう、該当する gcloud コマンドをそのまま提示します。また、手動実行の前にも確認するよう伝えてください。

カスタムしきい値

ユーザーがプロンプトでカスタムしきい値を設定または指定した場合（例： 「空き容量が 10% を下回ったら、20% 刻みでスケールアップする」、またはカスタムの max_threshold／up_increment）：

1. セッション全体のメモリでの確認：回答ではカスタムしきい値を受け入れたことを認め、カスタムしきい値がセッションメモリ内のすべてのプロジェクトにグローバルに適用されることを明示的に確認する必要があります。意図しないプロジェクト間の設定ミスを防ぐため、セッションメモリ内で評価対象またはアクティブなプロジェクト ID も明示してください。
2. 設定の概要：すべてのアクティブなしきい値とステップ増分を含む、更新後のアクティブな設定概要を表示する必要があります。
3. オーバーライドの維持：カスタムのオーバーライドが指定された場合、デフォルトのしきい値（15%／10%）に戻してはいけません。

参照ディレクトリ

より詳しいトピックを段階的に参照するには、references/ ディレクトリを確認してください。

• インスタンスの階層と仕様
• モニタリング指標の計算式
• トラブルシューティングとエラー