Kubernetes Specialist
Structured investigation for Kubernetes workloads. Five phases: gather context, diagnose,
root-cause, recommend, verify.
Arguments
$0 — cluster context, namespace, problem description, or manifest path. Required.
Phase 1: Context Gathering
Establish what you are working with before touching any cluster.
- Glob for YAML/Helm templates in the working directory:
**/*.yaml, **/templates/**/*.yaml.
- Read
kustomization.yaml or Chart.yaml if present to understand the structure.
- If a cluster context is available, run:
kubectl config current-context
kubectl get nodes -o wide
kubectl get namespaces
- Note the namespace(s) in scope. Scope all subsequent commands to
--namespace <ns> to
avoid reading unrelated resources.
Phase 2: Diagnosis
Gather the signals that describe the current state.
For pod or workload issues:
kubectl get pods -n <ns> -o wide
kubectl describe pod <pod> -n <ns>
kubectl get events -n <ns> --sort-by=.lastTimestamp | tail -30
kubectl logs <pod> -n <ns> --previous --tail=100 # if CrashLoopBackOff
For networking issues:
kubectl get services -n <ns>
kubectl get ingress -n <ns>
kubectl get networkpolicies -n <ns>
For resource pressure:
kubectl top nodes
kubectl top pods -n <ns>
kubectl describe node <node> # check Conditions and Allocatable vs Requests
For RBAC issues:
kubectl auth can-i --list --as=system:serviceaccount:<ns>:<sa>
kubectl get rolebindings,clusterrolebindings -n <ns> -o wide
Phase 3: Root-Cause Analysis
For each signal found in Phase 2, trace to its cause:
| Symptom |
Common Causes |
Check |
Pending pod |
Insufficient resources, node selector, taint/toleration mismatch |
kubectl describe pod → Events |
CrashLoopBackOff |
App crash, misconfigured probe, missing env/secret |
kubectl logs --previous |
ImagePullBackOff |
Bad tag, registry auth, network policy blocking egress |
kubectl describe pod → Events |
OOMKilled |
Memory limit too low, memory leak |
kubectl describe pod → Last State |
| Service not routing |
Selector mismatch, port mismatch, NetworkPolicy blocking |
kubectl get endpoints |
| 5xx from Ingress |
Upstream pod not ready, probe too aggressive, readiness failing |
Ingress controller logs |
Cite resource/name or file:line for every finding.
Phase 4: Recommendations
Present findings as a prioritized list:
[CRITICAL] <title>
Resource: <kind/name> or <file:line>
Issue: <one sentence>
Evidence: <command output or manifest snippet>
Fix: <specific change>
[WARNING] <title>
...
[INFO] <title>
...
- Order: CRITICAL → WARNING → INFO.
- For each fix, explain the trade-off if there is a meaningful alternative.
- Reference relevant docs in
references/ where applicable.
Phase 5: Verification
After fixes are applied:
- Confirm pods reach
Running and pass readiness:kubectl rollout status deployment/<name> -n <ns>
kubectl get pods -n <ns> -w # watch for 30 s
- Check events are clean:
kubectl get events -n <ns> --sort-by=.lastTimestamp | tail -10
- Validate probes are passing — no
Liveness probe failed in events.
- For networking changes, confirm endpoints are populated:
kubectl get endpoints <service> -n <ns>
- For RBAC changes, re-run
kubectl auth can-i to confirm access is as expected.
Reference Docs
Consult references/ for decision guides:
| File |
When to use |
workload-types.md |
Choosing Deployment vs StatefulSet vs DaemonSet vs Job |
resource-sizing.md |
Setting requests/limits, VPA vs HPA |
networking.md |
Service types, Ingress, NetworkPolicy, DNS |
rbac.md |
Role design, ServiceAccount least-privilege |
storage.md |
PV/PVC, StorageClass, stateful workloads |
observability.md |
Probes, metrics, logging patterns |
security-hardening.md |
Pod security, admission control, image signing |
helm-patterns.md |
Chart structure, values, hook ordering |
ci-cd-integration.md |
GitOps, manifest generation in pipelines |
troubleshooting.md |
Failure modes and diagnostic commands |
deployment-strategies.md |
Rolling, blue/green, canary trade-offs |
1---2# dotbabel:generated projection=sha256:fb142e51962e06aff81c35b99b1eae2a8346efc07f919fafa1dedee1fb52dcfc source=skills/kubernetes-specialist/SKILL.md — do not edit directly3allowed-tools: Read Grep Glob Bash4argument-hint: <cluster context, namespace, or problem description>5description: |6 Deep-dive Kubernetes troubleshooting, workload design, and cluster health review. Use when you need a structured investigation of a cluster issue, a design review of Kubernetes manifests, or a health audit of a namespace or workload. Triggers on: "debug kubernetes", "why is my pod", "review my manifests", "cluster health", "kubernetes design review", "k8s audit".7name: kubernetes-specialist-38metadata:9 source: https://skillmd.com/skills/kaiohenricunha/kubernetes-specialist-310---1112# Kubernetes Specialist1314Structured investigation for Kubernetes workloads. Five phases: gather context, diagnose,15root-cause, recommend, verify.1617## Arguments1819- `$0` — cluster context, namespace, problem description, or manifest path. Required.2021---2223## Phase 1: Context Gathering2425Establish what you are working with before touching any cluster.26271. Glob for YAML/Helm templates in the working directory: `**/*.yaml`, `**/templates/**/*.yaml`.282. Read `kustomization.yaml` or `Chart.yaml` if present to understand the structure.293. If a cluster context is available, run:30 ```bash31 kubectl config current-context32 kubectl get nodes -o wide33 kubectl get namespaces34 ```354. Note the namespace(s) in scope. Scope all subsequent commands to `--namespace <ns>` to36 avoid reading unrelated resources.3738---3940## Phase 2: Diagnosis4142Gather the signals that describe the current state.4344**For pod or workload issues:**4546```bash47kubectl get pods -n <ns> -o wide48kubectl describe pod <pod> -n <ns>49kubectl get events -n <ns> --sort-by=.lastTimestamp | tail -3050kubectl logs <pod> -n <ns> --previous --tail=100 # if CrashLoopBackOff51```5253**For networking issues:**5455```bash56kubectl get services -n <ns>57kubectl get ingress -n <ns>58kubectl get networkpolicies -n <ns>59```6061**For resource pressure:**6263```bash64kubectl top nodes65kubectl top pods -n <ns>66kubectl describe node <node> # check Conditions and Allocatable vs Requests67```6869**For RBAC issues:**7071```bash72kubectl auth can-i --list --as=system:serviceaccount:<ns>:<sa>73kubectl get rolebindings,clusterrolebindings -n <ns> -o wide74```7576---7778## Phase 3: Root-Cause Analysis7980For each signal found in Phase 2, trace to its cause:8182| Symptom | Common Causes | Check |83| ------------------- | ---------------------------------------------------------------- | ----------------------------------- |84| `Pending` pod | Insufficient resources, node selector, taint/toleration mismatch | `kubectl describe pod` → Events |85| `CrashLoopBackOff` | App crash, misconfigured probe, missing env/secret | `kubectl logs --previous` |86| `ImagePullBackOff` | Bad tag, registry auth, network policy blocking egress | `kubectl describe pod` → Events |87| `OOMKilled` | Memory limit too low, memory leak | `kubectl describe pod` → Last State |88| Service not routing | Selector mismatch, port mismatch, NetworkPolicy blocking | `kubectl get endpoints` |89| 5xx from Ingress | Upstream pod not ready, probe too aggressive, readiness failing | Ingress controller logs |9091Cite `resource/name` or `file:line` for every finding.9293---9495## Phase 4: Recommendations9697Present findings as a prioritized list:9899```100[CRITICAL] <title>101Resource: <kind/name> or <file:line>102Issue: <one sentence>103Evidence: <command output or manifest snippet>104Fix: <specific change>105106[WARNING] <title>107...108109[INFO] <title>110...111```112113- Order: CRITICAL → WARNING → INFO.114- For each fix, explain the trade-off if there is a meaningful alternative.115- Reference relevant docs in `references/` where applicable.116117---118119## Phase 5: Verification120121After fixes are applied:1221231. Confirm pods reach `Running` and pass readiness:124 ```bash125 kubectl rollout status deployment/<name> -n <ns>126 kubectl get pods -n <ns> -w # watch for 30 s127 ```1282. Check events are clean:129 ```bash130 kubectl get events -n <ns> --sort-by=.lastTimestamp | tail -10131 ```1323. Validate probes are passing — no `Liveness probe failed` in events.1334. For networking changes, confirm endpoints are populated:134 ```bash135 kubectl get endpoints <service> -n <ns>136 ```1375. For RBAC changes, re-run `kubectl auth can-i` to confirm access is as expected.138139---140141## Reference Docs142143Consult `references/` for decision guides:144145| File | When to use |146| -------------------------- | ------------------------------------------------------ |147| `workload-types.md` | Choosing Deployment vs StatefulSet vs DaemonSet vs Job |148| `resource-sizing.md` | Setting requests/limits, VPA vs HPA |149| `networking.md` | Service types, Ingress, NetworkPolicy, DNS |150| `rbac.md` | Role design, ServiceAccount least-privilege |151| `storage.md` | PV/PVC, StorageClass, stateful workloads |152| `observability.md` | Probes, metrics, logging patterns |153| `security-hardening.md` | Pod security, admission control, image signing |154| `helm-patterns.md` | Chart structure, values, hook ordering |155| `ci-cd-integration.md` | GitOps, manifest generation in pipelines |156| `troubleshooting.md` | Failure modes and diagnostic commands |157| `deployment-strategies.md` | Rolling, blue/green, canary trade-offs |