k8s-troubleshoot_skill

Overview

This skill is a Kubernetes troubleshooting toolkit that helps you find pods by labels and run diagnostic commands inside container(s). It is designed for rapid diagnosis of service errors, crashes, timeouts, and resource or network problems in Kubernetes clusters. Use it to inspect logs, processes, network sockets, and resource usage without leaving your CLI.

How this skill works

First it searches the cluster for pods matching a label selector and returns structured JSON with pod names, namespaces, phases, and containers. Then it executes user-provided shell commands inside a chosen pod container and returns the command output in JSON. The workflow enables scripted checks (logs, ps, netstat, df/free) and ad-hoc interactive diagnostics.

When to use it

• User reports service errors, exceptions, crashes, or timeouts
• You need to tail or inspect application logs inside a pod
• Verify process status or application health within a container
• Diagnose network connectivity or listening ports in a pod
• Check disk space, memory usage, or OOM-related issues

Best practices

• Use precise label selectors to limit returned pods and avoid noisy results
• Run read-only diagnostic commands by default; avoid destructive commands in production
• Specify the container when pods are multi-container to target the right runtime
• Combine search and exec in scripts for repeatable checks and alerts
• Capture and store JSON outputs for post-mortem analysis and sharing with teams

Example use cases

• Find all nginx pods in a namespace: search pods by label and inspect phases and containers
• Tail recent application logs to identify errors: exec into pod and run tail -n 100 on the log file
• Verify process list when a service is unresponsive: run ps aux inside the container
• Check network listeners for connection problems: exec netstat -tlnp to confirm ports are bound
• Quick resource checks for suspected OOMs: run df -h && free -m inside the pod to inspect disk and memory