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
  }
}

For more information on how to configure containers, please see the Container reference page for many more options.

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. We also need to set the scheme that must be used, in this case http.

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

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 "right" 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 "left" 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

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

    instructions {
      panel = "right"
    }
  }
}

Preview your changes

Like in the previous section, you can validate your changes using instruqt lab validate, and then git add, git commit, and 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 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.