Links
Comment on page

Create a custom VM image

Go your own way.
This guide explains how to create a custom Virtual machine (VM) image and use it as a sandbox host in a track.
A VM is a virtual environment that functions as a virtual computer system with its own CPU, memory, network interface, and storage. And custom VMs are just like any other VM, but you have to customize the installation of the operating system and the configuration of the virtualized hardware. Furthermore, a custom image is a file that contains the custom VM definition.

Why use custom VM images?

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 packages needed for a track. Your track will start faster and be more reliable by pre-installing software, which your learners will appreciate.

Increased image size

Furthermore, custom images can be any size you like and are not restricted to the default 10GB that ships with the stock images.
This guide is based on a Google Compute Engine custom image.

Video Demonstration

Not one for words? Here's a video demo of how to create a custom VM image:
Video walkthrough of creating a custom image.

Before you begin

You should have a Google Cloud Platform (GCP) project available or have your GCP admin create a GCP project for you.
Don't have access to a Google Cloud? Contact [email protected] and we will create a 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.

Create a custom VM image

Step 1: Create a VM

  1. 1.
    Open your browser and navigate to your GCP project on the Google Cloud Platform.
  2. 2.
    If the navigation menu is not opened, click the
    menu.
  3. 3.
    Click Compute Engine > VM instances. ↳ This opens the VM instances page.
  4. 4.
    Click [+] CREATE INSTANCE.
  5. 5.
    In the Name field, enter a name of your liking (ex: my-build-instance).
  6. 6.
    Click Change under Boot disk. ↳ This opens the Boot disk subpanel.
  7. 7.
    In the Operating system list, select your desired OS (ex: Ubuntu).
  8. 8.
    In the Version list, select the desired OS version (ex: Ubuntu 22.04 LTS).
  9. 9.
    Click Select. ↳ This closes the Boot disk subpanel.
  10. 10.
    Click Create. ↳ This creates the instance and redirects you to the VM instances page.

Step 2: Customize the VM

  1. 1.
    Click SSH on the VM instance you created in step 1. ↳ This opens a new SSH-IN-BROWSER window.
  2. 2.
    Modify your VM. In this case, we install the Java Development Kit:
    sudo apt -y update
    sudo apt -y install git openjdk-11-jre
  3. 3.
    Close the terminal.
  4. 4.
    Click
    on your newly created VM instance, followed by Stop. And click Stop to confirm. ↳ This shuts down your VM, and the green checkmark will turn into a dark stop symbol.
    Verify that your VM instance is stopped before going further.

Step 3: Create a image

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.
  1. 1.
    Under Storage, click Images on the navigation menu. ↳ This opens the Images page.
  2. 2.
    Click [+] Create Image.
  3. 3.
    In the Name field, enter a name of your liking (ex: ubuntu22-openjdk11).
  4. 4.
    In the Source Disk list, select the disk from your instance (ex: my-build-instance). ⇨ This is the custom VM disk that you created in step 1.
  5. 5.
    For Location, choose Regional.
  6. 6.
    In the Select location list, select europe-west1 (Belgium).
  7. 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.

Step 4: Grant permissions to Instruqt

  1. 1.
    Click IAM & Admin > IAM on the navigation menu.
  2. 2.
    Click
    to add a new principal. ↳ This opens the Add principals subpanel.
  3. 3.
    In the New principals field, enter the following: [email protected].
  4. 4.
    In the Select a role list, select Compute Image User.
  5. 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
💻 Instruqt CLI
  1. 1.
    Open your track from your Content.
  2. 2.
    In the Sandbox section, click Edit.
  3. 3.
    Click + Add a host.
  4. 4.
    Select the Virtual machine host type.
  5. 5.
    In the Hostname field, enter a name of your liking (ex: workstation).
  6. 6.
    Select the Choose your own image type.
  7. 7.
    In the GCP compute image field, enter YOUR-GCPPROJECT-ID/YOUR-IMAGE-NAME. ⇨ Replace YOUR-GCPPROJECT-ID and YOUR-IMAGE-NAME with your GCP project id and image name (ex: root-fort-99999/ubuntu22-openjdk11).
  8. 8.
    For Machine type, select Small (1 vCPUs, 4GB).
  9. 9.
    Click Show optional settings.
  10. 10.
    In the Shell field, enter /bin/bash.
  11. 11.
    Click Save host.
Now you can add a Terminal tab to a challenge and refer in this tab to the new host.
  1. 1.
    Open the config.yml file of your track in your code editor.
  2. 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. 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.
Use Packer to build VM images for multiple platforms from a single configuration
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, or our How-to guide.