Containerlab

---
name: containerlab
description: "Expert coverage of Containerlab container-based network lab orchestration: topology YAML files, supported NOS kinds, lab lifecycle, multi-vendor topology design, CI/CD integration, vrnetlab VM-based nodes, graph visualization, and network automation testing. Use for \"Containerlab\", \"clab\", \"network lab\", \"container topology\", \"clab deploy\", \"clab.yml\", \"vrnetlab\", \"network emulation\", \"network CI/CD\". Do NOT use for cross-vendor comparison, platform selection, or category-wide architecture -- use the `dc-fabric` skill."
license: MIT
---

# Containerlab

This skill covers Containerlab (v0.73+), the open-source container-based network lab orchestration tool. Areas of expertise include:

- Topology YAML files (.clab.yml): Node definitions, kinds, links, startup configuration
- Lab lifecycle: deploy, inspect, destroy, graph, save
- Supported NOS kinds: Nokia SR Linux, Arista cEOS, Cisco XRd, SONiC VS/VM, Juniper cRPD/vMX, FRR, Linux
- vrnetlab: VM-based network nodes (vMX, XRv9K, CSR1000v) running inside containers
- Link types: point-to-point, bridge, macvlan, host interface attachment
- Graph visualization: HTML, draw.io, Mermaid, Graphviz DOT output
- CI/CD integration: GitHub Actions, GitLab CI, automated network testing
- VS Code extension: IDE integration for topology management
- WSL2 and macOS support: Cross-platform lab environments

## How to Approach Tasks

1. **Classify** the request:
   - **Topology design** -- Build topology YAML for the target network architecture
   - **NOS selection** -- Choose appropriate kind for the required platform
   - **Lab operations** -- Deploy, inspect, connect, destroy, save workflows
   - **CI/CD pipeline** -- GitHub Actions / GitLab CI integration for network testing
   - **Troubleshooting** -- Container issues, link problems, image availability
   - **Visualization** -- Graph command output options

2. **Gather context** -- Target NOS platforms, number of nodes, link topology (leaf-spine, ring, full-mesh), available container images, host platform (Linux, WSL2, macOS)

3. **Analyze** -- Consider container image licensing (cEOS requires Arista download, XRd requires Cisco entitlement), host resource requirements (CPU, memory per node), and topology complexity.

4. **Recommend** -- Provide complete topology YAML with all required fields, deploy commands, and validation steps.

5. **Verify** -- Suggest validation (clab inspect, SSH access, ping tests, routing verification).

## Topology YAML Structure

### Basic Topology

```yaml
name: dc-fabric

topology:
  nodes:
    spine1:
      kind: nokia_srlinux
      image: ghcr.io/nokia/srlinux:latest
    spine2:
      kind: nokia_srlinux
      image: ghcr.io/nokia/srlinux:latest
    leaf1:
      kind: ceos
      image: ceos:4.32.0F
    leaf2:
      kind: ceos
      image: ceos:4.32.0F

  links:
    - endpoints: ["spine1:e1-1", "leaf1:et1"]
    - endpoints: ["spine1:e1-2", "leaf2:et1"]
    - endpoints: ["spine2:e1-1", "leaf1:et2"]
    - endpoints: ["spine2:e1-2", "leaf2:et2"]
```

### Advanced Features

```yaml
name: advanced-lab

topology:
  defaults:
    kind: nokia_srlinux
    image: ghcr.io/nokia/srlinux:latest

  kinds:
    nokia_srlinux:
      type: ixrd2l
    linux:
      image: alpine:latest

  nodes:
    spine1:
      # Inherits defaults
    leaf1:
      startup-config: configs/leaf1.cfg
    server1:
      kind: linux
      exec:
        - ip addr add 10.1.1.10/24 dev eth1
        - ip route add default via 10.1.1.1
      binds:
        - configs/server1:/etc/app/config

  links:
    - endpoints: ["spine1:e1-1", "leaf1:e1-49"]
    - endpoints: ["leaf1:e1-1", "server1:eth1"]
```

### Key Topology Fields

| Field | Description |
|---|---|
| `name` | Lab name; used as container name prefix (clab-<name>-<node>) |
| `topology.nodes` | Node definitions with kind, image, and config |
| `topology.links` | Point-to-point connections between node interfaces |
| `topology.defaults` | Default kind and image for all nodes |
| `topology.kinds` | Per-kind defaults (type, image, env) |
| `startup-config` | Path to initial configuration file loaded on deploy |
| `exec` | Commands to run inside container at startup |
| `binds` | Host-to-container volume mounts |
| `env` | Environment variables passed to container |
| `ports` | Port mappings (host:container) for external access |
| `labels` | Container labels for metadata |

## Supported NOS Kinds

| Kind | NOS | Image Source | License |
|---|---|---|---|
| `nokia_srlinux` | Nokia SR Linux | ghcr.io/nokia/srlinux | Free (community) |
| `ceos` | Arista cEOS | Arista download portal | Requires Arista account |
| `xrd` | Cisco XRd | Cisco software download | Requires entitlement |
| `linux` | Any Linux/FRR | Docker Hub / any registry | Varies |
| `sonic-vs` | SONiC Virtual Switch | docker-sonic-vs image | Open source |
| `sonic-vm` | SONiC VM (vrnetlab) | SONiC .img via vrnetlab | Open source |
| `juniper_crpd` | Juniper cRPD | Juniper download | Requires license |
| `vr-vmx` | Juniper vMX | VM via vrnetlab | Requires license |
| `vr-xrv9k` | Cisco XRv9K | VM via vrnetlab | Requires license |
| `vr-csr` | Cisco CSR1000v | VM via vrnetlab | Requires license |
| `dell_sonic` | Dell Enterprise SONiC | Dell image | Requires agreement |
| `ovs-bridge` | Open vSwitch | openvswitch image | Open source |
| `bridge` | Linux bridge | Kernel bridge | N/A |

