Custom Topology

The information on this page reflects the workflows for the new Air UI. The legacy UI is being deprecated. View documentation for the legacy UI

The Drag-and-Drop Topology Builder

One way to create fully custom simulations is with the built-in topology builder, which provides a drag-and-drop editor to design any custom network. To get started, navigate to https://air.nvidia.com/simulations.

Select Create Simulation.
Provide a name for your simulation.
Select Blank Canvas as the type.
(Optional) Assign the simulation to an Organization.
(Optional) Add a ZTP script to the simulation.
1. Toggle on the Apply ZTP Template button.
2. Enter your ZTP script. A default script is prefilled to help get you started.
Click Create.

ZTP Scripts

When you create a new simulation, Air gives you the option to add a zero-touch provisioning (ZTP) script. The ZTP script is copied to the simulation’s oob-mgmt-server. Any node making a ZTP request on the out-of-band management network has access to this ZTP script through a DHCP server and web server running on the oob-mgmt-server.

A default script is prefilled to help you get started. It implements some common ZTP features on Cumulus Linux, such as changing the default password or downloading SSH keys. You can edit the default script directly in the UI.

▼ Default ZTP script

#!/bin/bash
# Created by Topology-Converter v4.7.1
#    Template Revision: v4.7.1

function error() {
  echo -e "e[0;33mERROR: The Zero Touch Provisioning script failed while running the command $BASH_COMMAND at line $BASH_LINENO.e[0m" >&2
}
trap error ERR

SSH_URL="http://192.168.200.1/authorized_keys"
# Uncomment to setup SSH key authentication for Ansible
# mkdir -p /home/cumulus/.ssh
# wget -q -O /home/cumulus/.ssh/authorized_keys $SSH_URL

# Uncomment to unexpire and change the default cumulus user password
# passwd -x 99999 cumulus
# echo 'cumulus:Cumu1usLinux!' | chpasswd

# Uncomment to make user cumulus passwordless sudo
# echo "cumulus ALL=(ALL) NOPASSWD:ALL" > /etc/sudoers.d/10_cumulus

# Uncomment to enable all debian sources & netq apps3 repo
# sed -i 's/#deb/deb/g' /etc/apt/sources.list
# wget -q -O pubkey https://apps3.cumulusnetworks.com/setup/cumulus-apps-deb.pubkey
# apt-key add pubkey
# rm pubkey

# Uncomment to allow NTP to make large steps at service restart
# echo "tinker panic 0" >> /etc/ntp.conf
# systemctl enable ntp@mgmt

exit 0
#CUMULUS-AUTOPROVISIONING

Manage Nodes

You can drag servers and switches from the System Palette to the workspace. Air provides access to hardware models based on available NVIDIA Spectrum switches. The model does not affect the simulation, but allows Air to pre-populate the number of ports based on the switch model. You do not need to use each port.

Select a node to view or edit its properties.

Name: Node hostname.
Operating System: Name of the OS installed on the node. The OS is installed automatically.
CPUs: Number of CPUs. The default is 1 or 2 GB depending on the Spectrum switch.
Memory (GB): Amount of RAM (default is 2 GB).
Storage (GB): Amount of hard disk space (default is 10 GB).
Connectors: Choose an available port to connect directly to any port on another node.

Make sure to select Update Node when you complete the changes. You can delete nodes by selecting Delete Node.

Air also provides Advanced Options, such as enabling UEFI Secure Boot.

When you finish creating your topology, click Workspace > Start Simulation. You cannot add, remove, or edit nodes after the simulation starts for the first time.

OOB Management Network

On the System Palette, there is an option to Enable OOB. This setting enables the out-of-band management network that connects all nodes with each other. It also adds an oob-mgmt-switch and oob-mgmt-server to your simulation. When you enable SSH, you SSH into the oob-mgmt-server, making this node an ideal starting point for configurations. Air handles the configuration automatically for you.

You can add more oob-mgmt-switches and oob-mgmt-servers to your simulation manually even when Enable OOB is set to off. However, you must switch Enable OOB to use the OOB network.

Custom Topologies with DOT Files

You can create custom topologies in Air using a DOT file, which is the file type used with the open-source graph visualization software, Graphviz. DOT files are simple, customizable text-based files.

You can upload DOT files directly to Air to generate a topology, allowing you to share and create copies of a topology, and save the topology in a reusable file. You can modify the file with a text editor.

DOT Syntax

DOT files use the .dot file extension. They define nodes, attributes, and connections for generating a topology for a network.

The following is an example of a simple topology DOT file with 1 spine, 2 leaf nodes, and 2 servers connected to each leaf.

