google-cloud-filestore-autoscale

Files (4)

• SKILL.md
• instance-tiers-specs.md · references/
• monitoring-metrics.md · references/
• troubleshooting-errors.md · references/

SKILL.md (first lines)

# 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:

    ```bash
    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.

## 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)
```

## 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 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."*).

## 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.

## 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 (256

From google/skills, Apache-2.0.

More from google/skills