Skip to content
Get packs

Guide · Agent skill

How to use the GKE Storage Troubleshooting agent skill

Updated · written with AI from the project's own documentation and checked against our catalogue data

The gke-storage-troubleshooting skill is a guided runbook that an AI agent follows when a workload on Google Kubernetes Engine (GKE) has a persistent-storage failure. It covers pods stuck in ContainerCreating, volumes that fail to attach or mount, disk performance and node storage pressure, and related errors. This guide is for platform and DevOps engineers who are new to agent skills, and by the end you will know how to install the skill, ask for help with natural requests, and understand what the agent will and will not change.

GKE Storage Troubleshootinggoogle/skills · Apache-2.0

Quick start

  1. 1Download the skill ZIP. Download the ZIP for gke-storage-troubleshooting from the skill's page on this directory.
  2. 2Install the skill. Unzip it into ~/.claude/skills/ for personal use, into .claude/skills/ in a project, or upload the ZIP under Settings → Capabilities → Skills in the Claude apps.
  3. 3Prepare cluster access. Make sure gcloud can reach the target project and that kubectl has a configured context for the cluster. Fetch credentials with gcloud container clusters get-credentials if needed.
  4. 4Describe the failure. Ask the agent in plain language, giving the project, cluster, namespace, pod or PVC name, and the symptom you see.
  5. 5Review the diagnosis. Check which symptom branch the agent chose and the read-only commands it ran before accepting its conclusion.
  6. 6Apply the fix through GitOps. Take the proposed configuration correction into your GitOps workflow and have a person apply it, rather than changing live resources directly.

What does the GKE Storage Troubleshooting skill make the agent do?

An agent skill is a folder of instructions and supporting files that an AI agent loads when a task matches the skill's description. This one contains a structured playbook for GKE storage problems. It covers pods stuck in ContainerCreating, volumes that fail to attach or mount, disk performance and node storage pressure, volume expansion not showing inside containers, Local SSD or Hyperdisk creation errors, and Cloud Storage FUSE out-of-memory events.

The agent first gathers cluster details, then runs read-only kubectl and gcloud diagnostics, classifies the symptom, and applies only the fix branch that matches. If the cluster cannot be reached, it gives the exact commands for a person to run and proposes a configuration correction instead.

  • Pods stuck in ContainerCreating with attach or mount events
  • Volumes that fail to attach or mount, including Regional PD on optimized VMs and fsGroup mount timeouts
  • Disk performance problems and StoragePressureDetected or PLEG events on nodes
  • Volume expansion not reflected inside the container
  • Local SSD and Hyperdisk Storage Pool creation errors
  • Cloud Storage FUSE sidecar out-of-memory events

What do you need before you install the skill?

The skill assumes you already have access to the cluster. It needs the gcloud CLI with access to the target Google Cloud project, and kubectl with a configured context for the cluster. The agent also needs access to GKE cluster credentials, which it fetches with gcloud container clusters get-credentials.

The skill is licensed under Apache-2.0. It is specific to GKE and gcloud, so it does not apply to non-GKE Kubernetes clusters or to other clouds.

  • gcloud CLI with access to the target Google Cloud project
  • kubectl with a configured context for the cluster
  • Access to GKE cluster credentials
gcloud container clusters get-credentials {cluster_name} --location {cluster_location} --project {project_id}

How do you install the GKE Storage Troubleshooting skill?

Download the ZIP file for the skill from the skill's page on this directory. Unzip it so that the skill folder, which contains SKILL.md and a references folder, sits in one of the skills locations below. Use the personal location to make the skill available across your projects, or use a project location to share it with one repository.

If you use the Claude apps instead, you can upload the ZIP under Settings, then Capabilities, then Skills, rather than placing files on disk.

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

How do you trigger the skill with a natural request?

You do not need to name the skill. The agent loads it when your request matches its description, which covers pods stuck in ContainerCreating, volumes that fail to attach or mount, and nodes reporting storage pressure. Give the agent as much context as you have, such as the project, cluster, location, namespace, pod name, PVC or PV name, or node name. If you leave the namespace out, the agent uses default.

