Kubernetes

Kubernetes Patterns

Best practices and anti-patterns for Kubernetes deployments, resource configuration, and cluster management. Run the linter on every manifest before review; use this prose guidance to explain findings and propose fixes.

Purpose

• Ensure reliable, scalable Kubernetes deployments
• Prevent resource exhaustion and scheduling failures
• Establish security and observability patterns

Core Patterns

Pattern 1: Resource Requests and Limits

When to use: Every production container deployment.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: api-service
spec:
  template:
    spec:
      containers:
        - name: api
          image: api:v1.2.3
          resources:
            requests:
              memory: "256Mi"
              cpu: "250m"
            limits:
              memory: "512Mi"
              cpu: "500m"

Benefits: Predictable scheduling, protection against resource exhaustion, fair resource sharing across pods.

Pattern 2: Health Probes

When to use: All production deployments.

containers:
  - name: api
    livenessProbe:
      httpGet:
        path: /health
        port: 8080
      initialDelaySeconds: 30
      periodSeconds: 10
      failureThreshold: 3
    readinessProbe:
      httpGet:
        path: /ready
        port: 8080
      initialDelaySeconds: 5
      periodSeconds: 5
      successThreshold: 1

Benefits: Auto-restart unhealthy pods, traffic only to ready pods, graceful startup handling.

Pattern 3: Pod Disruption Budgets

When to use: Production services requiring high availability.

apiVersion: policy/v1
kind: PodDisruptionBudget
metadata:
  name: api-pdb
spec:
  minAvailable: 2
  selector:
    matchLabels:
      app: api

Anti-Patterns

Anti-Pattern 1: No Resource Limits

Anti-Pattern 2: Using :latest Tag

Anti-Pattern 3: Missing Health Probes

Anti-Pattern 4: Running as Root

Anti-Pattern 5: Single Replica in Production

Validation Checklist

Implementation

• Resource requests and limits set
• Specific image tags (no :latest)
• Liveness and readiness probes configured
• Security context with non-root user
• ConfigMaps/Secrets for configuration
• Multiple replicas with anti-affinity
• PodDisruptionBudget defined

Post-Implementation

• Pods schedule successfully
• Health checks pass consistently
• Rolling updates work without downtime
• kubectl get events shows no warnings

Invocation — Kubernetes Manifest Linter (L3 Script)

Run the linter on every manifest before review. Consume its output only — the script source never enters context.

Input: JSON representation of one or more Kubernetes manifests. YAML must be converted to JSON first (see below).

YAML to JSON conversion:

python3 -c "import sys,json,yaml; print(json.dumps(yaml.safe_load(sys.stdin)))" < deployment.yaml \
  | python .claude/skills/devops/kubernetes/scripts/k8s_lint.py -

Or with yq:

yq -o json deployment.yaml | python .claude/skills/devops/kubernetes/scripts/k8s_lint.py -

Run via Bash (file argument — JSON):

python .claude/skills/devops/kubernetes/scripts/k8s_lint.py manifest.json

Run via Bash (stdin — JSON):

cat manifest.json | python .claude/skills/devops/kubernetes/scripts/k8s_lint.py -

Input format — single manifest:

{"apiVersion": "apps/v1", "kind": "Deployment", "metadata": {"name": "api"}, "spec": {...}}

Input format — multiple manifests:

[
  {"kind": "Deployment", ...},
  {"kind": "Service", ...}
]

Output:

1. JSON object with findings array (each finding has id, severity, manifest, container, title, detail, reference) and summary counts.
2. Markdown findings table sorted by severity (CRITICAL → HIGH → MEDIUM).

Findings covered:

What to do with the output:

1. CRITICAL findings (privileged containers, hostNetwork) must be blocked — these are container escape paths.
2. HIGH findings must be addressed before production deployment.
3. MEDIUM findings are strongly recommended; document and justify any exceptions.

Error handling: The script exits non-zero with an ERROR message to stderr on I/O failure or invalid JSON. The kind field is required in every manifest.

Quick Reference