Creating Labs

lab.yml & config.yml

Complete reference for the lab.yml and config.yml configuration files.

lab.yml Example

slug: "kubernetes-pods-lab"
title: "Kubernetes: Pods and Deployments"
difficulty: "intermediate"        # beginner | intermediate | advanced
estimatedLaunchTime: 5            # Minutes for VMs to provision
estimatedTime: 45                 # Target completion time in minutes

teaser: "Practice creating and managing Kubernetes Pods and Deployments"
description: |
  In this lab, you will explore the fundamentals of Kubernetes Pods and
  Deployments through hands-on exercises in a real cluster environment.
icon: "kubernetes"
category: "Kubernetes"
tags:
  - "kubernetes"
  - "containers"
  - "devops"

prerequisites:
  - "Basic understanding of containers"
  - "Familiarity with command-line tools"

owner: "tekanaid"
instructors:
  - "Sam Gabrail"
instructorEmails:
  - "[email protected]"
developers:
  - "[email protected]"

accessTier: "premium"             # free | premium
freePreview: false                # Allow non-subscribers to preview
comingSoon: false

ai_fix:
  enabled: true
  max_attempts: 3

published: true
featured: false
isBeta: false

lab.yml Field Reference

Field	Type	Description
`slug`	string	Unique URL-safe identifier. Used in URLs and CLI commands.
`title`	string	Display name shown to learners.
`difficulty`	string	beginner, intermediate, or advanced (exact lowercase).
`estimatedLaunchTime`	number	Minutes for the infrastructure to provision (typically 5).
`estimatedTime`	number	Target lab completion time in minutes (aim for 30–45).
`teaser`	string	One-line description shown in lab listings.
`description`	string	Full description. Supports multi-line YAML (use \| block scalar).
`icon`	string	Icon identifier (e.g. "kubernetes", "terraform", "nomad").
`category`	string	Primary category (e.g. "Kubernetes", "DevOps").
`tags`	string[]	Keywords for search and discovery.
`prerequisites`	string[]	What learners should know before starting.
`owner`	string	Your organization identifier.
`instructors`	string[]	Display names of instructors (shown in the lab listing).
`instructorEmails`	string[]	Email addresses of instructors.
`developers`	string[]	Email addresses of content developers.
`accessTier`	string	Access control. "free" (visible to all) or "premium" (subscribers only). Defaults to "free".
`freePreview`	boolean	Allow non-subscribers to preview the lab even when accessTier is premium.
`comingSoon`	boolean	Show the lab in listings with a Coming Soon badge. Not yet launchable.

config.yml Example

version: "3"
virtualmachines:
  - name: "ubuntu-1"
    image: "ubuntu2024"
    machine_type: "medium"

aws_accounts:
  - count: 1
    provisioning_strategy: "pool_with_fallback"
    max_pool_accounts: 50
    fallback_to_dynamic: true
    inline_policy:
      Version: "2012-10-17"
      Statement:
        - Effect: "Allow"
          Action:
            - "s3:*"
            - "ec2:Describe*"
          Resource: "*"

For multi-VM labs, add more entries to virtualmachines. Each VM gets its own name (e.g. nomad-server-1, nomad-client-1). See the Infrastructure Options page for GCP and Azure cloud config blocks.

config.yml Field Reference

Field	Type	Description
`version`	string	Config schema version. Always "3".
`virtualmachines[].name`	string	VM identifier used in script filenames (e.g. setup-ubuntu-1).
`virtualmachines[].image`	string	Base image slug. See Infrastructure Options for available images.
`virtualmachines[].machine_type`	string	VM size. See Infrastructure Options for sizes.
`aws_accounts[].count`	number	Number of AWS accounts to provision. Always 1.
`aws_accounts[].provisioning_strategy`	string	How accounts are allocated. Always "pool_with_fallback".
`aws_accounts[].max_pool_accounts`	number	Maximum number of pre-provisioned accounts to keep in the pool (e.g. 50).
`aws_accounts[].fallback_to_dynamic`	boolean	If the pool is exhausted, provision an account on demand. Always true.
`aws_accounts[].inline_policy`	object	IAM policy document granting permissions to the lab. See Infrastructure Options for details.

Publishing Options

Field	Default	Description
`published`	false	Set to true to make the lab publicly visible.
`featured`	false	Highlight the lab in featured listings.
`isBeta`	false	Shows a beta badge. Must be at the same indentation level as published — not nested under any other key.
`accessTier`	"free"	Access control. "free" makes the lab visible to all users. "premium" restricts it to subscribers.
`freePreview`	false	Allow non-subscribers to view the lab landing page even when accessTier is premium.
`comingSoon`	false	Show the lab in listings with a Coming Soon badge but prevent launching.

The isBeta field is placed at the top level, alongside published and featured. A common mistake is nesting it under another field, which the validator will reject.

AI Assistant

When a check script fails, learners can optionally trigger an AI assistant that analyzes the failure and suggests a fix. Add an ai_fix block to lab.yml to enable it.

ai_fix:
  enabled: true
  max_attempts: 3

Field	Type	Description
`enabled`	boolean	Set to true to show the AI assistant button when a check fails.
`max_attempts`	number	Maximum number of times a learner can invoke the AI assistant per task.

Note: The AI assistant reads the check script's output and the task assignment to generate its suggestion. Well-written check scripts that emit clear error messages produce better AI suggestions.