How to scale a Kubernetes Deployment

Kubernetes Deployments express how many matching application Pods should stay available while the controller replaces failed Pods and manages rollout state. Changing that replica target is a routine way to add short-term capacity, reduce an idle workload, or return a test Deployment to its normal size without changing the Pod template.

kubectl scale writes a new replica count to the Deployment scale subresource. The Deployment controller then updates the owned ReplicaSet until the READY, UP-TO-DATE, and AVAILABLE counts reflect the requested target.

Manual scaling should not compete with another controller. A HorizontalPodAutoscaler can write a different replica count after the manual change, so check the namespace before treating the new count as stable.

1. Check whether a HorizontalPodAutoscaler is already managing replicas in the namespace.

   $ kubectl get hpa --namespace team-a
   No resources found in team-a namespace.

   If an HPA targets the Deployment, change the HPA bounds or pause that automation instead of relying on a one-time manual replica count.

2. Check the Deployment before changing the replica target.

   $ kubectl get deployment web --namespace team-a
   NAME   READY   UP-TO-DATE   AVAILABLE   AGE
   web    2/2     2            2           25s

   If this reaches the wrong cluster or namespace, fix the active context before scaling.
   Related: How to check Kubernetes cluster access

3. Choose the target replica count before applying the change.

   Account for node capacity, resource requests, rollout surge, and any PodDisruptionBudget before increasing production replicas.
   Tool: Kubernetes Cluster Capacity Calculator

4. Scale the Deployment to the target replica count.

   $ kubectl scale deployment/web --namespace team-a --replicas=4
   deployment.apps/web scaled

5. Wait for the Deployment controller to finish the scale-out.

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

   If rollout status times out, inspect the Deployment, Pods, and recent events before increasing the replica count again.
   Related: How to check Kubernetes events

6. Verify that the Deployment reports the target count.

   $ kubectl get deployment web --namespace team-a
   NAME   READY   UP-TO-DATE   AVAILABLE   AGE
   web    4/4     4            4           26s

   READY, UP-TO-DATE, and AVAILABLE should match the target replica count before the workload is treated as scaled.

7. Confirm that the ReplicaSet and Pods match the scaled Deployment.

   $ kubectl get replicasets,pods --namespace team-a -l app=web
   NAME                             DESIRED   CURRENT   READY   AGE
   replicaset.apps/web-76f74bd998   4         4         4       22s
   
   NAME                       READY   STATUS    RESTARTS   AGE
   pod/web-76f74bd998-2wnmt   1/1     Running   0          2s
   pod/web-76f74bd998-fgl2q   1/1     Running   0          21s
   pod/web-76f74bd998-j8r8c   1/1     Running   0          21s
   pod/web-76f74bd998-ljhvv   1/1     Running   0          2s

   Use the Deployment's selector labels when the workload does not use app=web.