name: kubernetes
description: |-
Production-grade Kubernetes manifests and debugging for containerized applications.
This skill should be used when users ask to deploy to Kubernetes, create K8s manifests,
containerize for K8s, set up Deployments/Services/Jobs/StatefulSets/CronJobs, create
namespaces with resource quotas, set up multi-team isolation, configure ResourceQuota/
LimitRange, secure with RBAC (ServiceAccount, Role, RoleBinding), configure init
containers (model download, db wait, migrations), set up sidecars (logging, metrics),
or debug pods (CrashLoopBackOff, logs, exec, describe, events). Auto-detects from
Dockerfile/code, generates hardened manifests with educational comments. CKAD-aligned.
hooks:
PreToolUse:
- matcher: "Bash"
hooks:
- type: command
command: "bash \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/verify-kubectl-context.sh"

Kubernetes

Production-grade K8s manifests with security-first defaults and educational comments.

Resource Detection & Adaptation

Before generating manifests, detect the target environment:

# Detect node resources
kubectl get nodes -o jsonpath='{range .items[*]}{.metadata.name}: {.status.capacity.memory}, {.status.capacity.cpu}{"\n"}{end}'

# Detect if Docker Desktop (local) or real cluster
kubectl get nodes -o jsonpath='{.items[0].metadata.labels.node\.kubernetes\.io/instance-type}' 2>/dev/null || echo "local"

# Detect available resources
kubectl describe nodes | grep -A 5 "Allocated resources"

Adapt configurations based on detection:

Agent Behavior

1. Detect cluster type and resources before generating manifests
2. Adapt resource requests/limits to cluster capacity
3. Warn if requested workload exceeds available resources
4. Calculate safe limits: (node_memory * 0.7) / expected_pod_count

Adaptive Resource Templates

Local/Constrained (< 6GB allocatable):

resources:
  requests:
    memory: 128Mi
    cpu: 100m
  limits:
    memory: 256Mi
    cpu: 500m

Standard (6-16GB allocatable):

resources:
  requests:
    memory: 256Mi
    cpu: 100m
  limits:
    memory: 512Mi
    cpu: 1000m

Production (> 16GB or cloud):

resources:
  requests:
    memory: 512Mi
    cpu: 250m
  limits:
    memory: 1Gi
    cpu: 2000m

Pre-Deployment Validation

Before applying manifests, agent should verify:

# Check if deployment would exceed node capacity
kubectl get nodes -o jsonpath='{.items[0].status.allocatable.memory}'

If insufficient: warn user and suggest scaling down or increasing Docker Desktop resources.

What This Skill Does

Analysis & Detection:
- Auto-detects from Dockerfile: ports, health endpoints, resources
- Identifies workload type from project structure
- Reads existing manifests to understand patterns
- Detects GPU requirements from dependencies

Generation:
- Creates production-hardened manifests (non-root, read-only, resource limits)
- Generates all supporting resources (Service, ConfigMap, HPA, PDB)
- Creates namespace governance (ResourceQuota, LimitRange, NetworkPolicy)
- Supports multi-team isolation with environment progression (dev → staging → prod)
- Adds educational comments explaining WHY each config choice
- Outputs ArgoCD-compatible directory structure

Validation:
- Verifies kubectl context exists
- Creates namespace if needed
- Deploys to local cluster (kind/minikube)
- Confirms pods are running before delivering

Security:
- Non-root user by default (runAsNonRoot: true)
- Read-only root filesystem
- No privilege escalation
- Dropped capabilities
- Resource limits always set
- Unprivileged ports only (>=1024) - privileged ports (<1024) require root

What This Skill Does NOT Do

• Generate Helm charts (document in references for future)
• Create Kustomize overlays (document in references for future)
• Handle Dapr sidecar injection (separate skill)
• Deploy Kafka/Strimzi operators (separate skill)
• Generate ArgoCD Application CRDs (separate skill)

Before Implementation

Gather context to ensure successful implementation:

Required Clarifications

After auto-detection, confirm with user if ambiguous:

Pre-flight Checks (CRITICAL)

Before generating manifests, verify:

# 1. Cluster access
kubectl cluster-info

# 2. Current context
kubectl config current-context

# 3. Target namespace (create if needed)
kubectl get namespace $NAMESPACE || kubectl create namespace $NAMESPACE

# 4. Image exists (or build it)
docker images | grep $IMAGE_NAME || docker build -t $IMAGE_NAME .

# 5. For local clusters: load image
kind load docker-image $IMAGE_NAME  # or minikube image load

