YAML Configurations
YAML Configuration file format
Either YAML file or a JSON file can be used for network configuration. If the YAML file contains multiple documents(or, alternatively, JSON file has a list as the root element) then these documents will be processed sequentially.
Every network configuration must have name
, topology
, and state
keys.
name
parameter describes the network name which can be superseded by id
parameter that is the network's numerical ID.
When creating/updating a network connections
dictionary must be present and it represents the connections between specified endpoints and the format depends on the topology of the network.
Network topologies:
Three network topologies are available, such as:
P2P
- Point To Point: describes connections between pairs of endpoints.P2M
- Point To Multipoint: describes connections from a single endpoint to a collection of many endpoints.MESH
- describes a mesh network connections, where every endpoint is connected to every other endpoint.
Connections
The connections parameter is a dictionary whose keys are the endpoint names, tags, or ids(depending on the type of the endpoint).
Connection parameters:
state
- state of the connection, eitherpresent
orabsent
. Specifies whether to create/keep or delete existing connections respectively.type
- type of the connection name.connect_to
- a dictionary describing connections that the root connection connects to. The structure is the same as described here, except for the keyconnect_to
.services
- a list of services to enable for the endpoint.
Connection types:
endpoint
- refer to endpoints by their full nameid
- refer to endpoints by their numerical idtag
- refer to a collection of endpoints that have the specified tag
Each connection must have connect_to
parameter for P2P
and P2M
topologies.
NOTE: The connections are created using "ADD NEW" strategy and deleted "DELETE EXISTING", therefore if you are trying to update an existing network with new connections, those connections will be created (if state == present
) and existing and explicitly not specified connections will be untouched.
Endpoint services
Each endpoint may have services configured. And we can expose those services from one endpoint to the other endpoint by creating a connection.
If a service specified in the configuration file is not available in the endpoint - it will be ignored.
NOTE: The services will be only enabled if they are specified in the configuration file. All other services that are configured on the endpoint will be disabled.
Example configurations
P2M Example
connections:
za-libracloud-nat12.syntropystack.com:
connect_to:
AGENT_SE:
type: endpoint
Ubuntu-1804-bionic-64-minimal:
type: endpoint
fr-aws-nat15.syntropystack.com:
type: endpoint
nl-altushost-nat01.syntropystack.com:
services:
- nginx
type: endpoint
us-khanwebhost-nat04.syntropystack.com:
services:
- iperf
type: endpoint
type: endpoint
name: "Point To Multipoint"
state: present
topology: P2M
This configuration will yield this network:
However, in this particular example, two connections are in an error state. This is because there is a service subnet overlap for those particular connections.
Multiple networks in one YAML
The following configuration file will create three networks and delete one by processing each document inside the YAML configuration file one-by-one.
---
# Create point-to-point connections
name: interconnect
# Network topology is mandatory. Values: P2P, P2M, MESH
topology: p2p
# Network state is mandatory. Values: present, absent
state: present
# Connections to create
connections:
# Endpoint can be referred to by name and by id
endpoint-1:
# state is present by default
state: present
# type is endpoint by default. Values: endpoint, tag, id
type: endpoint
# services specify what services to enable for a given endpoint
services:
- nginx
# id has precedence before name when type is endpoint
id: 123
connect_to:
endpoint-2:
type: endpoint
services:
- postgres
# In certain situations endpoints must be specified by id instead of name
3:
connect_to:
endpoint-4:
type: endpoint
state: present
type: id
endpoint-5:
connect_to:
6:
type: id
state: absent
type: endpoint
---
# Connect mqtt server with iot devices
name: iot-network
state: present
topology: p2m
connections:
mqtt-server-name.com:
type: endpoint
connect_to:
# Will connect mqtt server with all the endpoints tagged as "iot-devices"
iot-devices:
state: present
type: tag
---
# Create DNS servers mesh network
name: dns-mesh
state: present
topology: mesh
connections:
# Will create a mesh network using endpoints tagged as "dns-servers"
dns-servers:
state: present
type: tag
---
# Delete a network
name: old-iot-network
topology: mesh
state: absent
Updated about a month ago