Kubernetes Deployer

---
name: k8s-deployer
description: |
  Trigger when the user asks to deploy to Kubernetes, write manifests,
  or set up a Helm chart. Phrases: "Kubernetes", "k8s deploy", "Helm chart",
  "kubectl apply", "production deployment".
allowed-tools:
  - Read
  - Write
  - Bash(kubectl *)
  - Bash(helm *)
---

# Kubernetes Deployer

Ship a web app to Kubernetes with the basics done right: healthchecks,
resource limits, graceful shutdown, rolling updates.

## Prerequisites

- Docker image pushed to a registry the cluster can pull from
- kubectl access to the target cluster
- Namespace planned (never deploy to `default` in production)

## Steps

1. **Three manifests at minimum:**
   - `Deployment` - pod spec, replica count, update strategy
   - `Service` - ClusterIP or LoadBalancer
   - `Ingress` - external routing with TLS

2. **Deployment essentials:**
   ```yaml
   apiVersion: apps/v1
   kind: Deployment
   spec:
     replicas: 2
     strategy:
       type: RollingUpdate
       rollingUpdate:
         maxSurge: 1
         maxUnavailable: 0
     template:
       spec:
         terminationGracePeriodSeconds: 30
         containers:
         - name: app
           image: registry/app:tag
           readinessProbe:
             httpGet: { path: /health, port: 3000 }
             periodSeconds: 5
           livenessProbe:
             httpGet: { path: /health, port: 3000 }
             periodSeconds: 30
           resources:
             requests: { cpu: 100m, memory: 256Mi }
             limits: { cpu: 500m, memory: 512Mi }
   ```

3. **Readiness vs liveness, different purposes:**
   - Readiness - "can I serve traffic now?" - fails mean traffic stops
   - Liveness - "am I wedged and need a restart?" - fails mean pod restart
   Don't point both at the same deep healthcheck. Liveness should be cheap.

4. **Resource requests matter for scheduling.** Requests too low = noisy
   neighbor problems. Requests too high = wasted cluster capacity.
   Start from observed usage: double the p99.

5. **Secrets via `Secret`, not env literals.** Never commit secrets to
   manifest YAML. Use Sealed Secrets, External Secrets Operator, or the
   cluster's native secret store.

6. **Ingress with cert-manager** for TLS. Let's Encrypt certs auto-renew.
   No reason to provision certs manually in 2026.

## Graceful shutdown

Containers should:
- Catch SIGTERM
- Stop accepting new connections
- Let in-flight requests finish (up to grace period)
- Exit

Node: `process.on("SIGTERM", () => server.close())`. If your app ignores
SIGTERM, rolling updates drop connections.

## For Helm

- Use Helm for anything with more than one environment or more than five
  manifests. Raw YAML gets unmanageable fast.
- Keep `values.yaml` flat and documented.
- Pin chart versions in production; don't track `latest`.

## Output

- Deployment, Service, Ingress YAML (or Helm chart)
- Healthcheck endpoints defined
- Resource requests/limits set
- TLS via cert-manager
- One manual `kubectl rollout status` confirms deploy