Skip to main content

Deploy a virtual lab with Containerlab

This tutorial walks you through deploying a virtual data center topology using Containerlab. You'll take the configurations generated by Infrahub and spin up a fully functional network lab with Arista cEOS virtual switches.

By the end of this tutorial, you'll have a running virtual data center that you can access, test, and validate before deploying to production hardware.

What you'll accomplish​

In this tutorial, you will:

  1. Generate a data center topology with Arista switches
  2. Extract device configurations and topology files from Infrahub
  3. Deploy the virtual lab using Containerlab
  4. Verify the deployment and access virtual devices

Prerequisites​

Before starting this tutorial, ensure you have:

  • Completed the installation guide and have Infrahub running
  • Completed the user walkthrough to understand the basic workflow
  • Docker installed and running with sufficient resources (at least 16GB RAM recommended to support a few cEOS containers)
  • Containerlab installed (installation instructions)
  • sudo access for running Containerlab (required for network namespace operations)
info

This tutorial builds on the user walkthrough. You must complete the basic workflow (creating branches, loading designs, running generators) before deploying to Containerlab.

Understanding the workflow​

The Containerlab deployment workflow connects Infrahub's generated artifacts to a virtual lab environment:

Infrahub Data → Generator → Artifacts → Containerlab Deployment
                                ↓
                    Config Files + Topology File
                                ↓
                    Virtual Network Lab (cEOS)

Key components:

  • Generated configurations - Device startup configs extracted from Infrahub artifacts
  • Containerlab topology file - YAML definition of virtual lab including device connections
  • cEOS images - Arista Container EOS virtual switches
  • Containerlab - Network lab orchestration tool that creates Docker containers with proper network connectivity

Step 1: generate the Arista data center topology​

Use the automated demo command to create a complete Arista data center in Infrahub:

uv run invoke demo-dc-arista

This command:

  1. Creates a new branch add-dc3
  2. Loads the DC-3 Arista design (objects/dc/dc-arista-s.yml)
  3. Returns immediately after loading (generator runs asynchronously)

Wait for generator completion​

The generator runs automatically in the background. Monitor its progress:

  1. Navigate to http://localhost:8000
  2. Switch to the add-dc3 branch using the branch selector
  3. Go to System → Tasks in the left sidebar
  4. Find the create_dc generator task
  5. Wait for status to change from "Pending" → "Running" → "Completed"

Generator execution typically takes 2-3 minutes as it creates devices, interfaces, IP addresses, and routing configurations.

tip

While waiting, you can review the design parameters at Network Topologies → Deployments → Data center → DC-3 to see what will be created.

Step 2: Create a proposed change and merge​

Before extracting configurations, merge the topology to the main branch:

  1. Navigate to Proposed Changes
  2. Click New Proposed Change
  3. Fill in the form:
    • Name: Add DC-3 Arista data center
    • Source Branch: add-dc3
    • Destination Branch: main
    • Description: Deploy DC-3 with Arista switches for Containerlab testing
  4. Click Create Proposed Change
  5. Review validations and artifacts
  6. Click Merge once all checks pass
info

You can also extract configurations from the branch without merging, but merging ensures the topology is validated and ready for production use.

Step 3: Extract configurations and topology files​

Run the containerlab deployment command:

uv run invoke containerlab

This command performs two operations:

Operation 1: Extract artifacts from Infrahub​

The invoke task runs uv run scripts/get_configs.py --branch add-dc3 which:

  • Queries Infrahub for all artifacts in the specified branch
  • Downloads device configurations (startup configs for each switch)
  • Downloads the Containerlab topology file
  • Saves everything to the generated-configs/ directory

Directory structure created:

generated-configs/
├── clab/
│   └── DC-3.clab.yml       # Containerlab topology definition
└── devices/
    ├── dc3-spine1.cfg      # Spine switch configurations
    ├── dc3-spine2.cfg
    ├── dc3-leaf1.cfg       # Leaf switch configurations
    ├── dc3-leaf2.cfg
    ├── dc3-leaf3.cfg
    ├── dc3-leaf4.cfg
    ├── dc3-border-leaf1.cfg  # Border leaf configurations
    └── dc3-border-leaf2.cfg

Operation 2: Deploy with Containerlab​

