k8s-debug_skill

Overview

This skill is a comprehensive Kubernetes debugging and troubleshooting toolkit for diagnosing cluster, node, pod, network, storage, and deployment issues. It bundles diagnostic scripts, workflows, and command patterns to quickly gather evidence, narrow root causes, and apply targeted fixes. Use it to standardize incident response and capture reproducible diagnostics for analysis.

How this skill works

The toolkit runs layered diagnostics from pod-level to cluster-level: pod diagnostics collect status, events, logs and resource usage; network checks validate DNS, endpoints and network policies; and cluster health scripts enumerate node conditions, failed pods, PVC/PV states and control-plane component health. It also provides step-by-step workflows and a common-issues database to guide remediation and verification.

When to use it

• Pod failures such as CrashLoopBackOff, ImagePullBackOff, Pending, or OOMKilled
• Service connectivity, DNS resolution, or ingress failures
• Network policy or pod-to-pod connectivity investigations
• Volume mount, PVC binding, or storage access problems
• Deployment rollouts stuck, rollback or restart scenarios
• Cluster health checks and resource exhaustion or performance degradation

Best practices

• Follow a systematic workflow: observe, analyze, hypothesize, test, fix, verify, document
• Collect and save diagnostic outputs (logs, describe, script output) before restarting or deleting resources
• Use ephemeral debug containers and port-forwarding to replicate and test connectivity from inside the cluster
• Apply fixes incrementally and test in non-production environments before rolling out cluster-wide changes
• Set resource requests/limits, health probes, and monitoring/alerting to prevent common failures

Example use cases

• Run pod_diagnostics.py to collect pod description, events, current and previous logs, node info and resource usage for a crashing pod
• Execute cluster_health.sh to create a snapshot of node status, failing pods, component health, PVC/PV states and recent events for incident postmortem
• Use network_debug.sh plus a debug pod (netshoot) to reproduce DNS failures and verify service endpoints from within the namespace
• Follow the CrashLoopBackOff workflow: gather logs, check liveness/readiness probes, inspect image and environment variables, then test fixes in a debug copy of the pod
• Port-forward a pod or service to your workstation to test API or app endpoints during a rolling update