network

Manages one network interface’s runtime configuration — IP addresses, MTU, and admin up/down — via the iproute2 ip tool, optionally rendering a boot-survive file (systemd-networkd or netplan) so the config persists across reboot. Idempotent: re-applying an unchanged declaration reports no change.

Category: Network (base)

States

State	Meaning
`present`	The interface carries the declared addresses, MTU, and admin state; when `persist` is set, a matching boot-survive file is written. The module does not create or remove interfaces.

Parameters

Parameter	Type	Required	Description
`interface`	string	yes	Interface name to reconcile (≤15 chars; letters/digits/`._-`). The interface must already exist.
`addresses`	list		Full set of CIDR addresses for the interface; extras are removed (kernel link-local addresses are never stripped). An empty list means “no addresses”.
`mtu`	int		Link MTU, in the range 68–65535.
`up`	bool		Link admin state (`ip link set up\|down`). Runtime-only; not rendered to the persistent file.
`persist`	string		Boot-survive renderer: `networkd`, `netplan`, or `auto` (netplan if `/etc/netplan` exists, else networkd). Requires `addresses` or `mtu`. Omit for runtime-only config.

Examples

Set addresses and MTU on an interface

network:
  configure-eth0:
    state: present
    interface: eth0
    addresses:
      - 192.168.1.10/24
      - 10.0.0.1/24
    mtu: 1500

Persist config across reboot

persist: auto also writes a networkd or netplan file for the next boot.

network:
  configure-eth1:
    state: present
    interface: eth1
    addresses:
      - 10.20.0.5/24
    mtu: 9000
    persist: auto

Bring a link up

network:
  bring-up-eth2:
    state: present
    interface: eth2
    up: true

Notes

At least one of addresses / mtu / up must be set — a bare interface: declaration is a no-op and is rejected.
persist renderers are limited to systemd-networkd and netplan; NetworkManager, Debian /etc/network/interfaces, and RHEL ifcfg-* are planned for v0.6+ (#25).
persist writes the file for the next boot only — the runtime is already live via ip, so nothing is auto-activated (no netplan apply / networkctl reload).
up is runtime-only and is not rendered to the persistent file (networkd brings a matched link up by default).
Kernel-auto-assigned link-local addresses (IPv6 fe80::/10, IPv4 169.254.0.0/16) are never removed by address reconciliation.
The module does not create or remove interfaces (use bond / bridge / vlan for virtual interfaces). Linux-only; other operating systems get a no-op provider.
Out of scope (v0.x candidates): per-family address sets, address scope/lifetime attributes, and DNS / NTP / search-domain management.

bridge route