Variable

The variable resource defines input parameters that can be used throughout your lab configuration. Variables provide a way to parameterize your lab configuration, making it more flexible and reusable by allowing values to be customized without modifying the core configuration.

Use Cases

As a lab author, you can use variables to create configurable lab experiences:

• Environment Customization: Define different resource allocations (CPU, memory) for different lab environments or user tiers
• User Personalization: Allow customization of usernames, workspace names, or personal preferences within labs
• Multi-Variant Labs: Create labs with different difficulty levels or feature sets controlled by variable values
• Resource Scaling: Configure container counts, instance sizes, or service configurations based on lab requirements
• Feature Flags: Enable or disable specific lab features, tools, or resources using boolean variables
• Dynamic Naming: Generate consistent naming patterns across resources using variable-based naming schemes

Variables make your lab configurations maintainable and adaptable to different scenarios and requirements.

HCL Syntax

Basic Syntax

variable "name" {
  default = "value"
}

Full Syntax

variable "name" {
  default     = "default_value"
  description = "Description of what this variable controls"
}

Fields

Field	Type	Required	Description
default	any	—	Default value for the variable
description	string	—	Description of the variable
type	string	—	Variable type constraint Allowedany string number bool list map

Variable Types

Variables can hold different data types:

Type	Example	Usage
string	default = “admin”	Text values like usernames, passwords, names
number	default = 2048	Numeric values like CPU, memory, ports, counts
bool	default = false	Enable/disable flags for features or resources
list	default = [“web”, “api”, “db”]	Arrays of values like service names, ports
object	default = { cpu = 1024, memory = 512 }	Complex configurations with multiple fields

Variable Reference

Variables are referenced in other resources using the syntax:

variable.variable_name

System Variables

In addition to author-declared variables, Instruqt automatically provides a set of reserved system variables in every lab. These variables require no variable block — the platform injects their values at launch — and are referenced the same way as any other variable, e.g. variable.instruqt_session_id.

Variable	Description
instruqt_session_id	Unique ID for this lab session
instruqt_team_id	ID of the team running this session
instruqt_team_slug	Slug of the team running this session
instruqt_lab_id	ID of this lab
instruqt_lab_slug	Slug of this lab
instruqt_user_id	ID of the user running this session
instruqt_sandbox_domain	Base domain used to construct public URLs for this sandbox (e.g. labs.instruqt.com)

Caution

The instruqt_ prefix is reserved for platform-provided variables. If you declare your own variable "instruqt_..." block, or pass a custom parameter whose name starts with instruqt_, the platform overwrites that value with its own value at launch — your value is silently discarded. Do not use the instruqt_ prefix for your own variables.

For example, you can use the reserved session and domain variables to construct a public callback URL for OAuth configuration at setup time:

resource "exec" "configure_oauth" {
  target = resource.vm.workshop
  script = "scripts/exec/configure_oauth/script.sh"

  environment = {
    CALLBACK_URL = "https://service-workshop-${variable.instruqt_session_id}.${variable.instruqt_sandbox_domain}"
  }
}

Examples

String Variable

variable "username" {
  default     = "admin"
  description = "Default username for system access"
}

resource "container" "web" {
  image {
    name = "nginx:latest"
  }

  environment = {
    USER = variable.username
  }
}

Numeric Variable

variable "cpu_resources" {
  default     = 2048
  description = "CPU resources allocation in millicores"
}

resource "container" "app" {
  image {
    name = "myapp:latest"
  }

  resources {
    cpu = variable.cpu_resources
  }
}

Boolean Variable

variable "debug_enabled" {
  default     = false
  description = "Enable debug mode for applications"
}

resource "container" "service" {
  image {
    name = "myservice:latest"
  }

  disabled = !variable.debug_enabled

  environment = {
    DEBUG = variable.debug_enabled ? "true" : "false"
  }
}

List Variable

variable "service_names" {
  default     = ["web", "api", "database"]
  description = "List of services to deploy"
}

resource "container" "services" {
  count = len(variable.service_names)

  image {
    name = "${variable.service_names[count.index]}:latest"
  }

  environment = {
    SERVICE_NAME = variable.service_names[count.index]
  }
}

Object Variable

variable "database_config" {
  default = {
    username = "dbuser"
    password = "dbpass"
    database = "myapp"
    port     = 5432
  }
  description = "Database connection configuration"
}

resource "container" "postgres" {
  image {
    name = "postgres:13"
  }

  environment = {
    POSTGRES_USER     = variable.database_config.username
    POSTGRES_PASSWORD = variable.database_config.password
    POSTGRES_DB       = variable.database_config.database
  }

  port {
    local = "5432"
    host  = format("%d", variable.database_config.port)
  }
}

Multiple Variables Example

variable "environment" {
  default     = "development"
  description = "Environment name (development, staging, production)"
}

variable "replica_count" {
  default     = 1
  description = "Number of application replicas to run"
}

variable "enable_monitoring" {
  default     = false
  description = "Enable monitoring and logging components"
}

resource "container" "app" {
  count = variable.replica_count

  image {
    name = "myapp:latest"
  }

  environment = {
    INSTANCE_NAME = format("app-%s-%02d", variable.environment, count.index + 1)
    ENV = variable.environment
  }
}

resource "container" "monitor" {
  image {
    name = "prometheus:latest"
  }

  disabled = !variable.enable_monitoring
}

Best Practices

1. Descriptive Names: Use clear, descriptive variable names that indicate their purpose
2. Provide Descriptions: Always include descriptions to document what each variable controls
3. Reasonable Defaults: Set sensible default values that work for most use cases
4. Type Consistency: Use consistent types for similar variables across your configuration
5. Validation: Consider the range of values users might provide when setting defaults
6. Documentation: Document variable usage patterns in your lab instructions or README

Common Patterns

Resource Scaling

variable "worker_count" {
  default     = 3
  description = "Number of worker containers to create"
}

resource "container" "worker" {
  count = variable.worker_count

  image {
    name = "worker:latest"
  }

  environment = {
    WORKER_NAME = format("worker-%02d", count.index + 1)
  }
}

Feature Toggles

variable "features" {
  default = {
    monitoring = true
    debugging  = false
    caching    = true
  }
  description = "Feature flags for lab components"
}

resource "container" "cache" {
  disabled = !variable.features.caching

  image {
    name = "redis:alpine"
  }
}

Environment-Specific Configuration

variable "config" {
  default = {
    dev = {
      cpu    = 512
      memory = 256
      debug  = true
    }
    prod = {
      cpu    = 2048
      memory = 1024
      debug  = false
    }
  }
  description = "Environment-specific configurations"
}

variable "environment" {
  default = "dev"
  description = "Target environment"
}

resource "container" "app" {
  image {
    name = "myapp:latest"
  }

  resources {
    cpu    = variable.config[variable.environment].cpu
    memory = variable.config[variable.environment].memory
  }

  environment = {
    DEBUG = variable.config[variable.environment].debug ? "1" : "0"
  }
}