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, either present or absent. 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 key connect_to.
• services - a list of services to enable for the endpoint.

Connection types:

• endpoint - refer to endpoints by their full name
• id - refer to endpoints by their numerical id
• tag - 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