Networking

Learn about the key aspects of networking in the Instruqt platform.

Overview

There are three areas of networking to understand with Instruqt:

1. Inbound traffic from learners and external systems to the sandbox hosts.

2. Host to host communication between sandbox hosts.

3. Outbound traffic from sandbox hosts to the public internet.

Inbound traffic

There are two ways to send traffic to sandbox hosts on the Instruqt platform:

• Authenticated web traffic from learners through the Instruqt web proxy (instruqt.com).

• Unauthenticated TCP/UDP traffic to sandbox VMs, only if explicitly enabled (instruqt.io).

Authenticated learner traffic

If you apply a service tab in a track, Instruqt forwards requests from learners to the sandbox hosts through the Instruqt web proxy:

The features of the proxy include the following:

• Allowing requests from logged-in learners only.

• Forwarding requests to both containers and VMs.

• Terminating the HTTPS connection on the proxy and forwarding plain HTTP (or HTTPS if the port contains 443).

Web proxy subdomain

The web proxy uses a formatted subdomain to decide where to forward a request to:

https://[HOSTNAME]-[PORT]-[PARTICIPANT_ID].env.play.instruqt.com

There are three components in the subdomain:

Component	Notes
HOSTNAME	The name assigned to the host (VM or container).
[PORT]	The port to forward traffic to.
[PARTICIPANT_ID]	An identifier that uniquely identifies a sandbox environment.

If you're forwarding traffic to a container, make sure to expose the port in its configuration.

HTTPS endpoints If aport contains 443 ( ex: 443, 8443, and 4431), the proxy expects an HTTPS endpoint on the sandbox host. The web proxy accepts any non-expired TLS certificate, including self-signed certificates.

Unauthenticated TCP/UDP traffic

By default, sandbox hosts are not exposed to the public internet. You can change that behavior.

• Sandbox VMs have an external IP address. You can allow external ingress traffic to some ports or port ranges.

• Sandbox containers can never receive direct traffic from external sources.

You can allow external ingress traffic to sandbox VMs using the attribute allow_external_ingress in config.yml (There is currently no way to set this property using the Web UI. Install Instruqt CLI first and pull your track to edit config.yml)

config.yml

version: "3"
virtualmachines:
- name: host01
  image: ubuntu-minimal-2004-lts
  shell: /bin/bash
  machine_type: n1-standard-1
  allow_external_ingress:
  - http
  - https
  - high-ports 

You can specify one or more ports or port ranges. There are three valid values:

• http: Port 80 (HTTP)

• https: Port 443 (HTTPS)

• high-ports: Port range 1024-65535, excluding 15770-15779, which are reserved for Instruqt use.

Resolving the external IP of a sandbox VM

To connect to a sandbox VM from an external system, you will need to know its external IP address. Instruqt adds two temporary DNS records for every sandbox VM with allow_external_ingress enabled:

• [HOSTNAME].[SANDBOX ID].instruqt.io

• *.[HOSTNAME].[SANDBOX ID].instruqt.io (wildcard record)

Here are three examples of fully qualified hostnames that resolve to the same sandbox VM:

• host1.lbnlkljkcpfa.instruqt.io

• api.host1.lbnlkljkcpfa.instruqt.io (due to the wildcard)

• www.host1.lbnlkljkcpfa.instruqt.io (due to the wildcard)

Run this snippet on the sandbox VM to print its fully qualified hostname:

# Prints the hostname of the sandbox host 
echo $HOSTNAME.$_SANDBOX_ID.instruqt.io

The environment variable _SANDBOX_ID contains the sandbox identifier. Sandboxes are created on-demand for every track play, and every sandbox has a unique identifier.

If the attribute allow_external_ingress is empty, we do not add DNS records.

When using unauthenticated access, you can directly link to the VM using a website tab. If you use ${_SANDBOX_ID} in the URL, it will be replaced with the sandbox ID—for example, api.host1.${_SANDBOX_ID}.instruqt.io

HTTP URLs are also supported, but due to browser security restrictions, you must enable the `new_window` (or "Open website in a new window") option. This is because Instruqt is served over HTTPS, and modern browsers block embedding HTTP content (mixed content) in an iframe within an HTTPS page.

Host to host communication

All hosts in a sandbox can communicate with one another without any restrictions or blocked ports. This includes both containers and VMs. The Instruqt platform provides internal DNS for sandbox environments. If you add a host with the name host01, and another host with the name host02, they can reach one another using these short hostnames.

Container-to-container, VM-to-container, and container-to-VM communications all work using this method, so you won't need to keep track of IP addresses.

root@host01:~# ping host02 -c 1
PING host02.cn7p5alqphbi.svc.cluster.local (10.96.8.158) 56(84) bytes of data.
64 bytes from 10.96.8.158 (10.96.8.158): icmp_seq=1 ttl=63 time=1.34 ms

You may also use the internal private domain names for host-to-host communication. The _SANDBOX_DNS environment variable contains the full domain address and can be used in complementary to the hostname to construct the FQDN, as demonstrated below. This should only be necessary if your application requires a fully-qualified domain name (FQDN) for communication.

host01.${_SANDBOX_DNS}

Outbound traffic from sandbox hosts

Sandbox hosts can connect to the public internet without limitations, as we do not block any outbound traffic from the sandbox.