Scale the Number of Machines

The maximum capacity of an app is determined by the number of Fly Machines belonging to it. You scale an app horizontally by creating or destroying Machines.

There are two ways to change the number of Machines managed by Fly Launch after deploying an app for the first time:

1. with the fly scale count subcommand
2. by explicitly cloning or destroying existing Machines on the app

fly scale count uses internal rules to create or destroy Machines to reach the target scale that you specify. Machines get created when the target number of Machines is higher than the existing total, and Machines get destroyed when the target number of Machines is lower than the existing total.

When Machines are created or destroyed using fly scale count or fly machine clone/fly machine destroy, the resulting scale is preserved by fly deploy—except in the case that you scale right down to zero Machines. If there are no existing Machines, then fly deploy seeds the app with new Machines in the primary_region and according to the [processes] configured in your fly.toml file. For more information about how many Machines are created when you launch a new app or deploy from zero, refer to Redundancy by default on first deploy.

View the app’s current scale

fly scale show outputs all the scale information about an app’s Machines: how many Machines of each VM specification, in each of the app’s process groups, in each region.

Here’s an example to illustrate that:

fly scale show

VM Resources for app: my-app-name

Groups
NAME    COUNT   KIND            CPUS    MEMORY  REGIONS
app     3       shared          4       1024 MB mia,scl(2)
disk    3       shared          4       1024 MB ord(2),scl
task    4       performance     1       2048 MB iad,mia,ord,scl

This app has 10 Machines total. The app process group has two in scl (Santiago) and one in mia (Miami). disk has two in ord (Chicago) and one in scl. task has one Machine in each of iad (Ashburn), mia, ord, and scl. You can put your Machines wherever works best for your app.

Scale the number of Machines in a single region

The following examples apply to a Fly App’s default process group: the app process group. If you don’t define process groups, then all of the app’s Machines belong to the app process group, with the exception of any Machines created with fly machine commands or the Machines API.

fly scale count applies changes to the default process group if it is not passed explicit per-process target counts.

Here’s the fly scale show output for a newly deployed web app, with two machines in yyz (Toronto):

fly scale show

VM Resources for app: my-app-name

Groups
NAME    COUNT   KIND    CPUS    MEMORY  REGIONS 
app     2       shared  1       256 MB  yyz(2) 

The simplest way to scale up is by using fly scale count <target-count>. This command just adds more Machines to the default process group in the app’s existing region:

fly scale count 4

The result:

Groups
NAME    COUNT   KIND    CPUS    MEMORY  REGIONS 
app     4       shared  1       256 MB  yyz(4) 

Now there are four Machines in yyz.

Scale an app with volumes

When you scale an app with volumes, the fly scale count command attaches volumes to the Machines it creates: first using unattached volumes that already exist in the Machine’s region, and then creating new volumes if there are not enough—or any—existing volumes.

When the fly scale count command destroys Machines, the volumes become unattached and can be used again when scaling up.

In this example, the app starts with 1 Machine with an attached volume in the disk process and 1 unattached volume, all in the yul region. The following command to scale the disk process to 3 Machines creates 2 new Machines and 1 new volume:

fly scale count disk=3 --region yul

App 'my-app-name' is going to be scaled according to this plan:
  +2 machines for group 'disk' on region 'yul' with size 'shared-cpu-1x'
  +1 new volumes and using 1 existing volumes for group 'disk' in region 'yul'
? Scale app my-app-name? (y/N)

Note that the preceding example specifies:

• The region where we have unattached volumes and want the Machines to live.
• The process group, because our my-app-name app has volumes for Machines that belong to the disk process group.

Scale an app’s regions

The --region option takes one or more region codes. fly scale count creates and/or destroys Machines to reach the specified target count across the regions you list in this option, and tries to balance its changes across these regions.

For example, to end up with a total of three Machines between the yyz (Toronto) and ewr (Secaucus) regions on an app:

fly scale count 3 --region yyz,ewr

In the above example, the resulting total Machine count seen with fly scale show will be more than 3 if the app has existing Machines in regions other than yyz and ewr:

Groups
NAME    COUNT   KIND    CPUS    MEMORY  REGIONS        
web     4       shared  1       256 MB  ewr,mia,yyz(2)

You can also set the scale explicitly per region by specifying a single region per fly scale command. For example:

fly scale count 4 --region ewr

If --region is not used, then the target count is distributed across all the regions in which the app already has Machines that belong to any process group.

Scale by process group

fly scale count takes explicit target counts per process group.

Here’s an app with two process groups running in two regions, nrt (Tokyo) and yyz (Toronto):

fly scale show

VM Resources for app: my-app-name

Groups
NAME    COUNT   KIND    CPUS    MEMORY  REGIONS       
web     4       shared  1       256 MB  nrt(2),yyz(2)
worker  4       shared  1       256 MB  nrt(2),yyz(2)

Scale it out to 10 web Machines and 6 worker Machines, without constraining the change by region:

fly scale count web=10 worker=6

App 'my-app-name' is going to be scaled according to this plan:
  +3 machines for group 'web' on region 'yyz' with size 'shared-cpu-1x'
  +3 machines for group 'web' on region 'nrt' with size 'shared-cpu-1x'
  +1 machines for group 'worker' on region 'yyz' with size 'shared-cpu-1x'
  +1 machines for group 'worker' on region 'nrt' with size 'shared-cpu-1x'
? Scale app my-app-name? Yes
Executing scale plan
  Created 9080eeddc29387 group:web region:yyz size:shared-cpu-1x
  ...
  Created 1781779b52d489 group:worker region:nrt size:shared-cpu-1x

fly scale show

...
Groups
NAME    COUNT   KIND    CPUS    MEMORY  REGIONS       
web     10      shared  1       256 MB  nrt(5),yyz(5)
worker  6       shared  1       256 MB  nrt(3),yyz(3)

If an app has more capacity than required in a particular region, then you can also scale Machines by region. The following example scales both processes down by one Machine in only the yyz (Toronto) region:

fly scale count web=4 worker=2 --region yyz

As requested, nrt is unchanged, but in yyz the web process is scaled down to 4 and worker to 2 Machines.

Groups
NAME    COUNT   KIND    CPUS    MEMORY  REGIONS       
web     9       shared  1       256 MB  nrt(5),yyz(4)
worker  5       shared  1       256 MB  nrt(3),yyz(2)

You can also specify a single process group to scale using the --process-group option:

fly scale count 4 --process-group web --region nrt,yyz

Add a new region

Adding a region to an app just means putting at least one Machine there.

For example, add syd (Sydney) to an app’s regions by scaling up from 0 there:

fly scale count 2 --region syd

Now syd will show up in the app’s regions list:

fly regions list

Regions [app]: yyz, syd

If the app has multiple process groups, specify which process or processes to put in the new region:

fly scale count web=1 worker=1 --region syd

Alternatively, you can clone specific Machines to a new region, and the new Machine inherits the process group of its source Machine.

Balance Machines between regions with --max-per-region

Use --max-per-region for added control over Machine placement by region if the changes proposed by fly scale count look unbalanced. This option caps the resulting count of Machines in any one region to the number you provide.

You can also use --max-per-region to redistribute the Machine count more evenly among regions.

For example, on an app with 8 machines in yyz (Toronto), 2 in yul (Montreal) and only 1 in ewr (Secaucus):

NAME    COUNT   KIND    CPUS    MEMORY  REGIONS           
app     11      shared  1       256 MB  ewr,yul(2),yyz(8)

fly scale count 11 --max-per-region 5

NAME    COUNT   KIND    CPUS    MEMORY  REGIONS              
app     11      shared  1       256 MB  ewr(3),yul(3),yyz(5)

You can combine --max-per-region with process groups and --region in a single fly scale count command.

Scale to zero and back up

Scale to zero Machines with fly scale count. Don’t leave out any processes:

fly scale count web=0 worker=0

Check that it worked:

fly scale show

VM Resources for app: my-app-name

Groups
NAME    COUNT   KIND    CPUS    MEMORY  REGIONS 

Now if there are no Machines in any process groups, we can’t just scale up, because fly scale count relies on essentially cloning an existing Machine. But we can simply redeploy:

fly deploy

fly scale show

...
Groups
NAME    COUNT   KIND    CPUS    MEMORY  REGIONS 
web     2       shared  1       256 MB  yyz(2) 
worker  2       shared  1       256 MB  yyz(2) 

fly deploy creates two Machines per process, for resilience purposes.

We’re back in business and can scale as desired!

Scale up with fly machine clone

You can add Machines to an app by cloning Machines. The new Machine will be, as you would expect, a copy of the specified Machine, and will belong to the same process group. If the original Machine has a Fly Volume attached, an empty volume will be provisioned for the new Machine. It’s up to you to decide what to put on the new volume; fly machine clone will not automatically copy the contents of the original Machine’s volume.

The following commands create three new Machines by cloning an existing Machine:

$ fly machine clone 21781973f03e89
$ fly machine clone --region syd 21781973f03e89
$ fly machine clone --region nrt 21781973f03e89

Scale down with fly machine destroy

Use fly machine stop and fly machine destroy to scale down the app by removing specific Machines:

$ fly machine stop 9080524f610e87
$ fly machine destroy 9080524f610e87

If a Machine is misbehaving (for instance, it’s not stopping successfully), you can use fly machine destroy --force to get rid of it.

fly machine destroy --force 0e286039f42e86