Manage virtual machines with machine provisioner
Machine provisioner controls how machine executor and Remote Docker jobs are run.
This section describes the available configuration options for machine provisioner.
| Prescaling controls will be exposed in a future release for tuning. |
Provider
The following configuration options are for the machine provisioner provider, either AWS or GCP.
AWS
Configure machine provisioner to work with AWS EC2 in your values.yaml file. During installation you will have set up a security group and authentication. See the Installation Phase 3 - Execution Environments page for more information.
The information in this section describes post-installation configuration options for machine provisioner.
Windows image
If you require Windows executors, you can supply an AMI ID in your values.yaml file. To create a Windows image, use the CircleCI Server Windows image builder.
machine_provisioner:
providers:
ec2:
...
windowsAMI: "<my-windows-ami>"Alternative Linux VM image
If you wish to provide a custom AMI for Linux machine executors, you can supply an AMI ID in your values.yaml file. To create a Linux image, use the CircleCI Server Linux image builder.
machine_provisioner:
providers:
ec2:
...
linuxAMI: "<my-linux-ami>"Default AWS AMI lists
The default AMIs for server 4.10 are available for Ubuntu 22.04, 24.04, and 26.04, in both x86 and Arm variants.
-
Ubuntu 22.04
-
Ubuntu 24.04
-
Ubuntu 26.04
| Region | AMI |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| Region | AMI |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| Region | AMI |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| Region | AMI |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| Region | AMI |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| Region | AMI |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Default machine executor images
The machine provisioner ships a fixed set of default images. Share the following image names with your developers, who reference them in the machine.image key of their .circleci/config.yml.
Linux (AMD64)
-
ubuntu-2204 -
ubuntu-2404 -
ubuntu-2604 -
default- alias that resolves toubuntu-2204. -
docker-default- alias used by Remote Docker jobs that resolves toubuntu-2204.
Linux (Arm)
-
arm-default -
ubuntu-2404 -
ubuntu-2604
Windows
-
windows-default
For an example of how developers reference these images and the resource classes available in their .circleci/config.yml, see the LinuxVM Execution Environment section of the configuration reference.
GCP
Configure machine provisioner to work with GCP in your values.yaml file. During installation you will have set up a security group and authentication. See the Installation Phase 3 - Execution Environments page for more information.
The information in this section describes post-installation configuration options for machine provisioner.
Windows image
If you require Windows executors, you can supply an AMI ID in your values.yaml file. To create a Windows image, use the CircleCI Server Windows image builder.
machine_provisioner:
providers:
gcp:
...
windowsImage: "<my-windows-image>"Alternative Linux VM image
If you wish to provide a custom AMI for Linux machine executors, you can supply an AMI ID in your values.yaml file. To create a Linux image, use the CircleCI Server Linux image builder.
machine_provisioner:
providers:
gcp:
...
linuxImage: "<my-linux-image>"Default machine executor images
The machine provisioner ships a fixed set of default images. Share the following image names with your developers, who reference them in the machine.image key of their .circleci/config.yml.
Linux (AMD64)
-
ubuntu-2204 -
ubuntu-2404 -
ubuntu-2604 -
default- alias that resolves toubuntu-2204. -
docker-default- alias used by Remote Docker jobs that resolves toubuntu-2204.
Windows
-
windows-default
Android
| The Android machine executor is only available when machine provisioner is configured with GCP. |
-
android-default
For an example of how developers reference these images and the resource classes available in their .circleci/config.yml, see the LinuxVM Execution Environment section of the configuration reference.
Instance preallocation
| When using preallocated instances be aware that a cron job is scheduled to cycle through these instances once per minute to ensure they do not end up in an unworkable state. |
To configure server to keep instances preallocated, use the keys shown in the following machine-provisioner-config.yaml examples:
# -- Configuration options for, and numbers of, prescaled instances for remote Docker jobs.
preboot:
scheduled:
- executor: linux
class: medium
image: docker-default
cron: ""
count: 2# -- Configuration options for, and numbers of, prescaled instances for machine jobs.
preboot:
scheduled:
- executor: linux
class: medium
image: default
cron: ""
count: 2