YAML Configurations
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 topology
and state
keys.
topology
parameter tells the NAC tool how to interpret theconnections
part of the YAML filestate
parameter tells whether the connections should be created or removed
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
description: "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 by processing each document inside the YAML configuration file one by one.
---
# Create point-to-point connections
# 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
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
state: present
topology: mesh
connections:
# Will create a mesh network using endpoints tagged as "dns-servers"
dns-servers:
state: present
type: tag
Updated over 1 year ago