Kubernetes Deployment

Kubernetes Deployment Manager

Implements apps/v1 Deployment YAML manifests for stateless application workloads with rolling update strategies, replica management, and controlled rollback procedures. When loaded, the model generates production-grade Deployment resources with proper strategy configuration, health probes, and rollout monitoring.

TL;DR Checklist

• Use apps/v1 API version — never extensions/v1beta1 or apps/v1beta1
• Set strategy.type: RollingUpdate with explicit maxSurge and maxUnavailable
• Define minReadySeconds to prevent premature rollout of next batch
• Include livenessProbe and readinessProbe with appropriate initial delays
• Never use strategy.type: Recreate for zero-downtime deployments
• Verify rollout status with kubectl rollout status before proceeding

When to Use

Use this skill when:

• Creating a Deployment manifest for a stateless application (web servers, API services, worker processes)
• Configuring rolling update parameters to control rollout speed and safety
• Implementing rollback procedures for failed deployments
• Scaling replica count for horizontal capacity adjustments
• Managing deployment strategy for blue-green or canary deployment patterns

When NOT to Use

Avoid this skill for:

• Stateful applications requiring stable network IDs — use kubernetes-statefulset instead
• Pods needing guaranteed ordering during creation/deletion — use kubernetes-statefulset instead
• Persistent storage per replica — use kubernetes-persistentvolume with StatefulSet
• Single-instance workloads that should never run in parallel — consider a Job instead

Core Workflow

1. Determine Deployment Requirements — Identify replica count, container image, ports, and resource limits. Checkpoint: Verify the application is stateless (no local disk writes, no sticky sessions) — if not, StatefulSet is required.

2. Define Pod Template Spec — Create the spec.template.spec with containers, ports, environment variables, volume mounts, and security context. Checkpoint: Every container must have a livenessProbe and readinessProbe configured.

3. Configure Rolling Update Strategy — Set strategy.type: RollingUpdate with rollingUpdate.maxSurge and rollingUpdate.maxUnavailable. Checkpoint: maxSurge and maxUnavailable must sum to no more than 50% of replicas for safe scaling, unless explicitly tolerating temporary excess.

4. Set Replicas and Selector — Define spec.replicas and a spec.selector.matchLabels that matches the pod template labels. Checkpoint: Selector labels must exactly match spec.template.metadata.labels — mismatched selectors cause deployment rejection.

5. Create and Validate Manifest — Apply the manifest with kubectl apply -f deployment.yaml --dry-run=client then kubectl apply -f deployment.yaml. Checkpoint: Run kubectl rollout status deploy/<name> and verify all pods reach Ready state.

6. Plan Rollback Path — Keep the previous revision history available. Use kubectl rollout undo deploy/<name> if the new version shows errors. Checkpoint: Monitor pod logs and metrics during the first 60 seconds after each rollout.

Implementation Patterns

Pattern 1: Production-Grade Deployment Manifest

A complete Deployment with rolling update strategy, health probes, resource limits, and proper labeling for service discovery.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: web-frontend
  namespace: production
  labels:
    app: web-frontend
    tier: frontend
    version: v2.1.0
spec:
  replicas: 3
  revisionHistoryLimit: 5
  selector:
    matchLabels:
      app: web-frontend
      tier: frontend
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 1
      maxUnavailable: 0
      minReadySeconds: 30
  template:
    metadata:
      labels:
        app: web-frontend
        tier: frontend
        version: v2.1.0
    spec:
      terminationGracePeriodSeconds: 30
      securityContext:
        runAsNonRoot: true
        runAsUser: 1000
        fsGroup: 1000
      containers:
        - name: web-frontend
          image: registry.example.com/web-frontend:2.1.0
          ports:
            - containerPort: 8080
              protocol: TCP
              name: http
          env:
            - name: APP_ENV
              value: production
            - name: LOG_LEVEL
              valueFrom:
                configMapKeyRef:
                  name: app-config
                  key: log-level
          resources:
            requests:
              cpu: 250m
              memory: 256Mi
            limits:
              cpu: 500m
              memory: 512Mi
          livenessProbe:
            httpGet:
              path: /healthz
              port: 8080
            initialDelaySeconds: 15
            periodSeconds: 10
            timeoutSeconds: 3
            failureThreshold: 3
          readinessProbe:
            httpGet:
              path: /ready
              port: 8080
            initialDelaySeconds: 5
            periodSeconds: 5
            timeoutSeconds: 2
            failureThreshold: 3
          volumeMounts:
            - name: config-volume
              mountPath: /etc/app/config
              readOnly: true
      volumes:
        - name: config-volume
          configMap:
            name: app-config

Pattern 2: Rolling Update Strategy Configuration (BAD vs GOOD)

Configuring the rolling update strategy incorrectly can cause service downtime or excessive resource usage.

# ❌ BAD — default strategy causes unpredictable rollout behavior
# maxSurge and maxUnavailable are unset, using defaults (25%/25%) which
# may take down too many pods or spin up too many simultaneously.
strategy:
  type: RollingUpdate

