@shumoku/core · input model

YAML reference

Fields of the network YAML, generated from the input model's types.

Document

The whole YAML document: one network.

Field	Type	Description	Required
`name`	`string`	The network's name.	no
`description`	`string`	What the network is, in words.	no
`groups`	`Group[]`	Its places, written nested: sites, buildings, rooms, racks.	no
`routingDomains`	`RoutingDomain[]`	Its separate routing domains, such as VPCs and VRFs.	no
`connections`	`Connection[]`	Logical connections made of several links.	no
`segments`	`Segment[]`	Its shared networks, such as VLANs and subnets.	no
`redundancy`	`Redundancy[]`	Its redundancy sets, such as VRRP pairs and HA clusters.	no
`nodes`	`Node[]`	Its devices, virtual machines and services.	yes
`links`	`Link[]`	Its links, each between two nodes or between a node and a segment or routing domain.	yes

Node

A device, a virtual machine or a service: one thing links end at.

Field	Type	Description	Required
`id`	`node id`	Unique among nodes; links, segments and redundancy sets name the node by it.	yes
`label`	`string`	The node's name, left out when it is not known; the id is then only a handle.	no
`type`	`string`	What kind of node it is, such as router, l3-switch, firewall, server, virtual-machine or access-point.	no
`product`	`Product`	What it is, from its maker down to its model, as far as is known.	no
`software`	`string`	The software it runs, such as its operating system or hypervisor.	no
`address`	`string`	An address whose segment is not known; once it is, the address goes in the segment.	no
`asn`	`number`	The autonomous system it is in, such as a router's local AS.	no
`description`	`string`	Anything else worth knowing about it, in words.	no
`group`	`group id`	The place it is in.	no
`assumed`	`true`	Its existence is not confirmed. Details that are not known are left out instead.	no
`host`	`node id \| redundancy id`	What it runs on: a node, or a redundancy set when which of its nodes is not known. This is a hosting relationship, not a network link; communication is written in links. A host alone does not identify a VM: services and other workloads can also be hosted.	no
`members`	`string[]`	The devices it stands for when their links are not told apart, such as stack units.	no

Link

Undirected: the two ends have no order. Two nodes may have several links, such as parallel cables or the two tunnels of one VPN.

Field	Type	Description	Required
`id`	`link id`	Written only when something refers to the link, such as its layout or its cable run.	no
`endpoints`	`[Endpoint, Endpoint]`	Its two ends, in either order.	yes
`speed`	`Rate`	The rate the link runs at.	no
`bandwidth`	`Rate`	A lower rate than the link runs at, that traffic over it is held to.	no
`cable`	`string`	The cable's type, such as cat6, mmf-om4, smf or dac.	no
`length`	`Length`	The cable's length.	no
`segments`	`segment id[]`	The segments the link carries. Both ends are in each of them.	no
`description`	`string`	Anything else worth knowing about it, in words.	no
`connection`	`connection id`	The connection this link is one part of.	no
`assumed`	`true`	Its existence is not confirmed. Unknown ports or segments are left out instead.	no
`virtual`	`true`	It has no cable of its own, such as a VPN tunnel, a VM's adapter in a port group, or a BGP session across a shared LAN. A link whose way is not known is neither virtual nor cabled.	no

Link end: node

One end of a link: a node (and its port when known), a segment the node is in, or a routing domain the node is attached to as a whole.

Field	Type	Description	Required
`node`	`node id`	The node the link ends at.	yes
`port`	`string`	The port's name as the device calls it, such as `ge-0/0/1`; left out when not known.	no

Link end: segment

A link end at a segment: the node at the other end is joined to the segment as a whole.

Field	Type	Description	Required
`segment`	`segment id`	The segment the node is joined to.	yes

Link end: routing domain

A link end at a routing domain: the node at the other end is attached to it as a whole.

Field	Type	Description	Required
`routingDomain`	`routing domain id`	The routing domain the node is attached to.	yes

Group

A place: site, building, room. A group written inside another is a place within it.

Field	Type	Description	Required
`id`	`group id`	Unique among groups; nodes and segments name their group by it.	yes
`label`	`string`	The place's name, such as `Tokyo DC` or `Rack A1`.	no
`groups`	`Group[]`	The places within it.	no

Segment

A shared network that any number of links can carry, such as a VLAN, a handoff segment or a cloud subnet. A node is in a segment when it has an address there, when a link carrying the segment ends at it, or when a link joins it to the segment itself.

Field	Type	Description	Required
`id`	`segment id`	Unique among segments; links name the segments they carry by it.	yes
`label`	`string`	Its name, such as `mgmt` or `users-a`.	no
`vlan`	`number`	Its VLAN ID, 1 to 4094.	no
`prefix`	`OneOrMore<string>`	Its subnets, such as `10.0.10.0/24`, or one for each address family.	no
`routingDomain`	`routing domain id`	The routing domain it belongs to, when it is a separate one such as a VPC or a VRF.	no
`group`	`group id`	The place the segment is confined to, such as an availability zone.	no
`addresses`	`Readonly<Record<node id \| redundancy id, OneOrMore<string>>>`	The addresses nodes have in the segment, by node. An address belongs to a node's presence in the segment rather than to a port. A redundancy set's shared address is written under the set.	no

Routing domain

A separate routing domain that segments belong to, such as a VPC, a cloud virtual network or a VRF. Written only when such a domain is known; a network with a single routing table has none, and a subnet, a place or an autonomous system is not one (see a node's asn).

Field	Type	Description	Required
`id`	`routing domain id`	Unique among routing domains; segments name theirs by it.	yes
`label`	`string`	Its name, such as the VPC's or the VRF's.	no
`prefix`	`OneOrMore<string>`	The address ranges it holds, such as a VPC's CIDR blocks.	no

Connection

One logical connection made of several links, such as a VPN made of two tunnels.

Field	Type	Description	Required
`id`	`connection id`	Unique among connections; each of its links names it by this.	yes
`label`	`string`	Its name, such as the VPN's.	no

Redundancy set

Separate nodes that stand in for one another, such as a VRRP pair or an HA cluster.

Field	Type	Description	Required
`id`	`redundancy id`	Unique among redundancy sets; a node's host or a segment address can name the set by it.	yes
`label`	`string`	Its name, such as the cluster's.	no
`nodes`	`node id[]`	Two or more.	yes
`kind`	`string`	How they stand in for one another, such as ha (VRRP, HSRP), vc (a virtual chassis), vss, vpc, mlag or stack.	no
`assumed`	`true`	The pairing is believed but not confirmed.	no

Value types

Shapes that fields above refer to by name.

Field	Type	Description	Required
`Rate`	`${number}${'M' \| 'G' \| 'T'}`	A rate: a number and its unit, such as 100M, 2.5G or 50M.	no
`Length`	`${number}${'mm' \| 'cm' \| 'm' \| 'km' \| 'in' \| 'ft'}`	A cable's length with its unit, such as 3m.	no
`Product`	`string`	A product path from its maker down to as specific as is known, such as `juniper`, `juniper/ex4400` or `juniper/ex4400/ex4400-48p`. An unknown maker is `?`, as in `?/ex4400-48p`.	no
`OneOrMore`	`T \| [T, ...T[]]`	One value is written bare and several as a list, which is never empty.	no

Executable example

name: Branch network
nodes:
  - id: router
    label: Router
    type: router
  - id: switch
    label: Access switch
    type: l2-switch
links:
  - endpoints: [{node: router}, {node: switch}]

examples/getting-started.yaml