Skip to main content
Agent skill

Kubernetes Patterns

Kubernetes workload patterns, resource management, RBAC, probes, autoscaling, ConfigMap/Secret handling, and kubectl debugging for production-grade deployments. Use when writing or reviewing Kubernetes manifests, or debugging probes, RBAC, autoscaling, or resource limits.

Get started

Get the complete skill folder, including its scripts and reference files.

When to use this skill

Use Kubernetes Patterns when an AI agent needs a reusable SKILL.md workflow for this job: Kubernetes workload patterns, resource management, RBAC, probes, autoscaling, ConfigMap/Secret handling, and kubectl debugging for production-grade deployments. Use when writing or reviewing Kubernetes manifests, or debugging probes, RBAC, autoscaling, or resource limits.

When not to use it

Skip Kubernetes Patterns when the task is outside the coding category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.

How to install

Where will you use it?

Install scope
Claude Code folder setup
mkdir -p ~/.claude/skills/kubernetes-patterns
# Save SKILL.md to ~/.claude/skills/kubernetes-patterns/SKILL.md
  1. Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/kubernetes-patterns/SKILL.md. For a shared project, commit the folder at .claude/skills/kubernetes-patterns/ instead.
  2. Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
  3. For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.

Full install guide for Claude, Cursor, and Codex →

Try a starter prompt

After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.

Starter prompt
Use the Kubernetes Patterns skill for this task: Use Kubernetes Patterns when this documented workflow matches the task. Confirm any required inputs or files before making changes.

What supports this recommendation?

71/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.

Documentation
77/100
Practical detail
68/100
Source evidence
63/100
Source signals
72/100
Model compatibility evidence
  • claudeuntested

    No model-specific signal or recorded compatibility test was found.

  • chatgptuntested

    No model-specific signal or recorded compatibility test was found.

  • geminiuntested

    No model-specific signal or recorded compatibility test was found.

  • copilotuntested

    No model-specific signal or recorded compatibility test was found.

  • llamauntested

    No model-specific signal or recorded compatibility test was found.

  • perplexityuntested

    No model-specific signal or recorded compatibility test was found.

  • mistraluntested

    No model-specific signal or recorded compatibility test was found.

  • grokuntested

    No model-specific signal or recorded compatibility test was found.

Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.

What this skill does

# Kubernetes Patterns

Production-grade Kubernetes patterns for deploying, managing, and debugging workloads reliably.

## When to Activate

- Writing Kubernetes manifests (Deployments, Services, Ingress, Jobs) - Configuring resource requests/limits, liveness/readiness probes - Setting up RBAC, namespaces, or ServiceAccounts - Managing configuration and secrets in K8s - Debugging CrashLoopBackOff, OOMKilled, pending pods, or image pull errors - Configuring HPA (Horizontal Pod Autoscaler) or PodDisruptionBudgets - Reviewing K8s YAML for security or correctness

## When to Use

> Same as **When to Activate** above. This alias satisfies repo skill-format conventions. Use this skill any time you are writing, reviewing, or debugging Kubernetes YAML and workloads.

## How It Works

This skill provides **copy-pasteable, production-grade YAML patterns** and **kubectl debugging commands** organized by task:

1. **Deployment template** — A fully configured production `Deployment` with security context, rolling update strategy, all three probe types, resource limits, and environment injection from ConfigMap/Secret. 2. **Probes** — Decision table for startup vs liveness vs readiness, with correct `failureThreshold × periodSeconds` math. 3. **Services & Ingress** — ClusterIP, LoadBalancer, and TLS Ingress patterns with cert-manager annotations. 4. **ConfigMaps & Secrets** — `envFrom`, file-mount, and external secrets guidance. 5. **Resource management** — Requests vs limits rules of thumb by workload type (web API, JVM, worker, sidecar). 6. **RBAC** — Least-privilege ServiceAccount → Role → RoleBinding chain. 7. **HPA & PDB** — Autoscaling and node-drain safety configurations. 8. **Jobs & CronJobs** — One-off and scheduled workload patterns with correct `restartPolicy`. 9. **kubectl cheatsheet** — Logs, exec, rollback, port-forward, dry-run, and common error diagnosis commands. 10. **Anti-patterns & checklist** — What NOT to do, and a security/reliability/observability checklist.

## Examples

