How to create a Kubernetes Deployment

Kubernetes Deployments keep stateless application Pods running from a desired Pod template and replica count. A Deployment is the normal controller for an HTTP service, worker, or internal tool when the cluster should replace failed Pods and manage future rollouts instead of leaving a single Pod unmanaged.

kubectl create deployment can create a starter Deployment without writing YAML first. With a name, image, replica count, and port, kubectl sends a Deployment object to the API server, and the Deployment controller creates a ReplicaSet that owns the matching Pods.

A disposable namespace keeps the validation workload separate from existing applications. Use a release-specific image tag or digest, then move to a reviewed manifest when the workload needs probes, resource requests, security context, environment variables, or source-controlled rollout settings.

1. Create a namespace for the Deployment test.

   $ kubectl create namespace app-deployment
   namespace/app-deployment created

   Use the target application namespace instead of app-deployment when creating a real workload.

   Related: How to create a Kubernetes namespace

2. Create the Deployment with the target image, replica count, and container port.

   $ kubectl create deployment web --namespace app-deployment --image=nginx:1.29.5-alpine --replicas=2 --port=80
   deployment.apps/web created

   --replicas sets the desired Pod count, and --port records the container port in the Pod template. Replace the image with the application image that should run in the cluster.

3. Wait for the Deployment rollout to finish.

   $ kubectl rollout status deployment/web --namespace app-deployment --timeout=120s
   Waiting for deployment "web" rollout to finish: 0 of 2 updated replicas are available...
   Waiting for deployment "web" rollout to finish: 1 of 2 updated replicas are available...
   deployment "web" successfully rolled out

4. Check the Deployment replica status.

   $ kubectl get deployment web --namespace app-deployment
   NAME   READY   UP-TO-DATE   AVAILABLE   AGE
   web    2/2     2            2           9s

   READY and AVAILABLE should match the requested replica count before the workload is treated as running.

5. List the ReplicaSet and Pods created by the Deployment.

   $ kubectl get rs,pods --namespace app-deployment -l app=web
   NAME                             DESIRED   CURRENT   READY   AGE
   replicaset.apps/web-76f74bd998   2         2         2       9s
   
   NAME                       READY   STATUS    RESTARTS   AGE
   pod/web-76f74bd998-ccb7m   1/1     Running   0          9s
   pod/web-76f74bd998-nwqjd   1/1     Running   0          9s

   kubectl create deployment labels the starter workload with app=web. Use labels that match the application naming policy when creating production objects.

6. Inspect the Deployment template for the selected image, labels, and port.

   $ kubectl describe deployment web --namespace app-deployment
   Name:                   web
   Namespace:              app-deployment
   Labels:                 app=web
   Selector:               app=web
   Replicas:               2 desired | 2 updated | 2 total | 2 available | 0 unavailable
   StrategyType:           RollingUpdate
   ##### snipped #####
   Pod Template:
     Labels:  app=web
     Containers:
      nginx:
       Image:         nginx:1.29.5-alpine
       Port:          80/TCP
   ##### snipped #####
   NewReplicaSet:   web-76f74bd998 (2/2 replicas created)

7. Run a small smoke check inside one Deployment Pod.

   $ kubectl exec deployment/web --namespace app-deployment -- nginx -v
   nginx version: nginx/1.29.5

   Use an application-specific health or version command when the container image does not include nginx.

8. Delete the test namespace when the Deployment was only created for validation.

   $ kubectl delete namespace app-deployment
   namespace "app-deployment" deleted

   Skip this command for a real application namespace. Delete only the test Deployment if the namespace contains other workloads.