/google-cloud-filestore-nfs-browser

name: google-cloud-filestore-nfs-browser
metadata:
  version: "1.0.1"
  category: Storage
description: >-
  Inspects, searches, and reads files and POSIX metadata on Filestore (NFS)
  instances on Google Cloud without local NFS client packages or root
  privileges. Use when browsing Filestore shares, searching files, reading
  remote logs, or inspecting file attributes; don't use for Cloud Storage
  buckets, Cloud NetApp Volumes, Persistent Disks, or modifying/deleting files.

Filestore NFS File Browser

Enables autonomous agents and cloud engineers to inspect, search, and read files located on Filestore (NFS) instances without needing local NFS client packages (`nfs-common`), root privileges, or manual VPC network mounting.

Quick Start

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

    gcloud services enable file.googleapis.com compute.googleapis.com run.googleapis.com --quiet

3. Discover instances and choose an execution engine (see [Execution Engine Selection](#execution-engine-selection) below). 4. Run inspection actions using the self-contained runner `scripts/nfs_browser.py` included within this skill package.

Attribution

Tag every Cloud Filestore command or API request provided or executed. Prefix `gcloud` commands with the metrics environment targeting this skill:

CLOUDSDK_METRICS_ENVIRONMENT="gcs-skills gcs-skills/1.0 (skill:google-cloud-filestore-nfs-browser)" \
gcloud filestore instances list ...

On direct HTTP calls to the REST API, append the `User-Agent`:

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

Conceptual & Informational Queries (CRITICAL)

For purely conceptual, educational, or architectural questions (e.g., "How do I inspect files on Filestore?", "How to deploy the Serverless Cloud Run NFS Bridge?", "Explain Cloud Run NFS volume mounts"):

• **Rule**: **Answer immediately using your pre-trained knowledge and the

documentation below.** Answering directly minimizes tool invocation latency and token consumption when the user only seeks architecture or workflow guidance.

• **Constraint**: **Do not execute external tool calls or API requests** for

basic knowledge questions.

• **Bridge Deployment Explanations**: Always highlight that Cloud Run scales

to zero with **$0 idle compute cost**, detail the `gcloud run deploy` command with `--add-volume` and `--vpc-egress=all-traffic`, and specify the required IAM permissions (`roles/run.invoker` for callers and `roles/run.admin` for deployers).

Handling "No-Command" Constraints (CRITICAL)

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

• **Rule**: **Strictly avoid executing any shell or `gcloud` commands**

(including read-only discovery or list commands) to respect user-specified execution boundaries and prevent unauthorized environment inspection.

• **Discovery**:

1. Check if mock definitions or instance parameters are provided directly in the user's prompt, conversation history, or local documentation files. 2. Explain the required steps, output the exact commands the user should run with proper attribution, and explain what the commands do. 3. Do not attempt to read or search `EVAL.*` configuration files during evaluations as access to eval suites is restricted.

Execution Engine Selection

Filestore instances are accessible via private VPC IPs. Select the engine matching your environment:

• **Engine 1: Cloud Run Serverless Bridge (Primary)**: Use

`--bridge-url={bridge_url}` for low-latency (sub-50ms) REST calls. Scales to zero ($0 idle cost). Requires `roles/run.invoker`. See [references/nfs-bridge-setup.md](references/nfs-bridge-setup.md).

• **Engine 2: GCE Jump Host via IAP SSH (Fallback)**: Use

`--jump-host-vm={vm_name}` when an existing VM in the VPC is available. Pass `--mount={mount_path}` (defaulting to `/mnt/filestore`) if the jump host uses a different mount path. Zero new deployment needed. Requires `roles/iap.tunnelResourceAccessor`. See [references/iap-jump-host.md](references/iap-jump-host.md).

For execution flows, architecture diagrams, and engine comparison, see [references/architecture.md](references/architecture.md).

Core Operational Workflow

1. Discovery & Instance Targeting

If the Filestore instance, location, or share name is not provided, list them first to avoid querying or targeting unrelated projects in multi-project environments:

CLOUDSDK_METRICS_ENVIRONMENT="gcs-skills gcs-skills/1.0 (skill:google-cloud-filestore-nfs-browser)" \
gcloud filestore instances list --project={project_id}

2. Directory Tree Exploration (`tree`)

Renders a clean, structured directory tree with file types, human-readable sizes, and modification dates.

# List top-level folders with depth 1
python3 scripts/nfs_browser.py tree \
  --project={project_id} \
  --instance={instance_id} \
  --path=/ \
  --depth=1

# List subfolder recursively with depth 2 and pagination cap
python3 scripts/nfs_browser.py tree \
  --project={project_id} \
  --instance={instance_id} \
  --path=/backup/logs/ \
  --depth=2 \
  --max-entries=100

3. File Pattern & Content Grep (`search`)

Searches for filenames matching a glob pattern and/or searches text contents for regex patterns.

# Search for all tar.gz backup archives
python3 scripts/nfs_browser.py search \
  --project={project_id} \
  --instance={instance_id} \
  --path=/backups/ \
  --pattern="*.tar.gz"

# Grep for error patterns inside log files
python3 scripts/nfs_browser.py search \
  --project={project_id} \
  --instance={instance_id} \
  --path=/app/logs/ \
  --pattern="*.log" \
  --grep="FATAL|Exception|OutOfMemor