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
Ensure gcloud is installed. See
gcloud installation guide if
needed.
Enable essential APIs:
gcloud services enable file.googleapis.com monitoring.googleapis.com --quiet
Inspect fleet capacity and free space (see "Discovery & Read Operations"
below).
Evaluate against configured up/down capacity thresholds.
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.
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:
- Whenever outputting or recommending a
gcloud command (including when
evaluating instance values provided directly in the user prompt), read
Usage Attribution 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.
- Otherwise, check if Filestore MCP tools (
list_instances,
get_instance) are available and use them (these are API calls, not
command executions).
- 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).
- 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.labels.instance_name /
metric.labels.instance_name) in the returned timeSeries data to
extract its latest int64Value bytes.
- If an instance is not listed in
timeSeries or has no points, default
its used_bytes to 0.
- Calculate
used_bytes_gb = used_bytes / (1024^3).
- Calculate
Free Space % = ((capacityGb - used_bytes_gb) / capacityGb) * 100.
- NEVER leave
Used Bytes or Free Space % as "N/A". Populate actual
numbers into the output summary table.
2. Autoscale Needed Matrix
The skill must categorize each evaluated instance into one of 5 definitive verdicts. On the initial analysis/fleet inspection run, the skill suggests the required scaling action with target capacity and update commands, and prompts for user confirmation before executing any autoscale modifications. State the value of the "Autoscale Needed" column clearly as one of the following:
- Yes (Scale Up): Triggered when free space percentage is below the
scale-up safety threshold (< 15% free space remaining). The evaluation
response MUST explicitly state that the current free space percentage is
below the 15% scale-up safety threshold. Capacity must be increased by 10%
(default) or step-size minimum, rounded to the tier's step increment (1 GiB
for Regional Small Band [100 GiB-10,239 GiB] or Basic, 256 GiB for Zonal
Small Band [1-9.75 TiB] or Enterprise [1-10 TiB],
2.5 TiB for Large Band [10-100 TiB],
as specified in
references/instance-tiers-specs.md), not exceeding the
maximum capacity. Always explicitly state the calculated target capacity in
both TiB and GiB (for example, for a 1 TiB [1024 GiB] Basic instance
increased by +10%, explicitly state 1.1 TiB alongside its 1 GiB
step-aligned equivalent 1126 GiB / 1127 GiB). Suggest target capacity,
provide the attributed gcloud
update command, and MUST conclude the response with a clear question
prompting the user for confirmation to execute (e.g., "Would you like me to
proceed with scaling [instance] from [A] TiB to [B] TiB? Please confirm to
execute.").
- Yes (Scale Down): Triggered when free space exceeds the scale-down
threshold (> 30% free space remaining) and the instance is eligible for
downscaling (Zonal or Regional / Enterprise tiers). Apply the default step
reduction of -10% of current capacity, aligned to the tier's step increment
(1 GiB for Regional Small Band [100 GiB-10,239 GiB], 256 GiB for Zonal
Small Band [1-9.75 TiB] or Enterprise [1-10 TiB],
2.5 TiB for Large Band [10-100 TiB],
as specified in
references/instance-tiers-specs.md). For example, for a
2 TiB (2048 GiB) Enterprise / Zonal Small Band instance, rounding to the
256 GiB step yields a proposed target capacity of 1.75 TiB (1792 GiB, or
1.8 TiB). The response MUST explicitly verify that the proposed target
capacity (e.g. 1.75 TiB / 1792 GiB or 1.8 TiB) remains strictly above both
the tier's minimum capacity floor (100 GiB for Regional Small Band, 1 TiB
for Zonal Small Band / Enterprise, or 10 TiB for Large Band) and currently
used space (e.g. 0.9 TiB). Do NOT reduce directly to the floor in a single
step. Suggest target capacity, estimated cost savings, provide the
attributed gcloud update command, and prompt the user for confirmation to
execute.
- No (Healthy): Triggered when the instance's free space is within the
optimal operating range (15% – 30%). No action required.
- No (At min capacity limit): Triggered when free space is > 30%, but the
instance is already at the minimum allowed tier capacity floor (100 GiB for
Regional Small Band, 1 TiB for Zonal Small Band / Enterprise, or 10 TiB for
Large Band) or currently used space limit. No action can be taken.
- No (Tier cannot scale down): Triggered when free space is > 30%, but the
instance is on a Basic tier (Basic HDD / Basic SSD) which does not support
downscaling. The agent must explicitly inform the user that scale-down is
not supported and suggest data migration instead. No action can be taken.
Output Format
Every status report, evaluation, or recommendation response MUST include a markdown table summarizing the evaluated instances. Even if evaluating a single instance, format it as a table.
The table MUST contain the following columns:
Instance
Service Tier
Provisioned Capacity
Used Bytes
Free Space %
Autoscale Needed (MUST contain one of: Yes (Scale Up), Yes (Scale Down), No (Healthy), No (At min capacity limit), or No (Tier cannot scale down))
Example standard output table:
| 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. `gcloud filestore instances update ...` |
3. Execution & Confirmation Workflow
- Analysis & Recommendation (First Run / Inspection):
- Calculate step-aligned target capacity adhering to tier ceilings, floors, and basic scale-up only rules.
- Present the summary table and proposed actions.
- MANDATORY USER CONFIRMATION PROMPT: Whenever recommending target capacity or providing a
gcloud filestore instances update command, your response MUST explicitly include a clear question asking the user to confirm execution before any modifications are made (e.g. "Would you like me to proceed with scaling [instance] from [A] TiB to [B] TiB? Please confirm to execute.") to prevent accidental billing spikes or capacity exhaustion.
- Do not execute autoscale commands without user confirmation.
- Execution upon Confirmation:
- Once the user confirms (e.g., "Yes, proceed with scaling", "Scale instance X"), execute the attributed
gcloud filestore instances update command on the confirmed instance(s).
- Fallback:
- If execution fails due to Prod mutation restrictions, output the failure reason and provide the user with the exact attributed
gcloud command to run manually, reminding them to confirm before manual execution.
Custom Thresholds
When the user configures or passes custom threshold values in prompts (e.g.
"Scale up if free space drops below 10% with a 20% step", or custom
max_threshold / up_increment):
- Global Session Memory Confirmation: The response MUST accept and
acknowledge the custom thresholds and MUST explicitly confirm that custom
thresholds apply globally across projects in session memory, explicitly
mentioning the target project IDs evaluated or active in session memory to
prevent accidental cross-project misconfiguration.
- Configuration Summary: The response MUST display the updated active
configuration summary showing all active thresholds and step increments.
- Preserve Overrides: The response MUST NOT revert to default thresholds
(15% / 10%) when custom overrides are provided.
Reference Directory
For progressive disclosure of deeper topics, consult the references/ directory:
- Usage Attribution
- Instance Tiers & Specs
- Monitoring Metrics Formulas
- Troubleshooting & Errors
1---2name: google-cloud-filestore-autoscale3metadata:4 source: https://skillmd.com/skills/google/google-cloud-filestore-autoscale5 version: "1.0.3"6 category: Storage7description: >-8 Inspects Filestore capacity and utilization on Google Cloud, evaluates storage9 scaling rules, and performs capacity autoscaling (scale UP for low free space10 or scale DOWN for cost optimization). Use when monitoring Filestore instance11 headroom, resizing instance shares, configuring automated growth/shrink12 thresholds (custom thresholds apply globally across projects in session memory),13 or preventing out-of-space outages. Don't use for Cloud Storage (GCS) buckets,14 Persistent Disk block storage, or NetApp Volumes.15---1617# Filestore Autoscale1819This skill enables agents to inspect, evaluate, and modify Filestore20instance capacities across Google Cloud projects based on configured21thresholds.2223## Prerequisites / IAM Requirements2425Before an agent or user can execute this skill, their runtime Service Account26must possess the following IAM roles on the target project(s):2728- **`roles/file.editor`** (Required for listing instances and triggering scale29 up/down updates)30- **`roles/monitoring.viewer`** (Required for reading Cloud Monitoring31 capacity metrics `used_bytes`)32- **`roles/mcp.toolUser`** (Required if utilizing backend Filestore MCP tools)3334## Quick Start35361. Ensure `gcloud` is installed. See37 [gcloud installation guide](https://cloud.google.com/sdk/docs/install) if38 needed.392. Enable essential APIs:4041 ```bash42 gcloud services enable file.googleapis.com monitoring.googleapis.com --quiet43 ```443. Inspect fleet capacity and free space (see "Discovery & Read Operations"45 below).464. Evaluate against configured up/down capacity thresholds.475. Scale target instances and apply attribution tags.4849## Usage Attribution5051**MUST READ**: Before executing any `gcloud`, REST API, or MCP command, you52MUST read and follow the instructions in53[Usage Attribution](references/attribution.md).5455## Conceptual & Informational Queries (CRITICAL)5657For purely conceptual, educational, or informational questions (e.g., "What are Filestore scaling limits?",58"Can Basic instances scale down?", "Explain Filestore Tiers"):5960* **Rule**: **Answer immediately using your pre-trained knowledge and the matrix below.**61* **Constraint**: **Do not execute external tool calls or API requests** for basic knowledge questions.6263## Handling "No-Command" Constraints (CRITICAL)6465If the user prompt contains constraints like "Do not execute commands", "without executing", or "read-only":6667* **Rule**: **Strictly avoid calling the `run_command` tool** to execute any68 shell, `gcloud`, or code search (`cs`) commands (including read-only69 list/describe commands).70* **Discovery**:71 1. Whenever outputting or recommending a `gcloud` command (including when72 evaluating instance values provided directly in the user prompt), read73 [Usage Attribution](references/attribution.md) first so the command74 includes the required attribution prefix; do not search for additional75 unrelated files when instance tier, capacity, and utilization are76 already in the prompt.77 2. Otherwise, check if Filestore MCP tools (`list_instances`,78 `get_instance`) are available and use them (these are API calls, not79 command executions).80 3. If MCP tools are not available, check81 `references/instance-tiers-specs.md` for any mock instance definitions82 or project details matching the request. (Do NOT run repository-wide83 searches or attempt to read evaluation config files such as `EVAL.yaml`84 or `EVAL.txtpb` during evaluation runs as access is restricted).85 4. If no data can be found, explain the required steps and formulas, and86 output the attributed `gcloud` terminal commands for the user to confirm87 and run, without executing them yourself.88* **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."*).8990## Tier & Capacity Limits Matrix9192Filestore tiers enforce specific boundaries and behaviors. The skill must accept both modern UI names (`Basic`, `Zonal`, `Regional`) and legacy API enums interchangeably.9394See `references/instance-tiers-specs.md` for the full Tier & Capacity Limits Matrix (Min/Max capacities, step increments).9596**Critical Thresholds:**9798- **Basic HDD / Basic SSD**: Can scale up, but **cannot scale down**.99- **Zonal / Regional**: Can scale down, but cannot shrink below their minimum100 floor (100 GiB for Regional Small Band, 1 TiB for Zonal Small Band, or 10 TiB101 for Large Band) AND cannot shrink below current `used_bytes`.102103## Core Operational Workflow104105### 1. Discovery & Read Operations106107- **Step 1 (Fleet Discovery)**: Call the MCP tool108 `list_instances(parent='projects/{project_id}/locations/-')` or CLI `gcloud109 filestore instances list --project={project_id}` to discover all Filestore110 instances in the target project. Read the `capacityGb` and `tier` directly111 from the instances returned.112- **Step 2 (Single Bulk Utilization Metric Query)**: Immediately after113 discovering instances, query the Cloud Monitoring API for the114 `file.googleapis.com/nfs/server/used_bytes` metric across the entire project115 in a single request (see `references/monitoring-metrics.md` for116 runtime-specific options including GCP REST API, `gcloud`, `curl`, and MCP117 tools).118119 **CRITICAL**: Make exactly ONE bulk metric request for the entire project.120 **NEVER emit multiple per-instance queries or loops.** Do NOT filter by zone121 or region.122123- **Step 3 (Metric Extraction & Calculation)**:124125 - Match each instance's short name (or `resource.labels.instance_name` /126 `metric.labels.instance_name`) in the returned `timeSeries` data to127 extract its latest `int64Value` bytes.128 - If an instance is not listed in `timeSeries` or has no points, default129 its `used_bytes` to 0.130 - Calculate `used_bytes_gb = used_bytes / (1024^3)`.131 - Calculate `Free Space % = ((capacityGb - used_bytes_gb) / capacityGb) *132 100`.133 - NEVER leave `Used Bytes` or `Free Space %` as "N/A". Populate actual134 numbers into the output summary table.135136### 2. Autoscale Needed Matrix137138The skill must categorize each evaluated instance into one of 5 definitive verdicts. On the initial analysis/fleet inspection run, the skill suggests the required scaling action with target capacity and update commands, and **prompts for user confirmation before executing any autoscale modifications**. State the value of the "Autoscale Needed" column clearly as one of the following:139140- **Yes (Scale Up)**: Triggered when free space percentage is below the141 scale-up safety threshold (< 15% free space remaining). The evaluation142 response MUST explicitly state that the current free space percentage is143 below the 15% scale-up safety threshold. Capacity must be increased by 10%144 (default) or step-size minimum, rounded to the tier's step increment (1 GiB145 for Regional Small Band [100 GiB-10,239 GiB] or Basic, 256 GiB for Zonal146 Small Band [1-9.75 TiB] or Enterprise [1-10 TiB],147 2.5 TiB for Large Band [10-100 TiB],148 as specified in `references/instance-tiers-specs.md`), not exceeding the149 maximum capacity. Always explicitly state the calculated target capacity in150 **both TiB and GiB** (for example, for a 1 TiB [1024 GiB] Basic instance151 increased by +10%, explicitly state `1.1 TiB` alongside its 1 GiB152 step-aligned equivalent `1126 GiB` / `1127 GiB`). Suggest target capacity,153 provide the attributed `gcloud`154 update command, and MUST conclude the response with a clear question155 prompting the user for confirmation to execute (e.g., *"Would you like me to156 proceed with scaling `[instance]` from [A] TiB to [B] TiB? Please confirm to157 execute."*).158- **Yes (Scale Down)**: Triggered when free space exceeds the scale-down159 threshold (> 30% free space remaining) and the instance is eligible for160 downscaling (Zonal or Regional / Enterprise tiers). Apply the default step161 reduction of -10% of current capacity, aligned to the tier's step increment162 (1 GiB for Regional Small Band [100 GiB-10,239 GiB], 256 GiB for Zonal163 Small Band [1-9.75 TiB] or Enterprise [1-10 TiB],164 2.5 TiB for Large Band [10-100 TiB],165 as specified in `references/instance-tiers-specs.md`). For example, for a166 2 TiB (2048 GiB) Enterprise / Zonal Small Band instance, rounding to the167 256 GiB step yields a proposed target capacity of 1.75 TiB (1792 GiB, or168 1.8 TiB). The response MUST explicitly verify that the proposed target169 capacity (e.g. 1.75 TiB / 1792 GiB or 1.8 TiB) remains strictly above both170 the tier's minimum capacity floor (100 GiB for Regional Small Band, 1 TiB171 for Zonal Small Band / Enterprise, or 10 TiB for Large Band) and currently172 used space (e.g. 0.9 TiB). Do NOT reduce directly to the floor in a single173 step. Suggest target capacity, estimated cost savings, provide the174 attributed `gcloud` update command, and prompt the user for confirmation to175 execute.176- **No (Healthy)**: Triggered when the instance's free space is within the177 optimal operating range (15% – 30%). No action required.178- **No (At min capacity limit)**: Triggered when free space is > 30%, but the179 instance is already at the minimum allowed tier capacity floor (100 GiB for180 Regional Small Band, 1 TiB for Zonal Small Band / Enterprise, or 10 TiB for181 Large Band) or currently used space limit. No action can be taken.182- **No (Tier cannot scale down)**: Triggered when free space is > 30%, but the183 instance is on a Basic tier (Basic HDD / Basic SSD) which does not support184 downscaling. The agent must explicitly inform the user that scale-down is185 not supported and suggest data migration instead. No action can be taken.186187### Output Format188189**Every status report, evaluation, or recommendation response MUST include a markdown table summarizing the evaluated instances.** Even if evaluating a single instance, format it as a table.190The table MUST contain the following columns:191192* `Instance`193* `Service Tier`194* `Provisioned Capacity`195* `Used Bytes`196* `Free Space %`197* `Autoscale Needed` (MUST contain one of: `Yes (Scale Up)`, `Yes (Scale Down)`, `No (Healthy)`, `No (At min capacity limit)`, or `No (Tier cannot scale down)`)198199Example standard output table:200201```markdown202| Instance | Service Tier | Provisioned Capacity | Used Bytes | Free Space % | Autoscale Needed | Proposed Action |203|---|---|---|---|---|---|---|204| `[instance-name]` | REGIONAL | 2048 GiB | 900 GiB | 56.05% | Yes (Scale Down) | Scale down to 1792 GiB. `gcloud filestore instances update ...` |205```206207### 3. Execution & Confirmation Workflow2082091. **Analysis & Recommendation (First Run / Inspection)**:210 - Calculate step-aligned target capacity adhering to tier ceilings, floors, and basic scale-up only rules.211 - Present the summary table and proposed actions.212 - **MANDATORY USER CONFIRMATION PROMPT**: Whenever recommending target capacity or providing a `gcloud filestore instances update` command, your response MUST explicitly include a clear question asking the user to confirm execution before any modifications are made (e.g. *"Would you like me to proceed with scaling `[instance]` from [A] TiB to [B] TiB? Please confirm to execute."*) to prevent accidental billing spikes or capacity exhaustion.213 - **Do not execute autoscale commands without user confirmation.**2142. **Execution upon Confirmation**:215 - Once the user confirms (e.g., "Yes, proceed with scaling", "Scale instance X"), execute the attributed `gcloud filestore instances update` command on the confirmed instance(s).2163. **Fallback**:217 - If execution fails due to Prod mutation restrictions, output the failure reason and provide the user with the exact attributed `gcloud` command to run manually, reminding them to confirm before manual execution.218219### Custom Thresholds220221When the user configures or passes custom threshold values in prompts (e.g.222"Scale up if free space drops below 10% with a 20% step", or custom223max_threshold / up_increment):2242251. **Global Session Memory Confirmation**: The response MUST accept and226 acknowledge the custom thresholds and MUST explicitly confirm that custom227 thresholds apply globally across projects in session memory, explicitly228 mentioning the target project IDs evaluated or active in session memory to229 prevent accidental cross-project misconfiguration.2302. **Configuration Summary**: The response MUST display the updated active231 configuration summary showing all active thresholds and step increments.2323. **Preserve Overrides**: The response MUST NOT revert to default thresholds233 (15% / 10%) when custom overrides are provided.234235## Reference Directory236237For progressive disclosure of deeper topics, consult the `references/` directory:238239- [Usage Attribution](references/attribution.md)240- [Instance Tiers & Specs](references/instance-tiers-specs.md)241- [Monitoring Metrics Formulas](references/monitoring-metrics.md)242- [Troubleshooting & Errors](references/troubleshooting-errors.md)