Skip to content

Kubernetes workloads: Pods and Deployments

A workload is an application running on Kubernetes. You almost never run containers directly: you describe Pods, and in practice you describe a controller such as a Deployment that creates and replaces Pods for you. This page covers the Pod first, because every other workload is built from it, then the Deployment, which is how most stateless services run.

The examples follow an invented OrdersPortal application whose orders-api container listens on port 8080. The manifests were validated against the Kubernetes 1.37 API schemas with kubernetes-validate; kubectl and a cluster were not available, so kubectl commands and their output are not run here and follow the kubernetes.io documentation. To try them, use a local cluster such as kind or minikube and kubectl apply -f <file>.

Topic What it answers
Pods What a Pod is, how its containers share network and storage, and when to use a sidecar.
Pod lifecycle and probes Pod phases, and how startup, readiness and liveness probes differ.
Resource requests and limits How CPU and memory settings affect scheduling, throttling and OOM kills.
Deployments How a Deployment keeps N identical Pods running through ReplicaSets.
Rolling updates and rollbacks How to ship a new version without downtime and undo a bad one.
Scaling and autoscaling Manual scaling and the HorizontalPodAutoscaler.

A Pod is the smallest deployable unit in Kubernetes: one or more containers that are scheduled together on the same node and share a network namespace and volumes. Containers in a Pod have the same IP address, reach each other on localhost, and can mount the same volumes. A Pod is not a container; it is the wrapper Kubernetes schedules, restarts and gives an IP to.

Most Pods run one application container. Add a second container only when it is tightly coupled to the first and must share its lifecycle, for example a log shipper reading files the application writes. Since Kubernetes 1.33, native sidecar containers are stable: you declare them in initContainers with restartPolicy: Always. Kubernetes starts them before the main containers, keeps them running for the Pod’s lifetime, and stops them after the main containers, which fixes the old problem of sidecars blocking Jobs from completing.

# pod.yaml - a single Pod for a debugging session
apiVersion: v1
kind: Pod
metadata:
name: orders-api-debug
namespace: ordersportal
labels:
app.kubernetes.io/name: orders-api
spec:
initContainers:
- name: log-shipper
image: registry.example.test/ordersportal/log-shipper:1.3.0
restartPolicy: Always # native sidecar
volumeMounts:
- name: logs
mountPath: /var/log/orders-api
containers:
- name: orders-api
image: registry.example.test/ordersportal/orders-api:2.4.1
ports:
- containerPort: 8080
resources:
requests:
cpu: 250m
memory: 256Mi
limits:
memory: 512Mi
volumeMounts:
- name: logs
mountPath: /var/log/orders-api
volumes:
- name: logs
emptyDir: {}

Pods are disposable. If the node fails or the Pod is evicted, a bare Pod is gone; nothing recreates it. Its IP address changes when it is replaced, and anything written to its container file system or emptyDir volume disappears with it. That is why you put Pods behind a Service for a stable address, use PersistentVolumes for data that must survive, and let a controller manage them.

The commands you use most with Pods are kubectl get pods, kubectl describe pod <name> (events, conditions, the reason for the last restart), kubectl logs <name> -c <container> (add --previous for the crashed instance) and kubectl exec -it <name> -- sh. The kubectl command reference lists more.

Pitfalls:

  • Creating bare Pods for real services. Use a Deployment, StatefulSet, DaemonSet or Job. A bare Pod is not rescheduled when its node dies.
  • Putting unrelated services in one Pod. They then scale, restart and deploy together. Separate Pods talking through a Service is the default.

Every Pod has a status.phase:

Phase Meaning (from the Kubernetes documentation)
Pending Accepted by the cluster, but one or more containers is not yet set up and ready to run; includes time waiting to be scheduled and pulling images.
Running Bound to a node and all containers created; at least one is running, starting or restarting.
Succeeded All containers terminated successfully and will not be restarted.
Failed All containers terminated and at least one failed.
Unknown The Pod’s state could not be obtained, usually because the node is unreachable.

CrashLoopBackOff and ImagePullBackOff are not phases; they are container waiting reasons you see in kubectl get pods and kubectl describe pod.

