Kubernetes Deployment Specification

Kubernetes Deployment Specification Reference

Comprehensive reference for Kubernetes Deployment resources, covering all key fields, best practices, and common patterns.

Overview

A Deployment provides declarative updates for Pods and ReplicaSets. It manages the desired state of your application, handling rollouts, rollbacks, and scaling operations.

When to use this skill

• Authoring or reviewing a Kubernetes Deployment manifest.
• Pinning down which Deployment fields are mandatory vs recommended.
• Picking an update strategy (RollingUpdate vs Recreate) and its parameters.
• Choosing replica count, surge/unavailable budgets, and revisionHistoryLimit.
• Setting probes (startup / liveness / readiness), security context, and resource requests/limits.
• Picking a deployment pattern: high-availability, sidecar, init container.
• Diagnosing common Deployment failure modes (ImagePullBackOff, CrashLoopBackOff, stuck rollouts).

Reference map

The detailed reference material lives behind pointers so an invocation loads only what it needs.

Field reference index

Common patterns (one-line summaries)

• High availability — replicas: 3+, maxUnavailable: 0, pod anti-affinity by hostname.
• Sidecar container — primary app + sidecar container in the same pod (logging, proxy, secrets refresh) with shared emptyDir volume.
• Init container — run setup or dependency-wait steps before main containers start (DB migrations, fetching config).

Full YAML for each pattern: references/patterns.md.

Production checklist

• Set resource requests and limits.
• Implement all three probe types (startup, liveness, readiness).
• Use specific image tags (not :latest).
• Configure security context (non-root, read-only filesystem).
• Set replica count >= 3 for HA.
• Configure pod anti-affinity for spread.
• Set appropriate update strategy (maxUnavailable: 0 for zero-downtime).
• Use ConfigMaps and Secrets for configuration.
• Add standard labels and annotations.
• Configure graceful shutdown (preStop hook, terminationGracePeriodSeconds).
• Set revisionHistoryLimit for rollback capability.
• Use ServiceAccount with minimal RBAC permissions.

Performance tuning

Fast startup:

spec:
  minReadySeconds: 5
  strategy:
    rollingUpdate:
      maxSurge: 2
      maxUnavailable: 1

Zero-downtime updates:

spec:
  minReadySeconds: 10
  strategy:
    rollingUpdate:
      maxSurge: 1
      maxUnavailable: 0

Graceful shutdown:

spec:
  template:
    spec:
      terminationGracePeriodSeconds: 60
      containers:
        - name: app
          lifecycle:
            preStop:
              exec:
                command: ["/bin/sh", "-c", "sleep 15 && kill -SIGTERM 1"]

Troubleshooting

Common failure modes — load the full catalog in references/troubleshooting.md when diagnosing:

• Pods not starting — kubectl describe deployment <name>, then drill into the failing pod (get pods -l app=<app>, describe pod, logs).
• ImagePullBackOff — wrong image name/tag, missing imagePullSecrets, registry credentials.
• CrashLoopBackOff — application crashes, overly aggressive liveness probe, resource limits, missing dependencies.
• Rollout stuck in progress — progressDeadlineSeconds exceeded, readiness probe never succeeds, cluster resource pressure.

Related resources

• Kubernetes Deployment API Reference
• Pod Security Standards
• Resource Management

Source: kmshihab7878/claude-code-setup — distributed by TomeVault.