graph "Demo" {
  "spine01" [ function="spine" memory="4096" os="sonic-vs-202305" cpu="2" ]
  "leaf01" [ function="leaf" memory="4096" os="sonic-vs-202305" cpu="2" nic_model="e1000"]
  "leaf02" [ function="leaf" memory="4096" os="sonic-vs-202305" cpu="2" secureboot="true"]
  "server01" [ function="server" memory="2048" os="generic/ubuntu2404" cpu="2"]
  "server02" [ function="server" memory="2048" os="generic/ubuntu2204" cpu="3" storage="20"]
    "leaf01":"eth1" -- "server01":"eth1"
    "leaf02":"eth1" -- "server02":"eth1"
    "leaf01":"eth2" -- "spine01":"eth1"
    "spine01":"eth2" -- "leaf02":"eth2"
}

The following sections provide examples for common DOT file customizations.

Operating System

You can set the operating syatem of the node with the os option:

"server" [os="cumulus-vx-5.10.1"]

Disk Space

By default, nodes in Air have 10 GB of hard disk space. You can increase the space (in GB) by using the storage option:

"server" [os="generic/ubuntu2404" storage="20"]

If the node does not recognize the increased storage, run the following commands from the node to extend the partition and resize the file system:

sudo growpart /dev/vda 1
sudo resize2fs /dev/vda1

Verify the change:

df -h | grep vda1
/dev/vda1        20G  2.1G   18G  11% /

CPU

You can customize the number of allocated CPUs with the cpu option:

"server" [os="generic/ubuntu2404" cpu="4"]

Create Connections

You can create port connections by defining the node and its port with another node and port.

"leaf01":"swp49" -- "leaf02":"swp49"
"leaf01":"swp50" -- "leaf02":"swp50"

Memory

You can customize RAM (in MB) with the memory option:

"server" [os="generic/ubuntu2404"  memory="2048"]

Examples

Labs in the Demo Marketplace are maintained with external GitLab repositories. Here you can find the topology.dot file used to build the lab and use it as a reference. To access the files, select Documentation on any lab in the Demo Marketplace. It will direct you to the demo’s GitLab repository for the lab, where you can download the .dot file used for the demo topology.

Upload a DOT File

To upload a DOT file to Air, navigate to air.nvidia.com/simulations.

Select Create Simulation.
Provide a name for the simulation.
Select DOT as the type.
Upload the file to the UI.
(Optional) Assign the simulation to an organization.
(Optional) Add a ZTP scripts.
1. Select Apply ZTP Template.
2. Enter your ZTP script. A default script is prefilled to help you get started.
(Optional) Click Advanced and provide an out-of-band management server configuration script that executes on the oob-mgmt-server when the simulation starts.
Click Create.

Air builds a custom topology based on the DOT file.

Import a Topology with the API

You can import JSON formatted topologies through the API.

Example 1

The following topology defines two nodes (node-1 and node-2) connected to each other through eth1 interfaces. The out-of-band management network is enabled by default.

{
    "nodes": {
        "node-1": {
            "os": "generic/ubuntu2204"
        },
        "node-2": {
            "os": "generic/ubuntu2204"
        }
    },
    "links": [
        [{"node": "node-1", "interface": "eth1"}, {"node": "node-2", "interface": "eth1"}]
    ]
}

Example 2

The following topology defines two nodes (node-1 and node-2) connected to each other through eth1 interfaces. The out-of-band management network is disabled ("oob": false). The example includes:

Custom values for configurable node fields (cpu, memory, storage)
A public-facing interface (with a custom mac address) to the outside world (eth2 of node-1)
A reference to the os image by specific UUID (node-2)

{
    "oob": false,
    "nodes": {
        "node-1": {
            "os": "generic/ubuntu2204",
            "cpu": 2,
            "memory": 2048
        },
        "node-2": {
            "os": "defb3ffc-e29b-4d3a-a5fb-41ed1974f938",
            "memory": 2048,
            "storage": 25
        }
    },
    "links": [
        [{"node": "node-1", "interface": "eth1"}, {"node": "node-2", "interface": "eth1"}],
        [{"node": "node-1", "interface": "eth2", "mac": "02:00:00:00:00:07"}, "exit"]
    ]
}

For additional schemas, refer to the API documentation.

▼ Import Instructions

To import a topology, use the following APIv2 SDK method:

from air_sdk.v2 import AirApi

air = AirApi(
    authenticate=True,
    username='<username>',
    password='<password-or-token>',
)
simulation = air.simulations.create_from(
    title='<simulation-name>',
    format='JSON',
    content=<topology-content>,
    organization=<optional-organization>
)

This feature requires SDK version air-sdk>=2.14.0 or later.

You can also use the following methods to provide topology content:

Python Dictionary

simulation = air.simulations.create_from(
    'my-simulation',
    'JSON',
    {
        'nodes': {
            'node-1': {
                'os': 'generic/ubuntu2204',
            },
            'node-2': {
                'os': 'generic/ubuntu2204',
            },
        },
        'links': [
            [{'node': 'node-1', 'interface': 'eth1'}, {'node': 'node-2', 'interface': 'eth1'}]
        ]
    },
)

JSON String