See the sections below for complete, runnable examples. Quick references:

| Task | Jump to | |------|---------| | Full production Deployment YAML | [Core Workload Patterns](#core-workload-patterns) | | Probe configuration | [Probes](#probes--liveness-readiness-startup) | | RBAC least-privilege setup | [RBAC](#rbac--roles-and-serviceaccounts) | | Debug a CrashLoopBackOff | [kubectl Debugging Cheatsheet](#kubectl-debugging-cheatsheet) | | Autoscaling | [HPA](#horizontal-pod-autoscaler-hpa) |

---

## Core Workload Patterns

### Deployment — Production Template

```yaml apiVersion: apps/v1 kind: Deployment metadata: name: my-app namespace: my-namespace labels: app: my-app version: "1.0.0" spec: replicas: 3 selector: matchLabels: app: my-app strategy: type: RollingUpdate rollingUpdate: maxSurge: 1 # Allow 1 extra pod during update maxUnavailable: 0 # Never reduce below desired count template: metadata: labels: app: my-app version: "1.0.0" spec: # Security context at pod level securityContext: runAsNonRoot: true runAsUser: 1001 fsGroup: 1001

# Graceful shutdown terminationGracePeriodSeconds: 30

containers: - name: my-app image: ghcr.io/org/my-app:1.0.0 # Never use :latest imagePullPolicy: IfNotPresent

ports: - containerPort: 8080 protocol: TCP

# Resource requests AND limits are both required resources: requests: cpu: "100m" memory: "128Mi" limits: cpu: "500m" memory: "256Mi"

# Container security context securityContext: allowPrivilegeEscalation: false readOnlyRootFilesystem: true capabilities: drop: - ALL

# Probes (see Probes section below) startupProbe: httpGet: path: /health port: 8080 failureThreshold: 30 periodSeconds: 5 livenessProbe: httpGet: path: /health port: 8080 initialDelaySeconds: 0 periodSeconds: 30 failureThreshold: 3 readinessProbe: httpGet: path: /ready port: 8080 initialDelaySeconds: 5 periodSeconds: 10 failureThreshold: 2

# Environment from ConfigMap and Secret envFrom: - configMapRef: name: my-app-config env: - name: DB_PASSWORD valueFrom: secretKeyRef: name: my-app-secrets key: db-password

# Writable tmp directory when readOnlyRootFilesystem: true volumeMounts: - name: tmp mountPath: /tmp

volumes: - name: tmp emptyDir: {} ```

---

## Probes — Liveness, Readiness, Startup

Understanding when to use each probe is critical:

| Probe | Failure Action | Use For | |-------|---------------|---------| | `startupProbe` | Kills container if slow to start | Slow-starting apps (JVM, Python) | | `livenessProbe` | Restarts container | Deadlock / hung process detection | | `readinessProbe` | Removes from Service endpoints | Temporary unavailability (DB reconnect) |

```yaml # Correct pattern: startupProbe covers slow startup, # then liveness/readiness take over startupProbe: httpGet: path: /health port: 8080 failureThreshold: 30 # 30 * 5s = 150s max startup time periodSeconds: 5

livenessProbe: httpGet: path: /health port: 8080 periodSeconds: 30 failureThreshold: 3 # 3 * 30s = 90s before restart

readinessProbe: httpGet: path: /ready # Separate endpoint: checks DB, cache, etc. port: 8080 periodSeconds: 10 failureThreshold: 2 ```

```yaml # WRONG: initialDelaySeconds without startupProbe # If the app takes 60s to start, set a startupProbe instead livenessProbe: httpGet: path: /health port: 8080 initialDelaySeconds: 60 # BAD: Arbitrary wait, race condition ```

---

## Services and Ingress

### Service Types

```yaml # ClusterIP (default) — internal-only apiVersion: v1 kind: Service metadata: name: my-app namespace: my-namespace spec: selector: app: my-app ports: - port: 80 targetPort: 8080 protocol: TCP type: ClusterIP ```

```yaml # LoadBalancer — external traffic (cloud providers) spec: type: LoadBalancer ports: - port: 443 targetPort: 8080 ```

### Ingress with TLS

```yaml apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: my-app namespace: my-namespace annotations: nginx.ingress.kubernetes.io/ssl-redirect: "true" cert-manager.io/cluster-issuer: "letsencrypt-prod" spec: ingressClassName: nginx tls: - hosts: - myapp.example.com secretName: my-app-tls rules: - host: myapp.example.com http: paths: - path: / pathType: Prefix backend: service: name: my-app port: number: 80 ```

---

## ConfigMaps and Secrets

### ConfigMap — Non-sensitive configuration

```yaml apiVersion: v1 kind: ConfigMap metadata: name: my-app-config namespace: my-namespace data: LOG_LEVEL: "info" APP_ENV: "production" MAX_CONNECTIONS: "100" # Mount as a file for complex config app.yaml: | server: port: 8080 timeout: 30s ```

```yaml # Mount ConfigMap as a file volumes: - name: config configMap: name: my-app-config items: - key: app.yaml path: app.yaml volumeMounts: - name: config mountPath: /etc/app readOnly: true ```

### Secrets — Sensitive data

```bash # Create secret from literal (CLI, then store in Vault/SOPS) kubectl create secret generic my-app-secrets \ --from-literal=db-password='s3cr3t' \ --namespace=my-namespace \ --dry-run=client -o yaml | kubectl apply -f - ```

```yaml apiVersion: v1 kind: Secret metadata: name: my-app-secrets namespace: my-namespace type: Opaque # Values are base64-encoded (NOT encrypted — use Sealed Secrets or ESO for real encryption) data: db-password: czNjcjN0 # base64 of 's3cr3t' ```

> **Important:** Raw Kubernetes Secrets are only base64-encoded, not encrypted at rest unless your cluster has encryption configured. Use [Sealed Secrets](https://github.com/bitnami-labs/sealed-secrets) or [External Secrets Operator](https://external-secrets.io) for production.

---

## Resource Requests and Limits

```yaml resources: requests: # Scheduler uses this to place the pod cpu: "100m" # 100 millicores = 0.1 CPU memory: "128Mi" limits: # Container is killed/throttled above this cpu: "500m" memory: "256Mi" ```

**Rules of thumb:**

| Workload Type | CPU Request | Memory Request | Notes | |---------------|-------------|----------------|-------| | Web API | 100–250m | 128–256Mi | Set limits 2-4x requests | | Worker/consumer | 250–500m | 256–512Mi | Memory limit = request for predictability | | JVM app | 500m–1 | 512Mi–2Gi | Allow headroom above `-Xmx` for JVM overhead | | Sidecar | 10–50m | 32–64Mi | Keep minimal |

```yaml # WRONG: No requests or limits — unpredictable scheduling, OOM evictions containers: - name: app image: myapp:latest # Missing resources: {} — this is dangerous in production

# WRONG: Limits without requests — requests default to limits, over-reserves capacity resources: limits: cpu: "2" memory: "1Gi" # requests missing — will default to limits values ```

---

## RBAC — Roles and ServiceAccounts

### Principle of Least Privilege

**Two patterns depending on whether the app calls the Kubernetes API:**

#### Pattern A — App does NOT need the Kubernetes API (most apps)

Disable token automounting on the ServiceAccount. The Role/RoleBinding are not needed.

```yaml # ServiceAccount with token disabled — safest default apiVersion: v1 kind: ServiceAccount metadata: name: my-app-sa namespace: my-namespace automountServiceAccountToken: false # No K8s API token injected into pods ```

```yaml # Reference in Deployment — no token, no API access spec: template: spec: serviceAccountName: my-app-sa automountServiceAccountToken: false # Belt-and-suspenders: also set at pod level ```

#### Pattern B — App DOES need the Kubernetes API (operators, controllers, config watchers)

Enable the token and grant only the permissions actually required.

```yaml # 1. ServiceAccount — enable token for this SA apiVersion: v1 kind: ServiceAccount metadata: name: my-app-sa namespace: my-namespace automountServiceAccountToken: true # Token required: app calls K8s API ```

```yaml # 2. Role — grant only what the app needs (namespace-scoped) apiVersion: rbac.authorization.k8s.io/v1 kind: Role metadata: name: my-app-role namespace: my-namespace rules: - apiGroups: [""] resources: ["configmaps"] verbs: ["get", "list", "watch"] # Read-only, specific resource - apiGroups: [""] resources: ["secrets"] resourceNames: ["my-app-secrets"] # Restrict to specific secret by name verbs: ["get"] ```

```yaml # 3. Bind Role to ServiceAccount apiVersion: rbac.authorization.k8s.io/v1 kind: RoleBinding metadata: name: my-app-rolebinding namespace: my-namespace subjects: - kind: ServiceAccount name: my-app-sa namespace: my-namespace roleRef: kind: Role apiGroup: rbac.authorization.k8s.io name: my-app-role ```

```yaml # 4. Reference SA in Deployment spec: template: spec: serviceAccountName: my-app-sa # automountServiceAccountToken defaults to true from SA — token is injected ```

---

## Horizontal Pod Autoscaler (HPA)

```yaml apiVersion: autoscaling/v2 kind: HorizontalPodAutoscaler metadata: name: my-app-hpa namespace: my-namespace spec: scaleTargetRef: apiVersion: apps/v1 kind: Deployment name: my-app minReplicas: 2 # Always at least 2 for HA maxReplicas: 10 metrics: - type: Resource resource: name: cpu target: type: Utilization averageUtilization: 70 # Scale up when avg CPU > 70% - type: Resource resource: name: memory target: type: Utilization averageUtilization: 80 ```

> HPA requires `resources.requests` to be set on all containers — it calculates utilization as `current / request`.

---

## PodDisruptionBudget (PDB)

Prevent too many pods going down during node drains or rolling updates:

```yaml apiVersion: policy/v1 kind: PodDisruptionBudget metadata: name: my-app-pdb namespace: my-namespace spec: minAvailable: 2 # OR use maxUnavailable: 1 selector: matchLabels: app: my-app ```

---

## Namespaces and Multi-Tenancy

```bash # Create namespace with resource quotas kubectl create namespace my-namespace

# Apply ResourceQuota to limit namespace consumption kubectl apply -f - <<EOF apiVersion: v1 kind: ResourceQuota metadata: name: my-namespace-quota namespace: my-namespace spec: hard: requests.cpu: "4" requests.memory: 4Gi limits.cpu: "8" limits.memory: 8Gi pods: "20" EOF ```

---

## Jobs and CronJobs

```yaml # One-off Job (DB migration, data processing) apiVersion: batch/v1 kind: Job metadata: name: db-migrate namespace: my-namespace spec: backoffLimit: 3 # Retry up to 3 times on failure ttlSecondsAfterFinished: 3600 # Auto-delete after 1h template: spec: restartPolicy: OnFailure # Never for Jobs (not Always) containers: - name: migrate image: ghcr.io/org/my-app:1.0.0 command: ["python", "manage.py", "migrate"] resources: requests: cpu: "100m" memory: "256Mi" ```

```yaml # CronJob apiVersion: batch/v1 kind: CronJob metadata: name: cleanup-job namespace: my-namespace spec: schedule: "0 2 * * *" # 2am daily concurrencyPolicy: Forbid # Don't run if previous still running successfulJobsHistoryLimit: 3 failedJobsHistoryLimit: 1 jobTemplate: spec: template: spec: restartPolicy: OnFailure containers: - name: cleanup image: ghcr.io/org/cleanup:1.0.0 resources: requests: cpu: "50m" memory: "64Mi" ```

---

## kubectl Debugging Cheatsheet

```bash # --- Pod status and logs --- kubectl get pods -n my-namespace kubectl get pods -n my-namespace -o wide # Show node assignment kubectl describe pod <pod-name> -n my-namespace # Events and state details kubectl logs <pod-name> -n my-namespace # Current logs kubectl logs <pod-name> -n my-namespace --previous # Logs from crashed container kubectl logs <pod-name> -n my-namespace -c <container> # Multi-container pod

# --- Execute into a running container --- kubectl exec -it <pod-name> -n my-namespace -- sh kubectl exec -it <pod-name> -n my-namespace -- bash

# --- Check resource usage --- kubectl top pods -n my-namespace kubectl top nodes

# --- Deployment operations --- kubectl rollout status deployment/my-app -n my-namespace kubectl rollout history deployment/my-app -n my-namespace kubectl rollout undo deployment/my-app -n my-namespace # Rollback kubectl rollout undo deployment/my-app --to-revision=2 -n my-namespace

# --- Scale manually --- kubectl scale deployment my-app --replicas=5 -n my-namespace

# --- Inspect events (cluster-wide issues) --- kubectl get events -n my-namespace --sort-by='.lastTimestamp'

# --- Port-forward for local debugging --- kubectl port-forward pod/<pod-name> 8080:8080 -n my-namespace kubectl port-forward svc/my-app 8080:80 -n my-namespace

# --- Dry-run to validate YAML --- kubectl apply -f deployment.yaml --dry-run=client kubectl apply -f deployment.yaml --dry-run=server # Validates against live cluster ```

### Diagnosing Common Errors

```bash # CrashLoopBackOff: container keeps crashing kubectl logs <pod-name> --previous -n my-namespace # Check crash logs kubectl describe pod <pod-name> -n my-namespace # Check exit code & OOMKilled

# ImagePullBackOff: can't pull image kubectl describe pod <pod-name> -n my-namespace # Check Events section # Causes: wrong image tag, missing imagePullSecret, private registry

# Pending pod: not scheduled kubectl describe pod <pod-name> -n my-namespace # Causes: insufficient resources, no matching node selector, taint/toleration mismatch

# OOMKilled: out of memory # Increase memory limits, check for memory leaks kubectl describe pod <pod-name> -n my-namespace | grep -A5 "Last State" ```

---

## Anti-Patterns

```yaml # BAD: Using :latest tag — non-deterministic deployments image: myapp:latest

# GOOD: Pin to a specific immutable tag (SHA or semver) image: ghcr.io/org/myapp:1.4.2 # or image: ghcr.io/org/myapp@sha256:abc123...

# ---

# BAD: Running as root securityContext: {} # Defaults to root

# GOOD: Non-root with explicit UID securityContext: runAsNonRoot: true runAsUser: 1001

# ---

# BAD: No resource limits — one pod can starve the entire node containers: - name: app image: myapp:1.0.0 # No resources defined

# GOOD: Always set requests and limits resources: requests: cpu: "100m" memory: "128Mi" limits: cpu: "500m" memory: "256Mi"

# ---

# BAD: Storing plaintext secrets in ConfigMaps apiVersion: v1 kind: ConfigMap data: DB_PASSWORD: "mysecretpassword" # NEVER — use Secret or external secrets manager

# ---

# BAD: ClusterAdmin for application service accounts apiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRoleBinding roleRef: kind: ClusterRole name: cluster-admin # Grants god-mode to your app

# ---

# BAD: minAvailable: 0 in PDB — defeats the purpose spec: minAvailable: 0

# ---

# BAD: restartPolicy: Always in a Job (causes infinite restart loop) spec: restartPolicy: Always # Use OnFailure or Never for Jobs ```

---

## Best Practices Checklist

### Security - [ ] Container runs as non-root (`runAsNonRoot: true`, `runAsUser` set) - [ ] `readOnlyRootFilesystem: true` with `emptyDir` for writable paths - [ ] `allowPrivilegeEscalation: false` - [ ] All capabilities dropped (`capabilities.drop: [ALL]`) - [ ] Dedicated ServiceAccount per app, not `default` - [ ] `automountServiceAccountToken: false` unless needed - [ ] RBAC follows least privilege (use `Role`, not `ClusterRole` unless needed) - [ ] Secrets managed via Sealed Secrets or External Secrets Operator

### Reliability - [ ] All 3 probe types configured (startup + liveness + readiness) - [ ] Resource requests AND limits set on every container - [ ] `minReplicas: 2+` for any production workload - [ ] PodDisruptionBudget defined for stateful or critical services - [ ] `RollingUpdate` strategy with `maxUnavailable: 0` - [ ] HPA configured for variable-load services

### Observability - [ ] App exposes `/health` (liveness) and `/ready` (readiness) endpoints - [ ] Structured JSON logging (no PII in logs) - [ ] Resource labels: `app`, `version`, `environment`

---

## Related Skills

- `docker-patterns` — Multi-stage Dockerfiles and image security - `deployment-patterns` — CI/CD pipelines, rollback strategy, health check endpoints - `security-review` — Broader security hardening context - `git-workflow` — GitOps integration with K8s (ArgoCD / Flux patterns)

Intended uses

  • Use Kubernetes Patterns when this documented workflow matches the task.

Implementation notes

  • Review the source instructions and adapt inputs before running the workflow.

Try it, then tell us how it went

A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.