/google-cloud-filestore-autoscale

name: google-cloud-filestore-autoscale
metadata:
  version: "1.0.3"
  category: Storage
description: >-
  Inspects Filestore capacity and utilization on Google Cloud, evaluates storage
  scaling rules, and performs capacity autoscaling (scale UP for low free space
  or scale DOWN for cost optimization). Use when monitoring Filestore instance
  headroom, resizing instance shares, configuring automated growth/shrink
  thresholds (custom thresholds apply globally across projects in session memory),
  or preventing out-of-space outages. Don't use for Cloud Storage (GCS) buckets,
  Persistent Disk block storage, or NetApp Volumes.

Filestore Autoscale

This skill enables agents to inspect, evaluate, and modify Filestore instance capacities across Google Cloud projects based on configured thresholds.

Prerequisites / IAM Requirements

Before an agent or user can execute this skill, their runtime Service Account must possess the following IAM roles on the target project(s):

• **`roles/file.editor`** (Required for listing instances and triggering scale

up/down updates)

• **`roles/monitoring.viewer`** (Required for reading Cloud Monitoring

capacity metrics `used_bytes`)

• **`roles/mcp.toolUser`** (Required if utilizing backend Filestore MCP tools)

Quick Start

1. Ensure `gcloud` is installed. See [gcloud installation guide](https://cloud.google.com/sdk/docs/install) if needed. 2. Enable essential APIs:

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

3. Inspect fleet capacity and free space (see "Discovery & Read Operations" below). 4. Evaluate against configured up/down capacity thresholds. 5. Scale target instances and apply attribution tags.

Usage Attribution

**MUST READ**: Before executing any `gcloud`, REST API, or MCP command, you MUST read and follow the instructions in [Usage Attribution](references/attribution.md).

Conceptual & Informational Queries (CRITICAL)

For purely conceptual, educational, or informational questions (e.g., "What are Filestore scaling limits?", "Can Basic instances scale down?", "Explain Filestore Tiers"):

• **Rule**: **Answer immediately using your pre-trained knowledge and the matrix below.**
• **Constraint**: **Do not execute external tool calls or API requests** for basic knowledge questions.

Handling "No-Command" Constraints (CRITICAL)

If the user prompt contains constraints like "Do not execute commands", "without executing", or "read-only":

• **Rule**: **Strictly avoid calling the `run_command` tool** to execute any

shell, `gcloud`, or code search (`cs`) commands (including read-only list/describe commands).

• **Discovery**:

1. Whenever outputting or recommending a `gcloud` command (including when evaluating instance values provided directly in the user prompt), read [Usage Attribution](references/attribution.md) first so the command includes the required attribution prefix; do not search for additional unrelated files when instance tier, capacity, and utilization are already in the prompt. 2. Otherwise, check if Filestore MCP tools (`list_instances`, `get_instance`) are available and use them (these are API calls, not command executions). 3. If MCP tools are not available, check `references/instance-tiers-specs.md` for any mock instance definitions or project details matching the request. (Do NOT run repository-wide searches or attempt to read evaluation config files such as `EVAL.yaml` or `EVAL.txtpb` during evaluation runs as access is restricted). 4. If no data can be found, explain the required steps and formulas, and output the attributed `gcloud` terminal commands for the user to confirm and run, without executing them yourself.

• **Mandatory User Confirmation Requirement**: Even when the user prompt asks not to execute commands or asks only for command syntax/recommendations, your response MUST STILL end with a clear question prompting the user for confirmation before executing any capacity resizing commands (e.g., *"Would you like me to proceed with scaling `[instance]` from [A] TiB to [B] TiB? Please confirm to execute."*).

Tier & Capacity Limits Matrix

Filestore tiers enforce specific boundaries and behaviors. The skill must accept both modern UI names (`Basic`, `Zonal`, `Regional`) and legacy API enums interchangeably.

See `references/instance-tiers-specs.md` for the full Tier & Capacity Limits Matrix (Min/Max capacities, step increments).

**Critical Thresholds:**

• **Basic HDD / Basic SSD**: Can scale up, but **cannot scale down**.
• **Zonal / Regional**: Can scale down, but cannot shrink below their minimum

floor (100 GiB for Regional Small Band, 1 TiB for Zonal Small Band, or 10 TiB for Large Band) AND cannot shrink below current `used_bytes`.

Core Operational Workflow

1. Discovery & Read Operations

• **Step 1 (Fleet Discovery)**: Call the MCP tool

`list_instances(parent='projects/{project_id}/locations/-')` or CLI `gcloud filestore instances list --project={project_id}` to discover all Filestore instances in the target project. Read the `capacityGb` and `tier` directly from the instances returned.

• **Step 2 (Single Bulk Utilization Metric Query)**: Immediately after

discovering instances, query the Cloud Monitoring API for the `file.googleapis.com/nfs/server/used_bytes` metric across the entire project in a single request (see `references/monitoring-metrics.md` for runtime-specific options including GCP REST API, `gcloud`, `curl`, and MCP tools).

**CRITICAL**: Make exactly ONE bulk metric request for the entire project. **NEVER emit multiple per-instance queries or loops.** Do NOT filter by zone or region.

• **Step 3 (Metric Extraction & Calculation)**:

• Match each instance's short name (or `resource.l