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>.
Topics on this page
Section titled “Topics on this page”| 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 sessionapiVersion: v1kind: Podmetadata: name: orders-api-debug namespace: ordersportal labels: app.kubernetes.io/name: orders-apispec: 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.
Pod lifecycle and probes
Section titled “Pod lifecycle and probes”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.
Resource requests and limits
Section titled “Resource requests and limits”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.
Deployments
Section titled “Deployments”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.
apiVersion: apps/v1kind: Deploymentmetadata: name: orders-api namespace: ordersportal labels: app.kubernetes.io/name: orders-apispec: 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: 10Apply 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.selectoris immutable forapps/v1Deployments; changing it means deleting and recreating the Deployment. - Using the
latesttag. The Pod template does not change whenlatestmoves, so no rollout happens, and different nodes can run different builds. Use immutable version tags or digests.
Rolling updates and rollbacks
Section titled “Rolling updates and rollbacks”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.
# Not run here: needs a clusterkubectl set image deployment/orders-api orders-api=registry.example.test/ordersportal/orders-api:2.5.0 -n ordersportalkubectl rollout status deployment/orders-api -n ordersportalkubectl rollout history deployment/orders-api -n ordersportalkubectl rollout undo deployment/orders-api -n ordersportal # back to the previous revisionkubectl rollout undo deployment/orders-api --to-revision=3 -n ordersportalkubectl 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 statusin CI and alert on it. - Rolling back the cluster but not Git.
rollout undochanges the live object only. Revert the manifest too, or the next apply reintroduces the bad version.
Scaling and autoscaling
Section titled “Scaling and autoscaling”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.
apiVersion: autoscaling/v2kind: HorizontalPodAutoscalermetadata: name: orders-api namespace: ordersportalspec: scaleTargetRef: apiVersion: apps/v1 kind: Deployment name: orders-api minReplicas: 3 maxReplicas: 10 metrics: - type: Resource resource: name: cpu target: type: Utilization averageUtilization: 70When 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 withkubectl 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.
Choosing between them
Section titled “Choosing between them”| 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 |
Interview questions
Section titled “Interview questions”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.
Related pages
Section titled “Related pages”- Kubernetes introduction: architecture and core concepts.
- Kubernetes networking: Services, Ingress and Gateway API: giving Pods a stable address and exposing them.
- Kubernetes configuration: ConfigMaps, Secrets, namespaces and Helm: configuring and packaging workloads.
- kubectl command reference
- Docker images and containers: what goes into the image a Pod runs.