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
| Name | netplan |
| Description | The netplan files osapi writes, validated and applied |
| Placement | node |
| Internal | yes |
| API | no |
| CLI | no |
| Next | no |
| Platforms | debian |
| Sudo | netplan |
| Runs | netplan |
| Writes | /etc/netplan/osapi-*.yaml |
| Keeps state | no |
| Uses | managedfile |
| Used by | dns, interface, route |
Methods (3)
| NAME | VERB | ROUTE | PERMISSION | DESCRIPTION |
|---|---|---|---|---|
| update | write | - | - | Write a netplan file, validate it and apply it |
| delete | write | - | - | Remove a netplan file and apply what is left |
| get | read | - | - | Get what netplan status reports for an interface |
Types (3)
| NAME | INPUT | OUTPUT |
|---|---|---|
| update | UpdateInput { path*, content*, metadata } | Result { path, changed } |
| delete | DeleteInput { path* } | Result { path, changed } |
| get | GetInput { name* } | Interface { name, type, section, id, matches } |
Settings (0)
None. Declare them with behavior.Config.
Telemetry
| Span | behavior.netplan.<method> |
| Child spans | behavior.managedfile.<method>, exec netplan, exec chown, exec stat, file.write, file.remove, file.chmod, kv.get, kv.put |
| Metrics | osapi_behavior_calls_total, osapi_behavior_duration_seconds, osapi_behavior_changes_total |
| Attributes | osapi.behavior.name, osapi.behavior.method, osapi.behavior.verb, osapi.behavior.outcome, osapi.behavior.changed |
| Recorded inputs | path (update, delete), name (get) |
Method update
| Name | update |
| Verb | write |
| Description | Write a netplan file, validate it and apply it |
| Detail | Writes 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. |
| Route | other behaviors only; it is not served |
| Input type | UpdateInput |
| Output type | Result |
Input (3)
| FIELD | TYPE | REQUIRED | CONSTRAINTS | DESCRIPTION |
|---|---|---|---|---|
| path | string | yes | pattern ^/etc/netplan/osapi- | The file, under /etc/netplan, named osapi-<something>.yaml |
| content | string | yes | The file's whole YAML | |
| metadata | object | no | What the caller keeps in the file's record |
Output (2)
| FIELD | TYPE | DESCRIPTION |
|---|---|---|
| path | string | The file |
| changed | boolean | Whether the host changed |
Examples (1)
| EXAMPLE | INPUT | OUTPUT |
|---|---|---|
| A new file | path=/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
| Name | delete |
| Verb | write |
| Description | Remove a netplan file and apply what is left |
| Route | other behaviors only; it is not served |
| Input type | DeleteInput |
| Output type | Result |
Input (1)
| FIELD | TYPE | REQUIRED | CONSTRAINTS | DESCRIPTION |
|---|---|---|---|---|
| path | string | yes | pattern ^/etc/netplan/osapi- | The file, under /etc/netplan, named osapi-<something>.yaml |
Output (2)
| FIELD | TYPE | DESCRIPTION |
|---|---|---|
| path | string | The file |
| changed | boolean | Whether the host changed |
Examples (2)
| EXAMPLE | INPUT | OUTPUT |
|---|---|---|
| A file osapi wrote | path=/etc/netplan/osapi-dns.yaml | path=/etc/netplan/osapi-dns.yaml, changed=true |
| A file that is not there | path=/etc/netplan/osapi-dns.yaml | path=/etc/netplan/osapi-dns.yaml, changed=false |
Method get
| Name | get |
| Verb | read |
| Description | Get what netplan status reports for an interface |
| Detail | Reads 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. |
| Route | other behaviors only; it is not served |
| Input type | GetInput |
| Output type | Interface |
Input (1)
| FIELD | TYPE | REQUIRED | CONSTRAINTS | DESCRIPTION |
|---|---|---|---|---|
| name | string | yes | min length 1 | The interface, such as eth0 |
Output (5)
| FIELD | TYPE | DESCRIPTION |
|---|---|---|
| name | string | The interface |
| type | string | Its type, such as ethernet, bond or wifi; empty when netplan does not report it |
| section | string | The netplan section that configures it, such as ethernets or bonds |
| id | string | The 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 |
| matches | array | Each interface that the definition matches, this one too, in name order |
Examples (5)
| EXAMPLE | INPUT | OUTPUT |
|---|---|---|
| A bond | name=bond0 | name=bond0, type=bond, section=bonds, id=bond0, matches=[bond0] |
| An interface a match defines, as cloud-init's all for en* | name=enp0s1 | name=enp0s1, type=ethernet, section=ethernets, id=all, matches=[enp0s1 enp0s2] |
| An interface netplan does not define | name=lo | name=lo, type=ethernet, section=ethernets, id=lo, matches=[lo] |
| A netplan without status | name=eth0 | name=eth0, type=, section=ethernets, id=eth0, matches=[eth0] |
| An interface netplan does not manage | name=eth9 | name=eth9, type=, section=ethernets, id=eth9, matches=[eth9] |