Probes tell the kubelet how to judge a container’s health. They answer three different questions, and mixing them up causes outages:

  • A startup probe asks “has the application finished starting?” While it has not succeeded, the other probes are disabled. Use it for slow starters instead of a long initialDelaySeconds.
  • A readiness probe asks “should this Pod receive traffic now?” When it fails, the Pod is removed from Service endpoints but not restarted. Use it for warm-up and for temporarily shedding load.
  • A liveness probe asks “is this container stuck beyond recovery?” When it fails, the kubelet restarts the container.

The Deployment in the next sections uses all three. Keep liveness checks cheap and local: a liveness probe that calls the database restarts every replica at once when the database is slow, which turns a slowdown into an outage.

Pitfalls:

  • Same endpoint and thresholds for readiness and liveness. Readiness should fail first so traffic drains before any restart.
  • No startup probe for a slow application. The liveness probe kills it before it finishes starting, and the Pod never leaves CrashLoopBackOff.

Each container can declare requests and limits for CPU and memory. The scheduler uses requests to decide which node has room: a Pod requesting 250m CPU (a quarter of a core) and 256Mi memory is placed only on a node with that much unrequested capacity. Limits are enforced at run time: a container that exceeds its memory limit is killed (OOMKilled), and one that exceeds its CPU limit is throttled.

Requests and limits also decide the Pod’s quality of service class. Pods in which every container sets CPU and memory limits equal to its requests are Guaranteed; Pods with some requests are Burstable; Pods with none are BestEffort and are evicted first when a node runs out of memory.

A common, defensible setting for web services is the one in the samples: CPU and memory requests based on observed usage, a memory limit to contain leaks, and no CPU limit so the container can use idle CPU instead of being throttled. Teams that need strict isolation set CPU limits as well. Whatever you choose, measure: requests far above real usage waste nodes, and requests far below it overload them.

Pitfalls:

  • No requests at all. The scheduler packs Pods onto nodes it thinks are empty, and under load they evict each other.
  • Memory limit too close to normal usage. Garbage-collected runtimes such as the JVM and .NET grow toward the limit; leave headroom or configure the runtime’s heap limit.

A Deployment manages a set of identical, interchangeable Pods. You declare the desired number of replicas and a Pod template; the Deployment creates a ReplicaSet for that template, and the ReplicaSet keeps the right number of Pods running, replacing any that fail or disappear with their node. The selector must match the template’s labels; it is how the controller finds the Pods it owns.

deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: orders-api
namespace: ordersportal
labels:
app.kubernetes.io/name: orders-api
spec:
replicas: 3
revisionHistoryLimit: 5
selector:
matchLabels:
app.kubernetes.io/name: orders-api
strategy:
type: RollingUpdate
rollingUpdate:
maxUnavailable: 0
maxSurge: 1
template:
metadata:
labels:
app.kubernetes.io/name: orders-api
spec:
containers:
- name: orders-api
image: registry.example.test/ordersportal/orders-api:2.4.1
ports:
- name: http
containerPort: 8080
resources:
requests:
cpu: 250m
memory: 256Mi
limits:
memory: 512Mi
startupProbe:
httpGet:
path: /healthz
port: http
failureThreshold: 30
periodSeconds: 2
readinessProbe:
httpGet:
path: /ready
port: http
periodSeconds: 5
livenessProbe:
httpGet:
path: /healthz
port: http
periodSeconds: 10

Apply it with kubectl apply -f deployment.yaml, then kubectl get deployment orders-api -n ordersportal shows how many replicas are ready, up to date and available. Because the manifest is the source of truth, change the file and re-apply rather than editing live objects; that keeps Git, the cluster and your CI pipeline in agreement.

Deployments suit stateless services. For workloads that need a stable identity and their own persistent volume per replica (databases, brokers), use a StatefulSet; for one Pod per node (log or metrics agents), a DaemonSet; for run-to-completion tasks, a Job or CronJob.

Pitfalls:

  • Changing the selector. spec.selector is immutable for apps/v1 Deployments; changing it means deleting and recreating the Deployment.
  • Using the latest tag. The Pod template does not change when latest moves, so no rollout happens, and different nodes can run different builds. Use immutable version tags or digests.

Changing the Pod template (a new image tag, an environment variable, a resource value) starts a rollout. With the default RollingUpdate strategy, the Deployment creates a new ReplicaSet and shifts Pods from the old one to the new one gradually. maxSurge is how many extra Pods may exist above the desired count, and maxUnavailable is how many may be unavailable; both default to 25%. The sample sets maxUnavailable: 0 and maxSurge: 1, so capacity never drops below three ready Pods during a release. New Pods count as available only once their readiness probe passes, which is what makes the rollout zero-downtime. The alternative strategy, Recreate, stops all old Pods before starting new ones; use it only when two versions must never run at the same time.

