Custom Images for Runner
You can use custom images for your runners as well. One use case for that is you want pre installed packages.
AWS Custom AMI
One of the most common applications of Cirun is the ability to run CI on custom VM images on cloud. One common applcation for the same is using GPU enabled machine with NVIDIA VM image for running GPU related things in the CI
AWS Marketplace has many such useful images, which can help make your CI faster.
Using Prebuilt Images: NVIDIA Deep Learning AMI
Let's take an example of using an NVIDIA Deep Learning AMI for GPU enabled runners.
To use any AMI (Amazon Machine Image) in your
.cirun.yml, you need two things:
- The AMI ID for the runner in that region (default region is
- Accept Terms and condition for the AMI.
Here are the steps to achieve the above.
Go to AWS Marketplace and Search for "NVIDIA Deep Learning AMI".
In the search results click on the "NVIDIA Deep Learning AMI".
Click on "Continue to Subscribe" on the top right to accept terms and condition. (You need to be logged in to your AWS account for this). You should see the following page after subscribing.
Click on "Continue to configuration" button on the top right.
Here you can see the Ami Id of the image, which now you can use in your
region: "eu-west-1" # this is default region anyways (only required if using an AMI ID from different region)
In the above photo we can see the AMI ID for "NVIDIA Deep Learning AMI" in the Ireland region (
Pricing: This AMI is free to use, the pricing you see on the right is the price for the instance not for the AMI.
AWS Marketplace NVIDIA Deep Learning AMI
It is important to accept terms and conditions of the AMI you want to use, using the process described above, otherwise you'll not be able to provision the runner.
# Self-Hosted Github Action Runners on AWS via Cirun.io
# Reference: https://docs.cirun.io/Reference/yml.html
- name: "gpu-runner"
# Cloud Provider: AWS
# NVIDIA Deep Learning AMI from AWS Marketplace
AWS: Building Custom Images with user modification
You can also build custom images on AWS on top of already existing images and install packages and custom configuration and use that image for Cirun runner on GitHub Actions. Here are the steps for same:
Launch an instance on AWS (following the steps mentioned below):
Set the name for new instance and select the image for operating system:
Select Instance type (the size which is good enough for your CI job):
Select a keypair if you have one already or create a new one and make sure to save the private key generated, this will help you login to the created machine:
Select allow SSH traffic in the "Network" section and add storage in the "Configure storage" section (this storage will be available to your CI job, make sure to put enough space here, the default storage is quite low)
Now click on "launch instance" to launch the instance
After the instance has been created now click on the created instance (in the instances section of the EC2 Dashboard) and copy the "Public IPv4 address".
SSH into the machine (using the private key created using step 3) and install any packages tools you would like it to be available to the CI job.
Now click on the Actions > Image and templates > Create Imge to create image of the instance we just created.
Fill in image name, description and volume size and hit "Create Image"
Copy AMI ID for using with Cirun: Now go to EC2 Dashboard > Images > AMIs and copy the "AMI ID" and use it in your
.cirun.ymlfile, so that the instances created will be based in this image.
GCP Custom Images
- Create a new instance from GCP Cloud Compute:
The harware configuration (CPU, memory, location, etc.) does not matter. The instance is only used to configure a boot device.
Once the instance starts, SSH into the VM and install any libraries or packages the custom image should have.
Navigate to "Machine images"
- Create a new Machine Image from the VM instance:
Once the machine image is successfully created, you can safely terminate the VM instance.
Navigate to "IAM & Admin"
Edit permissions for the Cirun user (the same user which is used to set up Cirun in GCP here) to include "Service Account User":
- Configure the
.cirun.ymlfile with the custom machine image:
- name: "custom-image-runner"
machine_image: "cirun-runners:example-machine-image" # YOUR-PROJECT-NAME:MACHINE-IMAGE-NAME
Azure Custom Images
For making custom images in Azure user needs to just capture an existing VM and create the image in a resource group.
Nginx Ubuntu custom image
Let's take an example of how to create a custom image on Azure. We will make a ubuntu image with Nginx pre-installed. Then we will create a VM using this custom image. Here are the steps to achieve the above.
- Create a ubuntu VM in a new or existing resource group from the Azure dashboard.
- SSH into the VM and install Nginx using.
sudo apt install nginx
- Now capture the VM using the capture button inside the VM. "For Share image to Shared image gallery" option select "No, capture only a managed image".
- Also, tick the checkbox having the option "Automatically delete this virtual machine after creating the image".
- Change the name of VM and click on review and create.
- After the image has been created go to the resource group in which you have created the image. Your image will be present here.
- To list all custom images using Azure CLI use
az image list
- The above command shows all the custom images available on your Azure. It also shows "id" for all custom images. This is the parameter we use to make VM with a custom image.
Azure custom image vm
The .cirun.yml for above custom image will look like
# Self-Hosted Github Action Runners on Azure via Cirun.io
# Reference: https://docs.cirun.io/Reference/yml.html
- name: "azure-runner"
# Cloud Provider: Azure
Openstack Custom Images
In OpenStack only cirros image is provided by default, this image is not suitable for the runners to run the jobs. To build a custom image we need to download a cloud image and create an Openstack image from it. Here we will create a
ubuntu-20.04 cloud image.
Ubuntu cloud images are available at https://cloud-images.ubuntu.com. You can create any image but for this tutorial, we will use
focal cloud images.
- Open the terminal and make sure you are
stackor the user that build OpenStack
sudo -u stack -i
- Cd into devstack and authenticate yourself
cd devstack && source openrc admin
- Go to https://cloud-images.ubuntu.com/focal/current and copy the url of
- Download the image by using wget
- After the image has been downloaded you can create an image named
ubuntu-20.04with disk type
qcow2using the below command
openstack image create --file focal-server-cloudimg-amd64.img --disk-format qcow2 ubuntu-20.04
- Now if the above steps were fine you would have created an image named
ubuntu-20.04. You can verify it using
openstack image listor visiting the image section on the dashboard.