Kubernetes deployments: A complete guide with examples
Learn how to create and manage Kubernetes Deployments. Covers creating Deployments, rolling updates, rollback with kubectl rollout undo, scaling, and zero-downtime update strategy.
9 lessons · 27 min · Intermediate
Written by
Marketing Team at Civo
Written by
Marketing Team at Civo
A Deployment is the standard way to run stateless applications in Kubernetes. It manages pods through a ReplicaSet, ensures the desired number of replicas is always running, and enables rolling updates and rollbacks without downtime.
You should almost never create pods directly in production. If a pod dies, it stays dead. A Deployment automatically recreates pods that fail and maintains the replica count you specify.
Declarative YAML
Most practitioners define Deployments in YAML and apply them with kubectl apply. Here is a complete Deployment manifest:
apiVersion: apps/v1kind: Deploymentmetadata:name: demospec:replicas: 3selector:matchLabels:app: demostrategy:type: RollingUpdaterollingUpdate:maxSurge: 25%maxUnavailable: 25%template:metadata:labels:app: demospec:containers:- name: nginximage: nginxports:- containerPort: 80
kubectl apply -f deployment.yaml
Create a Deployment imperatively
For quick testing and learning, you can create a Deployment without a YAML file:
kubectl create deployment demo --image=nginx --replicas=3 --port=80
Verify the Deployment was created:
kubectl get deploy
Expected output:
NAME READY UP-TO-DATE AVAILABLE AGEdemo 3/3 3 3 15s
Check the rollout status:
kubectl rollout status deployment demo
Expected output:
deployment "demo" successfully rolled out
Check the pods:
kubectl get pods
Expected output:
NAME READY STATUS RESTARTS AGEdemo-6b7f9d8c5-abc12 1/1 Running 0 20sdemo-6b7f9d8c5-def34 1/1 Running 0 20sdemo-6b7f9d8c5-ghi56 1/1 Running 0 20s
Check the ReplicaSet created automatically by the Deployment:
kubectl get rs
Expected output:
NAME DESIRED CURRENT READY AGEdemo-6b7f9d8c5 3 3 3 25s
Rolling update
When you change the image, Kubernetes performs a rolling update. New pods are created with the new image and old pods are terminated only after the new ones are ready. Traffic is never fully interrupted.
Update the image:
kubectl set image deployment/demo nginx=nginx:1.25.0
Watch the rollout:
kubectl rollout status deployment demo
Expected output:
Waiting for deployment "demo" rollout to finish: 1 out of 3 new replicas have been updated...Waiting for deployment "demo" rollout to finish: 2 out of 3 new replicas have been updated...Waiting for deployment "demo" rollout to finish: 1 old replicas are pending termination...deployment "demo" successfully rolled out
Check the ReplicaSets:
kubectl get rs
Expected output — the old ReplicaSet scales to 0 and the new one scales to 3:
NAME DESIRED CURRENT READY AGEdemo-6b7f9d8c5 0 0 0 3mdemo-54b8f9d7c 3 3 3 30s
Describe the Deployment to see the rolling update events in detail:
kubectl describe deployment demo
The Events section shows the step-by-step scale up and scale down. The Strategy section shows maxSurge: 25% and maxUnavailable: 25%, meaning up to one extra pod can be created during the update and up to one pod can be unavailable at a time.
If you want to record what changed for audit purposes, annotate the Deployment after the update:
kubectl annotate deployment/demo kubernetes.io/change-cause="updated nginx to 1.25.0"
What happens when a wrong image is set
If you set an invalid image tag, Kubernetes creates a new pod but it fails to pull the image. The previous pods continue running because the max surge pod never becomes ready, so the old pods are never terminated:
kubectl set image deployment/demo nginx=nginx:does-not-existkubectl get pods
Expected output — the new pod is stuck in ImagePullBackOff while the old pods keep running:
NAME READY STATUS RESTARTS AGEdemo-6b7f9d8c5-abc12 1/1 Running 0 5mdemo-6b7f9d8c5-def34 1/1 Running 0 5mdemo-6b7f9d8c5-ghi56 1/1 Running 0 5mdemo-9f2a1b3c4-xyz99 0/1 ImagePullBackOff 0 30s
Your application continues serving traffic. Roll back to fix it.
Rollback
View rollout history:
kubectl rollout history deployment demo
Expected output:
REVISION CHANGE-CAUSE1 <none>2 updated nginx to 1.25.03 <none>
Roll back to the previous revision:
kubectl rollout undo deployment demo
Roll back to a specific revision:
kubectl rollout undo deployment demo --to-revision=2
Verify the rollback:
kubectl get podskubectl get rs
The ReplicaSet from revision 2 scales back up to 3 and the failed ReplicaSet scales to 0.
Scaling
Scale the Deployment up or down at any time:
kubectl scale deployment demo --replicas=5
Verify:
kubectl get pods
Expected output:
NAME READY STATUS RESTARTS AGEdemo-54b8f9d7c-abc12 1/1 Running 0 5mdemo-54b8f9d7c-def34 1/1 Running 0 5mdemo-54b8f9d7c-ghi56 1/1 Running 0 5mdemo-54b8f9d7c-jkl78 1/1 Running 0 5sdemo-54b8f9d7c-mno90 0/1 ContainerCreating 0 2s
kubectl get deploy
Expected output:
NAME READY UP-TO-DATE AVAILABLE AGEdemo 5/5 5 5 6m
Edit and delete
Edit the Deployment YAML directly:
kubectl edit deploy demo
This opens the live manifest in your editor. Save and exit to apply changes immediately.
Delete the Deployment and all its pods:
kubectl delete deployment demo
Pods enter a Terminating state. By default there is a 30-second grace period during which in-flight requests are completed before the pod is removed.
Marketing Team at Civo
Civo is the Sovereign Cloud and AI platform designed to help developers and enterprises build without limits. We bridge the gap between the openness of the public cloud and the rigorous security of private environments, delivering full cloud parity across every deployment. As a team, we are dedicated to providing scalable compute, lightning-fast Kubernetes, and managed services that are ready in minutes. Through CivoStack Enterprise and our FlexCore appliance, we empower organizations to maintain total data sovereignty on their own hardware.
Our mission is to make the cloud faster, simpler, and fairer. By providing enterprise-grade NVIDIA GPUs and streamlined model management, we ensure that high-performance AI and machine learning are accessible to everyone. Built for transparency and performance, the Civo Team is here to give you total control over your infrastructure, your data, and your spend.
Share this lesson