Network Shield and Relay
Limited Access
Network shield and relay is a new feature which is available to enterprise customers. If you would like to try it out now, please reach out to the Unikraft Cloud Discord or send an email to support@unikraft.com.
Dedicated unikraft CLI subcommands for the network shield and relay are coming soon.
In the meantime, configure them through the API, which you can invoke with curl or the unikraft api command.
A relay redirects all network traffic to and from a network interface toward another network interface. You can set up a relay VM and configure its interface as the relay for another VM's interface, so that all its traffic transparently passes through the relay.
The network shield
The network shield is an example of a relay: an instance inserted between a microVM and the public internet. It sits directly in the path, as a bump on the wire, so every packet the workload sends or receives goes through it first. Since many instances can specify the same microVM as their relay, many sandboxes can share the same network shield.
A microVM every packet passes through, which filters traffic and injects secrets
Third-party APIs, package registries
The shield provides filtering capabilities but also the possibility to inject credentials/secrets for agentic or other use cases. This is useful in sandbox environments, as it means the sandbox won't need unfiltered network access or access to secrets.
Each shield runs as its own microVM. This means each shield:
- Can be scaled to zero and woken up when it receives traffic.
- Is strongly isolated from the microVMs running the workloads, and also from other network shields.
- Is fully flexible and extensible in the capabilities it provides. The image it uses determines its behavior.
A first official network shield image will be available soon.
Relay
To use a relay, reference another interface by name inside a relay object:
Relay builds on custom network configuration: the relay object is a field of a network_interfaces entry, so the same permission, license, and limitations apply.
The relay object accepts the following fields:
| Field | Required | Description |
|---|---|---|
name | Yes | The name of the interface to relay traffic through, which must belong to another instance in your account. |
relay_dns | No | Whether the relay forwards DNS requests, true by default, with false leaving them to the default DNS server. |
Relay notes
-
All network traffic passes over the relay. Many VMs can share a single relay.
-
This feature supports managed interfaces with custom TAP devices.
-
You don't need to enable VM-to-VM communication to use this feature (which you don't want in a sandbox environment).
-
DNS requests can be either passed to the relay or the default DNS server. This is to simplify setups where security isn't the focus as you don't need to run a DNS server in the relay VM.
-
The guest acting as a relay VM should have net.ipv4.ip_forward=1 and rp_filter=0 set.
Error handling
| Error message | Cause |
|---|---|
Insufficient license. Please make sure your license is valid and includes custom network configurations | Your account's license doesn't include custom network configuration, which relay is part of. |
Unknown member 'network_interfaces' | Your account lacks the net_manager permission required for this feature. |
Limitations
- The feature requires the
net_managerpermission and a license that includes it (see the note at the top of this page). - Creating a template from an instance drops its network configuration, since binding a template to a specific TAP device or IP defeats the purpose of cloning many instances from it.
- The create call sets the configuration once, and no PATCH support exists yet.
- Every custom network configuration limitation applies here too, since relay is part of that feature.
Learn more
- Custom network configuration: the interface, gateway, and nameserver settings that relay builds on.
- Instances: how instances work, from their lifecycle to their configuration.
- Sandboxes: run untrusted code in a hardware-isolated microVM.
- Unikraft Cloud's REST API reference, in particular the section on instances.