DevOps Dictionary

Kubernetes Deployment is a Kubernetes workload API object that manages replicated pods and updates them safely over time. In practical terms, you define the desired state of an application, such as the container image, number of replicas, ports, and update strategy, and Kubernetes works to keep the running pods aligned with that state.

What a Kubernetes Deployment does

A Deployment is most commonly used for stateless applications, such as web services, APIs, background workers, and internal platform services. It helps you run multiple identical pod replicas and change them without replacing everything manually.

• Runs replicated pods: You can specify, for example, 3 replicas of an API service.
• Performs rolling updates: Kubernetes can replace old pods with new ones gradually when you change the container image or configuration.
• Supports rollback: If a new version fails, you can roll back to a previous ReplicaSet revision.
• Self-heals pods: If a pod crashes or gets deleted, Kubernetes creates a replacement.
• Scales workloads: You can increase or decrease the replica count manually or with autoscaling tools.

How it works

A Deployment manages a ReplicaSet, and the ReplicaSet manages the pods. You usually interact with the Deployment, while Kubernetes handles the lower-level objects.

1. You create a Deployment manifest in YAML.
2. The Deployment controller creates a ReplicaSet.
3. The ReplicaSet creates the required number of pods.
4. If you update the Deployment, Kubernetes creates a new ReplicaSet for the new version.
5. Kubernetes shifts traffic by replacing old pods with new pods according to the update strategy.

For example, if you change an image from my-api:1.4.0 to my-api:1.5.0, the Deployment controller creates new pods with the new image and gradually terminates pods from the old ReplicaSet.

Key fields in a Deployment

• metadata.name: The name of the Deployment.
• spec.replicas: The number of pod replicas to run.
• spec.selector: The label selector used to find pods managed by the Deployment.
• spec.template: The pod template, including labels, containers, images, ports, environment variables, volumes, and probes.
• strategy: Controls how updates are rolled out, usually with the default RollingUpdate strategy.

Common use cases

• Running a stateless HTTP API behind a Kubernetes Service.
• Deploying a frontend application served by NGINX or another web server.
• Running internal workers that can be horizontally scaled.
• Shipping new application versions through CI/CD pipelines.
• Managing workloads with GitOps tools such as Argo CD or Flux.

Teams often manage Deployment manifests with Helm, Kustomize, or Terraform. If you use Terraform to manage Kubernetes objects, this guide on how to deploy Kubernetes resources using Terraform shows a practical workflow.

Simple example

A minimal Deployment for a web API might run three replicas of the same container image:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: payments-api
spec:
  replicas: 3
  selector:
    matchLabels:
      app: payments-api
  template:
    metadata:
      labels:
        app: payments-api
    spec:
      containers:
        - name: payments-api
          image: example/payments-api:1.0.0
          ports:
            - containerPort: 8080

This tells Kubernetes to keep three pods running for the payments-api workload. If one pod fails, Kubernetes starts another. If you update the image tag, Kubernetes rolls out the new version according to the Deployment strategy.

Deployment update strategies

The default strategy is RollingUpdate. It replaces pods gradually so the application can stay available during a release, assuming the app is healthy and has enough replicas.

• RollingUpdate: Replaces old pods with new pods in controlled batches.
• Recreate: Terminates all old pods before starting new ones. This causes downtime and is usually used only when two versions cannot run at the same time.

Rolling updates depend heavily on good readiness probes. Without them, Kubernetes may send traffic to a pod before the application is ready to serve requests.

Deployment vs Pod vs ReplicaSet

• Pod: The smallest runnable unit in Kubernetes. It contains one or more containers.
• ReplicaSet: Ensures a specified number of matching pods are running.
• Deployment: Manages ReplicaSets and provides declarative updates, rollout history, and rollback behavior.

In most application deployments, you should create a Deployment rather than creating pods or ReplicaSets directly. The Deployment gives you safer updates and easier operational control.

How it differs from nearby Kubernetes objects

• StatefulSet: Use for stateful workloads that need stable identities and persistent storage, such as databases or clustered systems.
• DaemonSet: Use when you need one pod on every selected node, such as a log collector or node agent.
• Job: Use for finite tasks that should run to completion, such as migrations or batch processing.
• CronJob: Use for scheduled jobs, such as nightly cleanup tasks.

Benefits

• Declarative operations: You describe the desired state, and Kubernetes continuously reconciles toward it.
• Safer releases: Rolling updates reduce the need for manual pod replacement.
• Rollback support: You can return to a previous revision if a rollout breaks.
• Scaling support: You can change replica counts directly or pair the Deployment with a Horizontal Pod Autoscaler.
• Works well with CI/CD: A pipeline can update an image tag, apply a manifest, and let Kubernetes handle the rollout.

Tradeoffs and limitations

• Not ideal for stateful systems: Deployments do not provide stable pod identity or ordered startup and shutdown.
• Bad probes can break rollouts: Missing or incorrect readiness and liveness probes can cause downtime or failed releases.
• Configuration changes need care: Updating ConfigMaps or Secrets does not always restart pods automatically unless your workflow handles it.
• Rollbacks do not undo everything: A Deployment rollback changes the pod template, but it does not roll back databases, external services, or schema changes.

Real-world example

Suppose your team runs a SaaS billing API on Amazon Elastic Kubernetes Service. You define a Deployment with 6 replicas, a readiness probe on /healthz, and a rolling update strategy that allows at most 1 unavailable pod during a release.

When your CI pipeline builds billing-api:2.8.3, it updates the Deployment image. Kubernetes starts new pods, waits for them to become ready, and then removes old pods. If the new pods fail readiness checks, the rollout stalls instead of sending production traffic to broken instances.

The same release model applies whether you deploy a small API or a larger platform workload. For example, this walkthrough on how to deploy Apache Airflow on AWS Elastic Kubernetes Service shows how Kubernetes workloads fit into a real AWS-based setup.

Operational tips

• Set CPU and memory requests so the scheduler can place pods reliably.
• Use readiness probes before exposing pods through a Service.
• Use liveness probes only when the application can safely be restarted.
• Keep image tags traceable, such as Git SHA tags, instead of relying only on latest.
• Set maxUnavailable and maxSurge based on your traffic and capacity needs.
• Check rollout status with kubectl rollout status deployment/<name>.
• Plan Kubernetes version upgrades carefully because API behavior and defaults can change. These practical tips for Kubernetes upgrades for startups cover common upgrade concerns.

Where Deployments fit in infrastructure workflows

A Deployment handles application pods inside the cluster. It does not create cloud resources such as databases, IAM roles, queues, or object storage buckets. Platform teams often combine Deployments with infrastructure tools to manage the full application stack.

For example, Crossplane can manage cloud resources through Kubernetes APIs, while Deployments run the application workloads that use those resources. If you are exploring that pattern, see this guide on how to deploy AWS resources using Crossplane on Kubernetes.

Summary

A Kubernetes Deployment is the standard way to run and update stateless applications in a cluster. It manages ReplicaSets, keeps the desired number of pods running, supports rolling updates, and gives engineering teams a practical path for safer application releases.