google-cloud-filestore-autoscale

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Google Cloud Filestore Autoscale

Google Cloud Filestore 自动扩缩容

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

本技能支持Agent基于配置的阈值，跨GCP项目检查、评估并修改Google Cloud Filestore实例的容量。

Quick Start

快速开始

Ensure
```
gcloud
```
is installed. See gcloud installation guide if needed.

Enable essential APIs:

bash

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.

确保已安装
```
gcloud
```
。如需安装，请查看gcloud安装指南。

启用必要的API：

bash

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

检查集群容量与剩余空间（详见下方“发现与读取操作”）。
根据配置的扩容/缩容阈值进行评估。
对目标实例进行扩缩容并添加归因标签。

Attribution

归因

Tag every Cloud Filestore command or API request provided or executed. Prefix

gcloud

commands with the correct metrics environment targeting this skill:

bash

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

On direct HTTP calls to the REST API, append the

User-Agent

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

为所有提供或执行的Cloud Filestore命令或API请求添加标签。在

gcloud

命令前添加针对本技能的正确指标环境前缀：

bash

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

直接调用REST API时，需附加

User-Agent

：

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

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.

对于纯概念性、教育性或信息类问题（例如：“Filestore的扩缩容限制是什么？”、“Basic实例能否缩容？”、“解释Filestore层级”）：

规则：立即使用预训练知识及下方矩阵作答。
约束：针对基础知识类问题，请勿执行外部工具调用或API请求。

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 or
```
gcloud
```
commands (including read-only list/describe commands).
Discovery:
1. First, check if Filestore MCP tools (
```
list_instances
```
  ,
```
get_instance
```
  ) are available and use them (these are API calls, not command executions).
2. If MCP tools are not available, search local markdown documentation files (e.g.,
```
references/instance-tiers-specs.md
```
  ) for any mock instance definitions or project details matching the request. (Do NOT attempt to read evaluation config files such as
```
EVAL.yaml
```
  or
```
EVAL.txtpb
```
  during evaluation runs as access is restricted).
3. If no data can be found, explain the required steps and formulas, and output the exact commands the user should 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.").

如果用户提示包含“请勿执行命令”、“无需执行”或“只读”等约束：

规则：严格避免调用
run_command
工具执行任何Shell或
```
gcloud
```
命令（包括只读的列表/描述命令）。
发现流程：
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？请确认后执行。”）。

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 (1 TiB or 10 TiB depending on band) AND cannot shrink below the current
```
used_bytes
```
metric.

Filestore层级会强制执行特定的边界与行为。本技能必须同时兼容现代UI名称（

Basic

、

Zonal

、

Regional

）与旧版API枚举值。

完整的层级与容量限制矩阵（最小/最大容量、步长增量）请查看

references/instance-tiers-specs.md

。

关键阈值：

Basic HDD / Basic SSD：可扩容，但无法缩容。
Zonal / Regional：可缩容，但不能低于其最低容量下限（根据带宽不同为1 TiB或10 TiB），且不能低于当前
```
used_bytes
```
指标。

Core Operational Workflow

核心操作流程

1. Discovery & Read Operations

1. 发现与读取操作

MCP-First: Prefer using Filestore MCP tools (
```
list_instances
```
,
```
get_instance
```
) to discover and inspect fleet capacity.
CLI Fallback: If MCP is unavailable, use
```
gcloud filestore instances list --project={project_id}
```
. You MUST ask for the Project ID if not provided (e.g., "to avoid inspection of unrelated projects in a multi-project environment").
Utilization: Fetch the 5-minute average of
```
file.googleapis.com/nfs/server/used_bytes
```
from the Cloud Monitoring API to evaluate
```
used_bytes
```
. If you cannot fetch this programmatically, state the formulas explicitly for the user.

优先使用MCP：优先使用Filestore MCP工具（
```
list_instances
```
、
```
get_instance
```
）发现并检查集群容量。
CLI备选方案：如果MCP不可用，使用
```
gcloud filestore instances list --project={project_id}
```
。如果用户未提供项目ID，你必须询问（例如：“为避免在多项目环境中检查无关项目，请提供项目ID”）。
利用率计算：从Cloud Monitoring API获取
```
file.googleapis.com/nfs/server/used_bytes
```
的5分钟平均值以评估
```
used_bytes
```
。如果无法通过编程方式获取，请向用户明确说明计算公式。

