Kubernetes Troubleshooting with Inspektor Gadget

What it does

When your agent uses it

• Pods failing with DNS errors, connection resets or refused connections
• Finding out which pod or process opened a file, made a syscall or ran a command
• Diagnosing CrashLoopBackOff, OOMKilled or permission and seccomp denials
• Looking into slow disk or file I/O in a running workload

Example prompts

• “The checkout pod gets connection resets to the database; trace the TCP drops with Inspektor Gadget.”
• “Which pod is making the DNS queries that fail in the payments namespace?”
• “My container hits no such file or directory at startup but logs nothing; trace its file opens.”

Requirements

• The kubectl gadget plugin installed locally
• An Inspektor Gadget DaemonSet in the cluster (namespace gadget)
• Troubleshooting RBAC and nodes with BTF for CO-RE
• Compatibility (from SKILL.md): Requires the `kubectl gadget` plugin locally and an in-cluster Inspektor Gadget DaemonSet (`kubectl gadget deploy`, namespace `gadget`), on a cluster where you hold troubleshooting RBAC and nodes with BTF for CO-RE. Read-only. If the plugin or DaemonSet is missing, see references/install.md — ask the operator before installing.

Workflow steps

4 steps, taken from the first numbered list in SKILL.md.

1. 1Route. Map the symptom to a domain (networking / security /
2. 2Discover. Run :latest -h to read the real flags and fields.
3. 3Run bounded. Always scope and time-box
4. 4Read the columns. Inspect the enriched fields (k8s.*, proc.*, error

What it can do on your machine

Read from SKILL.md and the folder at commit b6dce71. It shows what the files ask for, not the result of running them.

• Tool permissions

  Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

  From allowed-tools in the SKILL.md frontmatter.

• Runs code

  Shell commands in SKILL.md call:

  • kubectl
  • jq

  From the folder's file list and the shell code blocks in SKILL.md.

• Network

  No URLs in SKILL.md. Its commands use kubectl, which can reach the network depending on how they are called.

  From URLs in SKILL.md, links to its own repository left out.

• Credentials

  Names no API keys, tokens, secrets or passwords.

  From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

• Compatibility

  Requires the `kubectl gadget` plugin locally and an in-cluster Inspektor Gadget DaemonSet (`kubectl gadget deploy`, namespace `gadget`), on a cluster where you hold troubleshooting RBAC and nodes with BTF for CO-RE. Read-only. If the plugin or DaemonSet is missing, see references/install.md — ask the operator before installing.

  From compatibility in the SKILL.md frontmatter.

Context cost

Kubernetes Troubleshooting with Inspektor Gadget loads about 2.3k tokens when it runs, and up to ~15k if it reads all its reference files. Until then it costs about 187 tokens; SKILL.md has 882 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it

~187

When it runs · the whole SKILL.md, loaded when a task matches

~2.3k

With references · SKILL.md plus every file in references/, read only if the agent opens them

~15k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from inspektor-gadget/inspektor-gadget at commit b6dce71, republished under its Apache-2.0 licence (© inspektor-gadget). 882 words, ~2,258 tokens.

name

kubernetes-troubleshooting

description

Debug live Kubernetes workloads at the kernel level with Inspektor Gadget via `kubectl gadget run`. Use when a pod or Service is misbehaving and application logs are not enough: DNS resolution failures or slow lookups, TCP connection resets / retransmits / drops / refused connections, CrashLoopBackOff, "no such file or directory", permission / capability / seccomp / LSM denials, OOMKilled, unexpected process execs, slow disk or file I/O, or "which pod/process made this syscall / connection / DNS query". Traces real kernel events with eBPF, auto-enriched with pod / namespace / container / node. Read-only, no workload changes. Not for plain application logs, long-term metrics dashboards, or editing cluster state.

compatibility

Requires the `kubectl gadget` plugin locally and an in-cluster Inspektor Gadget DaemonSet (`kubectl gadget deploy`, namespace `gadget`), on a cluster where you hold troubleshooting RBAC and nodes with BTF for CO-RE. Read-only. If the plugin or DaemonSet is missing, see references/install.md — ask the operator before installing.

command -v kubectl-gadget >/dev/null 2>&1 || echo "kubectl gadget plugin MISSING"
kubectl gadget version    # "Server version: not available" = inspect the gadget namespace

kubectl gadget run <gadget>:latest -h          # flags + a "--fields" block listing every data source & field
kubectl gadget run <gadget>:latest -A --timeout 5 -o json \
  | jq -s '(.[0] // {}) | if type == "array" then (.[0] // {}) else . end | keys'

© inspektor-gadget, Apache-2.0. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 10 other files (references) in skills/kubernetes-troubleshooting of inspektor-gadget/inspektor-gadget.

• SKILL.md
• references/common-flags.md
• references/discovering-params-and-fields.md
• references/domain-networking.md
• references/domain-performance.md
• references/domain-process-lifecycle.md
• references/domain-security.md
• references/domain-storage-fs.md
• references/gadget-catalog.md
• references/install.md
• references/linux-companion.md

Open the folder on GitHubat commit b6dce71