Getting started
Reference
Resources
Networking
This reference describes three key aspects of networking on the Instruqt platform:
- 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 virtual machines (VMs), only if explicitly enabled (instruqt.io).
Authenticated web traffic from learners
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).
The proxy uses a formatted subdomain
The web proxy uses a formatted subdomain to decide where to forward a request to:
https://[HOSTNAME]-[PORT]-[PARTICIPANT_ID].env.play.instruqt.comThere are three components in the subdomain:
- Port: The port to forward the traffic to. If you're forwarding traffic to a container, make sure to expose the port in config.yml.
- Participant ID: An identifier that uniquely identifies a sandbox environment. You can access the participant ID on any sandbox host through the environment variable
INSTRUQT_PARTICIPANT_ID.
No header rewriting
The web proxy does not support rewriting of
Host and Location headers. If your service tab breaks because your service redirects to an internal hostname, configure the Instruqt formatted subdomain as a virtual host. Using an HTTPS endpoint on the sandbox host
If the port contains
443 (examples include 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.To embed a web service in a tab, use a
service tab, not a website tab. Use a website tab to embed external websites.Unauthenticated TCP/UDP traffic to sandbox VMs
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
1
version: "2"
2
virtualmachines:
3
- name: host01
4
image: ubuntu-minimal-2004-lts
5
shell: /bin/bash
6
machine_type: n1-standard-1
7
allow_external_ingress:
8
- http
9
- https
10
- high-ports
Copied!
You can specify one or more ports or port ranges. There are three valid values:
http: Port80(HTTP)https: Port443(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.ioapi.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:
1
# Prints the hostname of the sandbox host
2
echo $HOSTNAME.$_SANDBOX_ID.instruqt.io
Copied!
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.ioHost 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.
1
[email protected]:~# ping host02 -c 1
2
PING host02.cn7p5alqphbi.svc.cluster.local (10.96.8.158) 56(84) bytes of data.
3
64 bytes from 10.96.8.158 (10.96.8.158): icmp_seq=1 ttl=63 time=1.34 ms
Copied!
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.
Last modified 1mo ago