Skip to content

You are viewing documentation for Instruqt 2.0 Labs. For Tracks documentation, please visit docs.instruqt.com.

Use an image in a lab


An image becomes useful when a lab boots from it. That happens on the vm resource’s image block, which takes the image’s reference as its name.

KindReferenceExample
An image your team builtteam-slug/image-nameacme/dev-tools
An Instruqt base imageThe bare nameubuntu, k3s

Either can carry a version tag, separated by a colon: acme/dev-tools:v2, ubuntu:24.04.

Base images are maintained by Instruqt rather than owned by your team, which is why they have no team-slug/ prefix. Write them as the catalog lists them — ubuntu, debian, rockylinux — optionally with one of their published tags.

resource "vm" "workstation" {
image {
name = "acme/dev-tools:v2"
}
resources {
cpu = 2
memory = 2048
}
}

The image block is required, and name is the only required field in it. username and password are for pulling from a private third-party registry, and are not needed for an Instruqt image.

Booting a base image directly and doing the light work at startup is a perfectly good option when the setup is small:

resource "vm" "workstation" {
image {
name = "ubuntu:24.04"
}
resources {
cpu = 2
memory = 4096
}
startup_script = <<-EOF
#!/bin/bash
apt-get update && apt-get install -y nginx
EOF
}

The two combine well: build an image for the heavy, slow, shared part, and use a startup_script for the per-lab tweaks.

  1. Open the lab’s Sandbox and select the virtual machine, or add one.
  2. Expand the Image section.
  3. Select Add a new public or private image.
  4. In Custom image, enter the reference — for example acme/dev-tools:v2.

Use a preset is the other option: a short list of Instruqt’s base images, which also sets a sensible CPU and memory for the one you pick. Your team’s own images are reached through the custom field.

ReferenceResolves to
With a tag — acme/dev-tools:v2The live digest under that tag: its newest published artifact. Once that digest is deleted, the tag is gone and the reference no longer resolves, even if older digests are still listed under it. See Delete a digest.
Without a tag — acme/dev-toolsThe highest version number among the image’s tags. A tag whose live digest was deleted is gone, so the next highest one is used.

An untagged reference is resolved by version number, not by publish date. v10 beats v9, and a tag that is not a version number — stable, edge — is never picked. An image whose tags are all words cannot be referenced without a tag at all.

Resolution happens when a session starts, so a lab picks up a newer version without being edited.

An image’s Used by tab lists the labs that boot from it. Check it before publishing a new version over an image or deleting one — those are the labs a change reaches.

Publishing a new version is safe for labs that pin an older one; it reaches the labs that follow the newest. Deleting is not safe either way: see Manage images and versions.

A Private image can only be referenced by labs in the team that owns it. A Public image — which includes every Instruqt base image — can be referenced by any team.