Topologies#

Topologies in EDA cover a lot of ground. Not only do they define the design of a physical or simulated network, they also drive the visualization of various overlays in the EDA UI.

Let's start with a familiar role of a topology - the network topology.

Network topology#

A network topology in a broader sense describes the network design. Be it a Clos, a Fat Tree or a Ring design, the topology is what inherently defines the network.

Like every topology is defined by its nodes and links, the EDA topology consists of node (TopoNode) and link (TopoLink) objects. The EDA topology nodes are represented by the devices in your network, and the topology links define the relationships between them.

If you come here after finishing the Getting Started guide, you may remember the 3-node topology that we worked on:

In EDA, this topology is represented by the TopoNode and TopoLink objects mirroring the physical design:

Almost no difference with a physical topology, right?

So if the TopoNode and TopoLink objects make up a topology, how do we create them?
The obvious way is to create these Custom Resources manually, but this is going to be a tedious and likely error-prone process when carried out manually.

To assist with this process, EDA provides a couple of methods to generate the required TopoNode and TopoLink resources based on an abstracted input:

• using a topology file
• or using the topology generator

Topology file#

Instead of creating the TopoNode and TopoLink resources individually, EDA provides a way to describes the nodes and links of a topology in a topology file. Based on the contents of this file EDA will drive the creation of the TopoNode and TopoLink resources making it possible to create a topology in a declarative way from a single file.

Let's have a look at the topology file structure and a corresponding snippet of it that was used in the quickstart topology:

---
items:
  - metadata:
    spec:
      nodes:
        - <TopoNode>

      links:
        - <TopoLink>

---
items:
  - metadata:
      namespace: default
    spec:
      nodes:
        - name: leaf1
          labels:
            eda.nokia.com/role: leaf
            eda.nokia.com/security-profile: managed
          spec:
            operatingSystem: srl
            version: 24.10.1
            platform: 7220 IXR-D3L
            nodeProfile: srlinux-ghcr-24.10.1
        # remaining nodes omitted for brevity
      links:
        - name: leaf1-spine1-1
          labels:
            eda.nokia.com/role: interSwitch
          spec:
            links:
              - local:
                  node: leaf1
                  interfaceResource: ""
                  interface: ethernet-1-1
                remote:
                  node: spine1
                  interfaceResource: ""
                  interface: ethernet-1-1
                type: interSwitch
        # remaining links omitted for brevity

The top level of the topology file consists of the two arrays: nodes and links. Elements of these arrays are modelled after the TopoNode and TopoLink resources, respectively. Let's take an example of each kind and describe the fields you would typically set in them.

name: leaf1 #(1)!
labels: #(2)!
  eda.nokia.com/role: leaf
  eda.nokia.com/security-profile: managed #(7)!
spec:
  operatingSystem: srl #(3)!
  version: 24.10.1 #(4)!
  platform: 7220 IXR-D3L #(5)!
  nodeProfile: srlinux-ghcr-24.10.1 #(6)!

name: leaf1-spine1-1 #(1)!
labels: #(2)!
  eda.nokia.com/role: interSwitch
spec:
  links:
    - local: #(3)!
        node: leaf1
        interface: ethernet-1-1
        interfaceResource: ""
      remote: #(4)!
        node: spine1
        interface: ethernet-1-1
        interfaceResource: ""
      type: interSwitch #(5)!

By adding node and link elements to the topology file you define your topology. This is exactly how the 3-node topology used in the Getting Started guide was created.

The topology file is now complete and we can apply it to drive the creation of the TopoNode and TopoLink resources. But before we get to the topology deployment, let's take a look at another way to generate a topology file.

Topology generation#

Using a topology file instead of creating the TopoNode and TopoLink resources manually is a step forward, but wouldn't it be nice to have a tool that could generate the topology file based on a more abstracted definition? This is exactly what the topology generator is for.

EDA Topology Generator allows users to define an abstracted input for a topology that can further simplify working with topologies. The topology generator expects user to provide a JSON file that consists of "layers". Each layer represents a set of nodes of the same type and role, and maps nicely to the tiers or stages of a Clos topology.
The example below should help clarify the layered structure and the definition of each field inside a layer.

{
  "leaf": { //(1)!
    "NodeCount": 2, //(2)!
    "NodeLabels": {
      "eda.nokia.com/security-profile": "managed" //(18)!
    },
    "Platform": "7220 IXR-D3L", //(3)!
    "LayerRole": "leaf", //(4)!
    "NextLayerRole": "spine", //(5)!
    "Uplinks": 2, //(6)!
    "Downlinks": 2, //(7)!
    "SlotCount": 1, //(8)!
    "PodId": "1", //(9)!
    "GenerateEdge": true, //(10)!
    "NodeProfile": "srlinux-ghcr-24.10.1", //(11)!
    "Version": "24.10.1", //(12)!
    "OperatingSystem": "srl", //(13)!
    "EdgeEncapType": "dot1q", //(14)!
    "RedundancyLabelsOdd": { //(15)!
      "eda.nokia.com/redundancy-group": "a"
    },
    "RedundancyLabelsEven": { //(16)!
      "eda.nokia.com/redundancy-group": "b"
    },
    "CanaryLabels": { //(17)!
      "eda.nokia.com/canary": "true"
    }
  },
  "spine": {
    "NodeCount": 1,
    "NodeLabels": {
      "eda.nokia.com/security-profile": "managed"
    },
    "Platform": "7220 IXR-H2",
    "LayerRole": "spine",
    "NextLayerRole": "superspine",
    "Uplinks": 2,
    "Downlinks": 4,
    "SlotCount": 1,
    "PodId": "1",
    "NodeProfile": "srlinux-ghcr-24.10.1",
    "Version": "24.10.1",
    "OperatingSystem": "srl"
  }
}

