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.
Starting and stopping existing Machines is much faster than creating and destroying them. Stopped Machines are cheaper than running ones. Machines release their CPU and RAM when they stop, and their rootfs is rebuilt fresh from their Docker image, ready to start.
For bursty workloads, we recommend creating enough Machines to handle your peak load, and adjusting the active capacity of the app by stopping and starting Machines as needed.
For more information, see:
There are two ways to change the number of Machines managed by Fly Launch after deploying an app for the first time:
- with the
fly scale countsubcommand
- 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.
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.
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.
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
Groups NAME COUNT KIND CPUS MEMORY REGIONS app 4 shared 1 256 MB yyz(4)
Now there are four Machines in yyz.
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.
fly scale count command destroys Machines, the volumes become unattached and can be used again when scaling up.
fly scale count command creates new empty volumes, or attaches existing volumes, and does not copy or move any data between volumes.
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-nameapp has volumes for Machines that belong to 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
--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.
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
fly scale count 4 --process-group web --region nrt,yyz
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
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.
--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 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 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!
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
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
If you destroy a Machine with a volume attached, the volume remains intact until you either explicitly destroy the volume or destroy the app it belongs to.