Network

Defined insandbox.hcl

The network resource creates an isolated network inside the sandbox. Both containers and virtual machines attach to networks through their network blocks, and resources on the same network discover each other using names or aliases.

Use Cases

As a lab author, you can use networks to create realistic networking scenarios:

• Multi-Tier Applications: Separate web, application, and database tiers on different networks to demonstrate network security and architecture patterns
• Network Segmentation: Split a lab into separate segments, such as a DMZ and an internal network, to show how traffic is kept apart
• Service Discovery: Show users how containers find each other using DNS names and aliases within networks

Networks enable you to create complex, production-like environments where users learn networking concepts through hands-on experience.

HCL Syntax

Basic Syntax

resource "network" "name" {
  subnet = "10.0.0.0/24"
}

Full Syntax

resource "network" "name" {
  subnet      = "10.100.0.0/16"
  enable_ipv6 = true
}

Fields

Field	Type	Required	Description
subnet	string	✓	Set the IPv4 subnet in CIDR notation, for example 10.100.100.0/24. It must not overlap with any existing network ranges. Containers on this network get addresses from this range. ConstraintsMust be a valid CIDR notation with octets 0-255 and prefix 0-32 (e.g., 10.0.0.0/24)
enable_ipv6	bool	—	Add an IPv6 range to this network so containers can receive IPv6 addresses. Leave off if you only need IPv4. Defaultfalse

Examples

Basic Network

resource "network" "backend" {
  subnet = "10.0.1.0/24"
}

Network with IPv6

resource "network" "frontend" {
  subnet      = "10.0.2.0/24"
  enable_ipv6 = true
}

Multiple Networks

resource "network" "web_tier" {
  subnet = "10.0.10.0/24"
}

resource "network" "db_tier" {
  subnet = "10.0.20.0/24"
}

resource "network" "management" {
  subnet = "10.0.30.0/24"
}

Container Network Usage

resource "network" "app_network" {
  subnet = "10.0.100.0/24"
}

resource "container" "web" {
  image {
    name = "nginx:latest"
  }

  network {
    id         = resource.network.app_network.meta.id
    ip_address = "10.0.100.10"
    aliases    = ["web", "frontend"]
  }
}

resource "container" "db" {
  image {
    name = "postgres:13"
  }

  network {
    id         = resource.network.app_network.meta.id
    ip_address = "10.0.100.20"
    aliases    = ["db", "database"]
  }
}

Network Communication

Resources on the same network reach each other by:

• Short name: db, web - resolved through the guest’s DNS search domains (works from containers and VMs attached to the network)
• Alias: db or the fully qualified db.sandbox.internal
• FQDN: web.container.sandbox.internal or box.vm.sandbox.internal
• IP: 10.0.100.10

Aliases must be unique; if two share one, the last to start wins.

## From web container to db container
curl http://db:5432
curl http://database:5432
curl http://10.0.100.20:5432

DNS Names per Network

Every network attachment also registers network-scoped DNS names, which matter when a resource sits on more than one network. For a resource web of type container with alias frontend attached to network app_network, all of these resolve:

Form	Example
<name>.<type>.sandbox.internal	web.container.sandbox.internal
<name>.<network>.sandbox.internal	web.app_network.sandbox.internal
<name>.<type>.<network>.sandbox.internal	web.container.app_network.sandbox.internal
<alias>.<network>.sandbox.internal	frontend.app_network.sandbox.internal

Attached guests receive a DNS search domain per network (<network>.sandbox.internal) plus the sandbox-wide zone (sandbox.internal), which is why short names work without qualification.

A VM on two networks can be addressed per network - useful when teaching multi-homed setups:

resource "network" "frontend" {
  subnet = "10.0.1.0/24"
}

resource "network" "backend" {
  subnet = "10.0.2.0/24"
}

resource "vm" "gateway" {
  image {
    name = "ubuntu:24.04"
  }

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

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

On the frontend network, the VM is gateway.frontend.sandbox.internal. On the backend network, it is gateway.backend.sandbox.internal.

Default Networks

Whether a lab starts with a network depends on how you created it:

• Labs created from scratch in the UI start with a network named main (subnet 10.0.5.0/24). Containers you create in the UI attach to it by default.
• Labs created with the CLI (instruqt lab init) have no network. Define one yourself, as the getting-started guide does.

The main network is normal configuration, which you can edit or delete. A container with no network block does not join any lab network. A VM with no network block joins a built-in network, instruqt-default (10.100.0.0/24).

Isolation Between Networks

Networks are always isolated from each other. There is no routing between networks, so resources on different networks can’t reach each other by IP or by name. To let two resources communicate, attach them to the same network. A resource can join several networks. You can’t turn this isolation off.

Best Practices

1. Logical Separation: Use separate networks for different application tiers (web, app, database)
2. Private Subnets: Always use private IP ranges to avoid conflicts
3. Subnet Sizing: Choose appropriate subnet sizes - /24 (254 hosts) is usually sufficient
4. Meaningful Names: Use descriptive network names that indicate their purpose
5. Network Aliases: Use aliases for service discovery instead of hardcoding IP addresses
6. Security: Networks provide isolation - resources on different networks cannot communicate, and this cannot be turned off

Common Subnet Ranges

Range	CIDR	Hosts	Use Case
Small	/28	14	Small labs with few containers
Medium	/24	254	Most common choice for lab environments
Large	/20	4094	Complex labs with many containers
Very Large	/16	65534	Multi-network labs with many subnets