---

name: kubernetes description: >- Operate, troubleshoot, secure, upgrade, and automate Kubernetes clusters and workloads safely across upstream Kubernetes, k3s, RKE2, MicroK8s, k0s, Talos, OpenShift/OKD, kind, Minikube, Rancher-managed clusters, EKS, AKS, and GKE. Use when a task involves kubectl, Kubernetes APIs, Pods, Deployments, StatefulSets, Services, Ingress or Gateway API, CRDs, RBAC, NetworkPolicy, storage, scheduling, autoscaling, cluster lifecycle, or the bundled agent-first k8s-cli. Do not use this skill for unrelated requests; route to the nearest named specialist.

Kubernetes

Use this skill as a decision and routing layer. Do not treat it as a static kubectl cheat sheet.

Operating contract

1. Identify the target: distribution, provider, cluster version, client version, context, namespace, access mode, and whether the cluster is production.
2. Discover before assuming: query served API resources, API versions, CRDs, system workloads, nodes, and distribution markers.
3. Separate portable Kubernetes behavior from distribution/provider overlays. Load the matching reference before using lifecycle, networking, identity, storage, or upgrade instructions.
4. For mutations, preview first (k8s-cli ... --dry-run or kubectl diff / server dry-run), state scope, require explicit confirmation for destructive actions, then verify conditions, events, rollout, and the external boundary.
5. Prefer stable APIs and server-side validation. Treat beta/alpha APIs, feature gates, provider defaults, and version numbers as time-sensitive.
6. Keep evidence bounded and structured. Never dump kubeconfigs, Secret values, tokens, or unbounded logs into chat.

Choose the operating path

Situation	First move	Do not do
Live cluster operation	Run doctor, context, and discover; record context, namespace, distribution, and versions	Do not infer cluster state from configuration or a prior command
No cluster access	Produce a bounded plan and name the missing prerequisite	Do not claim a diagnosis, success, or invented command output
Any mutation	Render, diff/server-dry-run, state scope, obtain the required confirmation, then mutate and verify the relevant boundary	Do not treat command exit 0 as operational success
Provider or distribution present	Load the matching overlay before applying portable guidance	Do not apply upstream instructions unchanged

First-response discovery

scripts/k8s-cli --json doctor
scripts/k8s-cli --json context
scripts/k8s-cli --json discover

If the wrapper is unavailable, use the equivalent native commands from references/cli-reference.md. If kubectl is absent, stop and report the prerequisite rather than inventing cluster state.

Routing

Scenario	Load
API discovery, SSA, CRDs, or deprecations	references/api-and-versioning.md
Workloads, probes, rollouts, jobs, or controllers	references/workloads-and-rollouts.md
Scheduling, scaling, storage, node disruption, or reliability	references/scheduling-scaling-storage.md and references/nodes-and-reliability.md
Services, DNS, NetworkPolicy, Ingress, or Gateway API	references/networking.md
Pod is Running but not serving traffic or is absent from Service endpoints	references/workloads-and-rollouts.md, references/networking.md, references/troubleshooting.md, and the matching distribution overlay
RBAC, Pod Security, admission, audit, secrets, or policy engines	references/security-and-policy.md and references/policy.md
Evidence-first diagnosis or advanced debugging	references/troubleshooting.md and references/debugging.md
Backups, upgrades, HA, or observability	references/operations.md, references/backup-restore.md, and references/observability.md
Distribution/provider overlays or version matrix	references/distributions.md, references/version-skew.md, and references/source-index.md
Native command details or output contracts	references/cli-reference.md
Mutation safety gates	references/safety-gates.md

Templates and scripts

• templates/diagnostic-report.md: human-readable incident report
• templates/cluster-inventory.json: bounded inventory schema
• templates/upgrade-runbook.md: preflight, change, and verification runbook
• scripts/k8s-cli: agent-first wrapper around kubectl
• scripts/test-k8s-cli.sh: deterministic tests using a fake kubectl
• scripts/gather-cluster-state.sh: bounded diagnostic collection for incident reports
• scripts/verify-cluster-health.sh: bounded post-operation health verification
• scripts/refresh-version-matrix.sh: refreshes dated release observations, never silently edits guidance

Version policy

The research baseline was checked 2026-07-11. The Kubernetes project page reported maintained minors 1.36, 1.35, and 1.34. This is not a permanent claim. Refresh references/distributions.md and the source index before asserting current versions or support status.

Verification boundary

Claim	Minimum evidence
Pod is healthy	Pod conditions, readiness, events, and relevant EndpointSlice or external boundary
Pod is serving traffic	Ready condition, Service selector, EndpointSlice membership, events, and a bounded Service-level check
Rollout succeeded	Controller conditions, resulting Pods, events, and the relevant Service or external check
API/resource is available	Served API discovery, installed CRDs/controller support, and server-side validation
Command succeeded operationally	Bounded command result plus the resource condition and user-visible boundary

A component-level command result is evidence about that component only; do not promote it to a cluster or integration claim.

Hard boundaries

• Never expose Secret data or raw kubeconfig credentials.
• Never use --force-conflicts, delete, drain, patch, upgrade, or cluster-reset procedures without explaining scope and obtaining the required confirmation.
• Never call a Pod healthy from Running alone.
• Never call an integration successful from a component-level test alone.
• Never apply an upstream procedure to k3s, RKE2, a managed provider, Talos, or OpenShift without loading its overlay.