# ❌ BAD — Recreate strategy causes full downtime on every deployment
strategy:
  type: Recreate

# ✅ GOOD — explicit RollingUpdate with conservative safety parameters
strategy:
  type: RollingUpdate
  rollingUpdate:
    maxSurge: 1            # Only add 1 extra pod during rollout
    maxUnavailable: 0      # Never reduce below desired replica count
    minReadySeconds: 30    # Wait 30s after pod becomes ready before proceeding

# ✅ GOOD — aggressive strategy for development environments with low risk
strategy:
  type: RollingUpdate
  rollingUpdate:
    maxSurge: 2
    maxUnavailable: 1
    minReadySeconds: 5

Pattern 3: Deployment Rollback Procedure

Programmatic rollback logic using kubectl commands and manifest versioning.

# Rollback to previous revision
# kubectl rollout undo deployment/web-frontend -n production

# Rollback to a specific revision (if history is preserved)
# kubectl rollout undo deployment/web-frontend -n production --to-revision=2

# View rollout history
# kubectl rollout history deployment/web-frontend -n production

# View details of a specific revision
# kubectl rollout history deployment/web-frontend -n production --revision=3

# View rollout status after apply or undo
# kubectl rollout status deployment/web-frontend -n production --timeout=120s

# Pause and resume rollouts for manual approval gates
# kubectl rollout pause deployment/web-frontend -n production
# kubectl rollout resume deployment/web-frontend -n production

def check_deployment_healthy(name: str, namespace: str, timeout_seconds: int = 120) -> bool:
    """Check if a Deployment rollout completed successfully.

    Uses kubectl rollout status to verify all pods are Ready.
    Returns True if healthy, False if timeout or failure detected.

    Args:
        name: Deployment name.
        namespace: Kubernetes namespace.
        timeout_seconds: Maximum time to wait for rollout.

    Returns:
        True if rollout completed successfully, False otherwise.
    """
    import subprocess
    try:
        result = subprocess.run(
            ["kubectl", "rollout", "status", f"deploy/{name}",
             "-n", namespace, f"--timeout={timeout_seconds}s"],
            capture_output=True, text=True, timeout=timeout_seconds + 10
        )
        return result.returncode == 0 and "successfully rolled out" in result.stdout
    except subprocess.TimeoutExpired:
        return False
    except FileNotFoundError:
        return False

Constraints

MUST DO

• Always use apps/v1 API version — never extensions/v1beta1 or apps/v1beta1 (both are removed in Kubernetes 1.16+)
• Set explicit strategy.type: RollingUpdate with concrete maxSurge and maxUnavailable values
• Define both livenessProbe and readinessProbe on every container — never rely on defaults
• Use resources.requests and resources.limits on every container for proper scheduling and QoS
• Include terminationGracePeriodSeconds (≥ 30s for graceful shutdown) in the pod spec
• Match spec.selector.matchLabels exactly to spec.template.metadata.labels
• Set revisionHistoryLimit: 5 to preserve rollout history for rollbacks
• Use minReadySeconds (≥ 15s) to ensure pods are truly ready before the next batch starts

MUST NOT DO

• Never use strategy.type: Recreate for production stateless workloads — it causes full downtime
• Never omit livenessProbe or readinessProbe — the node cannot detect unhealthy pods otherwise
• Never set maxUnavailable to the total replica count — this allows complete outage during rollout
• Never use latest tag in production images — always pin to a specific image digest or semver tag
• Never set terminationGracePeriodSeconds: 0 — in-flight requests will be dropped on pod deletion
• Never match selector labels to pods outside this Deployment — it can cause unexpected pod management

Output Template

When implementing a Kubernetes Deployment, produce the following:

1. Deployment YAML — Complete apps/v1 Deployment manifest with metadata, spec.replicas, spec.strategy, spec.selector, and spec.template fully defined.
2. Strategy Rationale — Brief explanation of chosen maxSurge, maxUnavailable, and minReadySeconds values relative to the replica count.
3. Probe Configuration — Document the health check endpoints, intervals, and thresholds for liveness and readiness probes.
4. Rollback Plan — Command sequence for undoing the deployment if issues arise, including the revision number to target.

Related Skills

Live References

Authoritative documentation links for this skill's domain. The model follows markdown links at load time to resolve external references and inline content.

• Kubernetes Deployments Documentation — Official guide to Deployment concepts, strategies, and lifecycle
• Rolling Updates and Rollbacks — How rolling updates work and rollback procedures
• Deployment Strategy Types — RollingUpdate vs Recreate strategy configuration
• Probes Documentation — Liveness, readiness, and startup probe configuration
• Pod Security Context — Security context settings for containers and pods
• Kubernetes API Reference — apps/v1 Deployment — Complete API schema for Deployment resources
• Resource Management for Pods and Containers — CPU and memory requests/limits configuration