Static network routes

Luna keeps a reusable catalog of static routes. A route is defined once, then coupled to one or more networks, groups or nodes. At provisioning time luna resolves the routes that apply to a node and renders them into that node's network configuration (netplan for Ubuntu, NetworkManager keyfiles for RHEL-family images).

Static routes are available from Luna 2.1u8 (August 13 2026) and higher.

The route catalog

List, show, add, change and remove routes with luna network route:

luna network route list
luna network route show <name>
luna network route add <name> -D <destination> -g <gateway> [-m <metric>] [-dev <device>] [-c <comment>]
luna network route change <name> [-D ...] [-g ...] [-m ...] [-dev ...] [-N <newname>]
luna network route remove <name>

A route has these fields:

Example — a route to a storage network via a next-hop gateway:

luna network route add storage-net -D 10.20.0.0/16 -g 10.141.0.254 -m 100 -c "to storage fabric"

A route needs a gateway, a device, or both. The destination is one network or host in CIDR notation, the gateway is a single address of the same IP family as the destination, and the metric is a whole number. Luna refuses a route that does not meet these rules.

A route that is still coupled cannot be removed: luna network route remove names the networks, groups and nodes that use it. Clear the coupling on those first.

Coupling routes

Couple catalog routes to a network, group or node with -rt / --routes. The value is a comma-separated list of route names; pass "" to clear the coupling at that level. You can stack several routes on one object by listing their names, and reuse the same route on any number of objects — the route body itself is never duplicated.

luna network change <network> -rt storage-net,mgmt-net   # stack two routes on one network
luna group   change <group>   -rt storage-net            # reuse the same route on a group
luna node    change <node>    -rt storage-net,extra-net  # stack a reused and a node-specific route
luna node    change <node>    -rt ""                      # clear this node's own routes

Cloning a group or node copies its route couplings to the clone. Removing a network, group or node removes its couplings; the routes themselves stay in the catalog.

How routes are resolved for a node

Couplings follow a strict override precedence, identical to how interfaces are resolved:

node  overrides  group  overrides  network

The most specific scope that has any coupled routes wins outright; luna does not merge across scopes. So a node with its own routes ignores its group's and network's routes; a node with no routes inherits the group's; a node and group with none inherit the network's.

The network scope is every network that one of the node's interfaces is attached to. When the winning scope holds two routes with the same destination and metric, only one of them is written.

In luna node show / luna group show the resolved routes are shown with their source: a value owned at that scope is marked with routes *, an inherited value shows value (source), and no routes shows None.

Which interface carries a route

Each resolved route is written onto one of the node's interfaces:

1. If the route names a device, that interface. BOOTIF is the provisioning interface, and a device the node does not have also falls back to the provisioning interface.
2. Otherwise, if the route has a gateway, the interface whose network contains the gateway.
3. Otherwise, the provisioning interface.

IPv6 destinations are written as IPv6 routes. When the gateway lies outside the network of the chosen interface, the route is written as an off-link route (see below).

What gets rendered at boot

For each resolved route luna writes a static route into the node's network configuration:

• Ubuntu / netplan — a routes: entry with to:, via: and, when the next-hop is outside the interface's own subnet, on-link: true so the kernel installs the route without requiring the gateway to be directly connected.
• RHEL family / NetworkManager — a route<n>= line in the interface keyfile.

Verifying on a node

After a node has provisioned, confirm the routes are present:

ip route show

Each coupled destination should appear via its configured gateway and metric.

A node without coupled routes provisions exactly as it would without this feature. If Luna cannot resolve a node's routes, it logs the error and provisions the node without them: when a route is missing on a booted node, check the Luna daemon log.