How to use the Filestore Mount Troubleshooting agent skill

What is an agent skill and what does this one do?

An agent skill is a folder of instructions and optional scripts that an AI agent loads when a request matches the skill's description. This one is named google-cloud-filestore-log-troubleshooting and is licensed under Apache-2.0.

When a Filestore mount fails, the skill guides the agent through the likely causes: VPC firewall rules, the share's export access list (nfsExportOptions), and the client's IP or GKE node subnet. The agent can then explain what it found and suggest fixes. The skill also bundles a Python script that can run these checks against a live instance, and it is designed to ask for your confirmation before changing anything.

• Handles client mount failures, permission errors (EACCES) and network timeouts (ETIMEDOUT).
• Checks whether VPC ingress firewall rules or nfsExportOptions allow a client IP.
• Treats a GKE pod's traffic as coming from the GKE worker node IP, so the node subnet is evaluated.
• Does not cover Cloud Storage buckets, Persistent Disk, Cloud NetApp Volumes, Filestore capacity scaling, or backup and export-policy auditing.

How do you install the skill?

You can install the skill in one of two ways. Download the ZIP from this page and unzip it into a skills folder. For a personal setup, use ~/.claude/skills/. For a single project, use the .claude/skills/ folder inside the project.

If you use the Claude apps, you can instead upload the ZIP under Settings → Capabilities → Skills.

• Personal: unzip into ~/.claude/skills/
• Project: unzip into .claude/skills/ inside your project folder
• Claude apps: Settings → Capabilities → Skills, then upload the ZIP

What does the skill contain?

The folder contains SKILL.md, which holds the workflow the agent follows, plus reference files and scripts. Knowing the layout helps when you review what the skill will do before you run it.

• SKILL.md: the main instructions and workflow
• references/error-signatures.md: maps mount errors to likely causes and fixes
• references/logging-and-audit-queries.md: Cloud Logging and audit query examples
• references/network-firewall-spec.md: firewall reference material
• references/mock-fleet-data.md: fictional sample instances for offline evaluation only
• scripts/quick_diagnose.py and scripts/diagnose_lib.py: the bundled diagnostic script and its helper library

What do you need before it works?

The skill runs gcloud and Python commands, so you need the Google Cloud SDK (gcloud) and Python 3 on the machine where the agent runs. You also need a Google Cloud account with the right IAM roles on the target project, and the file, compute and logging APIs enabled.

For read-only diagnosis the source lists roles/file.viewer, roles/compute.networkViewer and roles/logging.viewer. Write roles such as roles/file.editor and roles/compute.securityAdmin are needed only for remediation.

• Google Cloud SDK (gcloud) and Python 3
• Read roles: roles/file.viewer, roles/compute.networkViewer, roles/logging.viewer
• Write roles, only for remediation: roles/file.editor, roles/compute.securityAdmin
• Enabled APIs: file, compute and logging

How do you trigger the skill with a natural request?

You do not need to name the skill. Describe the symptom in plain words and include the instance, location and project if you have them. The skill's description covers requests about NFS mounts that hang or fail, mount.nfs messages such as "Connection timed out" or "access denied by server", checks on firewall rules or nfsExportOptions, and shares that stopped mounting after an administrative change.

• "My GKE pod can't mount the Filestore share finance-share in us-central1. The error is access denied by server. Project is my-proj."
• "This VM's NFS mount hangs with Connection timed out. Does the firewall allow client 10.8.0.12?"
• "The ml-data share worked yesterday and now won't mount after someone changed the export settings. Check what changed."
• "Explain why a GKE pod's traffic shows the node IP instead of the pod IP for Filestore."

What can the bundled script do?

The script can diagnose a single instance or every instance in a project. You can give it a client IP or CIDR to test against the export list and firewall rules. The agent can run it for you, or you can run it yourself from a terminal.

• Single instance: pass --instance and --location, and optionally --project, --client-ip and --client-subnet.
• Whole project: use --all with --project. Add --json for machine-readable output on stdout; the narrative report then goes to stderr.
• --apply-fix executes generated remediation commands and should be passed only after you have explicitly confirmed.

What does a typical diagnosis look like?

The agent first confirms the instance state is READY, then reads the primary Filestore IP and VPC network, then checks the export list. If the client IP or subnet is not covered by any ipRanges entry, the error is classed as EACCES and the suggested remediation is to append the client IP or CIDR to nfsExportOptions while keeping the existing rules. A READ_ONLY access mode produces an EROFS (read-only file system) finding instead.

For GKE, the skill evaluates the GKE node subnet rather than the pod range, because the kernel mounts the volume on the worker node. The agent then reports what it found and asks you to confirm before creating or changing any firewall rule or export rule.

What safety rules should you know about?

The skill runs scripts and makes network calls to Google Cloud APIs, so review it before enabling it. It is designed to ask for confirmation before any change. Remediation commands are only run when you pass --apply-fix, and the skill instructs the agent to end its response with a question asking you to confirm before applying any fix.

If you ask for read-only or no-command work, the skill tells the agent not to run shell, Python or gcloud commands and to give you the commands to run yourself. When live access is unavailable and the instance is not one of the fictional sample instances, the skill says live access is required rather than guessing.

• Runs scripts and uses the network: review the files before use.
• Remediation requires explicit user confirmation.
• Use write roles only when you intend to remediate.
• Sample data in references/mock-fleet-data.md is fictional and must not be treated as real state.