kubectl-scale

Scale a replica set

$ kubectl scale --replicas=[number_of_replicas] rs/[replica_name]

$ kubectl scale --replicas=[number_of_replicas] [[-f|--filename]] [path/to/file.yml]

$ kubectl scale --current-replicas=[current_replicas] --replicas=[number_of_replicas] deployment/[deployment_name]

kubectl scale --replicas=<COUNT> (TYPE NAME | TYPE/NAME | -f <FILENAME> | --selector=<LABELS> TYPE) [options]

Example: kubectl scale --replicas=3 deployment/my-app

--replicas=COUNT
    The number of desired replicas for the resource. This is a mandatory option for scaling.

--current-replicas=COUNT
    A pre-condition for optimistic locking. The scale operation will only proceed if the resource's current replica count matches this value.

--resource-version=VERSION
    A pre-condition for optimistic locking. The scale operation will only proceed if the resource's resource version matches this value.

-f, --filename=FILE
    Path to a file, directory, or URL that contains the resource configuration to scale.

-l, --selector=LABELS
    Selector (label query) to filter resources. Used to scale multiple resources of the same type that match the specified labels.

--timeout=DURATION
    The maximum time to wait for the scale operation to be applied (e.g., '5s', '2m').

--dry-run=
    If set, only print the object that would be sent to the server, without actually performing the scale operation.

The kubectl scale command is used to imperatively change the desired number of replicas for scalable Kubernetes resources such as Deployments, ReplicaSets, StatefulSets, and ReplicationControllers. This operation directly updates the spec.replicas field of the specified resource via the Kubernetes API server.

It is a fundamental tool for performing horizontal scaling, allowing administrators and developers to quickly scale applications in or out to adapt to varying load demands, manage resource consumption, or perform maintenance tasks. While manual scaling with kubectl scale is effective for immediate adjustments, for dynamic and automatic scaling, Horizontal Pod Autoscalers (HPAs) are typically preferred.

RBAC Permissions: Requires appropriate Role-Based Access Control (RBAC) permissions to modify the specified resource's replica count.
Scalable Resources Only: Only applicable to Kubernetes resources that support scaling, primarily Deployments, ReplicaSets, StatefulSets, and ReplicationControllers.
HPA Interaction: If a Horizontal Pod Autoscaler (HPA) is managing the target resource, manual scaling via kubectl scale might be immediately overridden by the HPA's logic as it strives to maintain its desired metrics.
Optimistic Locking: Using --current-replicas and --resource-version helps prevent race conditions when multiple users or processes might try to scale the same resource simultaneously.
Imperative Nature: This command performs an immediate, imperative change. For declarative management, it's often better to update the resource's YAML definition or use HPAs.

The --current-replicas and --resource-version flags are used for optimistic locking. This mechanism ensures that the scale operation only proceeds if the resource is in the expected state before the update. If the resource's replica count or version has changed since it was last read, the command will fail, preventing unintended concurrent modifications and data inconsistencies. This is crucial in environments where multiple automated systems or users might be attempting to modify the same resource.

Common Kubernetes resource types that can be scaled using kubectl scale include:
Deployments: Manages a replicated application, handling updates and rollbacks.
ReplicaSets: Ensures a specified number of pod replicas are running at any given time. Deployments internally manage ReplicaSets.
StatefulSets: Used for stateful applications, ensuring stable, unique network identifiers and persistent storage.
ReplicationControllers (Legacy): Similar to ReplicaSets but is an older, deprecated API object.

The scale command has been an integral part of kubectl since the early days of Kubernetes, providing a straightforward and essential mechanism for managing application scalability. Its core functionality has remained consistent, adapting to new scalable resource types as Kubernetes has evolved. It exemplifies kubectl's role as a powerful, imperative control plane interface for Kubernetes clusters.

kubectl autoscale(1), kubectl get(1), kubectl apply(1), kubectl edit(1), kubectl describe(1)