Lab Environment Functions

Lab environment functions provide access to Instruqt-specific functionality, including Docker configuration, data directories, and system information.

Function Reference

data

Returns the path to a lab data directory, creating it if necessary.

1
data(name)

Parameters:

name - Name of the data directory

Returns: Absolute path to the data directory

Example:

1
data("workspace")          # Returns: "/root/.jumppad/data/workspace"
2
data("configs")            # Returns: "/root/.jumppad/data/configs"
3
data("lab-files")          # Returns: "/root/.jumppad/data/lab-files"

data_with_permissions

Returns the path to a lab data directory with specific permissions.

1
data_with_permissions(name, permissions)

Parameters:

name - Name of the data directory
permissions - Unix permissions (octal, e.g., 755)

Returns: Absolute path to the data directory

Example:

1
data_with_permissions("secrets", 700)    # Owner read/write/execute only
2
data_with_permissions("shared", 755)     # Owner all, others read/execute
3
data_with_permissions("public", 777)     # Full permissions for all

docker_host

Returns the Docker host URL for the current environment.

1
docker_host()

Parameters: None

Returns: Docker host connection string

Example:

1
docker_host()    # Returns: "tcp://docker:2375" or "unix:///var/run/docker.sock"
2

3
resource "container" "docker_client" {
4
  environment = {
5
    DOCKER_HOST = docker_host()
6
  }
7
}

docker_ip

Returns the IP address of the Docker host.

1
docker_ip()

Parameters: None

Returns: Docker host IP address

Example:

1
docker_ip()      # Returns: "172.17.0.1" (typical Docker bridge IP)
2

3
resource "template" "config" {
4
  source = <<-EOF
5
    database:
6
      host: ${docker_ip()}
7
      port: 5432
8
  EOF
9
  destination = "./db-config.yaml"
10
}

exists

Checks if a file or directory exists.

1
exists(path)

Parameters:

path - Path to check

Returns: Boolean (true if path exists)

Example:

1
exists("/etc/hosts")              # Returns: true
2
exists("./config.json")           # Returns: true/false
3
exists(data("workspace"))         # Returns: true (after creation)

jumppad

Returns the Jumppad home directory path.

1
jumppad()

Parameters: None

Returns: Path to Jumppad home directory

Example:

1
jumppad()        # Returns: "/root/.jumppad"
2

3
locals {
4
  config_dir = "${jumppad()}/config"
5
  state_file = "${jumppad()}/state.json"
6
}

system

Returns system information.

1
system(property)

Parameters:

property - System property to retrieve (“os” or “arch”)

Returns: System property value

Example:

1
system("os")     # Returns: "linux", "darwin", or "windows"
2
system("arch")   # Returns: "amd64", "arm64", etc.
3

4
locals {
5
  binary_name = "app-${system("os")}-${system("arch")}"
6
}

base64_encode

Encodes a string to Base64 (also available in encoding functions).

1
base64_encode(string)

Parameters:

string - String to encode

Returns: Base64-encoded string

Example:

1
base64_encode("instruqt")         # Returns: "aW5zdHJ1cXQ="
2
base64_encode(var.api_key)        # Encode sensitive data

base64_decode

Decodes a Base64 string (also available in encoding functions).

1
base64_decode(string)

Parameters:

string - Base64-encoded string

Returns: Decoded string

Example:

1
base64_decode("aW5zdHJ1cXQ=")    # Returns: "instruqt"
2
base64_decode(var.encoded_cert)   # Decode certificate data

Common Use Cases

Working Directory Setup

1
# Create organized workspace structure
2
locals {
3
  workspace_dir = data("workspace")
4
  config_dir = data("configs")
5
  scripts_dir = data_with_permissions("scripts", 755)
6
}
7

8
resource "copy" "lab_files" {
9
  source = "./files/"
10
  destination = local.workspace_dir
11
}
12

13
resource "template" "setup_script" {
14
  source = <<-EOF
15
    #!/bin/bash
16
    export WORKSPACE="${local.workspace_dir}"
17
    export CONFIG_DIR="${local.config_dir}"
18
    cd $WORKSPACE
19
  EOF
20

21
  destination = "${local.scripts_dir}/setup.sh"
22
}

Docker Integration

1
resource "container" "docker_cli" {
2
  image {
3
    name = "docker:cli"
4
  }
5

6
  environment = {
7
    DOCKER_HOST = docker_host()
8
  }
9

10
  volume {
11
    source = "/var/run/docker.sock"
12
    destination = "/var/run/docker.sock"
13
    type = "bind"
14
  }
15
}
16

17
resource "template" "docker_config" {
18
  source = jsonencode({
19
    host = docker_ip()
20
    api_version = "1.41"
21
    tls_verify = false
22
  })
23

24
  destination = "${data("configs")}/docker.json"
25
}

Platform-Specific Resources

1
# Download platform-specific binaries
2
resource "http" "binary" {
3
  url = "https://example.com/releases/tool-${system("os")}-${system("arch")}.tar.gz"
4
  destination = "${data("downloads")}/tool.tar.gz"
5
}
6

7
# Use platform-specific commands
8
resource "exec" "install" {
9
  command = system("os") == "darwin" ? "brew" : "apt-get"
10
  arguments = system("os") == "darwin" ?
11
    ["install", "tool"] :
12
    ["install", "-y", "tool"]
13
}

Conditional Resource Creation

1
# Check for existing configuration
2
locals {
3
  has_custom_config = exists("./custom-config.json")
4
  config = local.has_custom_config ?
5
    file("./custom-config.json") :
6
    file("./default-config.json")
7
}
8

9
# Create resources based on environment
10
resource "container" "app" {
11
  count = exists("${data("flags")}/enable-app") ? 1 : 0
12

13
  image {
14
    name = "app:latest"
15
  }
16
}

Secure Data Handling

1
# Create secure directories for sensitive data
2
locals {
3
  secrets_dir = data_with_permissions("secrets", 700)
4
  certs_dir = data_with_permissions("certificates", 700)
5
}
6

7
resource "template" "api_key" {
8
  source = base64_encode(var.api_key)
9
  destination = "${local.secrets_dir}/api-key.enc"
10
}
11

12
resource "exec" "generate_cert" {
13
  command = "openssl"
14
  arguments = ["req", "-x509", "-newkey", "rsa:4096",
15
               "-keyout", "${local.certs_dir}/key.pem",
16
               "-out", "${local.certs_dir}/cert.pem",
17
               "-days", "365", "-nodes", "-subj", "/CN=localhost"]
18
}

Lab State Management

1
locals {
2
  state_dir = data("state")
3
  state_file = "${local.state_dir}/lab-state.json"
4

5
  # Initialize or load state
6
  current_state = exists(local.state_file) ?
7
    jsondecode(file(local.state_file)) :
8
    { initialized = false }
9
}
10

11
resource "template" "update_state" {
12
  source = jsonencode(merge(local.current_state, {
13
    initialized = true
14
    last_updated = timestamp()
15
    docker_host = docker_host()
16
    platform = system("os")
17
  }))
18

19
  destination = local.state_file
20
}

Best Practices

Use Consistent Data Directories: Organize lab files systematically

1
locals {
2
  # Standard directory structure
3
  dirs = {
4
    workspace = data("workspace")
5
    configs   = data("configs")
6
    scripts   = data("scripts")
7
    temp      = data("temp")
8
  }
9
}

Set Appropriate Permissions: Use data_with_permissions for security

1
locals {
2
  # Secure sensitive directories
3
  secrets = data_with_permissions("secrets", 700)
4
  # Shared readable directories
5
  public = data_with_permissions("public", 755)
6
}

Handle Platform Differences: Use system() for compatibility

1
locals {
2
  # Platform-specific paths
3
  path_separator = system("os") == "windows" ? "\\" : "/"
4
  home_dir = system("os") == "windows" ? "C:\\Users\\lab" : "/home/lab"
5
}

Check Resource Existence: Always verify before operations

1
resource "copy" "optional_files" {
2
  count = exists("./optional/") ? 1 : 0
3

4
  source = "./optional/"
5
  destination = data("optional")
6
}