Base images — REF 04

Minimal shell container Workstation · Light

Smallest container option. Fast boot, basic tools, no cloud CLIs.

Includes

bash, curl, wget, jq
git, vim, nano
Instruqt agent helpers (fail-message, set-status, agent variable)

Doesn't include

Cloud CLIs (aws, az, gcloud)
Heavy language runtimes, DB clients

Use for: terminal labs and container-only tracks where the lightest possible boot beats tooling completeness.

Cloud-client container Workstation · Full

Workhorse for any cloud-account track. Boots slower, includes everything you'd reach for.

Includes

Everything in minimal shell
aws CLI v2, az CLI, gcloud SDK
kubectl, helm, terraform
gomplate, yq
nginx serving /var/www/html/ on port 80

Use for: any track with an aws_accounts, azure_subscriptions, or gcp_projects block. The boot tax pays for itself the moment a learner types aws s3 ls. Trap: with a cloud-account block but the minimal-shell image, learners hit "command not found" mid-demo. Switch image or install CLI in setup.

Stock Linux VMs Cloud-published

GCP-published cloud images. Reference by family slug or codename+date slug.

Available

Ubuntu 22.04 LTS, 24.04 LTS
Debian 12 (bookworm)
Rocky Linux 9
CentOS Stream 9

Use for: any VM that doesn't need pre-installed software. Family slugs auto-resolve to latest in family; date-versioned slugs pin a specific build. Has fail-message and set-status available.

Stock Windows VMs Cloud-published

Cloud-published Windows. Lifecycle scripts on Windows VMs are PowerShell, not bash — no shebang, register tasks via Register-ScheduledTask.

Available

Windows Server 2022 Datacenter

Pattern: a native PowerShell terminal tab plus a Guacamole RDP service tab gives learners both a console and a desktop without extra plumbing.

Pre-baked Kubernetes Platform-published

Platform-published VM images with Kubernetes pre-installed. Family spans many K8s versions.

Available

k3s family (versions 1.21 through current)
Docker family (current and a frozen 20.10 variant)

Multi-node bonus: the k3s family supports a K3S_CONTROL_PLANE_HOSTNAME env var. Set it on worker VMs in config.yml's environment: block and workers auto-join the named control plane on boot — no setup script needed on workers.

Custom Packer images Bring your own

Bake heavy dependencies in. Reference by <project>/<image-name> in virtualmachines:.

Worth baking

Multi-GB ML models, vendor product builds
Database seeds large enough that download-at-setup hits timeouts
Same scenario shipped across multiple tracks

Trade-off: faster lab boot vs ongoing image maintenance. Worth it when install-at-setup would exceed several minutes; not worth it for tools that install in seconds.

Notes

Image-aware vs image-unaware: Instruqt-published containers and most platform-published VM images carry the agent helpers (fail-message, set-status, agent variable). Raw upstream Docker images (e.g., a barebones Ubuntu container or Python slim) often do not — guard helper calls with || true.
Sentinel files for bootstrap: wait for /opt/instruqt/bootstrap/host-bootstrap-completed on most images. The cloud-client container uses /opt/instruqt/bootstrap/gcp-bootstrap-completed instead.
Custom-image conventions: images are referenced as <project-or-org>/<image-name>. The string before the slash is a GCP project ID; the string after is the image family or specific build. Follow the publishing org's catalog for available paths.
Arm64: Arm-published VM images are limited. If you need Arm, pair an Arm-built image with the t2a-standard-1 machine type. Mobile/embedded AI workshop tracks use this combination.