Terminal window
# Not run here: needs a cluster
kubectl set image deployment/orders-api orders-api=registry.example.test/ordersportal/orders-api:2.5.0 -n ordersportal
kubectl rollout status deployment/orders-api -n ordersportal
kubectl rollout history deployment/orders-api -n ordersportal
kubectl rollout undo deployment/orders-api -n ordersportal # back to the previous revision
kubectl rollout undo deployment/orders-api --to-revision=3 -n ordersportal

kubectl rollout status waits until the rollout finishes or exceeds progressDeadlineSeconds (600 seconds by default), which makes it a good final step in a deployment pipeline. The Deployment keeps old ReplicaSets, up to revisionHistoryLimit, so that rollout undo can scale one back up. kubectl rollout restart restarts all Pods with the same template, useful after a mounted Secret changes.

Pitfalls:

  • A rollout that never finishes. If new Pods never become ready (bad config, failing probe), the Deployment stops progressing but leaves old Pods serving. Watch rollout status in CI and alert on it.
  • Rolling back the cluster but not Git. rollout undo changes the live object only. Revert the manifest too, or the next apply reintroduces the bad version.

kubectl scale deployment/orders-api --replicas=5 changes the replica count immediately, but the next kubectl apply of a manifest with replicas: 3 sets it back. For load-driven scaling, use a HorizontalPodAutoscaler (HPA). The HPA reads metrics, usually CPU or memory utilization from the Metrics Server, and adjusts the Deployment’s replicas between a minimum and a maximum. Utilization is measured against the container’s request, which is another reason requests must be realistic.

hpa.yaml
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
name: orders-api
namespace: ordersportal
spec:
scaleTargetRef:
apiVersion: apps/v1
kind: Deployment
name: orders-api
minReplicas: 3
maxReplicas: 10
metrics:
- type: Resource
resource:
name: cpu
target:
type: Utilization
averageUtilization: 70

When an HPA manages a Deployment, remove replicas from the Deployment manifest (or leave it out of what your deployment tool applies), otherwise every apply fights the autoscaler. autoscaling/v2 also supports custom and external metrics, such as queue length, through a metrics adapter, and the behavior field controls how fast the HPA scales up and down.

Pitfalls:

  • No Metrics Server. The HPA shows <unknown> targets and never scales. Check with kubectl get hpa.
  • Scaling on CPU for an I/O-bound service. CPU stays low while requests queue. Scale on a metric that reflects the bottleneck.
You need Use
A stateless service with N interchangeable replicas Deployment
Stable identity and storage per replica StatefulSet
One Pod on every node DaemonSet
A task that runs to completion, once or on a schedule Job or CronJob
A helper process tied to one application container Native sidecar in the same Pod
Replica count that follows load HorizontalPodAutoscaler on the Deployment

What is the difference between a Pod and a container? A container is a process with its own image and file system. A Pod is the Kubernetes scheduling unit that wraps one or more containers sharing a network namespace (same IP, localhost) and volumes, scheduled together on one node.

What happens when a readiness probe fails, and when a liveness probe fails? A failing readiness probe removes the Pod from Service endpoints so it stops receiving traffic; the container keeps running. A failing liveness probe makes the kubelet restart the container.

How does a Deployment perform a zero-downtime update? It creates a new ReplicaSet for the new template and shifts replicas gradually within maxSurge and maxUnavailable, counting a new Pod as available only after its readiness probe passes. Old Pods keep serving until enough new ones are ready.

Why might a Pod be OOMKilled even though the node has free memory? The container exceeded its own memory limit. Limits are enforced per container regardless of node capacity.

Senior scenario: after a release, OrdersPortal’s API returns errors for 30 seconds on every deploy. How do you investigate and fix it? Check whether traffic reaches Pods before they are ready (missing or too-lenient readiness probe) and whether old Pods are killed while still handling requests. Add a readiness probe that checks the application can serve, set maxUnavailable: 0, add a preStop hook or handle SIGTERM by finishing in-flight requests within terminationGracePeriodSeconds, and make sure the startup probe covers slow starts. Verify with a load test during a rollout and alert on rollout status failures in the pipeline.