Skip to main content

Netplan

The netplan files osapi writes, validated and applied. osapi behavior get --name netplan and osapi behavior method get show the same. Its chain shows each call that its examples make.

Behavior​

Namenetplan
DescriptionThe netplan files osapi writes, validated and applied
Placementnode
Internalyes
APIno
CLIno
Nextno
Platformsdebian
Sudonetplan
Runsnetplan
Writes/etc/netplan/osapi-*.yaml
Keeps stateno
Usesmanagedfile
Used bydns, interface, route

Methods (3)​

NAMEVERBROUTEPERMISSIONDESCRIPTION
updatewrite--Write a netplan file, validate it and apply it
deletewrite--Remove a netplan file and apply what is left
getread--Get what netplan status reports for an interface

Types (3)​

NAMEINPUTOUTPUT
updateUpdateInput { path*, content*, metadata }Result { path, changed }
deleteDeleteInput { path* }Result { path, changed }
getGetInput { name* }Interface { name, type, section, id, matches }

Settings (0)​

None. Declare them with behavior.Config.

Telemetry​

Spanbehavior.netplan.<method>
Child spansbehavior.managedfile.<method>, exec netplan, exec chown, exec stat, file.write, file.remove, file.chmod, kv.get, kv.put
Metricsosapi_behavior_calls_total, osapi_behavior_duration_seconds, osapi_behavior_changes_total
Attributesosapi.behavior.name, osapi.behavior.method, osapi.behavior.verb, osapi.behavior.outcome, osapi.behavior.changed
Recorded inputspath (update, delete), name (get)

Method update​

Nameupdate
Verbwrite
DescriptionWrite a netplan file, validate it and apply it
DetailWrites the file with mode 0600, validates the whole config with netplan generate, and applies it with netplan apply. When netplan generate refuses it, the file gets back the content it had, or a new file is removed, because netplan reads every file in the directory. A file that already holds the content changes nothing.
Routeother behaviors only; it is not served
Input typeUpdateInput
Output typeResult

Input (3)​

FIELDTYPEREQUIREDCONSTRAINTSDESCRIPTION
pathstringyespattern ^/etc/netplan/osapi-The file, under /etc/netplan, named osapi-<something>.yaml
contentstringyesThe file's whole YAML
metadataobjectnoWhat the caller keeps in the file's record

Output (2)​

FIELDTYPEDESCRIPTION
pathstringThe file
changedbooleanWhether the host changed

Examples (1)​

EXAMPLEINPUTOUTPUT
A new filepath=/etc/netplan/osapi-dns.yaml, content=network: version: 2 ethernets: eth0: nameservers: addresses: [1.1.1.1]path=/etc/netplan/osapi-dns.yaml, changed=true

Method delete​

Namedelete
Verbwrite
DescriptionRemove a netplan file and apply what is left
Routeother behaviors only; it is not served
Input typeDeleteInput
Output typeResult

Input (1)​

FIELDTYPEREQUIREDCONSTRAINTSDESCRIPTION
pathstringyespattern ^/etc/netplan/osapi-The file, under /etc/netplan, named osapi-<something>.yaml

Output (2)​

FIELDTYPEDESCRIPTION
pathstringThe file
changedbooleanWhether the host changed

Examples (2)​

EXAMPLEINPUTOUTPUT
A file osapi wrotepath=/etc/netplan/osapi-dns.yamlpath=/etc/netplan/osapi-dns.yaml, changed=true
A file that is not therepath=/etc/netplan/osapi-dns.yamlpath=/etc/netplan/osapi-dns.yaml, changed=false

Method get​

Nameget
Verbread
DescriptionGet what netplan status reports for an interface
DetailReads netplan status: the interface's type, its section and the ID of the definition that matches it, which a write goes under, and each interface that definition matches. netplan lists only the interfaces it manages, so an interface that it does not list is an ethernet under its own name.
Routeother behaviors only; it is not served
Input typeGetInput
Output typeInterface

Input (1)​

FIELDTYPEREQUIREDCONSTRAINTSDESCRIPTION
namestringyesmin length 1The interface, such as eth0

Output (5)​

FIELDTYPEDESCRIPTION
namestringThe interface
typestringIts type, such as ethernet, bond or wifi; empty when netplan does not report it
sectionstringThe netplan section that configures it, such as ethernets or bonds
idstringThe netplan ID of the definition that matches it, such as all for a match on en*; the interface's name when netplan does not define it
matchesarrayEach interface that the definition matches, this one too, in name order

Examples (5)​

EXAMPLEINPUTOUTPUT
A bondname=bond0name=bond0, type=bond, section=bonds, id=bond0, matches=[bond0]
An interface a match defines, as cloud-init's all for en*name=enp0s1name=enp0s1, type=ethernet, section=ethernets, id=all, matches=[enp0s1 enp0s2]
An interface netplan does not definename=loname=lo, type=ethernet, section=ethernets, id=lo, matches=[lo]
A netplan without statusname=eth0name=eth0, type=, section=ethernets, id=eth0, matches=[eth0]
An interface netplan does not managename=eth9name=eth9, type=, section=ethernets, id=eth9, matches=[eth9]