Networking Guide

Volt uses Linux-native networking — bridges, virtual ethernet pairs, and nftables — instead of custom network drivers or plugins. This guide covers bridge setup, container connectivity, firewall management, and multi-container communication.

Network Architecture

                        ┌──────────────┐
                        │   Internet    │
                        └──────┬───────┘
                               │
                        ┌──────▼───────┐
                        │   eth0       │
                        │  (host NIC)  │
                        └──────┬───────┘
                               │
                        ┌──────▼───────┐
                        │  voltbr0     │  ← Default bridge
                        │  10.0.0.1/24 │
                        └──┬──────┬────┘
                           │      │
              ┌────────────▼┐  ┌──▼───────────┐
              │  veth-web   │  │  veth-api   │
              │  10.0.0.2   │  │  10.0.0.3    │
              ├─────────────┤  ├──────────────┤
              │ Container   │  │ Container    │
              │ "web"       │  │ "api"        │
              └─────────────┘  └──────────────┘

Each container gets a virtual ethernet pair (veth). One end stays in the host network namespace and is attached to a bridge; the other end moves into the container's network namespace.

Bridge Setup

Default Bridge: voltbr0

Volt creates a default bridge called voltbr0 when you first create a network. This bridge acts as a virtual switch connecting containers.

# Create the default network (creates voltbr0)
sudo volt net create default --subnet 10.0.0.0/24

# List networks
sudo volt net list

Custom Bridges

Create additional bridges for network isolation between container groups:

# Create a separate network for database containers
sudo volt net create dbnet --subnet 10.100.0.0/24

# Create a DMZ network
sudo volt net create dmz --subnet 172.16.0.0/24

Direct Bridge Management

For lower-level control, use the bridge subcommands:

# Create a bridge directly
sudo volt net bridge create mybridge

# List all bridges
sudo volt net bridge list

# Delete a bridge
sudo volt net bridge delete mybridge

Container Networking

Connecting Containers to Networks

# Connect a container to a network
sudo volt net connect default web

# Connect to multiple networks
sudo volt net connect default web
sudo volt net connect dbnet web

# Disconnect from a network
sudo volt net disconnect default web

Using Networks with Constellations (Compose)

In a volt-compose.yaml, networks are created automatically:

version: "1"
services:
  web:
    image: debian-minimal
    networks:
      - frontend
      - backend
  api:
    image: debian-minimal
    networks:
      - backend
  db:
    image: debian-minimal
    networks:
      - backend

networks:
  frontend:
  backend:

The web container can reach api and db on the backend network, while external traffic only touches the frontend network.

Network Status

Get a comprehensive view of all networking:

sudo volt net status

This shows bridges, assigned IPs, routes, and listening ports in one view.

Inspecting Networks

# Detailed info about a network
sudo volt net inspect default

# List DNS resolvers
sudo volt net dns list

# List listening ports
sudo volt net port list

# List VLAN interfaces
sudo volt net vlan list

nftables Firewall

Volt uses nftables for firewall management — the modern replacement for iptables. Rules are stored with metadata for easy management.

Listing Rules

sudo volt net firewall list

Adding Rules

# Allow HTTP traffic
sudo volt net firewall add --port 80 --protocol tcp

# Allow HTTPS
sudo volt net firewall add --port 443 --protocol tcp

# Allow SSH from a specific subnet
sudo volt net firewall add --port 22 --protocol tcp --source 10.0.0.0/8

# Allow DNS (UDP)
sudo volt net firewall add --port 53 --protocol udp

Deleting Rules

# Remove a specific rule
sudo volt net firewall delete --port 80

# Flush all rules
sudo volt net firewall flush

Rule Metadata

Volt stores firewall rule metadata in /etc/volt/firewall-rules.json, making it easy to track which rules were added by which workload or user.

Multi-Container Communication

Containers on the Same Bridge

Containers connected to the same bridge network can communicate directly via their assigned IP addresses:

  ┌────────────────┐           ┌────────────────┐
  │ web (10.0.0.2) │◄─────────▶│ api (10.0.0.3) │
  └───────┬────────┘           └───────┬────────┘
          │                            │
    ┌─────▼────────────────────────────▼─────┐
    │          voltbr0 (10.0.0.1/24)         │
    └────────────────────────────────────────┘

# From inside the web container, reach the api container:
curl http://10.0.0.3:8080/health

Isolated Networks

Containers on different bridges cannot communicate unless explicitly routed:

# Create isolated networks
sudo volt net create frontend --subnet 10.1.0.0/24
sudo volt net create backend --subnet 10.2.0.0/24

# web can only reach the frontend
sudo volt net connect frontend web

# db can only reach the backend
sudo volt net connect backend db

# api bridges both (can talk to web AND db)
sudo volt net connect frontend api
sudo volt net connect backend api

Port Forwarding

Expose container ports to the host using Constellation compose files:

services:
  web:
    image: debian-minimal
    ports:
      - "80:80"     # host:container
      - "443:443"

Network Policies

Network policies provide a higher-level abstraction for controlling workload-to-workload traffic:

# Allow web to talk to api on port 8080
sudo volt net policy create --from web --to api --allow 8080

# Allow api to talk to db on port 5432
sudo volt net policy create --from api --to db --allow 5432

# List all policies
sudo volt net policy list

# Test connectivity between workloads
sudo volt net policy test --from web --to db

# Delete a policy
sudo volt net policy delete <policy-id>

Troubleshooting

Common Issues

Diagnostic Commands

# Full network overview
sudo volt net status

# Check bridge details
ip link show type bridge
bridge link show

# Check nftables rules
sudo nft list ruleset

# Check listening ports
ss -tlnp

# Check IP forwarding
sysctl net.ipv4.ip_forward
sysctl net.ipv6.conf.all.forwarding