simulation = air.simulations.create_from(
    'my-simulation',
    'JSON',
    '{"nodes": {"node-1": {"os": "generic/ubuntu2204"}, "node-2": {"os": "generic/ubuntu2204"}}, "links": [[{"node": "node-1", "interface": "eth1"}, {"node": "node-2", "interface": "eth1"}]]}'
)

File Path

import pathlib
simulation = air.simulations.create_from(
    'my-simulation',
    'JSON',
    pathlib.Path('/path/to/topology.json')
)

File Descriptor

import pathlib
with pathlib.Path('/path/to/topology.json').open('r') as topology_file:
    simulation = air.simulations.create_from(
        'my-simulation',
        'JSON',
        topology_file
    )

Export a Topology through the API

You can export existing simulations into a JSON representation using the API. Refer to the API documentation for additional schema details.

▼ Export Instructions

Use the API v2 SDK to export a simulation:

from air_sdk.v2 import AirApi

air = AirApi(
    authenticate=True,
    username='<username>',
    password='<password-or-token>',
)
topology = air.simulations.export(
    simulation='<simulation-instance-or-id>',
    format='JSON',
    image_ids=True,  # defaults to False
)

This feature requires SDK version air-sdk>=2.15.0 or later.

Create a Custom Topology from the Production Network

This section describes how to create a simulation based on an existing production deployment.

NVIDIA has validated these scripts in a Linux environment only.

Gather cl-support from the Production Network

Use these Ansible playbooks to gather the cl-support script output. The ReadMe for the repository provides additional instructions.

Create topology.dot from the Production Network

After you obtain the cl-support output, you can create a topology.dot file using this parser script. You can run the script using python3. Here is sample output:

$ python3 cl_support_lldp_parser.py
Extracting: /home/cumulus/cl_support_lldp_parser/cl_support_leaf01_20210721_164553.txz
Extracting: /home/cumulus/cl_support_lldp_parser/cl_support_spine02_20210721_164553.txz
Extracting: /home/cumulus/cl_support_lldp_parser/cl_support_leaf02_20210721_164553.txz
Extracting: /home/cumulus/cl_support_lldp_parser/cl_support_spine01_20210721_084129.txz
folder is: /home/cumulus/cl_support_lldp_parser/cl_support_leaf01_20210721_164553
leaf01
    leaf01:eth0 -- oob-mgmt-switch:swp2
    leaf01:swp31 -- spine01:swp1
    leaf01:swp32 -- spine02:swp1
folder is: /home/cumulus/cl_support_lldp_parser/cl_support_spine02_20210721_164553
spine02
    spine02:eth0 -- oob-mgmt-switch:swp6
    spine02:swp1 -- leaf01:swp32
    spine02:swp2 -- leaf02:swp32
folder is: /home/cumulus/cl_support_lldp_parser/cl_support_leaf02_20210721_164553
leaf02
    leaf02:eth0 -- oob-mgmt-switch:swp4
    leaf02:swp31 -- spine01:swp2
    leaf02:swp32 -- spine02:swp2
folder is: /home/cumulus/cl_support_lldp_parser/cl_support_spine01_20210721_084129
spine01
    spine01:eth0 -- oob-mgmt-switch:swp5
    spine01:swp1 -- leaf01:swp31
    spine01:swp2 -- leaf02:swp31
DOTFILE: cl_support_lldp_parser.dot

The command writes the output to the cl_support_lldp_parser.dot file. You need to manually edit this file to define the node versions and clean up any extra configurations:

$ cat cl_support_lldp_parser.dot
graph dc1 {
"leaf01" [function="leaf" ]
"oob-mgmt-switch" [function="leaf" ]
"spine01" [function="leaf" ]
"spine02" [function="leaf" ]
"leaf02" [function="leaf" ]
    "leaf01":"eth0" -- "oob-mgmt-switch":"swp2"
    "leaf01":"swp31" -- "spine01":"swp1"
    "leaf01":"swp32" -- "spine02":"swp1"
    "spine02":"eth0" -- "oob-mgmt-switch":"swp6"
    "spine02":"swp2" -- "leaf02":"swp32"
    "leaf02":"eth0" -- "oob-mgmt-switch":"swp4"
    "leaf02":"swp31" -- "spine01":"swp2"
    "spine01":"eth0" -- "oob-mgmt-switch":"swp5"
}

Restore Configuration Files

After you create the simulation, you can restore the configuration files.

This python script extracts relevant files and collates them into folders which you can use to restore configurations.

You can also use the infrastructure-as-code Ansible playbook to restore configurations.

Custom Topology

The Drag-and-Drop Topology Builder

ZTP Scripts

Manage Nodes

OOB Management Network

Custom Topologies with DOT Files

DOT Syntax

Operating System

Disk Space

CPU

Create Connections

Memory

Examples

Upload a DOT File

Import a Topology with the API

Export a Topology through the API

Create a Custom Topology from the Production Network

Gather cl-support from the Production Network

Create topology.dot from the Production Network

Restore Configuration Files

Products

Solutions

Learn