Custom VM Images

WarpBuild allows you to use your own custom VM images in your custom runner configurations while running them on your own cloud. This is useful if you are using a custom VM image that you have built due to a specific need.

💡 Note: The "images" referred to in this section are VM images. This is distinct from the custom container images support.

VM Image requirements

AMIs

1. Linux and Windows based AMIs are currently supported.

Linux

1. The Linux distro the image is based on should be using systemd. WarpBuild relies on it to run its agent.
2. curl and wget should be present in the image.

Windows

1. aria2 is used for downloading the necessary artifacts since the default windows method is slow. The image needs to have aria2 present and it should be accessible through the system PATH. Below is sample script which can be used to install aria2.

New-Item -ItemType Directory -Path 'C:\Tools\aria2' -Force
# Use: https://github.com/aria2/aria2/releases/latest to fetch the latest release and replace it
Invoke-WebRequest -Uri 'https://github.com/aria2/aria2/releases/download/release-1.37.0/aria2-1.37.0-win-64bit-build1.zip' -OutFile 'C:\Tools\aria2\aria2.zip'
Expand-Archive -Path 'C:\Tools\aria2\aria2.zip' -DestinationPath 'C:\Tools\aria2' -Force
Remove-Item 'C:\Tools\aria2\aria2.zip' -Force
Move-Item -Path 'C:\Tools\aria2\aria2-1.37.0-win-64bit-build1\*' -Destination 'C:\Tools\aria2' -Force
Remove-Item -Path 'C:\Tools\aria2\aria2-1.37.0-win-64bit-build1' -Recurse -Force
[Environment]::SetEnvironmentVariable('Path', $Env:Path + ';C:\Tools\aria2', 'Machine')

2. If working with AWS instances, the EC2 instance must be sysprepped before making a windows image out of it. Please look at the 'Additional Notes' > 'Windows' > 'Sysprep' section for details on sysprepping.

Additional Notes

Windows on AWS

The runners are run under the runneradmin user, the same user as github's windows runners. If this user is not present, it will be added. If you have user scoped environment variables, you might need to change them to system level or add them to the runneradmin user's environment instead.

Sysprep (GUI)

For generalizing using the GUI,

1. RDP into the instance and open 'Amazon EC2Launch settings'. Press 'Shutdown with sysprep' > Press 'Yes' on the dialog box.
2. The above step will disconnect you in some time. This is expected. Go to the instance in the ec2 dashboard and wait for the instance to reach 'Stopped' state (might take a min).
3. Rest of the steps are mostly same. Use the console to create the image. Fill in the details. Unselect the 'reboot' option since we already have the machine in a shutdown state.

Wait for the AMI to be ready. The image should be a generalized one now.

Sysprep (Automation)

Refer to the following packer docs for sysprep automation. These commands can be invoked without the use of packer as well from a powershell instance.

Common issues

1. Unable to RDP into the instance

We don't expose RDP port (3389) by default when you create a stack. You must add a security policy enabling the inbound TCP connections to 3389 from a.b.c.d/e (replace this with your CIDR block)

2. Password incorrect when trying to login via Administrator

Administrator account for windows has a rotating password for each ec2 instance. AWS automatically creates and assigns this password. It is recommended that you create your own user and give it admin permissions. You can use the below commands to create the user and assign it admin.

Write-Host 'Creating custom user'
$MACHINE_USER = "customuser"
$MACHINE_PASSWORD = "CustomU$er!2025"
$Password = ConvertTo-SecureString $MACHINE_PASSWORD -AsPlainText -Force
New-LocalUser -Name $MACHINE_USER -Password $Password -FullName "Custom User" -Description "Custom User for CI/CD"
Add-LocalGroupMember -Group "Administrators" -Member $MACHINE_USER
Add-LocalGroupMember -Group "Users" -Member $MACHINE_USER
 
# Set customuser user to not require password change at next logon
Set-LocalUser -Name $MACHINE_USER -PasswordNeverExpires $true

Add the image

1. Setup a WarpBuild Stack
2. Add a VM image using the Add Image button on the custom images page. All the images in the region the stack is in will be listed. Select the image you want to use.
3. Create a custom runner using the image.
4. Use the custom runner label in your workflows to run the jobs on this container image.

Pricing

There is no additional cost for using custom VM images.