diagnose-storage-issue

X-McKay's avatarfrom X-McKay

Diagnose storage and persistent volume issues. Checks PVC binding, storage class configuration, and volume mount status. Use when pods are stuck pending due to volume issues. Keywords: PVC, PV, storage, volume, pending, mount, storage class.

⭐1stars🔀0forks📁View on GitHub🕐Updated Jan 11, 2026
[Incident Response]

When & Why to Use This Skill

This Claude skill automates the diagnosis of Kubernetes storage and Persistent Volume (PV) issues. It streamlines troubleshooting for pods stuck in a 'Pending' state by systematically verifying PVC bindings, StorageClass configurations, and volume mount statuses, helping SREs and DevOps engineers identify infrastructure root causes quickly.

Use Cases

  • Troubleshooting Kubernetes pods stuck in 'Pending' status due to volume binding failures or missing PersistentVolumes.
  • Verifying PersistentVolumeClaim (PVC) status and identifying mismatches between claims and available storage resources in a specific namespace.
  • Validating StorageClass configurations and availability to ensure successful dynamic volume provisioning across the cluster.
  • Analyzing Kubernetes events and pod volume mounts to pinpoint the root cause of storage-related deployment failures during incident response.
namediagnose-storage-issue
description>
due to volume issues. KeywordsPVC, PV, storage, volume, pending, mount,
domaink8s
categorydiagnostic
requires-approvalfalse
confidence0.8

Diagnose Storage Issue

Preconditions

Before applying this skill, verify:

  • PVC name or pod name is known
  • Namespace is specified
  • Storage issue symptoms observed

Actions

1. Get PVC Status

Check PersistentVolumeClaim binding status.

mcp_tool: kubernetes-mcp-server/resources_get
params:
  apiVersion: v1
  kind: PersistentVolumeClaim
  name: $pvc_name
  namespace: $namespace
timeout: 30s

2. Get PV Details

Check bound PersistentVolume if exists.

mcp_tool: kubernetes-mcp-server/resources_list
params:
  apiVersion: v1
  kind: PersistentVolume
timeout: 30s

3. Check Storage Classes

Verify storage class exists and is configured.

mcp_tool: kubernetes-mcp-server/resources_list
params:
  apiVersion: storage.k8s.io/v1
  kind: StorageClass
timeout: 30s

4. Get Pod Volume Mounts

Check pod's volume mount status.

mcp_tool: kubernetes-mcp-server/pods_get
params:
  name: $pod_name
  namespace: $namespace
timeout: 30s

5. Check Events

Look for storage-related events.

mcp_tool: kubernetes-mcp-server/events_list
params:
  namespace: $namespace
timeout: 30s

Success Criteria

The skill succeeds when:

  • PVC status determined (Bound/Pending/Lost)
  • Storage class availability confirmed
  • Root cause identified

Failure Handling

If storage issue cannot be resolved:

  1. Check CSI driver logs
  2. Verify node has available storage
  3. Escalate with volume details

Examples

Input Context:

{
  "pvc_name": "data-volume",
  "namespace": "default",
  "pod_name": "db-pod-abc123"
}

Output:

{
  "pvc_status": "Pending",
  "pv_bound": false,
  "storage_class": "local-path",
  "diagnosis": "No available PV matching storage class requirements",
  "recommendation": "Create PV with matching storage class or use dynamic provisioning"
}