If any check fails → stop and report. Don't generate manifests for broken state.

Auto-Detection Matrix

From Dockerfile

Port Selection (CRITICAL for Security)

Privileged ports (<1024) conflict with runAsNonRoot: true.

Common remappings:
| Standard Image | Security-Compatible Alternative |
|----------------|--------------------------------|
| nginx (port 80) | nginxinc/nginx-unprivileged (port 8080) |
| httpd (port 80) | Configure Listen 8080 or use unprivileged image |
| redis (port 6379) | ✅ Already unprivileged |
| postgres (port 5432) | ✅ Already unprivileged |

Service abstracts this: Service port: 80 → targetPort: 8080 keeps external API stable.

From Code

Workload Type Decision

Is this a one-time task that completes?
  → Job (or CronJob if scheduled)

Does it need stable network identity or ordered deployment?
  → StatefulSet

Must run on every node?
  → DaemonSet

Otherwise → Deployment (default)

Workflow

1. PRE-FLIGHT
   - Verify kubectl context
   - Check namespace exists
   - Verify image exists or build it
         ↓
2. ANALYZE PROJECT
   - Read Dockerfile for EXPOSE, HEALTHCHECK, USER
   - Scan code for health endpoints
   - Check existing k8s/ directory
   - Detect GPU requirements (torch, tensorflow)
         ↓
3. DETERMINE WORKLOAD TYPE
   - Deployment (default)
   - Job/CronJob (batch processing)
   - StatefulSet (databases, ordered)
   - DaemonSet (node-level agents)
         ↓
4. GENERATE MANIFESTS
   - Deployment/Job/StatefulSet with hardened security
   - Service (ClusterIP, NodePort, or LoadBalancer)
   - ConfigMap for non-secret config
   - HPA if autoscaling needed
   - PDB for availability
   - All with educational comments
         ↓
5. VALIDATE
   - kubectl apply --dry-run=server
   - kubectl apply -n $NAMESPACE
   - kubectl wait --for=condition=Ready pod
   - kubectl logs to verify startup
         ↓
6. DELIVER
   - Files in k8s/base/ directory
   - Summary of what was created
   - Next steps for production

Generated Directory Structure

k8s/
├── base/                         # Raw manifests (ArgoCD-compatible)
│   ├── namespace.yaml            # Optional, if new namespace
│   ├── resourcequota.yaml        # Namespace-wide resource caps
│   ├── limitrange.yaml           # Per-container defaults and bounds
│   ├── networkpolicy.yaml        # Namespace isolation rules
│   ├── deployment.yaml           # Or job.yaml, statefulset.yaml
│   ├── service.yaml              # ClusterIP by default
│   ├── configmap.yaml            # Non-secret configuration
│   ├── hpa.yaml                  # If autoscaling enabled
│   ├── pdb.yaml                  # Pod Disruption Budget
│   └── kustomization.yaml        # For future Kustomize use
└── README.md                     # Deployment instructions

Manifest Patterns

Deployment (Default)

apiVersion: apps/v1
kind: Deployment
metadata:
  name: ${APP_NAME}
  labels:
    # Standard K8s labels (see references/labels-annotations.md)
    app.kubernetes.io/name: ${APP_NAME}
    app.kubernetes.io/instance: ${APP_NAME}-${ENV}
    app.kubernetes.io/version: "${VERSION}"
    app.kubernetes.io/component: api  # or worker, frontend
    app.kubernetes.io/part-of: ${PROJECT}
    app.kubernetes.io/managed-by: kubectl
spec:
  replicas: 2  # WHY: Minimum for availability during rolling updates
  selector:
    matchLabels:
      app.kubernetes.io/name: ${APP_NAME}
  template:
    metadata:
      labels:
        app.kubernetes.io/name: ${APP_NAME}
    spec:
      # WHY: Security hardening - never run as root
      securityContext:
        runAsNonRoot: true
        runAsUser: 1000
        runAsGroup: 1000
        fsGroup: 1000
        seccompProfile:
          type: RuntimeDefault
      containers:
      - name: ${APP_NAME}
        image: ${IMAGE}:${TAG}
        # WHY: Never use :latest - breaks reproducibility
        imagePullPolicy: IfNotPresent
        ports:
        # WHY: Port must be >=1024 for runAsNonRoot (privileged ports need root)
        # Use Service port:80 → targetPort:8080 to expose standard ports externally
        - containerPort: ${PORT}  # Must be >=1024 (e.g., 8080, 8000, 3000)
          protocol: TCP
        # WHY: Container-level security context
        securityContext:
          allowPrivilegeEscalation: false
          readOnlyRootFilesystem: true
          capabilities:
            drop: ["ALL"]
        # WHY: Prevent resource starvation, enable HPA
        resources:
          requests:
            cpu: "100m"      # 0.1 CPU cores
            memory: "128Mi"
          limits:
            cpu: "500m"      # 0.5 CPU cores
            memory: "512Mi"
        # WHY: K8s restarts if app deadlocks
        livenessProbe:
          httpGet:
            path: /health/live
            port: ${PORT}
          initialDelaySeconds: 10
          periodSeconds: 15
          failureThreshold: 3
        # WHY: Only route traffic when ready
        readinessProbe:
          httpGet:
            path: /health/ready
            port: ${PORT}
          initialDelaySeconds: 5
          periodSeconds: 10
        # WHY: Slow-starting apps (ML models) need longer startup
        startupProbe:
          httpGet:
            path: /health/live
            port: ${PORT}
          initialDelaySeconds: 0
          periodSeconds: 10
          failureThreshold: 30  # 5 minutes to start
        # WHY: Graceful shutdown for in-flight requests
        lifecycle:
          preStop:
            exec:
              command: ["/bin/sh", "-c", "sleep 5"]
        # WHY: Allow time for graceful shutdown
      terminationGracePeriodSeconds: 30

Service

apiVersion: v1
kind: Service
metadata:
  name: ${APP_NAME}
  labels:
    app.kubernetes.io/name: ${APP_NAME}
spec:
  # WHY: ClusterIP is safest default - internal only
  # Use NodePort for dev/testing, LoadBalancer for prod external access
  type: ClusterIP
  ports:
  # WHY: Service abstracts internal port - clients connect to :80, Pod runs on :8080
  # This allows standard external ports while container runs unprivileged
  - port: 80              # WHY: Service port (what clients connect to)
    targetPort: ${PORT}   # WHY: Pod port (>=1024, e.g., 8080)
    protocol: TCP
    name: http
  selector:
    # CRITICAL: Must EXACTLY match Pod template labels from Deployment
    # Mismatch = zero endpoints = Service routes to nothing
    app.kubernetes.io/name: ${APP_NAME}

Verify Service→Pod connection: kubectl get endpoints ${APP_NAME}
- Shows Pod IPs if selector matches
- Shows <none> if selector MISMATCHES Pod labels

Security Context (Always Applied)

See references/security-contexts.md for full patterns.

# Pod level
securityContext:
  runAsNonRoot: true           # WHY: Never run as root
  runAsUser: 1000              # WHY: Consistent non-root UID
  runAsGroup: 1000             # WHY: Consistent GID
  fsGroup: 1000                # WHY: Volume permissions
  seccompProfile:
    type: RuntimeDefault       # WHY: Block dangerous syscalls

# Container level
securityContext:
  allowPrivilegeEscalation: false  # WHY: Prevent root escalation
  readOnlyRootFilesystem: true     # WHY: Immutable container
  capabilities:
    drop: ["ALL"]                  # WHY: Minimal capabilities

Output Checklist

Before delivering, verify:

Pre-flight

• [ ] kubectl context is valid
• [ ] Namespace exists or was created
• [ ] Image exists locally or in registry
• [ ] For kind/minikube: image loaded into cluster

Manifests

• [ ] All manifests have app.kubernetes.io/* labels
• [ ] Security context applied (runAsNonRoot, readOnlyRootFilesystem)
• [ ] containerPort >= 1024 (privileged ports incompatible with runAsNonRoot)
• [ ] Resource requests AND limits defined
• [ ] Liveness and readiness probes configured
• [ ] No hardcoded secrets (use Secret references or env vars)

Namespace Governance (if applicable)

• [ ] ResourceQuota sets namespace-wide CPU/memory/pod limits
• [ ] LimitRange provides default requests/limits for containers
• [ ] LimitRange max prevents single container from consuming quota
• [ ] NetworkPolicy isolates namespace (default-deny + explicit allows)
• [ ] Monitoring namespace allowed to scrape metrics

Validation

• [ ] kubectl apply --dry-run=server passes
• [ ] Deployed to cluster successfully
• [ ] Pods reach Running state
• [ ] Health endpoints respond
• [ ] Service has endpoints (kubectl get endpoints shows Pod IPs, not <none>)

Documentation

• [ ] Comments explain WHY for each config choice
• [ ] README.md with deployment instructions

Reference Files

Always Read First

Debugging & Operations

Workload-Specific

Infrastructure