google-cloud-filestore-autoscale

Filestore 自动扩缩容

此技能可让 Agent 根据配置的阈值，检查、评估和修改 Google Cloud 项目中的 Filestore 实例容量。

前提条件 / IAM 要求

Agent 或用户执行此技能前，其运行时服务账号必须在目标项目中拥有以下 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 时，请追加 User-Agent：

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

概念与信息查询（重要）

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

• 规则：立即使用预训练知识和下方的矩阵作答。
• 限制：对于基础知识问题，不要调用外部工具或 API。

处理“禁止执行命令”限制（重要）

如果用户提示包含“不要执行命令”、“不执行命令”或“只读”等限制：

• 规则：严格禁止调用 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？请确认后我再执行。”）。

层级与容量限制矩阵

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（单次批量利用率指标查询）：发现实例后，立即在一次请求中查询整个项目的 Cloud Monitoring API file.googleapis.com/nfs/server/used_bytes 指标（运行时特定选项，包括 GCP REST API、gcloud、curl 和 MCP 工具，请参阅 references/monitoring-metrics.md）。

  重要：整个项目只能发出一次批量指标请求。 切勿发出多个针对单个实例的查询，也不要循环查询。 不要按可用区或区域筛选。

• 步骤 3（指标提取与计算）：

  • 在返回的 timeSeries 数据中，匹配每个实例的短名称（或 resource.labels.instance_name / metric.labels.instance_name），提取其最新的 int64Value 字节数。
  • 如果某个实例未列在 timeSeries 中，或没有数据点，则将其 used_bytes 默认设为 0。
  • 计算 used_bytes_gb = used_bytes / (1024^3)。
  • 计算 空闲空间 % = ((capacityGb - used_bytes_gb) / capacityGb) * 100。
  • 切勿将 Used Bytes 或 Free Space % 留为“N/A”。在输出摘要表中填入实际数值。

2. 自动扩缩容需求判定矩阵

该技能必须将每个评估的实例归入 5 种明确的判定结果之一。在初次分析／集群检查运行时，该技能会建议所需的扩缩容操作、目标容量和更新命令，并且在执行任何自动扩缩容修改之前，先征求用户确认。请明确将“Autoscale Needed”列的值设为以下之一：

• Yes (Scale Up)：当剩余空间百分比低于扩容安全阈值（剩余可用空间 < 15%）时触发。评估响应必须明确说明当前剩余空间百分比低于 15% 的扩容安全阈值。容量必须增加 10%（默认值）或最小步长，并按层级的步长增量取整（Small Band [1–9.75 TiB] 为 256 GiB，Large Band [10–100 TiB] 为 2.5 TiB，详见 references/instance-tiers-specs.md），且不得超过最大容量。建议目标容量，提供带归属信息的 gcloud 更新命令，并且响应必须以明确的问题结尾，征求用户确认是否执行（例如：“是否要将 [instance] 从 [A] TiB 扩容到 [B] TiB？请确认后执行。”）。
• Yes (Scale Down)：当剩余空间超过缩容阈值（剩余可用空间 > 30%），且实例符合缩容条件（Zonal 或 Regional／Enterprise 层级）时触发。默认按当前容量的 -10% 缩减，并按层级的步长增量对齐（Small Band [1–9.75 TiB] 为 256 GiB，Large Band [10–100 TiB] 为 2.5 TiB，详见 references/instance-tiers-specs.md）。例如，对于容量为 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）时触发。Agent 必须明确告知用户不支持缩容，并建议改为迁移数据。无法采取任何操作。

输出格式

每份状态报告、评估或建议响应都必须包含一张汇总已评估实例的 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. 回退方案：
   • 如果执行因生产环境变更限制而失败，请输出失败原因，并提供用户可手动运行的完整 gcloud 命令，同时提醒用户在手动执行前确认。

自定义阈值

当用户在提示词中配置或传入自定义阈值时（例如： “如果可用空间低于 10%，则按 20% 的步长扩容”，或自定义 max_threshold / up_increment）：

1. 全局会话记忆确认：回复必须接受并确认自定义阈值，并明确确认这些自定义阈值将在会话记忆中全局应用于各个项目，同时明确提及会话记忆中评估或处于活动状态的目标项目 ID，以防意外的跨项目配置错误。
2. 配置摘要：回复必须显示更新后的活动配置摘要，其中包含所有活动阈值和步长增量。
3. 保留覆盖值：提供自定义覆盖值时，回复不得恢复为默认阈值（15% / 10%）。

参考目录

如需逐步了解更深入的主题，请查阅 references/ 目录：

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