Phrase the request around the symptom you see, not the fix you want. The agent will classify the symptom itself.

  • My pod checkout-db-0 in namespace payments has been stuck in ContainerCreating for 20 minutes. The events mention an attach error. Project is my-project, cluster is prod-gke in us-central1.
  • Nodes in pool storage-pool are reporting StoragePressureDetected. Help me find out why.
  • After I resized the PVC from 100Gi to 200Gi, the filesystem inside my container still shows the old size. What is going on?
  • My Cloud Storage FUSE sidecar keeps getting OOM killed. Diagnose it.

How does the agent work through a storage incident?

The agent extracts the parameters it needs from your message and its environment, then tries to fetch cluster credentials. Its first diagnostic step is to inspect the pod, the PVCs and PVs, the namespace events, and the node. Based on those signals, it picks the one branch that matches, such as the Volume Attach and Mount Failures branch, and does not run the others.

If live commands fail because the cluster is unreachable or does not exist, the agent limits its retries. It then lists the diagnostic commands for you to run, works out a likely root cause from the symptoms you reported, and proposes a configuration change.

  • Attach and mount failures include Regional PD on optimized machine types, where it suggests a non-regional PD StorageClass or taints and tolerations to separate node pools.
  • Persistent Disk on N4, N4A or N4D nodes is not supported, so the agent points to a Hyperdisk StorageClass or a PD-capable machine series such as N2.
  • Mixed machine generations can use a dynamic StorageClass so GKE selects a compatible disk type per node.
  • An fsGroup setting on a volume with many files can make the kubelet time out while changing ownership, which the skill also covers.

What are the safety notes for scripts and network use?

This skill runs scripts and uses the network. Its diagnostics are read-only, and it is designed to propose manifest or configuration corrections rather than apply them. The skill says those corrections should be applied through GitOps by a person, because a wrong fix could affect live data. Do not use the skill for unattended production changes.

The skill also asks the agent to tag its gcloud calls for usage attribution. It sets the CLOUDSDK_METRICS_REQUEST_ATTRIBUTION variable inline on each terminal command, and does not use gcloud config set, so the tag does not persist into unrelated work.

  • Diagnostics are read-only, so review any command before you approve it.
  • Corrections are proposed for GitOps review, not applied directly.
  • Use the separate gke-storage skill for routine provisioning and writing StorageClass and PVC manifests.
CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:gke-storage-troubleshooting)" gcloud <command> [flags]

What people use it for

  • Finding out why a StatefulSet pod stays in ContainerCreating after a node pool change
  • Checking whether a Regional PD request conflicts with optimized machine types in a node pool
  • Working out why a resized PVC does not show the new size inside a running container
  • Diagnosing Cloud Storage FUSE sidecar out-of-memory kills during a storage incident
  • Getting a written list of diagnostic commands for an on-call colleague when the cluster is unreachable from your machine

Frequently asked questions

How do I install the GKE storage troubleshooting skill?

Download the ZIP from this directory's skill page and unzip it into ~/.claude/skills/ for personal use or into .claude/skills/ in a project. In the Claude apps you can instead upload the ZIP under Settings, then Capabilities, then Skills.

What do I need to run the skill?

You need the gcloud CLI with access to the target Google Cloud project, kubectl with a configured context for the cluster, and access to GKE cluster credentials. The skill fetches credentials with gcloud container clusters get-credentials.

Is the GKE Storage Troubleshooting skill free?

The skill is licensed under Apache-2.0. This page does not state pricing for Google Cloud or the agent tool you use, so check those services for their own costs.

Does the skill change my cluster automatically?

No. The diagnostics are read-only, and the skill proposes manifest or configuration corrections to be applied through GitOps. It is not meant for unattended production changes, because a wrong fix could affect live data.

What if the agent cannot connect to my cluster?

The skill switches to fallback mode. It lists the exact kubectl and gcloud commands for a person to run, works out a likely root cause from the symptoms you describe, and proposes a configuration correction.

Can I use this skill for non-GKE Kubernetes or for creating StorageClasses?

No. The guidance is specific to GKE and gcloud, so it does not cover non-GKE clusters or other clouds. For routine provisioning and writing StorageClass and PVC manifests, the source points to the separate gke-storage skill.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

This skill suits platform and DevOps engineers who run stateful workloads on GKE and want a guided, read-only runbook for storage incidents. It is a poor fit if you need routine provisioning, non-GKE clusters, or an agent that makes unattended production changes; use the gke-storage skill for provisioning work instead.

Download the skill