Custom VM images

Create custom VM images for use in your sandboxes.

This guide explains how to create a custom Virtual machine (VM) image and use it as a sandbox host in a track.

Advantages of custom VMs

Faster and more reliable

The main benefit of using a custom VM image is that it allows you to pre-install your software and the files needed for a track. Your track will start faster, since software does not need to be installed as part of the track setup script.

Increased image size

Custom images can be have any disk size you like and are not restricted to the default 10GB that ships with the stock Instruqt images.

Create custom VM images

There are two ways to create a custom VM image:

• Using the Instruqt Host images

• Using your own GCP project

We recommend using Instruqt Host images if you are not familiar with Google Cloud, or want to avoid the complexity of managing a cloud account.

Instruqt Host images

Instruqt Host images allow you to create VM images directly inside your Instruqt team. You create Host images using the Web UI.

🌐 Web UI

1. Click Settings → Host images.

2. Click Create image in the upper-right corner.

3. On the Image details page, enter an image name, and optionally provide a description and disk size (the default disk is 10GB).

4. Select a base image. You can use an Instruqt preset image, or choose your own.

   • Custom image names follow a PROJECT_ID/IMAGE_NAME format.

   • Here is a helpful link for finding public images

5. At the bottom of the page, click Next.

6. On the Customize your image page, use the terminal and code editor tabs to edit your image by running install commands, adding files, etc.

7. Once you've finished customizing your image, click Save in the upper-right corner.

8. You can now reference your image in your sandboxes.

   • Instruqt host images follow a TEAM_NAME/IMAGE_NAME format.

Need to edit an existing host image? Open the Host images page. Select the image you want to edit. Click Edit in the top right corner, and then follow Step 3-7 again.

Using your own GCP project

Before you begin

You should have a Google Cloud Platform (GCP) project available or have your GCP admin create a GCP project for you.

Importing an existing image? If you are importing an existing image to GCP make sure to install the Google Guest Environment in your image. Instruqt requires the guest environment to bootstrap VMs.

☁️ Google Cloud Console

Step 1: Create a VM

1. Open your browser and navigate to your GCP project on the Google Cloud Platform.

2. Click Compute Engine → VM instances.

3. Click [+] CREATE INSTANCE.

4. In the Name field, enter a name of your liking (ex: my-build-instance).

5. Click Change under Boot disk.

6. In the Operating system list, select your desired OS (ex: Ubuntu).

7. In the Version list, select the desired OS version (ex: Ubuntu 23.04 LTS).

8. Click Select.

9. Click Create.

Step 2: Customize the VM

1. Click SSH on the VM instance you created in step 1. ↳ This opens a new SSH-IN-BROWSER window.

2. Modify your VM by running whatever commands you'd like.

3. Close the terminal.

4. Click ••• on your newly created VM instance, followed by Stop. And click Stop to confirm.

Step 3: Create an image

1. Under Storage, click Images on the navigation menu.

2. Click [+] Create Image.

3. In the Name field, enter a name of your liking (ex: ubuntu23-custom).

4. In the Source Disk list, select the disk from your instance (ex: my-build-instance).

5. For Location, choose Regional.

6. In the Select location list, select europe-west1 (Belgium).

7. Click Create. ↳ The custom image is built for you and shown on the Image page. Your custom image is ready when the Status column shows a green checkmark.

In Google Cloud there are Disk Images and Machine Images. In this guide, we only work with Disk Images. Machine Images will not work in Instruqt.

Step 4: Grant permissions to Instruqt

1. Click IAM & Admin → IAM on the navigation menu.

2. Click + Grant access to add a new principal.

3. In the New principals field, enter the following: [e-mail]

4. In the Select a role list, select Compute Image User

5. Click Save.

Step 5: Use the custom VM image in your track

You are ready to incorporate the custom VM into your track.

Head over to your Web UI or Instruqt CLI to incorporate the custom VM image into your track:

🌐 Web UI

1. Open your track from your Content.

2. In the Sandbox section, click Edit.

3. Click + Add a host.

4. Select the Virtual machine host type.

5. In the Hostname field, enter a name of your liking (ex: workstation).

6. Select the Choose your own image type.

7. In the GCP compute image field, enter <YOUR-GCPPROJECT-ID>/<YOUR-IMAGE-NAME>

8. Select a machine type.

9. Click Show optional settings.

10. In the Shell field, enter /bin/bash

11. Click Save host.

💻 Instruqt CLI

1. Open the config.yml file of your track in your code editor.

2. Enter or adjust the following code into the config.yml file:

   virtualmachines:
   - name: workstation
     image: YOUR_GCPPROJECT_ID/YOUR_IMAGE_NAME
     shell: /bin/bash
     machine_type: n1-standard-1

   ⇨ Replace YOUR_GCPPROJECT_ID and YOUR_IMAGE_NAME with your GCP project id and image name (ex: root-fort-99999/ubuntu22-openjdk11).

3. Save the config.yml file and deploy your track to the Instruqt platform.

Now you can add a Terminal tab to a challenge and refer in this tab to the new host.

Video tutorial

Watch the video tutorial on how to use your own GCP project to host VM images.

Video walkthrough of creating a custom image.

Automate image building

Packer is an open-source tool for creating identical VM images for multiple platforms from a single source configuration. See the Google Cloud documentation for how to build VM images using Packer.