Containerlab.dev: Quick Network Lab Setup Using Cisco IOL Containers

Containerlab has quickly become a de-facto standard for building reproducible, lightweight network labs using containers. In this article, I will walk through a minimal “hello world” setup that uses Cisco IOL images packaged as Docker containers, combined with Ubuntu endpoints, to form a simple routed topology.

The goal is not to cover every feature of Containerlab, but to demonstrate how quickly you can get a functional Cisco-based lab running with minimal resource requirements.

Prerequisites and Environment

This guide assumes one of the following environments:

• Windows with WSL2 enabled, or
• Native Linux installation (any modern distribution)

Both options work equally well. The examples below were executed on WSL2 running Ubuntu.

You will also need:

• Docker (Docker Desktop for Windows, or native Docker on Linux)
• Internet access to pull base images and dependencies
• A free Cisco account (for Cisco Modeling Labs images)

Step 1: Install Containerlab

Install Containerlab using the official installation script. On a Linux shell (including WSL), run:

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

This installs:

• containerlab
• Docker (if not already installed)
• Required supporting tools

Verify the installation:

containerlab version

---

Step 2: Obtain Cisco IOL Images

Cisco IOL (IOS on Linux) images are x86-compiled IOS binaries intended for lab and modeling purposes only. They are not production firmware and cannot be loaded onto physical Cisco devices.

That said, they are ideal for labs:

• Very low resource footprint (≈1 vCPU, ~768 MB RAM)
• Fast boot times
• Excellent feature coverage for routing and switching labs

Recommended Source: Cisco Modeling Labs (CML)

The most reliable approach is to use Cisco Modeling Labs (CML), which provides IOL images legally and free of charge via the Reference Platform ISO (refplat).

High-level steps:

1. Register for a free Cisco account.
2. Download the CML Reference Platform ISO from Cisco Software Central.
3. Mount the ISO.
4. Locate the IOL .bin images inside the mounted filesystem.

There are alternative community sources (for example, GitHub mirrors), but these are often outdated and may not align with current vrnetlab tooling. For long-term reliability, CML is strongly recommended.

Step 3: Convert Cisco IOL Images to Docker Images (vrnetlab)

Containerlab relies on Docker images. To convert Cisco IOL .bin files into Docker-compatible images, we use vrnetlab.

Clone vrnetlab

git clone https://github.com/hellt/vrnetlab.git
cd vrnetlab

Prepare Cisco IOL Images

Navigate to:

cd vrnetlab/cisco/iol

Place your IOL images in this directory and rename them to match vrnetlab’s expected naming convention. For example (note: The version 17.16.01a comes from the directory on the CML iso where the files were found, this version will be converted to docker container version tag and is mandatory):

• x86_64_crb_linux-adventerprisek9-ms.bin →
  cisco_iol-17.16.01a.bin
• x86_64_crb_linux_l2-adventerprisek9-ms.bin →
  cisco_iol-l2-17.16.01a.bin

Build Docker Images

Run:

make docker-image

If successful, verify the images:

docker images

Example output:

REPOSITORY             TAG           IMAGE ID       SIZE
vrnetlab/cisco_iol     17.16.01a     7242831d593a   713MB
vrnetlab/cisco_iol     l2-17.16.01a  49d4ddb34cb3   615MB

At this point, you have:

• Cisco IOL Layer 3 image
• Cisco IOL Layer 2 image

Step 4: Build an Ubuntu Endpoint Image

For endpoints, we will use a generic Ubuntu VM image provided by vrnetlab.

Navigate to:

cd vrnetlab/ubuntu

Then run:

./download.sh
make

This:

1. Downloads the official Ubuntu QCOW2 image
2. Converts it into a Docker image suitable for Containerlab

Verify:

docker images

You should now see as one of the images:

vrnetlab/canonical_ubuntu   jammy

---

Step 5: Define a Simple Containerlab Topology

We will create a minimal routed topology:

ubuntu1 ── cisco1 ── cisco2 ── ubuntu2

Create the following YAML file:

two_ubuntus_via_cisco_IOL_L3.clab.yaml

name: two_ubuntus_via_cisco_IOL_L3

topology:
  nodes:
    ubuntu1:
      kind: generic_vm
      image: vrnetlab/canonical_ubuntu:jammy

    ubuntu2:
      kind: generic_vm
      image: vrnetlab/canonical_ubuntu:jammy

    cisco1:
      kind: cisco_iol
      image: vrnetlab/cisco_iol:17.16.01a
      startup-config: |
        interface GigabitEthernet0/0
         no shutdown

    cisco2:
      kind: cisco_iol
      image: vrnetlab/cisco_iol:17.16.01a
      startup-config: |
        interface GigabitEthernet0/0
         no shutdown

  links:
    - endpoints: ["cisco1:Ethernet0/2", "ubuntu1:eth1"]
    - endpoints: ["cisco1:Ethernet0/1", "cisco2:Ethernet0/1"]
    - endpoints: ["cisco2:Ethernet0/2", "ubuntu2:eth1"]

---

Step 6: Deploy the Lab

Deploy the topology:

containerlab deploy ./two_ubuntus_via_cisco_IOL_L3.clab.yaml

After a short startup period, Containerlab will display a summary table showing all nodes in a running state. Here is a screenshot how a successfull deployment looks like and a table with running systems displayed at the end:

You can now connect directly using SSH, for example:

ssh admin@clab-two_ubuntus_via_cisco_IOL_L3-cisco1

To tear down the lab you can use command

containerlab destroy ./two_ubuntus_via_cisco_IOL_L3.clab.yaml

Summary

This article demonstrated a minimal, practical example of building a Cisco-based network lab using Containerlab + Cisco IOL + vrnetlab. With only a few commands and a YAML file, you can spin up a multi-node routed topology that is:

• Lightweight
• Reproducible
• Version-controlled
• Easy to tear down and rebuild

All configuration shown here closely follows official Containerlab documentation, with Cisco images sourced from Cisco Modeling Labs.