Task

The task resource defines interactive activities that participants must complete during a lab. Tasks can include multiple conditions with validation scripts, setup procedures, and solution scripts. Tasks are embedded in instruction pages and provide automated checking of participant progress.

HCL Syntax

Basic Syntax

resource "task" "name" {
  description = "Create a file in the home directory"

  config {
    target = resource.container.ubuntu
  }

  condition "create_file" {
    description = "Create /tmp/hello.txt"

    check {
      script = "scripts/check_file.sh"
    }
  }
}

Full Syntax

resource "task" "name" {
  description      = "Complete the Docker setup"
  success_message  = "Excellent! You've completed all requirements."

  config {
    target               = resource.container.ubuntu
    user                 = "root"
    group                = "root"
    working_directory    = "/home/user"
    timeout              = "30s"
    environment = {
      PATH = "/usr/local/bin:/usr/bin:/bin"
    }
    success_exit_codes   = [0]
    failure_exit_codes   = [1, 2]

    parallel_exec {
      condition = true
      check     = false
      solve     = false
      setup     = false
      cleanup   = false
    }
  }

  condition "setup_environment" {
    description = "Set up the Docker environment"

    config {
      timeout = "60s"
    }

    setup {
      script = "scripts/setup_docker.sh"
    }

    check {
      script          = "scripts/check_docker.sh"
      failure_message = "Docker is not running correctly"
    }

    solve {
      script = "scripts/solve_docker.sh"
    }

    cleanup {
      script = "scripts/cleanup_docker.sh"
    }
  }

  condition "create_container" {
    description = "Create and run a container"

    check {
      script = "scripts/check_container.sh"

      config {
        timeout = "45s"
      }
    }

    solve {
      script = "scripts/solve_container.sh"
    }
  }
}

Resource Structure

task
├─ description (required)
├─ success_message (optional metadata)
├─ config (default configuration for all scripts)
│  ├─ target, user, group, working_directory
│  ├─ timeout, environment
│  ├─ success_exit_codes, failure_exit_codes
│  └─ parallel_exec
│     └─ condition, check, solve, setup, cleanup
└─ conditions[] (one or more required)
   ├─ id (label), description (required)
   ├─ config (inherits from task config, can override)
   └─ script blocks (multiple of each type allowed)
      ├─ setup[] (runs when condition starts)
      ├─ check[] (runs during validation)
      ├─ solve[] (runs when skipped)
      └─ cleanup[] (runs when condition completes)
         └─ each script: script path, failure_message, config override

Fields

Core Configuration

task

Field	Required	Type	Description
description	✓	string	Description of the task shown to users
success_message		string	Message displayed when task completes successfully
config		block	Default configuration for all scripts
condition	✓	block	Conditions that must be met (repeatable)

Config Block

task → config

Configuration applied to all scripts within the task unless overridden at condition or script level.

Field	Required	Type	Description
target	✓	reference to container, vm	Container or VM to execute scripts on
user		string	User to run scripts as. Defaults to “root”.
group		string	Group to run scripts as. Defaults to “root”.
working_directory		string	Working directory for script execution. Defaults to ”/”.
timeout		string	Script execution timeout (Go duration format). Defaults to ”30s”.
environment		map(string)	Environment variables. Defaults to empty map.
success_exit_codes		list(number)	Exit codes considered successful. Defaults to [0].
failure_exit_codes		list(number)	Exit codes considered expected failures. Defaults to empty list.
parallel_exec		block	Parallel execution configuration

Parallel Exec Block

task → config → parallel_exec

Controls whether different types of scripts execute sequentially or in parallel. Parallel execution can speed up task processing but may require careful script design to avoid conflicts.

Field	Required	Type	Description
condition		bool	Execute conditions in parallel. Defaults to false.
check		bool	Execute check scripts in parallel. Defaults to false.
solve		bool	Execute solve scripts in parallel. Defaults to false.
setup		bool	Execute setup scripts in parallel. Defaults to false.
cleanup		bool	Execute cleanup scripts in parallel. Defaults to false.

Condition Block

task → condition

Defines a specific requirement that participants must meet to complete the task. Each condition represents a discrete validation step with its own setup, checking, and cleanup logic.

Field	Required	Type	Description
slug	✓	label	Condition identifier
description	✓	string	Description of what this condition validates
config		block	Configuration override for this condition. Defaults to inherits from task.
setup		block	Scripts run when condition starts (repeatable)
check		block	Validation scripts run during checking (repeatable)
solve		block	Solution scripts run when condition is skipped (repeatable)
cleanup		block	Scripts run when condition completes (repeatable)

Script Block

task → condition → {setup|check|solve|cleanup}

