route

Manages one entry in the kernel routing table at runtime via iproute2, keyed on (destination, table) (plus metric when set). Optionally renders the route to networkd or netplan so it survives a reboot. Idempotent: re-applying an unchanged declaration reports no change.

Category: Network (base)

States

State	Meaning
`present`	The route exists with the declared gateway and/or interface (added or `ip route replace`d to converge).
`absent`	No route for the declared destination/metric/table; an existing one is removed.

Parameters

Parameter	Type	Required	Description
`destination`	string	yes	Target as CIDR or a bare host IP (a host IP becomes a /32 or /128). Use `0.0.0.0/0` or `::/0` for the default route.
`gateway`	string		Next-hop IP. For state `present`, at least one of `gateway` / `interface` is required.
`interface`	string		Output interface (`dev`). For state `present`, at least one of `gateway` / `interface` is required; `persist` additionally requires it.
`metric`	int		Route metric. When set, it is part of the route’s identity (multiple routes to one destination at different metrics).
`table`	string		Routing table by `rt_tables` name (main/local/default/custom) or numeric value 1-254. Default: `main`.
`persist`	string		Boot-survive backend: `networkd`, `netplan`, or `auto`. Omit for runtime-only. Requires `interface`.

Examples

Default route via a gateway

route:
  default-route:
    state: present
    destination: 0.0.0.0/0
    gateway: 192.168.1.1

Static network route, persisted across reboots

persist renders the route to networkd so it survives a reboot; it requires interface.

route:
  vpn-net:
    state: present
    destination: 10.0.0.0/24
    gateway: 192.168.1.254
    interface: eth0
    metric: 100
    table: vpn
    persist: networkd

Remove a stale route

route:
  drop-old:
    state: absent
    destination: 10.0.0.0/24

Notes

Linux-only; manages routes via the iproute2 ip tool. present uses ip route replace (idempotent against an existing entry at the same dest/metric/table).
Without persist, the route is in the kernel immediately but does not survive a reboot.
persist supports networkd and netplan (or auto) and requires interface. networkd merges drop-ins; netplan replaces a route list across files, so use networkd for multiple routes on one interface.
Out of scope (v0.x candidates): additional persist backends (NetworkManager, sysconfig route-*, /etc/network/interfaces), richer route attributes (proto/scope/src/mtu/onlink/nexthop multipath), and source-routing policy rules.

network vlan