kubernetes-troubleshoot

timbuchinger's avatarfrom timbuchinger

Troubleshoot and manage Kubernetes clusters, including resource inspection, debugging, pod logs, events, and cluster operations. Use when the user needs to diagnose issues, inspect workloads, analyze pod failures, or perform Kubernetes cluster operations.

⭐0stars🔀0forks📁View on GitHub🕐Updated Dec 28, 2025
[Incident Response]

When & Why to Use This Skill

This Claude skill provides a comprehensive toolkit for managing and troubleshooting Kubernetes clusters. It enables users to inspect resources, retrieve pod logs, analyze cluster events, and diagnose workload failures like CrashLoopBackOff. By prioritizing MCP tools and falling back to kubectl, it ensures safe, efficient, and context-aware cluster operations, making it an essential asset for SREs and DevOps engineers.

Use Cases

  • Diagnosing Pod Failures: Rapidly identify the root cause of issues such as CrashLoopBackOff, ImagePullBackOff, or pending pods by analyzing resource conditions and events.
  • Cluster Resource Inspection: List and describe pods, deployments, services, and nodes across multiple namespaces to maintain visibility into cluster health.
  • Log Analysis and Debugging: Retrieve real-time logs from specific containers to troubleshoot application errors and performance bottlenecks.
  • Multi-Cluster Management: Safely perform operations across different environments by managing kubeconfig contexts and ensuring commands are scoped to the correct cluster.
  • Step-by-Step Incident Resolution: Follow recommended debugging sequences—from listing resources to inspecting configurations—to resolve infrastructure incidents systematically.
namekubernetes-troubleshoot
description"Troubleshoot and manage Kubernetes clusters, including resource inspection, debugging, pod logs, events, and cluster operations. Use when the user needs to diagnose issues, inspect workloads, analyze pod failures, or perform Kubernetes cluster operations."

Kubernetes Troubleshooting & Management Skill

What this Skill does

Use this skill when the user needs to troubleshoot or manage Kubernetes clusters. This includes operations such as:

  • Listing pods, deployments, namespaces, nodes
  • Getting pod logs
  • Fetching events for a resource
  • Inspecting workloads and resource conditions
  • Understanding CrashLoopBackOff, ImagePullBackOff, pending pods
  • Multi-cluster interactions through kubeconfig contexts
  • Suggesting next debugging steps

Tool Preference: MCP First, kubectl as Fallback

Preferred Method: Use the Kubernetes MCP server when available

  • MCP tools allow pre-approved operations for faster execution
  • More efficient for common read operations
  • Built-in safety guardrails

Fallback Method: Use kubectl commands via terminal when:

  • MCP server is not available or fails
  • MCP cannot provide the information needed
  • Specific kubectl features are required (port-forward, plugins, etc.)

This skill helps Claude:

  • Choose the appropriate tool based on availability and capabilities
  • Restrict queries to namespace/cluster automatically
  • Ask for confirmation before destructive actions
  • Recommend stepwise debugging strategies
  • Provide safe, context-efficient responses

Best Practices

1. Always scope operations

  • Include namespace unless user explicitly wants cluster-wide.
  • Include context when user has multiple clusters.
  • Encourage label selectors instead of listing all resources.

2. Prefer read-only operations first

Recommended sequence for debugging:

  1. List pods matching a selector
  2. Describe pod
  3. Fetch pod events
  4. Retrieve logs
  5. Inspect configmaps/secrets/environment
  6. Only then consider restart/delete/scale

4. Tool Usage Guidelines

When using MCP (preferred): Examples of safe MCP-driven operations:

  • List Pods: list pods --namespace=<ns> --context=<cluster>
  • Get Pod Logs: logs --namespace=<ns> --pod=<pod>
  • Get Events: get events --namespace=<ns> --field-selector=involvedObject.name=<name>
  • Inspect Deployment: get deployment <name> --namespace=<ns>

When using kubectl (fallback):

  • Always specify namespace with -n <namespace> or --namespace=<namespace>

  • Use --context when multiple clusters are configured

  • Consider using -o yaml or -o json for detailed inspection

  • Use kubectl explain for resource documentation

  • List Pods

    • list pods --namespace=<ns> --context=<cluster>

  • Get Pod Logs

    • logs --namespace=<ns> --pod=<pod>

  • Get Events

    • get events --namespace=<ns> --field-selector=involvedObject.name=<name>

  • Inspect Deployment

    • get deployment <name> --namespace=<ns>

5. Multi-Cluster Awareness

If multiple contexts exist:

  • Always request or infer the correct context.
  • Avoid ambiguous commands that default to the wrong cluster.
User wants Preferred (MCP) Fallback (kubectl)
"List pods in frontend namespace" list pods --namespace=frontend kubectl get pods -n frontend
"Show me events for api-server" get events --namespace=<ns> --field-selector=involvedObject.name=api-server kubectl get events -n <ns> --field-selector involvedObject.name=api-server
"Get logs for db-0" logs --namespace=<ns> --pod=db-0 kubectl logs -n <ns> db-0
"Why is pod web-123 CrashLooping?" List pod → describe → events → logs (stepwise) kubectl describe pod -n <ns> web-123, then logs
"Restart worker deployment" Ask confirmation → delete pods or rollout restart if supported kubectl rollout restart deployment/<name> -n <ns>

Tool Limitations

MCP Limitations:

  • Some advanced operations may not be available (port-forward, plugin commands)
  • Complex manifest edits may require kubectl fallback

kubectl Limitations:

  • Requires user approval for each command
  • Less efficient for multiple sequential operations
  • No pre-approval mechanisms) may not be available
  • Complex edits to manifests may require manual patching