### vrnetlab

vrnetlab wraps traditional VM-based network images in containers:

- VM runs inside a Docker container with a lightweight wrapper
- Provides SSH access on standard ports
- Significantly heavier than native container images (2-8 GB RAM per node)
- Required for NOS platforms without native container support (vMX, XRv9K, CSR)

## Lab Lifecycle Commands

```bash
# Deploy a lab
sudo clab deploy -t topology.clab.yml

# Deploy with reconfiguration (re-apply startup configs)
sudo clab deploy -t topology.clab.yml --reconfigure

# List all running labs
sudo clab inspect -a

# Inspect specific lab
sudo clab inspect -t topology.clab.yml

# Connect to a node via SSH
ssh admin@clab-<lab-name>-<node-name>

# Connect via docker exec
docker exec -it clab-<lab-name>-<node-name> bash

# Save current node configs
sudo clab save -t topology.clab.yml

# Destroy lab (remove containers and links)
sudo clab destroy -t topology.clab.yml

# Destroy all labs
sudo clab destroy -a

# Generate topology graph
sudo clab graph -t topology.clab.yml
```

## Graph Visualization

`clab graph` generates topology diagrams in multiple formats:

| Format | Command | Output |
|---|---|---|
| **HTML** (interactive) | `clab graph -t topo.clab.yml` | Browser-based interactive diagram |
| **draw.io** | `clab graph -t topo.clab.yml -o draw.io` | draw.io/diagrams.net format |
| **Mermaid** | `clab graph -t topo.clab.yml -o mermaid` | Mermaid markdown diagram |
| **Graphviz** | `clab graph -t topo.clab.yml -o dot` | DOT format for Graphviz |

## CI/CD Integration

### GitHub Actions

```yaml
name: Network Tests
on: [pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Containerlab
        run: |
          bash -c "$(curl -sL https://get.containerlab.dev)"

      - name: Deploy topology
        run: sudo clab deploy -t tests/topology.clab.yml

      - name: Run network tests
        run: |
          # Wait for convergence
          sleep 30
          # Run pytest network validation
          python -m pytest tests/test_network.py -v

      - name: Cleanup
        if: always()
        run: sudo clab destroy -t tests/topology.clab.yml
```

### GitLab CI

```yaml
network-test:
  image: docker:latest
  services:
    - docker:dind
  script:
    - bash -c "$(curl -sL https://get.containerlab.dev)"
    - clab deploy -t tests/topology.clab.yml
    - sleep 30
    - python -m pytest tests/test_network.py -v
  after_script:
    - clab destroy -t tests/topology.clab.yml
```

### Testing Patterns

- **Route verification** -- Deploy topology, wait for BGP convergence, verify route tables via SSH
- **Connectivity tests** -- Ping between endpoints across fabric; verify VXLAN/EVPN reachability
- **Configuration validation** -- Deploy topology with candidate configs; verify state matches intent
- **Ansible playbook testing** -- Run Ansible against Containerlab nodes before production deployment
- **Terraform plan testing** -- Apply Terraform configs against Containerlab NOS nodes

## Resource Planning

| NOS Kind | RAM per Node | CPU per Node | Disk |
|---|---|---|---|
| nokia_srlinux | 2-4 GB | 2 vCPU | 500 MB |
| ceos | 2 GB | 1-2 vCPU | 1 GB |
| linux/FRR | 256-512 MB | 0.5 vCPU | 100 MB |
| sonic-vs | 2-4 GB | 2 vCPU | 1 GB |
| vr-vmx (vrnetlab) | 4-8 GB | 4 vCPU | 2 GB |
| vr-xrv9k (vrnetlab) | 8-16 GB | 4 vCPU | 4 GB |

**Rule of thumb**: A 16-core, 64 GB RAM server can run a 4-spine, 8-leaf fabric with native container images. vrnetlab nodes require significantly more resources.

## Common Pitfalls

1. **Missing container images** -- Many NOS images require vendor download and local import. Verify `docker images` shows the required image before `clab deploy`.

2. **Insufficient host resources** -- vrnetlab nodes (vMX, XRv9K) consume 4-16 GB RAM each. Plan host capacity before building large topologies.

3. **Interface naming mismatch** -- Each NOS kind uses different interface naming conventions (e1-1 for SR Linux, et1 for cEOS, Ethernet0 for SONiC). Check kind documentation for correct naming.

4. **Convergence timing in CI/CD** -- BGP convergence takes 30-90 seconds after deploy. Add adequate wait time or poll for convergence before running tests.

5. **Running without sudo** -- Containerlab requires root privileges for network namespace manipulation. Use `sudo clab` or configure rootless Docker.

6. **WSL2 networking** -- WSL2 uses a NAT bridge. Container management IPs are accessible from WSL but may not be reachable from the Windows host without port forwarding.

7. **Not saving configs** -- `clab destroy` removes all container state. Use `clab save` or startup-config files to preserve configuration across lab restarts.