Horizontal Manual Scaling for a Deployment [page]deterministic

tasksschedulingworkloads

This page shows how to manually scale a Deployment horizontally, by changing its replica count. Manual scaling lets you directly control the number of running Pods for predictable load changes or cost management.

This is different from _vertical scaling_: leaving the replica count the same, but adjusting the amount of resources available to each Pod.

Scaling up a Deployment to handle more traffic.
Scaling down a Deployment to conserve resources.
Scaling a Deployment to zero to suspend a workload.
Understanding when to use manual scaling versus a HorizontalPodAutoscaler.

You need an existing Deployment. If you do not have one, and you just want to practice, you can create the nginx Deployment from [Run a Stateless Application Using a Deployment](/docs/tasks/run-application/run-stateless-application-deployment/):

```shell kubectl apply -f https://k8s.io/examples/application/deployment.yaml ```

Verify the Deployment runs two Pods:

```shell kubectl get deployment nginx-deployment ```

The output is similar to:

``` NAME READY UP-TO-DATE AVAILABLE AGE nginx-deployment 2/2 2 2 10s ```

## Scaling up a Deployment

There are several different ways you can change the replica count for an existing Deployment.

### Scaling up using `kubectl scale`

Use `kubectl scale` to set the replica count:

```shell kubectl scale deployment/nginx-deployment --replicas=4 ```

The output is similar to:

``` deployment.apps/nginx-deployment scaled ```

Verify that the Deployment has four Pods:

```shell kubectl get deployment nginx-deployment ```

The output is similar to:

``` NAME READY UP-TO-DATE AVAILABLE AGE nginx-deployment 4/4 4 4 1m ```

### Declarative scaling using `kubectl apply`

Instead of running an imperative command, you can update the manifest file and apply it. This approach fits well with version-controlled configuration workflows.

Save the current Deployment configuration to a local file:

```shell kubectl get deployment nginx-deployment -o yaml > /tmp/nginx-deployment.yaml ```

Edit `/tmp/nginx-deployment.yaml` and change `.spec.replicas` to `4`.

Before applying, compare your local changes against the cluster state:

```shell kubectl diff -f /tmp/nginx-deployment.yaml ```

Apply the edited manifest:

```shell kubectl apply -f /tmp/nginx-deployment.yaml ```

## Scaling down a Deployment

To reduce the number of Pods, set `--replicas` to a lower value:

```shell kubectl scale deployment/nginx-deployment --replicas=2 ```

Kubernetes gracefully terminates the excess Pods, respecting each Pod's `terminationGracePeriodSeconds` setting.

Verify that the Deployment has two Pods:

```shell kubectl get pods -l app=nginx ```

The output is similar to:

``` NAME READY STATUS RESTARTS AGE nginx-deployment-66b6c48dd5-7gl6h 1/1 Running 0 2m nginx-deployment-66b6c48dd5-v8mkd 1/1 Running 0 2m ```

## Scaling to zero

You can scale a Deployment to zero to temporarily suspend the workload without deleting the Deployment itself:

```shell kubectl scale deployment/nginx-deployment --replicas=0 ```

Verify that no Pods are running:

```shell kubectl get deployment nginx-deployment ```

The output is similar to:

``` NAME READY UP-TO-DATE AVAILABLE AGE nginx-deployment 0/0 0 0 5m ```

> Note: Scaling to zero removes all Pods but preserves the Deployment and its ReplicaSet. Scale back up at any time by setting `--replicas` to a positive number.

Common use cases for scaling to zero include: