How to run SONiC VS in ContainerLab?

[stordis-toc]

Introduction

Welcome to STORDIS ContainerLab Guide

In this article, we'll walk through the process of running a virtual switch based on SONiC VS inside ContainerLab. We will build a custom Docker image using vrnetlab and the official SONiC Virtual Switch image. 

What is The ContainerLab?

ContainerLab is an open-source tool that simplifies the deployment and management of container-based networking labs. It enables users to define network topologies using a simple YAML-based format and automatically launches containers (representing routers, switches, etc.) connected via virtual links.

What I need to run ContainerLab?

To run ContainerLab with Community SONiC VS (via vrnetlab), your system should meet the following requirements.

1. System requirements:

   1. Operating System: Linux (Ubuntu 20.04+ or Debian-based preferred), or macOS / Windows with WSL2.

   2. CPU: At least 4 cores (more recommended for larger labs).

   3. RAM: Minimum 8 GB (16+ GB recommended when running multiple SONiC containers).

   4. Disk Space: At least 60 GB free (depending on the number and size of container images).

2. Docker: Installed and running

3.  VS-SONiC image: downloaded.

4. ContainerLab: Installed via provided script or binary.

5. Git: Required to clone the image builder repository.

6. Root / sudo access: Required to set up virtual interfaces and namespaces.

7. Network support: Linux bridge and veth (kernel must support namespaces and virtual networking).

How To run it?

STEP 1: Prepare Your Machine

Ensure you are running a supported OS like Ubuntu 20.04+ and that your package list is updated using:

sudo apt update

STEP 2: Install Docker

Follow the official Docker installation guide.

STEP 3: Install ContainerLab

Run the following command to install ContainerLab quickly:

curl -sL https://containerlab.dev/setup | sudo -E bash -s "all"

You can verify it by using command clab version

STEP 4: Download the VS SONiC Image

You need to obtain the pre-built Community SONiC VS image. You can find the download links and instructions in this article: Where to download the SONiC Virtual Switch (VS) community pre-built image

STEP 5: Clone the vrnetlab repository

Open your terminal and clone the vrnetlab repository, which contains the tools to make VM-based Network OSes run in ContainerLab.

sudo apt install git
git clone https://github.com/srl-labs/vrnetlab.git
cd vrnetlab/sonic

STEP 6: Prepare the image

Move the unzipped SONiC VS image you downloaded in step 1 into this vrnetlab/sonic directory. You must rename the file to end in .qcow2. You can add a version

Unzip *.gz using command:

gzip -d sonic-vs.img

Then proceed with changing format using e.g. cp command additionally change its destination path using command below (NOTE that the best naming pattern is: sonic-vs-<Identification_name>):

cp sonic-vs.img <Your/Path>/vrnetlab/sonic/sonic-vs.qcow2

Then navigate to destination path and create docker image using command (Please make sure You are in the same destination as new *.qcow2 file):

sudo make

 Before we proceed with next steps please check if docker image was created You can verify it using docker images command, below there is screenshot that confirms that sudo make command went successfully

STEP 7: Create Your First Topology

In Your machine running ContainerLab create *.clab.yaml file to create Your first Topology.
Create a directory and YAML file:

mkdir -p /home/$USER/My-Topologies
cd /home/$USER/My-Topologies
touch SONiC-Topology.clab.yaml

Edit the file with your preferred editor (e.g., nano, vi):

nano / vi SONiC-Topology.clab.yaml

Below I will share a simple 3 switch in topology

Paste the following sample topology:

name: SONiC12
mgmt:
 network: mgmt-net
 ipv4-subnet: 192.168.0.0/24 #mgmt network address
topology:
 nodes: #list of devices
   sw1: # name of device
     kind: generic_vm # kind - type of device there is list of supported kinds in documentation
     image: vrnetlab/sonic_sonic-vs:community
   sw2:
     kind: generic_vm
     image: vrnetlab/sonic_sonic-vs:community
   sw3:
     kind: generic_vm
     image: vrnetlab/sonic_sonic-vs:community
 links:
   - endpoints: ["sw1:eth1", "sw2:eth2"]
   - endpoints: ["sw2:eth1", "sw3:eth1"]
   - endpoints: ["sw3:eth2", "sw1:eth2"]

Note: The final Docker image name is generated automatically based on the filename you provided. It follows the pattern vrnetlab/sonic_sonic-vs:<identifier>.

For example, if your qcow2 file is named sonic-vs-community.qcow2, the resulting image will be: vrnetlab/sonic_sonic-vs:community

STEP 8: Deploy the SONiC Topology

Use the following command:

clab deploy SONiC-Topology.clab.yaml

STEP 7: Visualize Your Topology
To generate a topology graph, use:

clab graph SONiC-Topology.clab.yaml

Open your browser and go to http://127.0.0.1:50080 to see the visual representation.

Can I use other GUI?

Yes! You can use VSCode or VSCodium with the ContainerLab Extension:

• Install the ContainerLab Extension
• The extension will list and visualize all created topologies

For more free resources, visit: https://stordis.com/free-resources/