1 of 96

Instruqt Labs (beta)

Instruqt

Overview

Hands-on learning

Instruqt enables you to create engaging hands-on learning experiences with your product. Using our cloud sandboxes, you can create real-world scenarios for product demos, tutorials, and workshops.

Learning made easy

Learners interact with your product alongside terminals, code editors, and more - all from a browser.

Integrate external systems

Embed Instruqt into your existing sites, such as an LMS, for a seamless learning experience.

Rich analytics

Monitor learner progress as they progress through your content with in-depth analytics.

Flexible sandboxes

Instruqt sandboxes can contain any of the cloud infrastructure you need to make your product shine.

Getting started

This guide will walk you through how to create and manage your first Instruqt Lab, using the Instruqt CLI and the GitHub integration. At the end of this guide you will have a complete lab with a live terminal, embedded web server, and an interactive quiz.

Creating your first lab

Before you begin, ensure you have the following:

A code editor to edit the configuration of the lab.

Create a New Lab from a starter template

Start by initializing a new lab from one of the starter templates, using the instruqt CLI. In your terminal, run the following command and follow the steps in the CLI.

instruqt lab init

You will be prompted to provide the title of the lab e.g. "My First Lab". This will be used to create a target directory on your machine for your configuration based on the sluggified title e.g. my-first-lab. The directory will be created in the current directory you are running the CLI command from.

The CLI will then prompt you to select one of the starter templates to base your lab on. For the purposes of this guide, we will be starting from the "Empty/Skeleton" template. Depending on which template you choose, the configuration will contain additional configuration to assist in that use-case.

Once the template is chosen, review the details and confirm to create the lab. For example ,given the title of "My First Lab", the directory structure will resemble:

my-first-lab
├── assets/README.md
├── files/README.md
├── instructions/README.md
├── notes/README.md
├── scripts/README.md
├── layouts.hcl
├── main.hcl
└── README.md

Create a Repository on GitHub

From your GitHub dashboard perform the following actions to create a repository in your own user account:

Click the New button.
Set the Repository Name. This can match your lab directory, e.g., my-first-lab, but is not required.
Optionally, add a description.
Choose the visibility (public or private).
Do not initialize with a README, .gitignore, or license. This is to keep the initial commit simpler, so you do not have to merge these changes to the README.md.
Click Create Repository.

You should now have an empty repository, and should see instructions how to interact with the repository. Copy the url in the input field of the "Quick setup — if you’ve done this kind of thing before" section of the instructions. For example if you named the repository my-first-lab, it should look something like:

git@github.com:my-username/my-first-lab.git

or:

https://github.com/my-username/my-first-lab.git

Push the Lab to GitHub

Open up your terminal and navigate to the lab directory you created in Step 1. If you did not do anything in the terminal after running instruqt lab init, you should just run:

cd my-first-lab

Otherwise navigate to the full path of the lab directory instead:

cd /path/to/my-first-lab

Now that you are in the lab directory, you need to initialize the git repository.

git init

You can then link your local directory to the repository you created on GitHub in Step 2. To do this, use the url you copied at the end of Step 2 and replace the url in the example below with your url:

git remote add origin git@github.com:my-username/my-first-lab.git

or:

git remote add origin https://github.com/my-username/my-first-lab.git

Now that you have linked the local directory to the remote repository, you can add the files and commit them. This will tell git which files you want to include in the commit, and the commit will store the changes to those files in version control and the git history.

Because we want to include all files in the current directory, we can use . as the files we want to include, which means "everything in the current directory".

git add .

Then commit the changes and write a short message that describes what the changes are that are included in the commit. Because this is the first change to the repository, a common commit message to use is "Initial commit".

git commit -m "Initial commit"

Now that the changes are stored in git and recorded in the history, you can push them to the remote repository by running the git push command. Because this is the first time you are pushing to the remote repository, you will need to set the upstream branch.

git push -u origin main

Import the Lab into Instruqt

Now that all configuration is done, we can import the lab from GitHub into the Instruqt platform. First log into your Instruqt account and navigate to the "Labs" section. Click the "Import Lab" button and select the repository you have created in Step 2, then click "Next". If you do not see your lab, make sure that the Instruqt GitHub application has access to the repository.

Fill out the form by entering a name for your lab, e.g. "My First Lab". This will be used as the slug of the lab, e.g. my-first-lab.

If you are using branches and the lab lives on a different branch than main, or if you want a specific branch/tag of your lab, you can specify the "ref". For the purpose of the guide, we can leave this blank and use the default ref that comes from the GitHub repository.

Next, fill in the path where the lab is located within the repository. If you are using a mono-repository, this is where you can select the directory the lab is in. For the purpose of this guide we can just leave it empty, which will default to the root path / of the directory.

The repository url is shown as the bottom of the form for reference.

You can then click "Import" to start importing your lab. All branches and tags of the repository will be imported and parsed, so you can launch any of them if needed.

Test the Lab in Instruqt

Now that the lab is imported, we can launch it to test it out. From the labs list, locate your lab e.g. my-first-lab and make sure that the status behind the lab has a checkmark and a text similar to #8ec1470 Success. The first part of the success message is the hash of the latest commit that was found on GitHub.

Click the "Start" button on your lab, this will create your lab environment and redirect you to the Lab UI for your lab. Once the lab environment is ready, click the "Enter Lab" button to enter your lab.

Explore the bare Instruqt lab as it will look for your end users. It looks a bit barren at the moment. In the next sections, you will explore adding some basic functionality to your labs.

Once you are done exploring your lab, click the "Stop" button at the top right of the Lab UI to shut down your lab environment and go back to the "Labs" list.

Exploring the lab configuration

code .

This will open up Visual Studio Code and all the files in the lab directory. You should see several directories containing a README.md file, explaining what the directories are used for, and two .hcl files that contain a minimal functional configuration for a lab.

Lets start by taking a look at the main.hcl file, which contains the definition of the lab resource.

resource "lab" "main" {
  title = "Skeleton Lab"
  description = <<-EOF
  This is the Skeleton Lab.
  You can use this as a minimal starting point for developing labs.
  EOF

  layout "single_column" {
    reference = resource.layout.single_panel
  }
}

Lab

Below the description field, you can see a layout block that is named "single_column". The layout block defines which layouts are available to the use inside the lab content. This block can be repeated multiple times, with unique names, and they have a reference to a layout resource.

You can reference other resources and fields within those resources by providing the full path to them. In the generated example lab, layout block on the lab is referencing a resource of type layout and a name of single_panel, which results in a reference of resource.layout.single_panel. If for instance you wanted to reference the title field of the lab, you could use resource.lab.main.title to get the value of "Skeleton Lab".

Layouts

The layout resource lets you define your own custom layouts of the Instruqt Lab UI. A layout consists of "panels", defined as nested columns and rows. For each panel, you can define the size of the panel in percentages e.g. 50.

In the layouts.hcl file there is a generated single panel layout. This layout defines a single column named "instructions". You can later use this name to assign tabs to that panel.

resource "layout" "single_panel" {
  column "instructions" {}
}

Making changes

Now lets see what the workflow is to make changes to an existing lab.

Change the title of the lab resource located in main.hcl to reflect the title of your lab e.g. "My First Lab", and update the description field to "This is my first lab".

To validate that the lab definition is still correct, you can run the validate command from the lab directory:

instruqt lab validate

If there are any validation errors, the CLI will tell you where and what is incorrect. Please correct any errors, until the lab validates successfully.

Now we can use standard developer workflows using git to manage the lab. To see what changes have been made to the lab, we can check the status:

git status

If there are no unintended changes, we can add the files we want to include in the commit:

git add main.hcl

And then commit the changes with a descriptive message, which helps others that are collaborating on the content to understand what has changed since the last time they worked on the lab.

git commit -m "Update title and description of the lab"

Finally the changes can be pushed to GitHub. Because we have already defined the upstream of the respository in the previous section, we can simply push the changes.

git push

This will trigger the changes to be pulled into the Instruqt platform from GitHub. Head on over to the "Labs" section of the Instruqt platform and find your lab. The status message on the lab should still contain a checkmark and the hash of your new commit on GitHub.

When you start the lab, you should now see your new title and description on the loading screen.

Once you are done exploring your lab, click the "Stop" button at the top right of the Lab UI to shut down your lab environment and go back to the "Labs" list.

Adding your first chapter

In the previous section you made the first changes to the lab, in this section you will start adding instructions to the lab. Instructions are what guide the end-user through the lab.

Instructions consist of chapters and pages that the end-user goes through to complete the lab. This outline of chapters and pages is defined on the lab resource, which makes it easy to move pages and chapters around by changing their order.

Creating the outline of your lab

Lets start by adding the content block to the lab resource. This block holds the outline of the lab and will dictate the structure of the instructions.

resource "lab" "main" {
  title = ...
  description = ...

  layout "single_column" {
    ...
  }

  # The newly added content block
  content {
    # The content block will contain our chapters
  }
}

Inside of the content block, you can add a chapter block for each chapter that your instructions contain. The order the chapter blocks are defined in, directly determines the order the chapters are displayed in within the instructions and how progression is determined within the lab. Each chapter has a label that defines the slug of the chapter, used when navigating between chapters.

Define a new chapter in the content block and name the slug "introduction", and set the title to "Introduction".

resource "lab" "main" {
  ...

  content {
    chapter "introduction" {
      title = "Introduction"
    } 
  }
}

Adding a `page` to your lab

Each chapter can contain any number of pages. These are defined by adding a page block to the chapter block you want to nest the page under. The page block also has a slug label, just like the chapter, used when navigating between pages.

Define a new page in the "introduction" chapter and name the slug "first_page".

resource "lab" "main" {
  ...

  content {
    chapter "introduction" {
      title = ...

      page "first_page" {
        # The page configuration will be here
      }
    } 
  }
}

Create a `page` resource

The page block only defines the page inside the outline of the instructions. To configure the actual contents of the page, we need to create a page resource that can be referenced inside of the page block. This makes it possible to reuse pages between labs, when bundling them into reusable "modules".

At a minimum, a page resource needs a file field that specifies where to find the markdown file that contains the contents of the page. The path specified in the file field is either an absolute path, or relative to the file the page resource itself is defined in.

Create a new file in the root of the lab directory and name it pages.hcl. Inside of the pages.hcl file, define a page resource and give it a name of "first". Because the instructions directory is located next to the pages.hcl file the page is defined in, we can use a relative path in the file field e.g. "instructions/first.md".

resource "page" "first" {
  file = "instructions/first.md"
}

Adding `markdown` content

Now that we have defined the page resource, we need to create the markdown file "instructions/first.md" that will contain the actual contents of the page. Create a new file in the "instructions" directory and name it the same as defined on the page resource e.g. first.md, and add markdown content to the file.

# First Page

Welcome to the first page of the introduction chapter.

If the markdown content of the page contains an H1 heading (e.g. # Heading) at the top of the file, this will be used as the fallback value for the title of the page. This value can be overridden with the title field of the page block on the lab.

Now that you have defined the page resource, we can reference it in the reference field of the page block. Update the page block on the chapter and add the reference field to it. A reference to the page resource, resource.page.first, works in the same way as you defined the reference to the layout resource in the previous section of this guide.

resource "lab" "main" {
  ...

  content {
    chapter "introduction" {
      title = "Introduction"

      page "first_page" {
        reference = resource.page.first
      }
    } 
  }
}

Displaying your instructions in the lab

The instructions are now configured on the lab, but they are not visible yet to the end user. To display the instructions, you need to assign the instructions tab to a panel on a layout of the lab. Since the layout currently has a single panel defined, lets add the instructions to that panel by adding an instructions block to the "single_column" layout block of the lab resource. Inside the instructions block, we need to assign it to a panel inside of the layout resource, by setting the panel field to the id of the panel (column/row) we want to add the instructions e.g. to "instructions" column in this case.

resource "lab" "main" {
  title = ...
  description = ...

  layout "single_column" {
    reference = resource.layout.single_panel
    
    instructions {
      panel = "instructions"
    }
  }

  content {
    ...
  }
}

Committing and pushing the changes

Like in the previous sections, you need to git add, git commit and then git push the changes to GitHub. You can then go to the "Labs" section, verify the latest commit on GitHub matches the status of your lab, and start the lab.

Your lab should now have an "Instructions" tab that displays the first page that you created in this guide. When you click the "Progress" button in the top-right of the Lab UI, you should see the outline you defined on the lab resource.

Once you are done exploring your lab, click the "Stop" button at the top right of the Lab UI to shut down your lab environment and go back to the "Labs" list.

Configuring sandboxes

In the previous section you added instructions to the lab, in this section you will add sandbox components to the lab and learn how to expose them to end-users within the Lab UI.

The sandbox of a lab is where your software runs inside of Instruqt. It contains all the resources that the end-user interacts with during the lifecycle of a lab.

Defining a `network` within your lab

To start off, define a network resource in the sandbox, which allows us to control networking of our resources by attaching them to the network. It is possible to attach resources to multiple networks. In most simple sandboxes a single network resource will suffice, but when simulating more complex situations such as "multi-cloud deployments" and "network federation", the network resource is what allows you to create those scenarios.

Lets create a sandbox.hcl file in the root of the lab directory, and define a network resource named "main" in it. The network resource has one required field, which is the subnet that you want the network to use e.g. "10.0.200.0/16".

resource "network" "main" {
  subnet = "10.0.200.0/16"
}

Adding a `container` to your lab

Next, in the sandbox.hcl file, add a container resource to the lab named "webserver".

resource "container" "webserver" {
}

In order for the container to be able to start, you must define what image it should use. For this guide we will use the nginx image as the webserver. Since the specific version of the image does not matter for this guide, you can omit the tag of the image to use the latest version of the image. But it is highly recommended to use a tagged version of an image e.g. nginx:1.27.4, so you know exactly what version of the image is used within the sandbox.

resource "container" "webserver" {
  image {
    name = "nginx"
  }
}

The nginx container image runs on port 80 by default, so you need to map that local port on the container.

resource "container" "webserver" {
  image {
    ...
  }

  port {
    local = 80
  }
}

And finally attach the container to the network resource you specified before by setting the id field of the network block to the meta.id field of the "main" network resource: resource.network.main.meta.id.

resource "container" "webserver" {
  image {
    ...
  }

  port {
    ...
  }

  network {
    id = resource.network.main.meta.id
  }
}

Create a `service` resource

To expose a web service to the end-user in the Lab UI, you need to add a service resource that points at the service you want to expose. This service resource can then be used within a layout as a tab on a specific panel, to show to the end-user.

Create a file called tabs.hcl in the root of the lab directory, and add a service resource named "webserver" to it. The service resource will contain all the configuration for exposing your web service. This makes it easier to reuse these tabs in multiple layouts, without having to redefine the configuration each time.

resource "service" "webserver" {
}

A service resource has a few fields that can be configured to point it exactly at the web service you want to expose. The most important field to configure is the target field, which is a reference to the resource that hosts the web service e.g. resource.container.webserver. It is also necessary to specify the port the web service is listening on, which in the case of the nginx image is port 80.

resource "service" "webserver" {
  target = resource.container.webserver
  port   = 80
}

In the case that the web service is not listening on the default path /, it is also possible to override this by specifying the path field and setting it to the desired path e.g. /ui.

Customizing layouts

In order to show both the instructions and the service in the Lab UI at the same time, we will separate them horizontally into two columns. Lets add a second layout resource in the layouts.hcl file, named "two_panels". Define two columns on the layout, named "left" and "right", and set the width of the "right" panel to 33.

resource "layout" "single_panel" {
  ...
}

resource "layout" "two_panels" {
  column "left" {}

  column "right" {
    width = 33
  }
}

This new layout can then be added to the lab resource by defining another layout block and referencing the new "two_panels" layout resource.layout.two_panels. Lets set this "two_column" layout as the default layout for now, so we can see the changes made to the lab.

resource "lab" "main" {
  ...

  layout "single_column" {
    ...
  }

  layout "two_columns" {
    reference = resource.layout.two_panels
    default = true
  }
}

Adding the `service` to a layout

In the previous section, you added the instructions tab to the single panel layout. Add the instructions tab to the "two_columns" layout block, as you did before on the "single_column" layout block, but assign it to the "left" panel.

Other tabs are defined in a similar way, but slightly different due to the unique nature of the instructions tab. To add other tabs to a layout, you can use the tab block with a label that specifies its id. This id can be used to interact with it from the instructions, such as focusing a specific tab on the push of a button within the content.

Define a new tab block on the "two_columns" layout block with a label of "webserver", set its target to point at the webserver service resource you created before resource.service.webserver, and assign the tab to the "right" panel.

To set the title of any tab, including instructions, you can specify the title field to.

resource "lab" "main" {
  ...

  layout "single_column" {
    ...
  }

  layout "two_columns" {
    reference = resource.layout.two_panels
    default = true

    instructions {
      panel = "left"
    }

    tab "webserver" {
      title = "Webserver"
      panel = "right"
      target = resource.service.webserver
    }
  }
}

Preview your changes

Your lab should now have a new layout with two columns, the left one showing the web service and the right one showing the instructions.

Once you are done exploring your lab, click the "Stop" button at the top right of the Lab UI to shut down your lab environment and go back to the "Labs" list.

Adding quizzes

(Explain quizzes briefly)

Add a `quiz` resource

Start by adding a quizzes.hcl file, then add the following resources

resource "quiz" "quizzes" {
	questions = [
		resource.single_choice_question.capital_france,
		resource.multiple_choice_question.cities_france,
	]
	show_hints = true
}

resource "single_choice_question" "capital_france" {
	question = "What is the capital of France?"
	answer = "Paris"
	distractors = ["Lyon", "Nantes", "London", "Berlin"]

	hints = [
		"The correct answer is Paris .",
		"No, really, it's Paris ..",
		"Just pick Paris already ..."
	]
}

resource "multiple_choice_question" "cities_france" {
	question = "Which of these cities are in France?"
	answer = ["Paris", "Lyon", "Nantes"]
	distractors = ["London", "Berlin"]

	hints = [
		"One of these cities is in the UK",
		"Another city is in Germany"
	]
}

(Explain the resources, fields)

Add a new page with activities

(Explain the activities block and what the fields mean)

resource "page" "quiz" {
  file = "instructions/quiz.md"

  activities = {
    "quizzes" = resource.quiz.quizzes
  }
}

resource "lab" "main" {
  ...
  content {
    ...
    chapter "introduction" {
      ...
      page "quiz" {
        reference = resource.page.quiz
      }
    }
  }
}

Embedding quizzes in your content

(Explain tasks, explain Instruqt Custom Component, especially )

Embed the quiz in your instructional content, create instructions/quiz.md and add the <instruqt-quiz> element so it looks like this

# Embedded quiz right here:

<instruqt-quiz id="quizzes"></instruqt-quiz>

Note that the id of the quiz must correspond to the resource name.

Preview your changes

(Guide, and screenshot of how our lab looks at this stage.)

Adding tasks and gating content

(Explain tasks and this section, what its used for)

Concepts we will learn about in this section:

Adding a new container & terminal

(Write better) We want to use a separate container to connect to a termainl and run our conditions against.

Add an ubuntu image container resource in sandbox.hcl. We will connect to this sandbox

resource "container" "ubuntu" {
  image {
    name = "ubuntu"
  }
}

(Add section on terminals)

Add a terminal resource called shell. Have it target the new ubuntu container we just defined.

resource "terminal" "shell" {
  title = "Terminal"

  target = resource.container.ubuntu

  shell = "/bin/bash"
  working_directory = "/root"
}

(Explain the fields, and why they are needed.)

Adding the `task` resource

In your acitivities.hcl file, add the following task resource.

resource "task" "helloworld" {
  config {
    target = resource.container.ubuntu
  }

  condition "file_exists" {
    description = "The file `/tmp/hello` should exist"

    check {
      script = "scripts/file_exists.sh"
      failure_message = "The file `/tmp/hello` does not exist"
    }
  }

  condition "file_contains" {
    description = "The file should contain the text `world`"

    check {
      script = "scripts/contents_match.sh"
      failure_message = "The file `/tmp/hello` does not contain the text `world`"
    }
  }
}

(Explain the fields, especially the scripts, as they are not yet defined)

Adding the scripts

(Explain scripts)

Create a new directory called scripts, inside the directory, create two new files; file_exists.sh & contents_match.sh. As the names indicate, we will be adding scripts to these files that check if a file exists and whether the content matches.

In /scripts/file_exists.sh add the following script:

#!/bin/sh
if [ ! -f /tmp/hello ]; then
  exit 1
fi

In /scripts/contents_match.sh add the following script:

#!/bin/sh
CONTENTS=$(cat /tmp/hello)

if [ ! "$CONTENTS" = "world" ]; then
  exit 1
fi

Add the activity to a page

In pages.hcl add a new page and name it task. Add the helloworld activity to it, like we did with quizzes before.

resource "page" "task" {
  file = "instructions/task.md"

  activities = {
    "helloworld" = resource.task.helloworld
  }
}

Add the new page & terminal the lab.

For the end user to interact with the shell terminal we created earlier, we need to connect a tab to the shell.

In main.hcl, add the terminal to the layout in our lab. While we're here, also add the new page in the content block.

resource "lab" "main" {
  ...
  tab "terminal" {
    panel = "main"
    target = "resource.terminal.shell"
  }
  ...
  content {
    chapter "introduction" {
      ...
      page "task" {
        reference = resource.page.quiz
      }
    }
  }
}

(Explain the shell targeting & fields)

Add the task to the instructional content

In instructions/page.md, add the <instruqt-task> element and point it to the helloworld task. This will give the end user feedback on how they're faring with their task.

# Tasks

In the left pane there is a terminal session on the ubuntu container.
We want the user to perform actions in the terminal and then validate that the actions had the desired outcome.

Each task can have multiple conditions that need to be met before the task is considered completed.

<instruqt-task id="helloworld">
  Write the text `world` to `/tmp/hello`.
</instruqt-task>

Preview your changes

(Guide, and screenshot of how our lab looks at this stage.)

Finishing up

(Write section on finishing up content.)

Concepts we will learn about in this section:

Adding feedback

(Write about feedback component, and use case)

In any page's markdown section, you can add a feedback component your end users can interact with. This can help you source feedback both during and after a lab has been completed.

Let's add a feedback component as a standalone page at the end of the lab.

Add a new page

resource "page" "feedback" {
  file = "instructions/feedback.md"
}

Add a full page layout

resource "layout" "full_page" {
  column "instructions" {}
}

Add new chapter and page.

resource "lab" "main" {
  ...
  content {
    ...
    chapter "feedback" {
      layout_name = "full_page"
      page "feedback" {
        reference = resource.page.feedback
      }
    }
  }
}

Add the markdown with the component

# How was your experience?

Please take a minute to give feedback on the content.

<instruqt-feedback></instruqt-feedback>

<instruqt-completion
  heading="Congratualtions!"
  finish-button-label="Take me home">
</instruqt-completion>

Upgrade from Tracks

Differences between Tracks and Labs

Content changes
- Notes vs Pages
- Challenges vs Pages and Activities
YAML vs HCL
- Single way to define all lab content, rather than mix of conventions and (file) formats
  - yaml, markdown, frontmatter, forced folder structure, scripts
- Flexible file/folder structure
Lifecycle scripts
Implicit vs Explicit dependencies
- Sandbox changes
- Resources and References
- Dependency Graph
- Health Checks
Native version control
- Versioning, Branches and Tags
- Workflow changes

Migrating a Track to a Lab

Step 1: Migration instructional content

instruqt lab convert --from-track <track-slug-or-directory>

>> Print the mapping from challenges to pages and activities

Step 2: Identify required sandbox components

List of containers, VMs, Cloud Accounts

List of setup scripts

Map out dependencies between components

Step 3: Implement Lab Sandbox

Configure Containers, VMs, Cloud Accounts
Replace scripted dependencies with health checks and resource references

Step 4: Push changes and test Lab

Tutorials

Content

Sandbox Container with Terminal

Sandbox Container with Web App Service

Sandbox Kubernetes Cluster

Organizing content in Chapters and Pages

Validation with Tasks and Conditions

Validation with Quizzes

Workflows

Running a Lab

Sharing a Lab with end users

Create a new Lab

Update an existing Lab

Content versioning

Integrate with GitHub

Import Lab from GitHub Repository

Documentation

Overview

Labs are guided learning experiences. Labs are created from two main concepts:

Sandbox environments
Instructional content
- Chapters/pages/instructions
- Task and Quiz activities

Sandbox environments

Components
- Container/VM/etc
- Setup scripts
Content Structure
- Chapters
- Pages
- Instructions
Learner Activities
- Tasks and conditions
- Quizes

Concepts

Instructional content

Sandboxes

Lab lifecycle

Validation through activities

Writing Lab Content

Project Structure

There is a lot of flexibility in how you can structure your lab configuration. One structure that we have found to work well is shown below.

This structure groups artifacts into manageable chunks and provides a clear structure of where files should live. In the example structure below we have separated resources into multiple .hcl files, mostly due to the amount of content in each of those files. If your labs are small, we recommend not splitting up the files too quickly, but chosing consistant names for them when splitting.

├── instructions
│   ├── first_chapter
│   │   ├── first_page.md
│   │   └── second_page.md
│   └── second_chapter
│       └── another_page.md
├── scripts
│   └── first_chapter
│       ├── first_task
│       │   ├── first_check
│       │   ├── my_solve
│       │   └── second_check
│       └── second_task
│           ├── my_solve.sh
│           └── my_check.sh
├── assets
│   ├── image.png
│   └── subdirectory
│       └── image.png
├── notes
│   └── my_note.md
├── files
│   ├── some_config.json
│   └── something.yaml
├── modules
│   └── layouts
│       ├── complex.hcl
│       └── minimal.hcl
├── lab.hcl
├── chapters.hcl
├── tabs.hcl
├── sandbox.hcl
├── tasks.hcl
├── quizzes.hcl
├── modules.hcl
└── variables.hcl

Directories

In the example project structure we have chosen to follow certain standards when placing our files. This structure follows the best practises we have found while creating content, but it is possible to deviate from the naming conventions above.

Instructions

The instructions directory holds all the written content of your lab. The instructions are separated by chapter which contains each of the pages as a separate markdown file.

Scripts

The lifecycle scripts of the tasks are contained in the scripts directory. We have separated by task name, and the scripts themselves can be named anything as they are referenced by path inside of the configuration.

Assets

Any assets that you want to use within the instructions should live in the assets directory. This has the benefit that they are automatically served from the sandbox itself, and can be referenced as e.g. /assets/subdirectory/image.png.

Notes

If you have note tabs defined, the content of those notes should be placed in the notes directory as a separate markdown file for each note.

Files

If your sandbox needs to use a configuration file, template, or any other arbitrary file, these can be placed in the files directory.

Modules

It is a good idea to keep any nested modules inside of the modules directory so they do not clutter the root directory of the project.

Markdown and Components

Check out the components that you can use inside the markdown of instructions

Link

Simple link to a URL:

<instruqt-link to="…">
  Link
</instruqt-link>

Attribute

Type

Description

to

string required

URL to link to

color

string optional

Custom text color

Button

Choose between different variants or customize it with your own colors:

<instruqt-button to="…">
  Button
</instruqt-button>

Attribute

Type

Description

to

string required

URL to link to

variant

enum optional

Pick a style: white, danger, warning, success or outline

background

string optional

Custom background color

color

string optional

Custom text color

Switch tab: link

Place a link that takes the user to a specific tab inside the lab:

<instruqt-switch-tab-link id="…">
  Go to tab
</instruqt-switch-tab-link>

Attribute

Type

Description

id

string required

Resource id of the target tab

color

string optional

Custom text color

Switch tab: button

Place a button that takes the user to a specific tab inside the lab:

<instruqt-switch-tab-button id="…">
  Go to tab
</instruqt-switch-tab-button>

Attribute

Type

Description

id

string required

Resource id of the target tab

variant

enum optional

Pick a style: white, danger, warning, success or outline

background

string optional

Custom background color

color

string optional

Custom text color

Code block

Show a code snippet to the user:

<instruqt-code language="shell">
  curl parrot.live
</instruqt-code>

Attribute

Type

Description

language

string optional

Which syntax highlight to use

line-numbers

boolean optional

Show each line number

line-numbers-start

number optional

What number to start counting from

no-copy

boolean optional

Hide the copy button

run

boolean optional

Offer to run the code in a terminal

title

string optional

Used only by the code group component

Code group

Group code snippets together:

<instruqt-code-group>
  <instruqt-code language="shell" title="parrot.sh">
    curl parrot.live
  </instruqt-code>
  <instruqt-code language="sql" title="query.sql">
    SELECT * FROM table
  </instruqt-code>
</instruqt-code-group>

Completion

Show how the user is progressing on their tasks, with a call to action when they are all complete:

<instruqt-completion
  heading="Congratualtions!"
  finish-button-label="Take me home">
</instruqt-completion>

Attribute

Type

Description

heading

string optional

Greetings message

finish-button-label

string optional

Call to action button text

Feedback

Ask the user to rate the track with an optional message:

<instruqt-feedback></instruqt-feedback>

PDF

Show the user an embedded PDF:

<instruqt-pdf url="…"></instruqt-pdf>

Attribute

Type

Description

url

string required

URL to the file

Quiz

Interactively ask questions to the user:

<instruqt-quiz id="…"></instruqt-quiz>

Attribute

Type

Description

id

string required

Resource id of the quiz

Slides

Embed a presentation from Google Slides:

<instruqt-slides id="…"></instruqt-slides>

Attribute

Type

Description

id

string required

Google Slides id

Task

Show the user a breakdown of task conditions:

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

Attribute

Type

Description

id

string required

Resource id of the task

Video

Embed a video from Vimeo or YouTube:

<instruqt-video id="…"></instruqt-video>

Attribute

Type

Description

id

string required

The id of the video

source

enum optional

Either vimeo or youtube, defaults to youtube

Lab reference

Content

Lab

The lab resource provides the metadata about the lab and some of its configuration. This is the equivalent of what is currently called a "track".


resource "lab" "name" {
 ...
}

Attributes

Attribute

Description

Title title required type: string

The title of the lab.

Description description required type: string

A description of the lab.

Tags tags type: []string

Tags that describe the lab.

Settings that configure the lab.

A layout that can be used within the lab. This block can be specified multiple times on a lab resource, to allow using multiple layouts throughout a lab.

The instructional content of the lab that is presented to the end-user.

Computed Attributes

These attributes are computed when the config is parsed and applied, and are therefore only known at parsetime or runtime.

Attribute

Description

Meta ID meta.id string

The full ID of the resource e.g. `resource.type.name`. This is computed from the full resource path:

Meta Type meta.type string

The type of the resource. This taken from the type label of the resource definition.

Meta Name meta.name string

The name of the resource. This taken from the name label of the resource definition.

DefaultLayout default_layout type: string

The default layout is determined by the first layout that has the `default` field set to `true`. In the case that no layout has a default set, the first layout defined on the lab will be set as the default.

Settings

Settings that configure the lab.


resource "lab" "name" {
  settings {
    ...
  }
}

Attributes

Attribute

Description

Theme theme type: string default: modern_dark

The theme used to style the lab.

Configure the timelimit settings.

Configure the idle timeout settings.

Configure the controls that are presented to the end-user.

Computed Attributes

These attributes are computed when the config is parsed and applied, and are therefore only known at parsetime or runtime.

TimeLimit

Configure the timelimit settings.


resource "lab" "name" {
  settings {
    timelimit {
      ...
    }
  }
}

Attributes

Attribute

Description

Duration duration type: int default: 15

The maximum duration of the lab in minutes.

Extend extend type: int default: 0

How long the lab can be extended in minutes once the timelimit is hit. Set to 0 to disable extending.

ShowTimer show_timer type: bool default: true

Whether or not to show the timelimit timer to the end-user.

Computed Attributes

These attributes are computed when the config is parsed and applied, and are therefore only known at parsetime or runtime.

Idle

Configure the idle timeout settings.


resource "lab" "name" {
  settings {
    idle {
      ...
    }
  }
}

Attributes

Attribute

Description

Enabled enabled type: bool default: true

Whether or not idle timeout is enabled.

Timeout timeout type: int default: 5

The inactivity duration in minutes after which an end user will be timed out.

ShowWarning show_warning type: bool default: true

Whether or not to show an idle timeout warning to the end user.

Computed Attributes

These attributes are computed when the config is parsed and applied, and are therefore only known at parsetime or runtime.

Controls

Configure the controls that are presented to the end-user.


resource "lab" "name" {
  settings {
    controls {
      ...
    }
  }
}

Attributes

Attribute

Description

ShowStop show_stop type: bool default: true

Whether or not to show the stop lab button to the end-user.

Computed Attributes

These attributes are computed when the config is parsed and applied, and are therefore only known at parsetime or runtime.

Layout

A layout that can be used within the lab. Layouts define what panels and tabs are visible and how they are arranged.


resource "lab" "name" {
  layout "name" {
    ...
  }
}

Attributes

Attribute

Description

Name name required type: string

The name of the layout, that can be used by chapters and pages to switch to.

A reference to the layout that defines the panels.

Default default type: bool

Whether or not the layout of the default one to use when the lab does not have any instructional content.

The tabs that are used within the layout.

The instructional content that is displayed in the layout.

Computed Attributes

These attributes are computed when the config is parsed and applied, and are therefore only known at parsetime or runtime.

Tab

A tab that is used within the layout and points at a tab target e.g. Terminal, Service, Editor, etc.


resource "lab" "name" {
  layout "name" {
    tab "name" {
      ...
    }
  }
}

Attributes

Attribute

Description

Name name required type: string

The Name of the tab.

Panel panel required type: string

The name of the panel of the layout that the tab is displayed in.

The target resource of the tab that is shown when the tab is active.

Title title type: string

The title of the tab.

Active active type: bool

Whether or not the tab is active.

Visible visible type: bool

Whether or not the tab is visible.

Closeable closeable type: bool

Whether or not the tab is closeable.

Movable movable type: bool

Whether or not the tab is movable.

Computed Attributes

These attributes are computed when the config is parsed and applied, and are therefore only known at parsetime or runtime.

Instructions

The instructional content that is displayed in the layout.


resource "lab" "name" {
  layout "name" {
    instructions {
      ...
    }
  }
}

Attributes

Attribute

Description

Panel panel required type: string

The panel of the layout that the instructions are displayed in.

Title title type: string

The title of the instructions tab.

Active active type: bool

Whether or not the tab is active.

Visible visible type: bool

Whether or not the tab is visible.

Closeable closeable type: bool

Whether or not the tab is closeable.

Movable movable type: bool

Whether or not the tab is movable.

Computed Attributes

These attributes are computed when the config is parsed and applied, and are therefore only known at parsetime or runtime.

Content

The instructional content of the lab that is presented to the end-user.


resource "lab" "main" {
  content {
    ...
  }
}

Attributes

Attribute

Description

Title title type: string

The title of the content tab.

The chapters that are part of the content.

Computed Attributes

These attributes are computed when the config is parsed and applied, and are therefore only known at parsetime or runtime.

Chapter

A chapter within the content.


resource "lab" "name" {
  content {
    chapter "name" {
      ...
    }
  }
}

Attributes

Attribute

Description

Slug slug required type: string

The slug of the chapter.

Title title required type: string

The title of the chapter.

LayoutName layout_name type: string

The default layout for all pages in the chapter.

The pages that are part of the chapter.

Computed Attributes

These attributes are computed when the config is parsed and applied, and are therefore only known at parsetime or runtime.

Page

A page within a chapter that is part of the content.


resource "lab" "name" {
  content {
    chapter "name" {
      page "name" {
        ...
      }
    }
  }
}

Attributes

Attribute

Description

Slug slug required type: string

The slug of the page.

A reference to the resource of the page that contains the content.

Title title type: string

The title of the page. This overrides the title of the page source.

LayoutName layout_name type: string

The layout to use for the page. When switching to that page, the layout will then change to the selected layout.

Computed Attributes

These attributes are computed when the config is parsed and applied, and are therefore only known at parsetime or runtime.

Examples

Full Example

resource "lab" "minimal" {
  title = "Minimal"
  description = "This is a minimal example lab."

  settings {
    idle {
      enabled = false
    }
  }

  layout "minimal" {
    default = true
    reference = resource.layout.minimal

    tab "terminal" {
      panel = "terminal"
      target = resource.terminal.shell
    }

    instructions {
      panel = "instructions"
    }
  }

  layout "instructions_only" {
    reference = resource.layout.minimal

    instructions {
      panel = "instructions"
    }
  }

  content {
    chapter "introduction" {
      title = "Introduction"
      layout_name = "minimal"
      
      page "first" {
        layout_name = "instructions_only"
        reference = resource.page.first
      }

      page "second" {
        reference = resource.page.second
      }
    }

    chapter "imported" {
      title = "Imported"

      page "first" {
        reference = module.chapter.output.pages.first
      }

      page "second" {
        reference = module.chapter.output.pages.second
      }
    }
  }
}

Activities

Task

The task resource is the new form of the lifecycle scripts, that can now be embedded anywhere on a page within the instructions.

Each task resource can have multiple condition blocks that need to be met before the task is completed, which in turn can have multiple of each type of lifecycle block and each of the blocks are executed in sequence in the order they appear in code.


resource "task" "name" {
  ...
}

Attributes

Attribute

Description

SuccessMessage success_message type: string

The message to display when the task is successfully completed.

Configuration for the task. This configuration will be used for all scripts within the task.

The conditions that have to be met in order for the task to successfully be validated.

Computed Attributes

These attributes are computed when the config is parsed and applied, and are therefore only known at parsetime or runtime.

Attribute

Description

Meta ID meta.id string

The full ID of the resource e.g. `resource.type.name`. This is computed from the full resource path:

Meta Type meta.type string

The type of the resource. This taken from the type label of the resource definition.

Meta Name meta.name string

The name of the resource. This taken from the name label of the resource definition.

Condition

A condition is a partial validation for a task. Conditions can be used to split up bigger task into smaller pieces, allowing for more granular feedback to users.


resource "task" "task" {
  condition "name" {
    ...
  }
}

Attributes

Attribute

Description

Name id required type: string

The id of the condition.

Description description required type: string

The description of the condition. This will be visible on the task in the frontend.

Configuration for the condition. This configuration will be used for all scripts within the condition. This overrides the configuration for the task.

The checks that need to be executed successfully in order for the condition to pass. Check scripts are triggered when a task is validated.

The solve scripts that are executed when skipping the condition.

The setup scripts that are executed when unlocking the condition.

The cleanup scripts that are executed when the condition is completed or skipped.

Computed Attributes

These attributes are computed when the config is parsed and applied, and are therefore only known at parsetime or runtime.

Script

A script that gets executed in the lifecycle of a lab. The script can be used to check the state of the lab, solve a challenge, setup the lab, or cleanup the lab, etc.


resource "task" "task" {
  condition "condition" {
    check {
      ...
    }

    solve {
      ...
    }

    setup {
      ...
    }

    cleanup {
      ...
    }
  }
}

Attributes

Attribute

Description

Script script required type: string

The file location of the script to execute.

The configuration for the script. This overrides the configuration for the task or condition.

FailureMessage failure_message type: string

The message to show if the check has failed.

Computed Attributes

These attributes are computed when the config is parsed and applied, and are therefore only known at parsetime or runtime.

Config

The configuration for scripts.


resource "task" "task" {
  # Default configuration for all conditions and their scripts.
  config {
    ...
  }
}



resource "task" "task" {
  condition "condition" {
    # Default configuration for all scripts in this condition.
    config {
      ...
    }
  }
}

resource "task" "task" {
  condition "condition" {
    # Setup, check, solve, or cleanup.
    check {
      # Configuration the specific script.
      config {
        ...
      }
    }
  }
}

Attributes

Attribute

Description

The target resource to execute the script on.

User user type: string default: root

The user to execute the script as.

Group group type: string default: root

The group to execute the script as.

WorkingDirectory working_directory type: string default: /

The working directory to execute the script in.

Environment environment type: map[string]string

The environment variables to set for the script.

Timeout timeout type: int default: 30

The timeout in seconds for the script to execute.

SuccessExitCodes success_exit_codes type: []int default: []int{0}

The exit codes that are considered successful.

FailureExitCodes failure_exit_codes type: []int default: []int{}

The exit codes that are considered expected failures. Any other failure codes will be considered errors.

ParallelExec configures wether conditions or scripts are executed in parallel.

Computed Attributes

These attributes are computed when the config is parsed and applied, and are therefore only known at parsetime or runtime.

ParallelExec

Configures wether conditions or scripts are executed in parallel.


resource "task" "task" {
  config {
    # Default configuration for all conditions and their scripts.
    parallel_exec {
      ...
    }
  }
}



resource "task" "task" {
  condition "condition" {
    config {
      # Default configuration for all scripts in this condition.
      parallel_exec {
        ...
      }
    }
  }
}

Attributes

Attribute

Description

Condition condition type: bool

Condition configures wether conditions are executed in parallel.

Check check type: bool

Check configures wether check scripts are executed in parallel.

Solve solve type: bool

Solve configures wether solve scripts are executed in parallel.

Setup setup type: bool

Setup configures wether setup scripts are executed in parallel.

Cleanup cleanup type: bool

Cleanup configures wether cleanup scripts are executed in parallel.

Computed Attributes

These attributes are computed when the config is parsed and applied, and are therefore only known at parsetime or runtime.

Examples

Full Example

resource "task" "first_task" {
  config {
    target = resource.container.ubuntu
    
    parallel_exec {
      condition = true
    }
  }

  condition "file_exists" {
    description = "The file exists"

    config {
      target = resource.container.ubuntu
    }

    check {
      script          = "scripts/first_task/file_exists.sh"
      failure_message = "The file could not be found at /tmp/hello"
    }

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

  condition "contents_match" {
    description = "The contents of the file contains the word 'world'"

    check {
      script          = "scripts/first_task/contents_match.sh"
      failure_message = "The file does not contain the word 'world'"
    }
  }
}

Quiz

A quiz consists of a number of questions that need to be answered in order to complete the quiz.


resource "quiz" "name" {
  ...
}

Attributes

Attribute

Description

The questions that need to be answered in order to complete the quiz.

ShowHints show_hints type: bool

Whether to show hints to the participants.

ShowAnswers show_answers type: bool

Whether to show answers to the participants.

Attempts attempts type: int

The number of attempts a participant can make.

Computed Attributes

These attributes are computed when the config is parsed and applied, and are therefore only known at parsetime or runtime.

Attribute

Description

Meta ID meta.id string

The full ID of the resource e.g. `resource.type.name`. This is computed from the full resource path:

Meta Type meta.type string

The type of the resource. This taken from the type label of the resource definition.

Meta Name meta.name string

The name of the resource. This taken from the name label of the resource definition.

Examples

Full Example

resource "quiz" "france" {
	questions = [
		resource.multiple_choice_question.cities_france,
		resource.text_answer_question.capital_france,
	]
	
	show_hints = true
}

Multiple Choice

MultipleChoiceQuestion

A question that requires a multiple choice answer.

Answers and distractors are combined in a single list and showed in randomized order.


resource "multiple_choice_question" "name" {
  ...
}

Attributes

Attribute

Description

Question question type: string

The question that needs to be answered.

Answer answer type: []string

The correct answer to the question.

Distractors distractors type: []string

Additional incorect options to present to the participants.

Hints hints type: []string

The hints to show to the participants.

Tags tags type: []string

The tags to associate with the question.

Computed Attributes

These attributes are computed when the config is parsed and applied, and are therefore only known at parsetime or runtime.

Attribute

Description

Meta ID meta.id string

The full ID of the resource e.g. `resource.type.name`. This is computed from the full resource path:

Meta Type meta.type string

The type of the resource. This taken from the type label of the resource definition.

Meta Name meta.name string

The name of the resource. This taken from the name label of the resource definition.

Examples

Full Example

question = "Which of these cities are in France?"
	answer = ["Paris", "Lyon", "Nantes"]
	distractors = ["London", "Berlin"]
	
	hints = [
		"One of these cities is in the UK",
		"Another city is in Germany"
	]
}

Single Choice

SingleChoiceQuestion


resource "single_choice_question" "name" {
  ...
}

Attributes

Computed Attributes

These attributes are computed when the config is parsed and applied, and are therefore only known at parsetime or runtime.

Text Answer

TextAnswerQuestion

A question that requires a text answer.


resource "text_answer_question" "name" {
  ...
}

Attributes

Attribute

Description

Question question type: string

The question that needs to be answered.

Answer answer type: string

The correct answer to the question.

Exact exact type: bool

Whether the answer needs to be an exact match.

Hints hints type: []string

The hints to show to the participants.

Tags tags type: []string

The tags to associate with the question.

Computed Attributes

These attributes are computed when the config is parsed and applied, and are therefore only known at parsetime or runtime.

Attribute

Description

Meta ID meta.id string

The full ID of the resource e.g. `resource.type.name`. This is computed from the full resource path:

Meta Type meta.type string

The type of the resource. This taken from the type label of the resource definition.

Meta Name meta.name string

The name of the resource. This taken from the name label of the resource definition.

Examples

Full Example

resource "text_answer_question" "capital_france" {
	question = "What is the capital of France?"
	answer ="Paris"
	hints = [
    "They host the olympics in 2024",
		"The city is known for the Eiffel Tower"
	]
}

Numeric Answer

NumericAnswerQuestion

A question that required an numerical (integer) answer.


resource "numeric_answer_question" "name" {
  ...
}

These attributes are computed when the config is parsed and applied, and are therefore only known at parsetime or runtime.

Nomad

Networking

Cloud Accounts

Certificates

Random

Types

Resource

Variable

Output

Local

Module

Functions

Lab

The lab resource provides the metadata about the lab and some of its configuration. This is the equivalent of what is currently called a "track".


resource "lab" "name" {
 ...
}

Attributes

Attribute

Description

Title title required type: string

The title of the lab.

title = "My Lab"

Description description required type: string

A description of the lab.

description = <<-EOF
The description of my lab.
EOF

description = file("instructions/description.md")

Tags tags type: []string

Tags that describe the lab.

tags = ["something", "else"]

Settings settings type: block

Settings that configure the lab.

settings {
  timeout {
    ...
  }

  idle {
    ...
  }

  controls {
    ...
  }
}

Layouts layout type: []block

A layout that can be used within the lab. This block can be specified multiple times on a lab resource, to allow using multiple layouts throughout a lab.

layout "single_panel" {
  reference = resource.layout.single
}

Content content type: block

The instructional content of the lab that is presented to the end-user.

content {
  chapter "first_chapter" {
    ...
  }
}

Computed Attributes

These attributes are computed when the config is parsed and applied, and are therefore only known at parsetime or runtime.

Attribute

Description

Meta ID meta.id string

The full ID of the resource e.g. `resource.type.name`. This is computed from the full resource path:

// given the following resource
resource "container" "ubuntu" {
  ...
}

// the resulting id will be
resource.container.ubuntu

Meta Type meta.type string

The type of the resource. This taken from the type label of the resource definition.

// given the following resource
resource "container" "ubuntu" {
  ...
}

// the resulting type will be
container

Meta Name meta.name string

The name of the resource. This taken from the name label of the resource definition.

// given the following resource
resource "container" "ubuntu" {
  ...
}

// the resulting name will be
ubuntu

DefaultLayout default_layout type: string

default_layout = "single_panel"

Settings

Settings that configure the lab.


resource "lab" "name" {
  settings {
    ...
  }
}

Attributes

Attribute

Description

Theme theme type: string default: modern_dark

The theme used to style the lab.

theme = "original"

TimeLimit timelimit type: block

Configure the timelimit settings.

timelimit {
  duration = 30
}

Idle idle type: block

Configure the idle timeout settings.

idle {
  enabled = false
}

Controls controls type: block

Configure the controls that are presented to the end-user.

controls {
  show_stop = true
}

Computed Attributes

These attributes are computed when the config is parsed and applied, and are therefore only known at parsetime or runtime.

TimeLimit

Configure the timelimit settings.


resource "lab" "name" {
  settings {
    timelimit {
      ...
    }
  }
}

Attributes

Attribute

Description

Duration duration type: int default: 15

The maximum duration of the lab in minutes.

duration = 15

Extend extend type: int default: 0

How long the lab can be extended in minutes once the timelimit is hit. Set to 0 to disable extending.

extend = 5

ShowTimer show_timer type: bool default: true

Whether or not to show the timelimit timer to the end-user.

show_timer = true

Computed Attributes

These attributes are computed when the config is parsed and applied, and are therefore only known at parsetime or runtime.

Idle

Configure the idle timeout settings.


resource "lab" "name" {
  settings {
    idle {
      ...
    }
  }
}

Attributes

Attribute

Description

Enabled enabled type: bool default: true

Whether or not idle timeout is enabled.

enabled = true

Timeout timeout type: int default: 5

The inactivity duration in minutes after which an end user will be timed out.

timeout = 5

ShowWarning show_warning type: bool default: true

Whether or not to show an idle timeout warning to the end user.

show_warning = true

Computed Attributes

These attributes are computed when the config is parsed and applied, and are therefore only known at parsetime or runtime.

Controls

Configure the controls that are presented to the end-user.


resource "lab" "name" {
  settings {
    controls {
      ...
    }
  }
}

Attributes

Attribute

Description

ShowStop show_stop type: bool default: true

Whether or not to show the stop lab button to the end-user.

show_stop = true

Computed Attributes

These attributes are computed when the config is parsed and applied, and are therefore only known at parsetime or runtime.

Layout

A layout that can be used within the lab. Layouts define what panels and tabs are visible and how they are arranged.


resource "lab" "name" {
  layout "name" {
    ...
  }
}

Attributes

Attribute

Description

Name name required type: string

The name of the layout, that can be used by chapters and pages to switch to.

Reference reference required type: Reference to

A reference to the layout that defines the panels.

reference = resource.layout.two_panels

Default default type: bool

Whether or not the layout of the default one to use when the lab does not have any instructional content.

default = true

Tabs tab type: []block

The tabs that are used within the layout.

tab "terminal" {
  panel = "left_panel"
  target = resource.terminal.ubuntu
}

Instructions instructions type: block

The instructional content that is displayed in the layout.

instructions {
  panel = "right_panel"
}

Computed Attributes

These attributes are computed when the config is parsed and applied, and are therefore only known at parsetime or runtime.

Tab

A tab that is used within the layout and points at a tab target e.g. Terminal, Service, Editor, etc.


resource "lab" "name" {
  layout "name" {
    tab "name" {
      ...
    }
  }
}

Attributes

Attribute

Description

Name name required type: string

The Name of the tab.

tab "name" {
  ...
}

Panel panel required type: string

The name of the panel of the layout that the tab is displayed in.

panel = "left_panel"

Target target required type: Reference to , , , ,

The target resource of the tab that is shown when the tab is active.

target = resource.terminal.ubuntu

Title title type: string

The title of the tab.

title = "Ubuntu"

Active active type: bool

Whether or not the tab is active.

active = true

Visible visible type: bool

Whether or not the tab is visible.

visible = true

Closeable closeable type: bool

Whether or not the tab is closeable.

closeable = true

Movable movable type: bool

Whether or not the tab is movable.

movable = true

Computed Attributes

These attributes are computed when the config is parsed and applied, and are therefore only known at parsetime or runtime.

Instructions

The instructional content that is displayed in the layout.


resource "lab" "name" {
  layout "name" {
    instructions {
      ...
    }
  }
}

Attributes

Attribute

Description

Panel panel required type: string

The panel of the layout that the instructions are displayed in.

panel = "left_panel"

Title title type: string

The title of the instructions tab.

title = "Assignment"

Active active type: bool

Whether or not the tab is active.

active = true

Visible visible type: bool

Whether or not the tab is visible.

visible = true

Closeable closeable type: bool

Whether or not the tab is closeable.

closeable = true

Movable movable type: bool

Whether or not the tab is movable.

movable = true

Computed Attributes

These attributes are computed when the config is parsed and applied, and are therefore only known at parsetime or runtime.

Content

The instructional content of the lab that is presented to the end-user.


resource "lab" "main" {
  content {
    ...
  }
}

Attributes

Attribute

Description

Title title type: string

The title of the content tab.

title = "Instructions"

Chapters chapter type: []block

The chapters that are part of the content.

chapter "first_chapter" {
  page "first_page" {
    reference = resource.page.first
  }
}

Computed Attributes

These attributes are computed when the config is parsed and applied, and are therefore only known at parsetime or runtime.

Chapter

A chapter within the content.


resource "lab" "name" {
  content {
    chapter "name" {
      ...
    }
  }
}

Attributes

Attribute

Description

Slug slug required type: string

The slug of the chapter.

chapter "slug" {
  ...
}

Title title required type: string

The title of the chapter.

title = "Introduction"

LayoutName layout_name type: string

The default layout for all pages in the chapter.

layout_name = "single_panel"

Pages page type: []block

The pages that are part of the chapter.

page "getting_started" {
  reference = resource.page.getting_started
}

Computed Attributes

These attributes are computed when the config is parsed and applied, and are therefore only known at parsetime or runtime.

Page

A page within a chapter that is part of the content.


resource "lab" "name" {
  content {
    chapter "name" {
      page "name" {
        ...
      }
    }
  }
}

Attributes

Attribute

Description

Slug slug required type: string

The slug of the page.

page "slug" {
  ...
}

Reference reference required type: Reference to

A reference to the resource of the page that contains the content.

reference = resource.page.getting_started

Title title type: string

The title of the page. This overrides the title of the page source.

title = "Getting Started"

LayoutName layout_name type: string

The layout to use for the page. When switching to that page, the layout will then change to the selected layout.

layout_name = "single_panel"

Computed Attributes

These attributes are computed when the config is parsed and applied, and are therefore only known at parsetime or runtime.

Examples

Full Example

resource "lab" "minimal" {
  title = "Minimal"
  description = "This is a minimal example lab."

  settings {
    idle {
      enabled = false
    }
  }

  layout "minimal" {
    default = true
    reference = resource.layout.minimal

    tab "terminal" {
      panel = "terminal"
      target = resource.terminal.shell
    }

    instructions {
      panel = "instructions"
    }
  }

  layout "instructions_only" {
    reference = resource.layout.minimal

    instructions {
      panel = "instructions"
    }
  }

  content {
    chapter "introduction" {
      title = "Introduction"
      layout_name = "minimal"
      
      page "first" {
        layout_name = "instructions_only"
        reference = resource.page.first
      }

      page "second" {
        reference = resource.page.second
      }
    }

    chapter "imported" {
      title = "Imported"

      page "first" {
        reference = module.chapter.output.pages.first
      }

      page "second" {
        reference = module.chapter.output.pages.second
      }
    }
  }
}

Cluster

The kubernetes_cluster resource allows you to create immutable Kubernetes clusters running in Docker containers using K3s.


resource "kubernetes_cluster" "name" {
  ...
}

Image Caching

Kubernetes clusters do not share the local machines Docker image cache. Each node in a cluster has it's own unqiue cache.

To save bandwidth all containers launched in the Kubernetes cluster pulled through an image cache that runs in Docker. After the first pull all images are subsequently pulled from the image cache not the public internet. This cache is global to all Nomad and Kubernetes clusters created with Jumppad.

For more information on the image cache see the container_registry resource.

Attributes

Attribute

Description

Attach to the correct network // only when Image is specified

Network attaches the container to an existing network defined in a separate stanza. This block can be specified multiple times to attach the container to multiple networks.

Image defines a Docker image to use when creating the container. By default the kubernetes cluster resource will be created using the latest Jumppad container image.

Nodes nodes type: int

The number of nodes to create in the cluster.

Additional volume to mount to the server and client nodes.

Docker image in the local Docker image cache to copy to the cluster on creation. This image is added to the Kubernetes clients docker cache enabling jobs to use images that may not be in the local registry.

Jumppad tracks changes to copied images, should the image change running jumppad up would push any changes to the cluster automatically.

A `port` stanza allows you to expose container ports on the local network or host. This stanza can be specified multiple times.

A `port_range` stanza allows you to expose a range of container ports on the local network or host. This stanza can be specified multiple times.

The following example would create 11 ports from 80 to 90 (inclusive) and expose them to the host machine.

Environment environment type: map[string]string

environment variables to set when starting the container

An env stanza allows you to set environment variables in the container. This stanza can be specified multiple times.

Specifies the configuration for the Kubernetes cluster.

APIPort api_port type: int

Port to expose the Kubernetes API on the host. By default this uses the standard api port `443`; however, if you are running multiple kubernetes instances you will need to override this value.

ContainerName container_name type: string

The fully qualified resource name for the Kubernetes cluster, this value can be used to address the server from the Docker network. It is also the name of the Docker container.

Computed Attributes

These attributes are computed when the config is parsed and applied, and are therefore only known at parsetime or runtime.

Attribute

Description

Meta ID meta.id string

The full ID of the resource e.g. `resource.type.name`. This is computed from the full resource path:

Meta Type meta.type string

The type of the resource. This taken from the type label of the resource definition.

Meta Name meta.name string

The name of the resource. This taken from the name label of the resource definition.

KubeConfig kube_config type: KubeConfig

Details for the Kubenetes config file that can be used to interact with the cluster.

ConnectorPort connector_port type: int

The port where the Jumppad connector is exposed to the host, this property is requied by the ingress resource and is not generally needed when building blueprints.

ExternalIP external_ip type: string

Local IP address of the Nomad server, this property can be used to set the NOAMD_ADDR on the Jumppad client.

Image

Image defines a Docker image used when creating this container. An Image can be stored in a public or a private repository.


container {
  image {
    ...
  }
}

Attributes

Attribute

Description

Name name required type: string

Name of the image to use when creating the container, can either be the full canonical name or short name for Docker official images. e.g. `consul:v1.6.1` or `docker.io/consul:v1.6.1`.

Username username type: string

Username to use when connecting to a private image repository

Password password type: string

Password to use when connecting to a private image repository, for both username and password interpolated environment variables can be used in place of static values.

Computed Attributes

These attributes are computed when the config is parsed and applied, and are therefore only known at parsetime or runtime.

Attribute

Description

ID id type: string

ID is the unique identifier for the image, this is independent of tag and changes each time the image is built. An image that has been tagged multiple times also shares the same ID. ID string `hcl:"id,optional" json:"id,omitempty"`

NetworkAttachment

Network attachment defines a network to which the container is attached.


network {
  ...
}

Attributes

Attribute

Description

ID id required type: string

ID of the network to attach the container to, specified in reference format. e.g. to attach to a network called `cloud`.

IPAddress ip_address type: string

Static IP address to assign container for the network, the ip address must be within range defined by the network subnet. If this parameter is omitted an IP address will be automatically assigned.

Aliases aliases type: []string

Aliases allow alternate names to specified for the container. Aliases can be used to reference a container across the network, the container will respond to ping and other network resolution using the primary assigned name `[name].container.shipyard.run` and the aliases.

Computed Attributes

These attributes are computed when the config is parsed and applied, and are therefore only known at parsetime or runtime.

Attribute

Description

Name name type: string

Name will equal the name of the network as created by jumppad.

AssignedAddress assigned_address type: string

`assigned_address` will equal the assigned IP address for the network. This will equal ip_address if set; otherwise, this is the automatically assigned IP address.

Port

A port stanza defines host to container communications


container {
  port {
    ...
  }
}

Attributes

Attribute

Description

Local local required type: string

The local port in the container.

Host host type: string

The host port to map the local port to.

Protocol protocol type: string

The protocol to use when exposing the port, can be "tcp", or "udp".

Computed Attributes

These attributes are computed when the config is parsed and applied, and are therefore only known at parsetime or runtime.

PortRange

A port_range stanza defines host to container communications by exposing a range of ports for the container.


container {
  port_range {
    ...
  }
}

Attributes

Attribute

Description

Range range required type: string

The port range to expose, e.g, `8080-8082` would expose the ports `8080`, `8081`, `8082`.

EnableHost enable_host type: bool

Expose the port range on the host.

Protocol protocol type: string

The protocol to use when exposing the port, can be "tcp", or "udp".

Computed Attributes

These attributes are computed when the config is parsed and applied, and are therefore only known at parsetime or runtime.

Volume

A volume type allows the specification of an attached volume.


container {
  volume {
    ...
  }
}

Attributes

Attribute

Description

Source source required type: string

The source volume to mount in the container, can be specified as a relative `./` or absolute path `/usr/local/bin`. Relative paths are relative to the file declaring the container.

Destination destination required type: string

The destination in the container to mount the volume to, must be an absolute path.

Type type type: string

The type of the mount, can be one of the following values:

bind: bind the source path to the destination path in the container
volume: source is a Docker volume
tmpfs: create a temporary filesystem

ReadOnly read_only type: bool

Whether or not the volume is read only.

BindPropagation bind_propagation type: string

Configures bind propagation for Docker volume mounts, only applies to bind mounts, can be one of the following values:

shared
slave
private
rslave
rprivate

For more information please see the Docker documentation https://docs.docker.com/storage/bind-mounts/#configure-bind-propagation

BindPropagationNonRecursive bind_propagation_non_recursive type: bool

Configures recursiveness of the bind mount.

By default Docker mounts with the equivalent of mount --rbind meaning that mounts below the the source directory are visible in the container. or instance running docker run --rm --mount type=bind,src=/,target=/host,readonly busybox will make /run of the host available as/host/run in the container. To make matters even worse it will be writable (since only the toplevel bind is set readonly, not the children).

If bind_propagation_non_recursive is set to true then the container will only see an empty /host/run, meaning thetmpfs which is typically mounted to /run on the host is not propagated into the container.

SelinuxRelabel selinux_relabel type: string

Configures Selinux relabeling for the container (usually specified as :z or :Z) and can be one of the following values:

shared (Equivalent to :z)
private (Equivalent to :Z)

Computed Attributes

These attributes are computed when the config is parsed and applied, and are therefore only known at parsetime or runtime.

ClusterConfig

Specifies the configuration for the Kubernetes cluster.


resource "kubernetes_cluster" "cluster" {
  config {
    ...
  }
}

Attributes

Attribute

Description

Docker configuration for the Kubernetes cluster.

Computed Attributes

These attributes are computed when the config is parsed and applied, and are therefore only known at parsetime or runtime.

DockerConfig

Specifies the configuration for the Docker engine in the cluster.


resource "kubernetes_cluster" "cluster" {
  config {
    docker {
      ...
    }
  }
}

Attributes

Attribute

Description

NoProxy no_proxy type: []string

A list of docker registries that should not be proxied.

InsecureRegistries insecure_registries type: []string

A list of insecure docker registries.

Computed Attributes

These attributes are computed when the config is parsed and applied, and are therefore only known at parsetime or runtime.

KubeConfig

Details for the Kubenetes config file that can be used to interact with the cluster.

Attributes

Computed Attributes

These attributes are computed when the config is parsed and applied, and are therefore only known at parsetime or runtime.

Attribute

Description

ConfigPath path type: string

The path to the kubeconfig file

CA ca type: string

The base64 encoded ca certificate

ClientCertificate client_certificate type: string

The base64 encoded client certificate

ClientKey client_key type: string

The base64 encoded client key

Examples

Simple cluster


resource "network" "cloud" {
  subnet = "10.5.0.0/16"
}

resource "kubernetes_cluster" "cluster" {
  network {
    id = resource.network.cloud.meta.id
  }
}

output "KUBECONFIG" {
  value = resource.kubernetes_cluster.cluster.kube_config.path
}

Full Example


resource "network" "cloud" {
  subnet = "10.5.0.0/16"
}

resource "kubernetes_cluster" "cluster" {
  network {
    id = resource.network.cloud.meta.id
  }

  copy_image {
    name = "shipyardrun/connector:v0.1.0"
  }
}

resource "k8s_config" "fake_service" {
  cluster = resource.kubernetes_cluster.cluster

  paths = ["./fake_service.yaml"]

  health_check {
    timeout = "240s"
    pods    = ["app.kubernetes.io/name=fake-service"]
  }
}

resource "helm" "vault" {
  cluster = resource.kubernetes_cluster.cluster

  repository {
    name = "hashicorp"
    url  = "https://helm.releases.hashicorp.com"
  }

  chart   = "hashicorp/vault"
  version = "v0.18.0"

  values = "./helm/vault-values.yaml"

  health_check {
    timeout = "240s"
    pods    = ["app.kubernetes.io/name=vault"]
  }
}

resource "ingress" "vault_http" {
  port = 18200

  target {
    resource = resource.kubernetes_cluster.cluster
    port = 8200

    config = {
      service   = "vault"
      namespace = "default"
    }
  }
}

resource "ingress" "fake_service" {
  port = 19090

  target {
    resource = resource.kubernetes_cluster.cluster
    port = 9090

    config = {
      service   = "fake-service"
      namespace = "default"
    }
  }
}

output "VAULT_ADDR" {
  value = "http://${resource.ingress.vault_http.local_address}"
}

output "KUBECONFIG" {
  value = resource.kubernetes_cluster.cluster.kube_config.path
}

Container

Container defines a structure for creating Docker containers


resource "container" "name" {
  ...
}

Attributes

Attribute

Description

Image defines a Docker image to use when creating the container.

A port stanza allows you to expose container ports on the local network or host. This stanza can be specified multiple times.

A port_range stanza allows you to expose a range of container ports on the local network or host. This stanza can be specified multiple times.

The following example would create 11 ports from 80 to 90 (inclusive) and expose them to the host machine.

Command command type: []string

Command allows you to specify a command to execute when starting a container. Command is specified as an array of strings, each part of the command is a separate string.

For example, to start a container and follow logs at /dev/null the following command could be used.

Environment environment type: map[string]string

Allows you to set environment variables in the container.

Labels labels type: map[string]string

Labels to apply to the container

A volume allows you to specify a local volume which is mounted to the container when it is created. This stanza can be specified multiple times.

Network attaches the container to an existing network defined in a separate stanza. This block can be specified multiple times to attach the container to multiple networks.

Entrypoint entrypoint type: []string

Entrypoint for the container, if not set, Jumppad starts the container using the entrypoint defined in the Docker image.

DNS dns type: []string

The nameservers to use to resolve dns requests.

Privileged privileged type: bool

Should the container run in Docker privileged mode?

The capabilities to add or drop.

MaxRestartCount max_restart_count type: int

The maximum number of times a container will be restarted when it exits with a status code other than 0

Define resource constraints for the container

Define a health check for the container, the resource will only be marked as successfully created when the health check passes.

Allows the container to be run as a specific user or group.

Computed Attributes

These attributes are computed when the config is parsed and applied, and are therefore only known at parsetime or runtime.

Attribute

Description

Meta ID meta.id string

The full ID of the resource e.g. `resource.type.name`. This is computed from the full resource path:

Meta Type meta.type string

The type of the resource. This taken from the type label of the resource definition.

Meta Name meta.name string

The name of the resource. This taken from the name label of the resource definition.

ContainerName container_name type: string

Fully qualified resource name for the container, this value can be used to access the container from within the Docker network. `container_name` is also the name of the created Docker container.

NetworkAttachment

Network attachment defines a network to which the container is attached.


network {
  ...
}

Attributes

Attribute

Description

ID id required type: string

ID of the network to attach the container to, specified in reference format. e.g. to attach to a network called `cloud`.

IPAddress ip_address type: string

Static IP address to assign container for the network, the ip address must be within range defined by the network subnet. If this parameter is omitted an IP address will be automatically assigned.

Aliases aliases type: []string

Computed Attributes

These attributes are computed when the config is parsed and applied, and are therefore only known at parsetime or runtime.

Attribute

Description

Name name type: string

Name will equal the name of the network as created by jumppad.

AssignedAddress assigned_address type: string

`assigned_address` will equal the assigned IP address for the network. This will equal ip_address if set; otherwise, this is the automatically assigned IP address.

Image

Image defines a Docker image used when creating this container. An Image can be stored in a public or a private repository.


container {
  image {
    ...
  }
}

Attributes

Attribute

Description

Name name required type: string

Name of the image to use when creating the container, can either be the full canonical name or short name for Docker official images. e.g. `consul:v1.6.1` or `docker.io/consul:v1.6.1`.

Username username type: string

Username to use when connecting to a private image repository

Password password type: string

Password to use when connecting to a private image repository, for both username and password interpolated environment variables can be used in place of static values.

Computed Attributes

These attributes are computed when the config is parsed and applied, and are therefore only known at parsetime or runtime.

Attribute

Description

ID id type: string

Volume

A volume type allows the specification of an attached volume.


container {
  volume {
    ...
  }
}

Attributes

Attribute

Description

Source source required type: string

The source volume to mount in the container, can be specified as a relative `./` or absolute path `/usr/local/bin`. Relative paths are relative to the file declaring the container.

Destination destination required type: string

The destination in the container to mount the volume to, must be an absolute path.

Type type type: string

The type of the mount, can be one of the following values:

bind: bind the source path to the destination path in the container
volume: source is a Docker volume
tmpfs: create a temporary filesystem

ReadOnly read_only type: bool

Whether or not the volume is read only.

BindPropagation bind_propagation type: string

Configures bind propagation for Docker volume mounts, only applies to bind mounts, can be one of the following values:

shared
slave
private
rslave
rprivate

For more information please see the Docker documentation https://docs.docker.com/storage/bind-mounts/#configure-bind-propagation

BindPropagationNonRecursive bind_propagation_non_recursive type: bool

Configures recursiveness of the bind mount.

SelinuxRelabel selinux_relabel type: string

Configures Selinux relabeling for the container (usually specified as :z or :Z) and can be one of the following values:

shared (Equivalent to :z)
private (Equivalent to :Z)

Computed Attributes

These attributes are computed when the config is parsed and applied, and are therefore only known at parsetime or runtime.

Port

A port stanza defines host to container communications


container {
  port {
    ...
  }
}

Attributes

Attribute

Description

Local local required type: string

The local port in the container.

Host host type: string

The host port to map the local port to.

Protocol protocol type: string

The protocol to use when exposing the port, can be "tcp", or "udp".

Computed Attributes

These attributes are computed when the config is parsed and applied, and are therefore only known at parsetime or runtime.

PortRange

A port_range stanza defines host to container communications by exposing a range of ports for the container.


container {
  port_range {
    ...
  }
}

Attributes

Attribute

Description

Range range required type: string

The port range to expose, e.g, `8080-8082` would expose the ports `8080`, `8081`, `8082`.

EnableHost enable_host type: bool

Expose the port range on the host.

Protocol protocol type: string

The protocol to use when exposing the port, can be "tcp", or "udp".

Computed Attributes

These attributes are computed when the config is parsed and applied, and are therefore only known at parsetime or runtime.

Resources

A resources type allows you to configure the maximum resources which can be consumed.


container {
  resources {
    ...
  }
}

Attributes

Attribute

Description

CPU cpu type: int

Set the maximum CPU which can be consumed by the container in MHz, 1 CPU == 1000MHz.

CPUPin cpu_pin type: []int

Pin the container CPU consumption to one or more logical CPUs. For example to pin the container to the core 1 and 4.

Memory memory type: int

Maximum memory which a container can consume, specified in Megabytes.

GPU settings to pass through to container

Computed Attributes

These attributes are computed when the config is parsed and applied, and are therefore only known at parsetime or runtime.

Capabilities


container {
  capabilities {
    ...
  }
}

Attributes

Attribute

Description

Add add type: []string

CapAdd is a list of kernel capabilities to add to the container

Drop drop type: []string

CapDrop is a list of kernel capabilities to remove from the container

Computed Attributes

These attributes are computed when the config is parsed and applied, and are therefore only known at parsetime or runtime.

User

User and Group configuration to be used when running a container, by default Docker runs commands in the container as root id 0.


user {
  ...
}

Attributes

Attribute

Description

User user required type: string

Linux user ID or user name to run the container as, this overrides the default user configured in the container image.

Group group required type: string

Linux group ID or group name to run the container as, this overrides the default group configured in the container image.

group = "root"

Computed Attributes

These attributes are computed when the config is parsed and applied, and are therefore only known at parsetime or runtime.

HealthCheckContainer

A health_check stanza allows the definition of a health check which must pass before the container is marked as successfully created. There are three different types of healthcheck http, tcp, and exec, these are not mutually exclusive, it is possible to define more than one health check.

Health checks are executed sequentially, if one health check fails, the following checks are not executed. The execution order is http, tcp, exec.


health_check {
  ...
}

Attributes

Attribute

Description

Timeout timeout required type: string

The maximum duration to wait before marking the health check as failed. Expressed as a Go duration, e.g. `1s` = 1 second, `100ms` = 100 milliseconds.

HTTP Health Check block defining the address to check and expected status codes.

Can be specified more than once.

TCP Health Check block defining the address to test.

Can be specified more than once.

Exec Health Check block defining either a command to run in the current container, or a script to execute.

Can be specified more than once.

Computed Attributes

These attributes are computed when the config is parsed and applied, and are therefore only known at parsetime or runtime.

HealthCheckHTTP

A HTTP health check executes an HTTP request for the given address and evaluates the response against the expected success_codes. If the reponse matches any of the given codes the check passes.


health_check {
  http {
    ...
  }
}

Attributes

Attribute

Description

Address address required type: string

The URL to check, health check expects a HTTP status code to be returned by the URL in order to pass the health check.

Method method type: string

HTTP method to use when executing the check

Body body type: string

HTTP body to send with the request

Headers headers type: map[string]string

HTTP headers to send with the check

SuccessCodes success_codes type: []int

HTTP status codes returned from the endpoint when called. If the returned status code matches any in the array then the health check will pass.

Computed Attributes

These attributes are computed when the config is parsed and applied, and are therefore only known at parsetime or runtime.

HealthCheckTCP

A TCP health check attempts to open a connection to the given address. If a connection can be opened then the check passes.


health_check {
  tcp {
    ...
  }
}

Attributes

Attribute

Description

Address address required type: string

The adress to check.

Computed Attributes

These attributes are computed when the config is parsed and applied, and are therefore only known at parsetime or runtime.

HealthCheckExec

Exec health checks allow you to execute a command or script in the current container. If the command or script receives an exit code 0 the check passes.


health_check {
  exec {
    ...
  }
}

Attributes

Attribute

Description

Command command type: []string

The command to execute, the command is run in the target container.

Script script type: string

A script to execute in the target container, the script is coppied to the container into the /tmp directory and is then executed.

ExitCode exit_code type: int

ExitCode to mark a successful check, default 0

Computed Attributes

These attributes are computed when the config is parsed and applied, and are therefore only known at parsetime or runtime.

Examples

Minimal Example


resource "container" "unique_name" {
    network {
        id         = resource.network.cloud.meta.id
        ip_address = "10.16.0.203"
        aliases    = ["my_unique_name_ip_address"]
    }

    image {
        name = "consul:1.6.1"
    }
}

Full Example


resource "container" "unique_name" {
    depends_on = ["resource.container.another"]

    network {
        id         = resource.network.cloud.meta.id
        ip_address = "10.16.0.200"
        aliases    = ["my_unique_name_ip_address"]
    }

    image {
        name     = "consul:1.6.1"
        username = "repo_username"
        password = "repo_password"
    }

    command = [
        "consul",
        "agent"
    ]

    environment = {
        CONSUL_HTTP_ADDR = "http://localhost:8500"
    }

    volume {
        source      = "./config"
        destination = "/config"
    }

    port {
        local  = 8500
        remote = 8500
        host   = 18500
    }

    port_range {
        range       = "9000-9002"
        enable_host = true
    }

    privileged = false
}

Instruqt Labs (beta)

Instruqt

Overview

Hands-on learning

Learning made easy

Integrate external systems

Rich analytics

Flexible sandboxes

Getting started

Creating your first lab

Create a New Lab from a starter template

Create a Repository on GitHub

Push the Lab to GitHub

Import the Lab into Instruqt

Test the Lab in Instruqt

Exploring the lab configuration

Lab

Layouts

Making changes

Adding your first chapter

Creating the outline of your lab

Adding a page to your lab

Create a page resource

Adding markdown content

Displaying your instructions in the lab

Committing and pushing the changes

Configuring sandboxes

Defining a network within your lab

Adding a container to your lab

Create a service resource

Customizing layouts

Adding the service to a layout

Preview your changes

Adding quizzes

Add a quiz resource

Add a new page with activities

Embedding quizzes in your content

Preview your changes

Adding tasks and gating content

Adding a new container & terminal

Adding the task resource

Adding the scripts

Add the activity to a page

Add the new page & terminal the lab.

Add the task to the instructional content

Preview your changes

Finishing up

Adding feedback

Add a new page

Add a full page layout

Add new chapter and page.

Add the markdown with the component

Upgrade from Tracks

Differences between Tracks and Labs

Migrating a Track to a Lab

Step 1: Migration instructional content

Step 2: Identify required sandbox components

Step 3: Implement Lab Sandbox

Step 4: Push changes and test Lab

Tutorials

Content

Sandbox Container with Terminal

Sandbox Container with Web App Service

Sandbox Kubernetes Cluster

Organizing content in Chapters and Pages

Validation with Tasks and Conditions

Validation with Quizzes

Workflows

Running a Lab

Sharing a Lab with end users

Create a new Lab

Update an existing Lab

Content versioning

Integrate with GitHub

Import Lab from GitHub Repository

Documentation

Overview

Sandbox environments

Concepts

Instructional content

Adding a `page` to your lab

Create a `page` resource

Adding `markdown` content

Defining a `network` within your lab

Adding a `container` to your lab

Create a `service` resource

Adding the `service` to a layout

Add a `quiz` resource

Adding the `task` resource