Skip to content

Installing a Google Cloud Platform (GCP) based actions runner or build system

Jump to bottom
Dan Walkes edited this page Oct 5, 2022 · 18 revisions

Overview

If your host machine isn't powerful enough for builds (especially Yocto builds) you may consider using a virtual machine in the cloud instead. Cloud virtual machine instances are flexible enough to scale up/down in CPU for faster build times and can be turned off when not in use to limit spend.

This document assumes you are using Google Compute Engine to setup your Virtual machine. You could use other hosting services like AWS Compute instaead as well, however Google Cloud has graciously sponsored free credits for students for this course (AWS has not).

Assuming you use Google Compute Engine, follow instructions there to create an account on Google Cloud. If you haven't created an account yet, you should get $300 in free cloud credit when creating, which should be plenty to complete the course.

  • When you first create your account you should see a screen like this:

signup-free-credits

  • On the next page, which asks you for a credit card, you should see a statement mentioning you won't be charged unless you upgrade from the free trial credits free-trial-no-charge

If you are an on-campus student in the ECEN-5713 course and you run out of free cloud credit please email Dan and the Student Assistants for a limited amount of $50 vouchers usable for cloud credit.

Creating Virtual Machine in Google Compute

See the instructions at https://cloud.google.com/compute/docs/quickstart-linux with the following modifications or additional instructions:

  1. Select the version of Ubuntu referenced in the assignment 1 setup documentation and x86 host type.
  2. Select an instance name like aesd-build-machine (it doesn't matter what you use, but I'll reference this in further instructions)
  3. For Machine type I suggest c2-standard-8 on the "Compute-Optimized" tab, with 8 virtual CPUs and 32GB of Memory. When combined with an SSD build disk (see next section) this machine can perform a typical yocto build from a clean build tree in around 1.5 hours. The cost (only when running) of this machine is around $0.42 cents per hour. For a lower cost machine with longer build times, you can consider the c2-standard-4 type instead. Build machines larger than c2-standard-8 aren't currently allowed with free google cloud credits.

Adding Build Disk

The OS disk will be too small to hold your Yocto/Buildroot build content. Even if it were large enough there might be some benefits for keeping on another disk. For instance, you can make your build disk a faster SSD type to speed up build times.

To add a build disk, first create a disk named build-cache under Compute Engine->VM Instances->aesd-build-machine->Edit->Additional Disks->Add New Disk

  1. Use a size of 150GB at minimum. If you want to do development on this machine in addition to running tests you might want to bump up to 250 or 300 GB.
  2. Use a name build-cache (You can use any name, but you'll need to substitute into the formatting instructions below).
  3. Consider using SSD provisioned space for fastest Yocto build times. Please note that this disk incurs costs (against your vouchers or free initial cloud credit) of around $20 per month even when not in use, see Disk image pricing. You can use slower "Standard provisioned space" of only $4 per month if you want to conserve your cloud credit.

Installing and using the gcloud command line utility

Use the instructions at this link to install the gcloud utility, which is very useful for controlling your virtual machine over the command line.
Initialize your gcloud environment using

gcloud init

from the command line.

You can then start your virtual machine with:

gcloud compute instances start aesd-build-machine

and login via SSH using

gcloud compute ssh aesd-build-machine

You can stop your machine using

gcloud compute instances stop aesd-build-machine

Instead of or in addition to using the instructions here, you can start or stop your virtual machine from the Compute Engine->VM Instances section.

Partitioning and formatting your build disk

Once you've started and logged into your instance via SSH, you can use these commands to partition and format your build cache disk, substituting your disk name for the DISK_NAME argument below if you used a name other than build-cache. These instructions will:

  • Partition and format your disk with a single EXT4 partition
  • Create a mountpoint at /mnt/build-cache where your disk will be mounted
  • Add an entry in your fstab file to automatically mount at boot time
  • Mount to /mnt/build-cache

First create the partition and ask the kernel to probe it:

export DISK_NAME=build-cache
sudo sgdisk -n 1:0:-1 /dev/disk/by-id/google-${DISK_NAME}
sudo partprobe

Next, format it, add to fstab so it will auto-mount on boot, and mount it

sudo mkfs.ext4 /dev/disk/by-id/google-${DISK_NAME}-part1
sudo mkdir -p /mnt/build-cache
echo "/dev/disk/by-id/google-${DISK_NAME}-part1 /mnt/build-cache ext4 defaults 0 1" | sudo tee -a /etc/fstab
sudo mount /mnt/build-cache
sudo chmod 777 /mnt/build-cache

You can now clone your git repository for buildroot/yocto into your /mnt/build-cache directory to perform builds from this location and use this storage space for your Yocto and Buildroot Builds

Using as test runner

You can configure this system to be self hosted a test runner using the same instructions you use on your build machine, and use this as an alternative to running your Github Actions runner.

Conserving Cloud Spend Tips

  • Be sure to shut off your instance when not in use, using the instructions above or the cloud console.
  • If you don't plan to use your build cache disk for a significant amount of time (especially if you are using SSD) consider deleting it and recreating using the instructions above. Make sure any modified content has been pushed to your github repository before deleting
  • Consider configuring your test runner to shut down after completing a test (see section below).

Configuring Test Runner to Shut Down Automatically

To allow your test runner to automatically shut down after completing a test (and therefore save budget on cloud spend) you may optionally follow the instructions below on your cloud instance:

  1. Add a new script in your actions-runner directory at the same level as your run.sh script run-then-shutdown.sh:
#!/bin/bash
pushd $(dirname $0)
./run.sh --once
echo shutting down server after run completion
sudo shutdown -h 1

Make the script executable using chmod a+x run-then-shutdown.sh

This script will:

  • Change to the current directory
  • Run the ./run.sh actions runner script with a --once parameter to exit after the actions run completes
  • Shutdown the server 1 minute after run completes
  1. Use visudo to edit the sudoers command and add this line to the bottom of the file:
%sudo   ALL=(root) NOPASSWD: /sbin/shutdown

This allows your account to execute sudo commands on /sbin/shutdown without a password.

  1. Modify your crontab to add an action on boot of the machine, using crontab -e
  • Add this line to the file:
@reboot /full/path/to/your/run-then-shutdown.sh

replacing /full/path/to/your with the path to your run-then-shutdown.sh script created above.

Troubleshooting

  • When following links to cloud console using your CU account, you might see messages like "We are sorry, but you do not have access to Google Developers". Attempt to access through https://console.cloud.google.com/ instead.
Clone this wiki locally