2. Autoscale Needed Matrix

2. 自动扩缩容必要性矩阵

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, not exceeding the maximum capacity. 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. Capacity must be decreased by 10% (default), rounded to step size. Target capacity must be
```
>= max(tier_min, used_bytes)
```
. Suggest target capacity, cost savings, and provide the attributed
```
gcloud
```
update command, prompting 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 (e.g. 1 TiB or 10 TiB) 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.

本技能必须将每个评估实例归类为以下5种明确结论之一。在初始分析/集群检查运行时，技能需建议所需的扩缩容操作、目标容量及更新命令，并在执行任何自动扩缩容修改前提示用户确认。需清晰说明“是否需要自动扩缩容”列的值，必须为以下选项之一：

是（扩容）：剩余空间百分比低于扩容安全阈值（剩余空间<15%）时触发。评估回复必须明确说明当前剩余空间百分比低于15%的扩容安全阈值。容量需增加10%（默认值）或最小步长，并四舍五入至对应层级的步长增量，且不超过最大容量。建议目标容量，提供带归因的
```
gcloud
```
更新命令，并必须以清晰的问题结尾提示用户确认执行（例如：“是否要继续将
[instance]
从[A] TiB扩容至[B] TiB？请确认后执行。”）。
是（缩容）：剩余空间超过缩容阈值（剩余空间>30%）且实例符合缩容条件时触发。容量需减少10%（默认值），并四舍五入至步长。目标容量必须
```
>= max(层级最小值, used_bytes)
```
。建议目标容量、成本节约情况，提供带归因的
```
gcloud
```
更新命令，并提示用户确认执行。
否（健康）：实例剩余空间处于最佳运行范围（15% – 30%）时触发。无需操作。
否（已达最小容量限制）：剩余空间>30%，但实例已达到对应层级允许的最小容量下限（例如1 TiB或10 TiB）或当前已用空间限制时触发。无法执行操作。
否（该层级无法缩容）：剩余空间>30%，但实例属于Basic层级（Basic HDD / Basic SSD），不支持缩容时触发。Agent必须明确告知用户不支持缩容，并建议数据迁移。无法执行操作。

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)

)

**所有状态报告、评估或建议回复必须包含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)

）

3. Execution & Confirmation Workflow

3. 执行与确认流程

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.

分析与建议（首次运行/检查）：
- 计算符合层级上限、下限及仅扩容规则的步长对齐目标容量。
- 展示汇总表格与拟执行的操作。
- 强制用户确认提示：无论何时建议目标容量或提供
```
gcloud filestore instances update
```
  命令，你的回复必须明确包含清晰的问题，请求用户在进行任何修改前确认执行（例如：“是否要继续将
  [instance]
  从[A] TiB扩缩容至[B] TiB？请确认后执行。”），以防止意外的费用激增或容量耗尽。
- 未经用户确认，请勿执行自动扩缩容命令。
确认后执行：
- 一旦用户确认（例如：“是的，继续扩缩容”、“扩缩容实例X”），对已确认的实例执行带归因的
```
gcloud filestore instances update
```
  命令。
备选方案：
- 如果因生产环境变更限制导致执行失败，输出失败原因，并向用户提供准确的带归因
```
gcloud
```
  命令供手动运行，提醒他们手动执行前需确认。

Custom Thresholds

自定义阈值

If the user passes custom threshold values in prompts (e.g. "Scale up if free space drops below 10% with a 20% step"), apply these globally across projects for the active session and acknowledge the new configuration. You MUST explicitly state in your response that these custom thresholds apply globally across all projects in the active session memory.

如果用户在提示中传入自定义阈值（例如：“剩余空间低于10%时扩容，步长为20%”），请在当前会话中全局应用这些阈值，并告知用户新配置已生效。你必须在回复中明确说明，这些自定义阈值将在当前会话内存中全局应用于所有项目。

Reference Directory

参考目录

For progressive disclosure of deeper topics, consult the

references/

directory:

Instance Tiers & Specs
Monitoring Metrics Formulas
Troubleshooting & Errors

如需深入了解相关主题，请查阅

references/

实例层级与规格
监控指标公式
故障排查与错误处理