The invoke task then runs sudo -E containerlab deploy -t generated-configs/clab/DC-3.clab.yml which:

  • Reads the topology definition file
  • Pulls the Arista cEOS Docker image from the OpsMill artifact repository
  • Creates Docker containers for each device
  • Configures virtual network connections between devices
  • Loads the generated startup configurations into each device
  • Starts all devices
info

The Containerlab topology file references a cEOS Docker image hosted in the OpsMill artifact repository. On first deployment, Docker will download this image (approximately 500MB). The generated configurations are automatically loaded into each cEOS container during instantiation via Containerlab's startup-configuration mechanism.

Monitor deployment progress​

Watch the console output as Containerlab:

  1. Creates the lab directory
  2. Creates network links between devices
  3. Creates containers for each device
  4. Loads configurations into devices
  5. Waits for devices to boot

Deployment typically takes 2-4 minutes depending on your system and whether the Docker image is cached.

Step 4: Verify the deployment​

Once deployment completes, verify the virtual lab is running:

Check container status​

sudo containerlab inspect --name DC-3

You should see output showing all devices with their management IP addresses and states.

List running containers​

docker ps --filter "label=containerlab=DC-3"

All device containers should show as "Up" with healthy status.

Check device connectivity​

# List all Containerlab labs
sudo containerlab inspect --all

# Show detailed topology
sudo containerlab graph --name DC-3

Step 5: Access virtual devices​

Connect to any device in your virtual lab using the Containerlab CLI:

Connect to a spine switch​

sudo containerlab exec --name DC-3 --node dc3-spine1 Cli

This drops you into the Arista EOS CLI. Try some commands:

# Check device hostname and version
show version

# Verify interfaces are up
show ip interface brief

# Check BGP neighbors
show ip bgp summary

# View running configuration
show running-config

Type exit to return to your shell.

Connect to a leaf switch​

sudo containerlab exec --name DC-3 --node dc3-leaf1 Cli

Verify the leaf's connectivity to spines:

# Check BGP neighbors (should see both spines)
show ip bgp summary

# Check VXLAN configuration
show vxlan vtep

# Verify EVPN routes
show bgp evpn summary

Connect to devices with SSH​

Containerlab also provides SSH access to devices. Find the management IPs:

sudo containerlab inspect --name DC-3

Then SSH using the displayed IP addresses:

ssh admin@<management-ip>

Default credentials are typically admin / admin for cEOS devices.

Step 6: Destroy the lab (cleanup)​

When you're done testing, destroy the lab to free resources:

sudo containerlab destroy --name DC-3

This command:

  • Stops all containers
  • Removes containers and networks
  • Cleans up Containerlab state
  • Preserves the configuration files in generated-configs/
tip

The generated configuration files remain in generated-configs/ even after destroying the lab. This allows you to redeploy quickly or version control your configs.

What you've learned​

Congratulations! You've completed the Containerlab deployment workflow:

  • ✅ Generated a multi-vendor data center topology in Infrahub
  • ✅ Extracted device configurations and topology files
  • ✅ Deployed a virtual network lab with Containerlab
  • ✅ Verified device connectivity and routing protocols
  • ✅ Accessed and tested virtual devices
  • ✅ Cleaned up lab resources

Advanced usage​

Using different branches​

Deploy configurations from any branch:

uv run invoke containerlab --branch my-branch --topology DC-3

Testing configuration changes​

Use this workflow to test changes before production:

  1. Create a branch in Infrahub
  2. Modify device configurations or topology
  3. Run generator
  4. Extract configs and deploy to Containerlab
  5. Test in virtual lab
  6. If successful, merge to main and deploy to production

Troubleshooting​

Deployment fails with "permission denied"​

Ensure you're using sudo for Containerlab commands:

sudo -E containerlab deploy -t generated-configs/clab/DC-3.clab.yml

The -E flag preserves environment variables (important for Docker access).

Docker image pull fails​

If the cEOS image pull fails, verify:

  1. Docker is running and you have internet connectivity
  2. You have sufficient disk space (at least 2GB free)
  3. You can access the OpsMill artifact repository

Devices don't boot or configurations aren't loaded​

Check container logs:

docker logs clab-DC-3-dc3-spine1

Look for configuration syntax errors or boot failures.

Out of memory errors​

Containerlab labs can be resource-intensive. For DC-3 with 8 devices:

  • Minimum: 4GB RAM
  • Recommended: 8GB RAM
  • Optimal: 16GB RAM

Reduce device count or increase Docker's memory allocation if needed.

Next steps​

For deeper understanding: