Skip to main content
Scale a replicated service by changing the number of container replicas. Scaling up adds more containers, while scaling down removes containers and requires confirmation.

​
Usage

uc service scale SERVICE REPLICAS

​
Arguments

​
SERVICE
string
required
Name or ID of the service to scale.
​
REPLICAS
integer
required
Target number of replicas. Must be greater than 0.

​
Examples

​
Scale up to 5 replicas

uc service scale web 5

​
Scale down to 1 replica

You’ll be asked to confirm when scaling down: 
uc service scale web 1
You’ll see a plan before confirming: 
Scaling plan for service web (3 → 1 replicas):
- Remove container web-def456 from machine vps1
- Remove container web-ghi789 from machine vps2

Do you want to continue?

​
Scaling Up

When you scale up, new containers are created on available machines: 
uc service scale api 3
Output: 
Scaling service api (1 → 3 replicas)
✓ Created container on machine vps1
✓ Created container on machine vps2

​
Scaling Down

When you scale down, containers are removed. You’ll see a plan and be asked to confirm: 
uc service scale api 1
Output: 
Scaling plan for service api (3 → 1 replicas):
- Remove container api-abc123 from machine vps1
- Remove container api-def456 from machine vps2

Do you want to continue? (y/N) y

Scaling service api (3 → 1 replicas)
✓ Removed container api-abc123
✓ Removed container api-def456

​
Important Notes

​
Replicated Services Only

This command only works for services in replicated mode. Global services (one container per machine) cannot be scaled. If you try to scale a global service: 
Error: scaling is only supported for services in replicated mode, service 'caddy' is in global mode

​
Cannot Scale to Zero

You cannot scale a service to 0 replicas. Use uc service rm to remove the service instead: 
uc service scale web 0
Error: 
Error: scaling to zero replicas is not supported. This would effectively remove
the service without preserving its configuration, making it impossible to scale
back up. Uncloud derives the service configuration from existing containers.
Use 'uc rm web' instead if you want to remove the service

​
Data Loss Warning

When scaling down, containers are removed. If they have local data (not in volumes), that data will be lost. Make sure important data is stored in volumes.

​
No Effect if Already at Target

If the service already has the target number of replicas: 
uc service scale web 3
Output: 
Service 'web' already has 3 replicas. No changes required.

​
Use Cases

​
Handle Traffic Spikes

Scale up during high traffic: 
uc service scale web 10
Scale down when traffic decreases: 
uc service scale web 3

​
Development vs Production

Run fewer replicas in development: 
uc service scale api 1
More replicas in production: 
uc service scale api 5

​
Maintenance

Scale down before maintenance: 
uc service scale worker 1

​
Container Distribution

Uncloud distributes containers across machines automatically. When scaling up, new containers are placed on machines with available resources.
  • uc service ls - View current replica count
  • uc ps - See which machines have containers
  • uc run - Create a service with initial replicas
  • uc deploy - Deploy with replica count from Compose file

Build docs developers (and LLMs) love

Get started for freeTalk to us