1. A layer name. It is an arbitrary name of a layer, but it must be unique across the entire topology.
2. The number of nodes in the layer.
3. The platform of the node.
4. The layer role. An arbitrary string value, but often named after a topology stage, like leaf, spine, etc.
5. The role of the next layer that this layer connects to.
   In this example the leaf role has the spine role as the next layer, and hence the uplinks of the leaf layer will connect to the spine layer.
6. The number of uplinks each node in this layer has.
7. The number of downlinks each node in this layer has.
8. Used with chassis platforms, and will result in uplinks/downlinks being evenly distributed over line cards.
9. Pod ID is translated to a TopoNode label that is leveraged by the Fabric app when dealing with multi-pod topologies.
10. Indicating whether to generate Interface resources for links not used for either uplinks or downlinks.
11. The profile of the node.
12. The software version of the node.
13. The operating system of the node.
14. Sets the encapType value for any Interface resources generated as edge interfaces.
15. Labels on odd TopoNode generated within the layer.
16. Labels on even TopoNode generated within the layer.
17. Labels on the first TopoNode generated within the layer.
18. Security profile label that is used by the NodeSecurityProfile CR as a selector. The managed profile means the certificates for the nodes are managed by EDA.

This input defines a three node topology with one spine and two leaves. The nodes are automatically tagged with the respected labels and edge links are created for the leaf nodes.

EDA topology generator is implemented in the edatopogen binary that you can find in the eda-toolbox pod. Feel free to use the makefile in the playground repository to quickly connect to the eda-toolbox pod or create a handy alias for the toolbox to use it from anywhere.

alias toolbox='kubectl -n eda-system exec -it \
  $(kubectl get -n eda-system pods \
  -l eda.nokia.com/app=eda-toolbox -o jsonpath="{.items[0].metadata.name}") \
  -- env "TERM=xterm-256color" bash'

make open-toolbox

Create a topology generator input file and name it something like topo.json. We will just copy the example used before:

cat <<EOF > topo.json
{
  "leaf": {
    "NodeCount": 2,
    "NodeLabels": {
      "eda.nokia.com/security-profile": "managed"
    },
    "Platform": "7220 IXR-D3L",
    "LayerRole": "leaf",
    "NextLayerRole": "spine",
    "Uplinks": 2,
    "Downlinks": 2,
    "SlotCount": 1,
    "PodId": "1",
    "GenerateEdge": true,
    "NodeProfile": "srlinux-ghcr-24.10.1",
    "Version": "24.10.1",
    "OperatingSystem": "srl",
    "EdgeEncapType": "dot1q",
    "RedundancyLabelsOdd": {
      "eda.nokia.com/redundancy-group": "a"
    },
    "RedundancyLabelsEven": {
      "eda.nokia.com/redundancy-group": "b"
    },
    "CanaryLabels": {
      "eda.nokia.com/canary": "true"
    }
  },
  "spine": {
    "NodeCount": 1,
    "NodeLabels": {
      "eda.nokia.com/security-profile": "managed"
    },
    "Platform": "7220 IXR-H2",
    "LayerRole": "spine",
    "NextLayerRole": "superspine",
    "Uplinks": 2,
    "Downlinks": 4,
    "SlotCount": 1,
    "PodId": "1",
    "NodeProfile": "srlinux-ghcr-24.10.1",
    "Version": "24.10.1",
    "OperatingSystem": "srl"
  }
}
EOF

Now we need to run the edatopogen binary to generate the topology file. We will use the -y flag to tell the generator to output the topology file in the ConfigMap format. It will be clear why we ask for the ConfigMap format in the next section:

edatopogen -y -f topo.json

By default this will generate the ConfigMap file in a file named generated_topo_pod_1.yaml where pod_1 is the pod ID used in the input file.

yq eval -i 'del(.metadata.namespace)' generated_topo_pod_1.yaml #(1)!

If you take a look at the generated file you will see that it has the familiar topology file structure, just packed into the ConfigMap resource. This knowledge will be useful in the next chapter when we will deploy the generated topology.

Topology deployment#

We have learned how to craft topologies using two different ways:

• by composing the topology file and specifying each TopoNode and TopoLink in a YAML file
• by using the topology generator to generate the topology file by parsing the layered input file

Both methods provided the same result in the end: a topology file that contains the TopoNode and TopoLink resources that describe the network topology. In order to drive the creation of these resources we need to perform the following steps:

1. Create a namespaced ConfigMap resource with a name topo-config in the cluster containing a JSON object describing the topology.
2. Call the api-server-topo -n <namespace> tool available in the eda-toolbox pod that will read the topology file from the namespaced topo-config ConfigMap and generate the required resources.

The api-server-topo tool will read the topology file from the topo-config ConfigMap and generate the following resources in EDA:

If you created your topology file in the YAML format as we did in the topology file section, you can use the available make target that will create the ConfigMap and call the api-server-topo tool to apply the topology in single step.

make TOPO=/path/to/topo.yml topology-load #(1)!

1. Using the makefile from the playground repository

If you used the topology generator, then you have a ConfigMap already created, all you need to do is to apply it to the cluster:

kubectl -n eda apply -f generated_topo_pod_1.yaml #(1)!

1. We create the ConfigMap with the topology file in the eda namespace. The eda namespace is a "user" namespace where user's resources are created.

and run the api-server-topo tool:

api-server-topo -n eda

The api-server-topo tool will generate the following resources in EDA:

• TopoNode resources matching the topology.
• TopoLink resources matching the topology.
• Interface resources for every interface in the topology.
• Loopback Interface resource for every TopoNode.

You can now admire your new Topology in the EDA UI.