kubernetes-deployment

name	kubernetes-deployment
description	Implements apps/v1 Deployment YAML manifests with rolling update strategies, replica scaling, and rollback procedures for stateless application workloads.
license	MIT
compatibility	opencode
metadata	{"version":"1.0.0","domain":"cncf","triggers":"rolling update, replica count, deployment strategy, rollback, apps/v1, deployment rollout, kubernetes deployment","archetypes":["tactical","generation"],"anti_triggers":["stateful persistence","stable network identity","ordered pod lifecycle"],"response_profile":{"verbosity":"low","directive_strength":"high","abstraction_level":"operational"},"role":"implementation","scope":"implementation","output-format":"code","content-types":["code","guidance","config","do-dont"],"related-skills":"cncf/kubernetes-deployment, cncf/kubernetes-services-management, cncf/kubernetes-configmap"}

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

Skill	Purpose
kubernetes-services-management	Expose the Deployment via ClusterIP, NodePort, or LoadBalancer service
kubernetes-ingress	Route external HTTP/HTTPS traffic to the Deployment's service
kubernetes-configmap	Inject configuration data into the Deployment via env vars or volume mounts
kubernetes-statefulset	Deploy stateful applications that need stable network identities and persistent storage

---

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