Skip to content
Documentation
State Modules
vlan

vlan

Manages a Linux 802.1Q VLAN interface — creates or removes a tagged interface on a parent link at runtime via ip link, optionally persisting it to the host network config. Idempotent: re-applying an unchanged declaration reports no change.

Category: Network (base)

States

StateMeaning
presentThe VLAN interface exists on parent with the declared id; when persist is set the matching network config is also written.
absentThe VLAN interface (matched by name) does not exist; any persisted config for it is removed.

Parameters

ParameterTypeRequiredDescription
namestringyesVLAN interface name, e.g. eth0.10 (max 15 chars; letters, digits, ._- only).
parentstringUnderlying interface the VLAN tags ride on, e.g. eth0. Required for state present; rejected for absent.
idintVLAN ID, 1–4094 (802.1Q reserves 0 and 4095). Required for state present; rejected for absent.
persiststringBoot-survive backend: networkd, netplan, or auto. Omit for runtime-only (the VLAN is in the kernel now but does not survive a reboot).

Examples

Runtime-only tagged interface 

vlan:
  eth0.10:
    state: present
    parent: eth0
    id: 10

Persist across reboots via networkd

Renders a .netdev plus an enslave drop-in under the parent’s .network.d/.

vlan:
  eth0.20:
    state: present
    parent: eth0
    id: 20
    persist: networkd

Remove a VLAN and its persisted config

absent deletes by name only — parent/id must not be set.

vlan:
  eth0.10:
    state: absent
    persist: networkd

Notes

  • Linux-only — created at runtime via ip link; non-Linux hosts get a reduced no-op provider.
  • No in-place reconciliation: an existing VLAN of the same name is treated as converged regardless of its live id/parent. To change a live VLAN, delete it first then declare it again (planned, #29).
  • Out of scope: QinQ / 802.1ad, VLAN ranges, QoS maps, and persist backends beyond networkd/netplan/auto.
  • DriftSeverity is HIGH — a missing tagged interface is a downed L2 segment.
routefirewall