# kubectl scale: Usage, Options & Common CI Errors

> kubectl scale sets the replica count on Deployments and StatefulSets. Conditional scaling with --current-replicas, and why HPAs fight a manual scale.

Source: https://latchkey.dev/learn/command-reference/kubectl-scale  
Updated: 2026-06-25

Set the replica count up or down in one command.

kubectl scale changes the desired replica count of a scalable controller. It is common in CI for scaling down a preview environment or scaling a job-runner deployment for a load test.

## What it does

kubectl scale --replicas=N sets the replica field on a Deployment, ReplicaSet, StatefulSet, or ReplicationController. --current-replicas makes the change conditional (only scale if currently at M), which avoids racing another actor. It returns once the spec is updated, not once pods are Ready.

## Common usage

```Terminal
kubectl scale deploy/web --replicas=5
kubectl scale statefulset/db --replicas=3
kubectl scale deploy/web --replicas=0          # park a preview env
kubectl scale deploy/web --current-replicas=2 --replicas=4
kubectl scale --replicas=3 -f deploy.yaml
```

## Common errors in CI

The most confusing "failure" is no error at all: you scale a Deployment that is also managed by a HorizontalPodAutoscaler, and the HPA immediately scales it back, so your replica count silently reverts. Scale the HPA bounds (or delete it) instead of the Deployment. "the object has been modified; please apply your changes to the latest version" on --current-replicas means another controller changed the count between read and write - re-read and retry. Remember scale does not wait for readiness; follow it with kubectl rollout status if the pipeline depends on the new pods being up.

## Using this in CI

A runner has no kubeconfig, no cached context, and no interactive auth. Every kubectl invocation in CI needs the context supplied explicitly, and most confusing CI failures here are the command running against the wrong cluster or no cluster at all.

```Terminal
# never rely on the ambient context on a runner
kubectl --context "$KUBE_CONTEXT" -n "$NAMESPACE" get pods

# confirm what you are actually connected to before mutating anything
kubectl config current-context
kubectl cluster-info

# fail fast instead of hanging on an unreachable API server
kubectl --request-timeout=30s get nodes
```

> Always set `--request-timeout` in CI. Without it an unreachable API server hangs until the job times out, which turns a thirty-second failure into a twenty-minute one.

## FAQ

### kubectl scale: Usage, Options & Common CI Errors?

kubectl scale changes the desired replica count of a scalable controller. It is common in CI for scaling down a preview environment or scaling a job-runner deployment for a load test.

### What it does?

kubectl scale --replicas=N sets the replica field on a Deployment, ReplicaSet, StatefulSet, or ReplicationController. --current-replicas makes the change conditional (only scale if currently at M), which avoids racing another actor. It returns once the spec is updated, not once pods are Ready.

### Common errors in CI?

The most confusing "failure" is no error at all: you scale a Deployment that is also managed by a HorizontalPodAutoscaler, and the HPA immediately scales it back, so your replica count silently reverts. Scale the HPA bounds (or delete it) instead of the Deployment.

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt