Kubernetes Deploy skill for Claude Code

A deployment is done when the rollout completes with zero failed requests, pods carry honest resource requests, probes reflect real readiness, the workload survives a node drain, and you can roll back in one command.

Ground rules

• Confirm the target before any mutating command: kubectl config current-context and namespace. Applying, deleting, scaling, or rolling back in production requires explicit user confirmation.
• Preview every change: kubectl diff -f <dir> (or kustomize build | kubectl diff -f -).
• Never use :latest or mutable tags in manifests; use an immutable tag or digest.
• Liveness probes check only the process itself, never databases or downstream services.
• Every container gets CPU and memory requests. Set a memory limit; be deliberate about CPU limits (they cause throttling).
• Secrets objects are base64, not encryption. Source them from a secret manager.

Workflow

- [ ] 1. Inspect current state (context, namespace, existing objects, events)
- [ ] 2. Write/adjust manifests: Deployment, Service, config, PDB, HPA
- [ ] 3. Size resources from observed usage
- [ ] 4. Configure probes and graceful shutdown
- [ ] 5. Validate: server-side dry run + diff
- [ ] 6. Apply (with confirmation), watch rollout, verify traffic
- [ ] 7. Record rollback command and outcome

1. Inspect

kubectl config current-context; kubectl config view --minify -o jsonpath='{..namespace}'
kubectl get deploy,rs,pods,svc,ingress,hpa,pdb -n <ns> -o wide
kubectl get events -n <ns> --sort-by=.lastTimestamp | tail -30
kubectl top pods -n <ns> --containers            # needs metrics-server

2. Reference Deployment

apiVersion: apps/v1
kind: Deployment
metadata:
  name: api
  labels: { app.kubernetes.io/name: api }
spec:
  replicas: 3
  revisionHistoryLimit: 5
  selector:
    matchLabels: { app.kubernetes.io/name: api }
  strategy:
    type: RollingUpdate
    rollingUpdate: { maxSurge: 25%, maxUnavailable: 0 }
  template:
    metadata:
      labels: { app.kubernetes.io/name: api }
    spec:
      terminationGracePeriodSeconds: 30
      securityContext:
        runAsNonRoot: true
        seccompProfile: { type: RuntimeDefault }
      topologySpreadConstraints:
        - maxSkew: 1
          topologyKey: topology.kubernetes.io/zone
          whenUnsatisfiable: ScheduleAnyway
          labelSelector:
            matchLabels: { app.kubernetes.io/name: api }
      containers:
        - name: api
          image: registry.example.com/api:1.14.2
          ports:
            - { name: http, containerPort: 8080 }
          envFrom:
            - configMapRef: { name: api-config }
            - secretRef: { name: api-secrets }
          resources:
            requests: { cpu: 250m, memory: 384Mi }
            limits: { memory: 384Mi }
          startupProbe:
            httpGet: { path: /healthz, port: http }
            periodSeconds: 5
            failureThreshold: 30          # up to 150 s to boot
          readinessProbe:
            httpGet: { path: /ready, port: http }
            periodSeconds: 5
            failureThreshold: 3
          livenessProbe:
            httpGet: { path: /healthz, port: http }
            periodSeconds: 10
            failureThreshold: 3
          lifecycle:
            preStop:
              sleep: { seconds: 5 }       # k8s 1.30+; older: exec ["sleep","5"]
          securityContext:
            allowPrivilegeEscalation: false
            readOnlyRootFilesystem: true
            capabilities: { drop: ["ALL"] }
---
apiVersion: v1
kind: Service
metadata:
  name: api
spec:
  selector: { app.kubernetes.io/name: api }
  ports:
    - { name: http, port: 80, targetPort: http }
---
apiVersion: policy/v1
kind: PodDisruptionBudget
metadata:
  name: api
spec:
  maxUnavailable: 1
  selector:
    matchLabels: { app.kubernetes.io/name: api }

readOnlyRootFilesystem: true needs an emptyDir mounted wherever the app writes (/tmp, caches).

3. Resources

Decision	Rule
Memory request	p95 observed working set + 20–30% headroom
Memory limit	Equal to request (predictable, avoids node-pressure eviction surprises)
CPU request	Around p90 steady-state usage; this is what HPA percentages are computed from
CPU limit	Omit for latency-sensitive services unless policy requires it; if set, 2–4x request
JVM / Node / Go	Make the runtime respect the limit: -XX:MaxRAMPercentage=75, --max-old-space-size, GOMEMLIMIT

4. Probes and shutdown

Probe	Answers	Failure does
startupProbe	Has it finished booting?	Delays the other probes; restarts after threshold
readinessProbe	Should it get traffic now?	Removes pod from Service endpoints
livenessProbe	Is the process wedged?	Restarts the container

Graceful shutdown sequence: pod marked Terminating -> removed from endpoints (async) -> preStop runs -> SIGTERM -> grace period -> SIGKILL. The preStop sleep covers the gap while load balancers stop routing. The app must stop accepting, drain in-flight requests, then exit within terminationGracePeriodSeconds.

5. Config, secrets, autoscaling

• ConfigMap/Secret changes do not restart pods. Use kustomize configMapGenerator (hash-suffixed names), a checksum annotation, or kubectl rollout restart.
• Secrets: External Secrets Operator, Sealed Secrets, or SOPS. Never commit plain Secret manifests.
• HPA (requires metrics-server and CPU requests):

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata: { name: api }
spec:
  scaleTargetRef: { apiVersion: apps/v1, kind: Deployment, name: api }
  minReplicas: 3
  maxReplicas: 20
  metrics:
    - type: Resource
      resource: { name: cpu, target: { type: Utilization, averageUtilization: 70 } }
  behavior:
    scaleDown: { stabilizationWindowSeconds: 300 }

When an HPA manages replicas, remove spec.replicas from the Deployment manifest so each apply does not reset the count.

6. Validate, apply, watch

kubectl apply --dry-run=server -f k8s/         # schema + admission checks
kubectl diff -f k8s/
kubectl apply -f k8s/                          # after user confirmation for prod
kubectl rollout status deploy/api -n <ns> --timeout=5m
kubectl get endpointslices -n <ns> -l kubernetes.io/service-name=api

Rollback: kubectl rollout undo deploy/api -n <ns> (confirm first). Prefer reverting the manifest in git when GitOps (Argo CD/Flux) owns the cluster, or the controller will re-apply the bad version.

Failure triage

Status	First command	Usual cause
Pending	kubectl describe pod (Events)	Insufficient CPU/memory, taints, unbound PVC, zone constraints
ImagePullBackOff	describe pod	Wrong tag, missing imagePullSecrets, private registry auth, arch mismatch
CreateContainerConfigError	describe pod	Missing ConfigMap/Secret or key
CrashLoopBackOff	kubectl logs <pod> --previous	App error on boot, bad config, failing liveness probe
OOMKilled (exit 137)	describe pod Last State	Memory limit too low or a leak
Exit 143 then restart	Events	Liveness probe failing, often too aggressive during load
Running but no traffic	get endpointslices	Readiness failing or Service selector mismatch
Rollout stuck	rollout status, get rs	New pods never Ready; maxUnavailable: 0 keeps old ones serving

For deeper diagnosis (ephemeral debug containers, DNS, network policies, node pressure), read references/kubectl-debugging.md.

Gotchas

• Changing spec.selector on an existing Deployment is rejected; it is immutable.
• kubectl apply of a manifest without resources silently removes resources set by hand.
• A liveness probe that calls the database turns a DB blip into a cluster-wide restart storm.
• maxUnavailable: 0 with a PDB of minAvailable: 100% blocks node drains forever.
• kubectl edit in production creates drift from git; change the manifest instead.
• Probes default to timeoutSeconds: 1; slow health endpoints under load fail spuriously.

Output

**Change:** api 1.14.1 -> 1.14.2, memory 256Mi -> 384Mi, startupProbe added
**Context/namespace:** prod-eu / shop
**Validation:** dry-run=server OK, diff reviewed (3 objects changed)
**Rollout:** completed in 2m10s, 0 restarts, endpoints 3/3 ready
**Rollback:** kubectl rollout undo deploy/api -n shop  (revision 41)