We created this repository as a collection of templates for netreplica nrx software. It might be useful outside of nrx for any other effort to automate creation of software network labs.
This repository provides a set of such templates as a starting point. You're welcome to clone and adopt to your needs. If you'd like to contribute back, it would be greatly appreciated.
This project is in a proof-of-concept phase. We're experimenting with the best ways to automate software network lab orchestration. If you have any feedback, questions or suggestions, please reach out to us via the Netreplica Discord server linked above, #netreplica channel in NetDev Community on Slack, or open a github issue in this repository.
- Containerlab – Open-source network emulation software using containers.
- Cisco Modeling Labs - Commercial network emulation software from Cisco.
- Graphite - Network topology visualization software from Netreplica.
- D2 – Declarative diagramming language.
- nrx software also supports user-provided formats. You can extend this repository with your own set of templates.
Platform | Containerlab | CML | Interface Mapping | Startup Config |
---|---|---|---|---|
Arista EOS | ceos |
no |
Interface Map | clab |
Cisco CSR1000v | vr-cisco_csr1000v |
no |
Not supported | clab |
Cisco IOSv | no |
iosv |
CML Node Template | cml |
Cisco IOSvL2 | no |
iosvl2 |
CML Node Template | cml |
Cisco NX-OSv9000 | no |
nxosv9000 |
CML Node Template | cml |
Linux | linux |
no |
Not supported | wanted |
RARE/freeRtr | rare |
no |
Not supported | wanted |
Nokia SR-Linux | srl |
no |
Clab Interface Naming | clab |
SONiC | sonic-vs |
no |
Not supported | wanted |
Ubuntu | ubuntu -> linux |
ubuntu |
Not supported | wanted |
Default | default -> linux |
default -> iosvl2 |
Not supported | n/a |
Containerlab artifacts:
clab/topology.j2
: template for the final Containerlab topology file.clab/nodes/<kind>.j2
: templates for individual device node entries in the topology file. Unique for eachkind
.clab/nodes/default.j2
: default node template used when a template for a specifickind
is not found.clab/interface_names/<kind>.j2
: templates for generating emulated interface names used by a specifickind
.clab/interface_names/default.j2
: default template for generating emulated interface names.clab/interface_maps/<kind>.j2
: templates for mapping between real interface names and emulated interface names used by thekind
. Only a fewkinds
likeceos
support such mapping.clab/node_params.j2
: extended set of node parameters supported by allkinds
. Always include this template at the end of eachclab/nodes/<kind>.j2
template to leverage these parameters. When some of the parameters needs to be rendered, define the values you need for eachkind
inplatform_map.yaml
.clab/labels.j2
: custom labels supported by Netreplica Graphite visualization software. Include this template at the end of theclab/nodes/<kind>.j2
template to initialize these labels with data from NetBox.
Cisco Modeling Labs artifacts:
cml/topology.j2
: template for the final CML topology file.cml/nodes/<kind>.j2
: templates for individual CML node entries in the topology file.cml/interface_names/<kind>.j2
: templates for generating emulated interface names used by the NOSkind
in CML.cml/configs/<family>.j2
: templates for embedding startup configuration in the topology file. Use<family>
to denote NOS family likeios
,nxos
, etc.
To customize the way a topology file should be generated, change these templates as needed. For example, you might want to modify image
values depending on the kind
. You can also add new templates, if the platforms you have are not covered by the provided set of templates.
Suppose you want to add a set of templates for a new node kind. The first step is to clone this repository:
git clone https://github.com/netreplica/templates.git
Note, if you would like to contribute your templates back to the community, please fork the repository first and then clone the fork instead.
As a practical example, let's create templates for Containerlab sonic-vs
kind. This kind represents SONiC open-source NOS.
As a next step, let's create a new development branch, for example new-clab-kind-sonic-vs
:
cd templates
git checkout -b new-clab-kind-sonic-vs
Now, we need to create a template called sonic-vs.j2
under clab/nodes
directory:
nrx
will pass the name of the node to the template asname
variable- According to documentation, we should use
kind: sonic-vs
to describe SONiC nodes - As the Docker image tag let's use a generic
sonic-vs:latest
. We will initialize theimage
variable here as part of a conditional statement to allow overriding it with a different value - Including
clab/node_params.j2
provides a way to extend the node template with some common parameters, likeimage
orstartup-config
. See the file for the full list of parameters. - Including
clab/labels.j2
will add a few useful custom labels, likegraph-level
to visually align nodes when showing the topology in Graphite
cat > clab/nodes/sonic-vs.j2 << EOF
{{ name }}:
kind: sonic-vs
{% if image is not defined %}
{% set image = "sonic-vs:latest" %}
{% endif %}
{% include 'clab/node_params.j2' %}
{% include 'clab/labels.j2' %}
EOF
The next step is to create another template – for interface naming. Some Containerlab node kinds, like srl
, use special naming conventions for interfaces. In case of sonic-vs
, the interface naming convention uses default linux-based interface names. As there is already a default.j2
template for this naming convention, we don't need to add any templates here.
If the interface naming convention for the kind you are adding follows different rules, you will need to create a custom template for that kind. See srl.j2
as an example. nrx
passed the following variables to the interface naming templates you can leverage:
interface
– original interface name exported from NetBoxindex
– position of the interface in the list of exported interfaces for this node, sorted by name
It is possible that some interface naming conventions cannot be created using current set of variables. Consider creating a Feature Request for
nrx
to support such a kind.
Now that you created the template files, check relevant Device records in NetBox – specifically, what Platform is used in their configuration. If no Platform is configured currently, create a new Platform record that would describe NOS used on these devices. In our example, we should create a Platform record for SONiC NOS. Importing the CSV below into Platforms would do it:
name,slug
SONiC,sonic
Note, that although we used sonic-vs
for our template names because this is how Containerlab identifies SONiC nodes, in NetBox you would typically use a platform.name
and platform.slug
that match NOS name on a physical device. For example, eos
for Arista EOS, instead of ceos
for Arista cEOSLab.
Different NetBox users may have very different Platform records. To support platform.slug
values from your NetBox instance, we can map them to the kind sonic-vs
using platform_map.yaml
.
For our SONiC case, we need to map sonic
to sonic-vs
. Add the following entry to the platform_map.yaml
under the platforms
section:
platforms: # this line already exists, do not add it again
sonic: # platform.slug value from NetBox
kinds:
clab: sonic-vs # template name (kind) to use in Containerlab topologies
You may also want to provide paths to the templates to be used for sonic-vs
kind explicitly. If not provided, nrx
will first look for sonic-vs.j2
and then for default.j2
files in the respective folders. The configuration below will tell nrx
to skip looking for sonic-vs.j2
when determining interface names, and use default.j2
right away.
You can also override parameters used in the template. Most common example would be to use a different image tag. There is a Docker image for SONiC hosted under Netrepica Docker Hub with an image tag netreplica/docker-sonic-vs:latest
, and this is what we are going to use.
kinds: # this line already exists, do not add it again
clab: # this line already exists, do not add it again
sonic-vs: # kind value mapped under platforms section
nodes: # template parameters used to render the nodes
template: clab/nodes/sonic-vs.j2
image: netreplica/docker-sonic-vs:latest
interface_names: # template parameters used to render the interface names
template: clab/interface_names/default.j2
Time to test if your templates work as planned. It is recommended to export a topology from NetBox with devices you made the templates for into a cyjs
file. This step doesn't actually require the templates to be present. Make sure to update API connection parameters in nrx.conf
, as well as Device Roles to export:
cd ..
nrx.py --config nrx.conf --input netbox --site YOUR_SITE --output cyjs
Now you're ready to convert cyjs
data into Containerlab topology using the new templates:
nrx.py --input cyjs --file YOUR_SITE.cyjs --output clab --templates templates --debug
Inspect resulting YOUR_SITE.clab.yaml
and if looks good, try to deploy it with:
sudo -E clab deploy -t YOUR_SITE.clab.yaml
You might need to adjust your templates and run nrx
again, using cyjs
as input.
Once you are satisfied with the results, commit your work:
cd templates
git add .
git commit -m "new template for YOUR_DEVICE_PLATFORM"
In case your want to contribute your changes, create a Pull Request into netreplica/templates. Otherwise, just merge the development branch into the main
:
git checkout main
git merge new-clab-kind-sonic-vs
Copyright 2023 Netreplica Team
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.