Skip to main content
Version: v1.1

Per-Instance Network Lifecycle

Introduction​

This page walks through the life of a single instance's network, from the moment the instance starts, through the steps that give it connectivity, to the teardown that reclaims everything when it stops. The same components introduced in the Networking overview are applied here in a fixed order, and that order is what makes setup recoverable: each step builds on the one before it, and teardown simply runs them in reverse.

Lifecycle Overview​

loading...

When an instance starts, the Service Manager first asks the Communication Manager for that instance's network parameters, then applies them locally in a fixed sequence:

  1. Ask for network parameters. The Service Manager requests the instance's networking from the Communication Manager and receives its IP address and subnet, DNS servers, firewall policy, and bandwidth limits.
  2. Bridge and veth. A virtual ethernet pair is created; one end is attached to the AosCore bridge and the other is moved into the instance's own network namespace, where it is given the assigned IP address and route.
  3. Firewall. The instance's allow rules are installed, together with the outbound masquerade for its subnet, so that only the permitted connections are possible and traffic to external networks is translated behind the Node's address.
  4. Bandwidth. Rate shaping is applied to the host-side interface in both directions, capping the instance's ingress and egress throughput.
  5. DNS. The instance's names and address are registered with the resolver for its bridge, which is then reloaded so other instances on the same network can resolve it by name.
  6. Traffic accounting. Byte and packet counters are started for the instance's address, so its traffic can be measured for monitoring and quota enforcement.

Once these steps complete, the instance is connected: traffic flows within the limits set for it, names resolve, and its usage is being counted.

Ordering and Recovery​

The steps run in dependency order, because there is no point installing firewall rules or shaping for an interface that does not exist yet, so the bridge and veth come first. If any step fails, the steps already completed are unwound, leaving no half-built network behind. Because the on-Node state is rebuilt from the parameters supplied by the Communication Manager, the Service Manager can also recover cleanly after a restart: it reconciles what it finds on the Node against what should be running and repairs any difference.

Teardown​

Stopping an instance reverses the sequence. Traffic accounting is stopped, the instance's DNS entries are removed and the resolver reloaded, bandwidth shaping is cleared, the firewall rules for the instance are removed, and finally the virtual ethernet pair and the network namespace are deleted. Removing the virtual ethernet pair also removes its peer inside the namespace, so the instance's networking is fully reclaimed and the next start begins from a clean slate.

Deferred Firewall Updates​

Sometimes an instance is allowed to communicate with another instance that has not been created yet. In that case the firewall policy delivered at start time is necessarily incomplete. The rule for the not-yet-existing peer cannot be finalized. The Communication Manager tracks these pending connections and, once the missing instance is allocated, streams the resolved firewall rules back to the Service Manager. The Service Manager applies just those firewall changes to the affected instance, without rebuilding the rest of its network.

  • Networking — the components, foundations, and firewall tables this lifecycle is built on.
  • Service Lifecycle — the broader instance lifecycle that network setup is part of.
  • Monitoring — how the per-instance traffic counters started here are consumed.