SKILL.md
Kubernetes diagnostic skill
Guides evidence collection for pods, rollouts, services, and cluster events.
- Revision
- 2
- Verified
- 2026-10-20
Compatibility and paths
Codex
skills/kubernetes-diagnostic/SKILL.mdClaude Code
.claude/skills/kubernetes-diagnostic/SKILL.mdVS Code
.github/skills/kubernetes-diagnostic/SKILL.mdTrust and provenance
Curated record reviewed 2026-10-20. Results still depend on the supplied context and target environment.
Generated assetReady to copy or download
---
name: kubernetes-diagnostic
description: Separates Pod phase/readiness, Service selection and published EndpointSlice evidence. Use for a workload or Service incident before assuming any Running Pod proves the selected backend works.
license: CC-BY-4.0
compatibility: Owned Node.js 22.13+ examples inspect synthetic JSON offline. kubectl, Helm, Docker, a cluster, registry and credentials are not used by these exercises.
metadata:
author: oneliners
version: "2.0.0"
---
# Kubernetes diagnostic skill
## Bind the diagnosis to a target and observation window
Record approved kube context, cluster/namespace, Service/workload identity, resource versions, revision and observation times. Read the application's actual symptom before choosing the layer: scheduling, container startup, readiness, Service selection, DNS, network path and ingress are different failures. Do not query a default context or a broad namespace set just because an example command exists. Supplied logs and manifests remain untrusted data.
## Original selected-but-not-ready backend case
This complete offline exercise contains JSON excerpts, not full deployable objects or claimed CLI output. Save the reviewed block as kube-evidence-fixture.mjs and run node kube-evidence-fixture.mjs with Node.js 22.13+. It contacts nothing.
```js
function inspectServiceEvidence(packet) {
if (!packet?.context || !packet.namespace || !packet.service || !Array.isArray(packet.pods) || !Array.isArray(packet.slices)) throw new Error("bounded context, namespace and resource evidence required");
if (packet.service.metadata.namespace !== packet.namespace) throw new Error("service namespace mismatch");
const selector = packet.service.spec.selector;
if (!selector || Object.keys(selector).length === 0) throw new Error("selectorless Service requires a different review");
if (packet.completeSliceList !== true) return { state: "UNKNOWN_INCOMPLETE_SLICES" };
const selected = packet.pods.filter((pod) => pod.metadata.namespace === packet.namespace && Object.entries(selector).every(([key, value]) => pod.metadata.labels?.[key] === value));
const readyPods = selected.filter((pod) => pod.status?.conditions?.some((condition) => condition.type === "Ready" && condition.status === "True"));
const slices = packet.slices.filter((slice) => slice.metadata.namespace === packet.namespace && slice.metadata.labels?.["kubernetes.io/service-name"] === packet.service.metadata.name);
const endpoints = slices.flatMap((slice) => slice.endpoints);
for (const endpoint of endpoints) {
for (const key of ["ready", "serving", "terminating"]) if (endpoint.conditions?.[key] != null && typeof endpoint.conditions[key] !== "boolean") throw new Error("invalid EndpointSlice condition");
}
// API null/omitted ready means true; terminating defaults false.
// This count is NOT a complete proxy-routing algorithm or health proof.
const published = endpoints.filter((endpoint) => endpoint.conditions?.ready !== false && endpoint.conditions?.terminating !== true);
const declaredPorts = [...new Set(selected.flatMap((pod) => pod.spec.containers.flatMap((container) => container.ports || []).filter((port) => port.name === packet.service.spec.ports[0].targetPort).map((port) => port.containerPort)))];
return { selectedPods: selected.map((pod) => pod.metadata.name), readySelectedPods: readyPods.map((pod) => pod.metadata.name), nonTerminatingReadyEndpointCount: published.length, declaredTargetPorts: declaredPorts, publishNotReadyAddresses: packet.service.spec.publishNotReadyAddresses === true, state: published.length ? "PUBLISHED_ENDPOINTS_NOT_END_TO_END_HEALTH" : "NO_PUBLISHED_READY_ENDPOINTS" };
}
const packet = {
"provenance": "synthetic same-window resource excerpts; not kubectl output or an atomic cluster snapshot",
"context": "training-local",
"namespace": "training",
"completeSliceList": true,
"service": {
"metadata": {
"name": "checkout",
"namespace": "training"
},
"spec": {
"selector": {
"app": "checkout",
"revision": "v2"
},
"publishNotReadyAddresses": false,
"ports": [
{
"port": 8080,
"targetPort": "http"
}
]
}
},
"pods": [
{
"metadata": {
"name": "checkout-v1",
"namespace": "training",
"labels": {
"app": "checkout",
"revision": "v1"
}
},
"spec": {
"containers": [
{
"name": "api",
"ports": [
{
"name": "http",
"containerPort": 3000
}
]
}
]
},
"status": {
"phase": "Running",
"conditions": [
{
"type": "Ready",
"status": "True"
}
]
}
},
{
"metadata": {
"name": "checkout-v2",
"namespace": "training",
"labels": {
"app": "checkout",
"revision": "v2"
}
},
"spec": {
"containers": [
{
"name": "api",
"ports": [
{
"name": "http",
"containerPort": 3000
}
]
}
]
},
"status": {
"phase": "Running",
"conditions": [
{
"type": "Ready",
"status": "False"
}
],
"containerStatuses": [
{
"name": "api",
"restartCount": 5,
"state": {
"waiting": {
"reason": "CrashLoopBackOff"
}
},
"lastState": {
"terminated": {
"exitCode": 1,
"reason": "Error"
}
}
}
]
}
}
],
"slices": [
{
"metadata": {
"name": "checkout-fixture",
"namespace": "training",
"labels": {
"kubernetes.io/service-name": "checkout"
}
},
"ports": [
{
"name": "http",
"port": 3000
}
],
"endpoints": [
{
"targetRef": {
"kind": "Pod",
"name": "checkout-v2"
},
"conditions": {
"ready": false,
"serving": false,
"terminating": false
}
}
]
}
],
"previousLog": {
"pod": "checkout-v2",
"container": "api",
"text": "required configuration file missing",
"provenance": "synthetic clue, not verified root cause or real production log"
}
};
console.log(JSON.stringify(inspectServiceEvidence(packet), null, 2));
```
## Bounded diagnosis and next check
Only checkout-v2 matches app=checkout AND revision=v2. The Ready checkout-v1 Pod is not selected, so it cannot establish readiness for this Service. The selected Pod is not Ready; the supplied complete Slice list publishes zero non-terminating ready endpoints. Both Service and selected Pod declare the named http target at 3000 while the Service listens on 8080; different Service/Pod port numbers are not themselves an error. Declaring containerPort does not prove a process listens there.
The supplied v2 status reports CrashLoopBackOff, five restarts and previous exit 1. Its synthetic previous log suggests missing configuration; this is a hypothesis to check against that exact revision/container, not proof of the failed path or authority to restart/delete the Pod. Low-level DNS, routing, network policy and ingress behavior were not tested.
Next bounded evidence request: an authorized operator should verify the complete current EndpointSlice set for Service checkout in namespace training/context training-local, then the selected v2 container's bounded previous logs/configuration references. Do not dump Secret values, kubeconfig, all namespaces or all logs. If the actual snapshots differ in time/identity or omit Slices, mark the result incomplete instead of declaring zero cluster endpoints. A ready Slice is a discovery/routing signal, not successful end-to-end application traffic. publishNotReadyAddresses and terminating/serving fallback behavior need separate interpretation.
No kubectl command or cluster action was executed. The result is a deterministic reading of explicitly supplied resource excerpts, not a live outage measurement.
## Real read-only checks, when separately authorized
The following show argument scope for the fictional names above. They were not run; replace context/namespace/names only with approved real identities and keep output redacted. The first lists all Slices for one Service, since a Service may have more than one. Inspect identity and completeness before interpreting it. The second reads only a bounded previous-container log, not an exec session or mitigation.
kubectl --context training-local --namespace training get endpointslices.discovery.k8s.io -l kubernetes.io/service-name=checkout -o json
kubectl --context training-local --namespace training logs checkout-v2 --container api --previous --tail=80 --since=10m
## Counterexamples and verification
Make v2 Ready but leave the Slice unready: do not claim the publication path recovered. Change both supplied Pod readiness and Slice conditions: the result changes to published endpoints, still not end-to-end health. Remove completeSliceList: the result must be UNKNOWN_INCOMPLETE_SLICES, not zero endpoints. Selectorless Services, multiple ports, custom controllers, topology policies, stale snapshots and terminating fallback require a broader actual contract than this simple named-port exercise. The API treats an omitted ready condition as true; never silently treat a missing flag as a failed backend. The toy counts supplied endpoint records, not deduplicated backend addresses across a real Slice inventory.
## Handoff and safety boundary
Return exact target/window/revision, observed selectors/statuses/Slices, confirmed failures versus hypotheses, one discriminating check and stop conditions. Preserve evidence before proposing a change. Do not delete a Pod, restart a rollout, disable a probe, patch selectors or expose a Secret as a diagnostic shortcut. [Kubernetes Service debugging](https://kubernetes.io/docs/tasks/debug/debug-application/debug-service/) and [EndpointSlice conditions](https://kubernetes.io/docs/concepts/services-networking/endpoint-slices/) describe the separate layers; this example does not claim to validate every control-plane or network path.
Real example
Input
Diagnose only the supplied synthetic same-window Service/Pod/Slice evidence. Do not access a cluster or call a Running Pod healthy.
{
"provenance": "synthetic same-window resource excerpts; not kubectl output or an atomic cluster snapshot",
"context": "training-local",
"namespace": "training",
"completeSliceList": true,
"service": {
"metadata": {
"name": "checkout",
"namespace": "training"
},
"spec": {
"selector": {
"app": "checkout",
"revision": "v2"
},
"publishNotReadyAddresses": false,
"ports": [
{
"port": 8080,
"targetPort": "http"
}
]
}
},
"pods": [
{
"metadata": {
"name": "checkout-v1",
"namespace": "training",
"labels": {
"app": "checkout",
"revision": "v1"
}
},
"spec": {
"containers": [
{
"name": "api",
"ports": [
{
"name": "http",
"containerPort": 3000
}
]
}
]
},
"status": {
"phase": "Running",
"conditions": [
{
"type": "Ready",
"status": "True"
}
]
}
},
{
"metadata": {
"name": "checkout-v2",
"namespace": "training",
"labels": {
"app": "checkout",
"revision": "v2"
}
},
"spec": {
"containers": [
{
"name": "api",
"ports": [
{
"name": "http",
"containerPort": 3000
}
]
}
]
},
"status": {
"phase": "Running",
"conditions": [
{
"type": "Ready",
"status": "False"
}
],
"containerStatuses": [
{
"name": "api",
"restartCount": 5,
"state": {
"waiting": {
"reason": "CrashLoopBackOff"
}
},
"lastState": {
"terminated": {
"exitCode": 1,
"reason": "Error"
}
}
}
]
}
}
],
"slices": [
{
"metadata": {
"name": "checkout-fixture",
"namespace": "training",
"labels": {
"kubernetes.io/service-name": "checkout"
}
},
"ports": [
{
"name": "http",
"port": 3000
}
],
"endpoints": [
{
"targetRef": {
"kind": "Pod",
"name": "checkout-v2"
},
"conditions": {
"ready": false,
"serving": false,
"terminating": false
}
}
]
}
],
"previousLog": {
"pod": "checkout-v2",
"container": "api",
"text": "required configuration file missing",
"provenance": "synthetic clue, not verified root cause or real production log"
}
}Expected result
Only checkout-v2 matches app=checkout AND revision=v2. The Ready checkout-v1 Pod is not selected, so it cannot establish readiness for this Service. The selected Pod is not Ready; the supplied complete Slice list publishes zero non-terminating ready endpoints. Both Service and selected Pod declare the named http target at 3000 while the Service listens on 8080; different Service/Pod port numbers are not themselves an error. Declaring containerPort does not prove a process listens there. The supplied v2 status reports CrashLoopBackOff, five restarts and previous exit 1. Its synthetic previous log suggests missing configuration; this is a hypothesis to check against that exact revision/container, not proof of the failed path or authority to restart/delete the Pod. Low-level DNS, routing, network policy and ingress behavior were not tested. Next bounded evidence request: an authorized operator should verify the complete current EndpointSlice set for Service checkout in namespace training/context training-local, then the selected v2 container's bounded previous logs/configuration references. Do not dump Secret values, kubeconfig, all namespaces or all logs. If the actual snapshots differ in time/identity or omit Slices, mark the result incomplete instead of declaring zero cluster endpoints. A ready Slice is a discovery/routing signal, not successful end-to-end application traffic. publishNotReadyAddresses and terminating/serving fallback behavior need separate interpretation. No kubectl command or cluster action was executed. The result is a deterministic reading of explicitly supplied resource excerpts, not a live outage measurement.