Define executable scripts that perform specific actions during task execution. All script block types share the same structure but serve different purposes in the task lifecycle.

Field	Required	Type	Description
script	✓	string	Path to script file to execute
config		block	Configuration override. Defaults to inherits from condition/task.
failure_message		string	Message shown when script fails (check scripts only)

Validation Rules

• Script execution: Scripts are loaded from files at parse time
• Target requirement: Tasks must have a target (container/vm) configured at task level or condition level
• Configuration inheritance: Script config → Condition config → Task config → Defaults
• File paths: Script file paths are resolved relative to the config file location

Default Configuration

The following defaults are applied automatically:

config {
  timeout              = "30s"
  working_directory    = "/"
  environment          = {}
  user                 = "root"
  group                = "root"
  success_exit_codes   = [0]
  failure_exit_codes   = []

  parallel_exec {
    condition = false
    check     = false
    solve     = false
    setup     = false
    cleanup   = false
  }
}

Examples

Simple File Creation Task

resource "task" "create_file" {
  description = "Create a configuration file"

  config {
    target = resource.container.ubuntu
  }

  condition "file_exists" {
    description = "Create /etc/myapp.conf"

    check {
      script = "scripts/check_config_file.sh"
    }

    solve {
      script = "scripts/create_config_file.sh"
    }
  }
}

Multi-Condition Docker Task

resource "task" "docker_setup" {
  description     = "Set up Docker environment"
  success_message = "Great! Docker is now configured and running."

  config {
    target = resource.container.ubuntu
    timeout = "60s"
  }

  condition "install_docker" {
    description = "Install Docker"

    setup {
      script = "scripts/install_docker.sh"
    }

    check {
      script          = "scripts/check_docker_installed.sh"
      failure_message = "Docker installation failed. Check the logs."
    }

    solve {
      script = "scripts/solve_install_docker.sh"
    }
  }

  condition "start_service" {
    description = "Start Docker service"

    check {
      script = "scripts/check_docker_running.sh"
    }

    solve {
      script = "scripts/start_docker.sh"
    }
  }

  condition "run_container" {
    description = "Run a test container"

    check {
      script = "scripts/check_test_container.sh"

      config {
        timeout = "45s"
      }
    }

    solve {
      script = "scripts/run_test_container.sh"
    }

    cleanup {
      script = "scripts/cleanup_test_container.sh"
    }
  }
}

Task with Custom Configuration

resource "task" "advanced_networking" {
  description = "Configure advanced network settings"

  config {
    target = resource.container.network_lab
    user   = "student"

    environment = {
      NETWORK_CONFIG = "/etc/networks.conf"
      DEBUG_MODE     = "true"
    }
  }

  condition "configure_bridge" {
    description = "Set up bridge network interface"

    check {
      script = "scripts/check_bridge.sh"
    }
  }
}

Parallel Execution Task

resource "task" "parallel_checks" {
  description = "Run multiple parallel validations"

  config {
    target = resource.container.test_env

    parallel_exec {
      check = true  # Run all check scripts in parallel
    }
  }

  condition "check_service_a" {
    description = "Validate service A is running"

    check {
      script = "scripts/check_service_a.sh"
    }
  }

  condition "check_service_b" {
    description = "Validate service B is running"

    check {
      script = "scripts/check_service_b.sh"
    }
  }

  condition "check_service_c" {
    description = "Validate service C is running"

    check {
      script = "scripts/check_service_c.sh"
    }
  }
}

Script Execution Flow

Tasks execute scripts in a specific order:

1. Setup scripts: Run when a condition becomes active
2. Check scripts: Run when validating the condition
3. Solve scripts: Run when the user skips the condition
4. Cleanup scripts: Run when the condition completes (success or skip)

Within each condition:

• All setup scripts execute first (in order)
• Check scripts execute during validation
• Solve scripts execute only when skipped
• Cleanup scripts execute last (in order)

Usage in Instructions

Tasks must be referenced in instruction markdown using the <instruqt-task> component:

## Complete the Setup

<instruqt-task id="docker_setup"></instruqt-task>

Continue to the next step once the task is complete.

Best Practices

1. Clear Descriptions: Write descriptive names for tasks and conditions that explain what users need to do
2. Granular Conditions: Break complex tasks into smaller, logical conditions for better user feedback
3. Error Messages: Provide helpful failure messages in check scripts
4. Timeouts: Set appropriate timeouts based on expected script execution time
5. Cleanup: Always clean up resources in cleanup scripts to avoid side effects
6. Script Organization: Organize scripts in directories matching task names (e.g., scripts/docker_setup/)
7. Configuration Inheritance: Use task-level config for common settings, override at condition/script level when needed