netclab 0.9.0

❓ What is this?

Helm chart for automating the deployment of virtual network topologies on Kubernetes using Pods with multiple interfaces. It leverages the Multus CNI plugin and renders the required Kubernetes resources (e.g., ConfigMaps, Pods, NetworkAttachmentDefinitions) from a structured YAML-based topology definition.
Use it to quickly bring up containerized network labs for testing, automation, development, and education — all within your cluster.

⚙️ Use cases

This chart enables rapid deployment of containerized network topologies on Kubernetes. Key use cases include:

• Network design validation: Test high- and low-level design (HLD/LLD) configurations and device behavior before committing to a final design.
• Test automation: Develop and verify automation scripts for traffic or protocol generators/analyzers (e.g., IxNetwork APIs, OTG) — effectively unit-testing your test logic.
• Image validation: Validate new versions of network operating systems (NOS), whether virtual or hardware-aligned, to ensure feature support and functionality.
• Training & certification prep: Practice CLI, protocols, and topologies in a safe, repeatable lab — ideal for students and professionals preparing for vendor certifications.

📦 Prerequisites

Before installing Netclab Chart, ensure the following are present:

• docker
• kind
• kubectl
• helm

⚡ Quick start: netclab

netclab, on PyPI, brings a lab up in one command: the kind cluster, the CNI plugins, Multus, a local registry, and this chart, from a topology file such as examples/topology-frrouting.yaml:

uvx netclab up --namespace dc2 --values topology-frrouting.yaml
uvx netclab down --namespace dc2    # this lab
uvx netclab down                    # the whole cluster; the registry and its images stay

cEOS cannot be pulled, so it goes into the registry once. The cluster finds ceos:<version> there before Docker Hub, and the topology names it in ceos.image:

docker import ./cEOS64-lab-<version>.tar.xz ceos:<version>
docker tag ceos:<version> localhost:5001/library/ceos:<version>
docker push localhost:5001/library/ceos:<version>

ceos:
  image: ceos:<version>

netclab works only on a cluster made with its kind.yaml, and refuses any other; netclab down removes it. It also refuses a lab whose nodes ask for more CPU or memory than the cluster has free. etcd keeps its data in memory, so the cluster does not survive a restart of Docker or of the host.

🚀 What netclab up does, by hand

netclab up runs these steps for you, and also sets up the local registry. They are here to show what it does, or to run a lab without it.

• Kind cluster, with kind.yaml:

kind create cluster --name netclab --config kind.yaml

• CNI plugins (bridge and host-device), from their latest release:

CNI=$(basename "$(curl -s -o /dev/null -w '%{redirect_url}' https://github.com/containernetworking/plugins/releases/latest)")
docker exec netclab-control-plane bash -c \
"curl -L https://github.com/containernetworking/plugins/releases/download/${CNI}/cni-plugins-linux-amd64-${CNI}.tgz \
| tar -xz -C /opt/cni/bin ./bridge ./host-device"

• Multus CNI plugin, thin, from its latest release:

MULTUS=$(basename "$(curl -s -o /dev/null -w '%{redirect_url}' https://github.com/k8snetworkplumbingwg/multus-cni/releases/latest)")
kubectl apply -f https://raw.githubusercontent.com/k8snetworkplumbingwg/multus-cni/${MULTUS}/deployments/multus-daemonset.yml
kubectl -n kube-system wait --for=jsonpath='{.status.numberReady}'=1 --timeout=5m daemonset.apps/kube-multus-ds

• Add helm repo for netclab chart:

helm repo add netclab https://netclab.github.io/netclab-chart
helm repo update

🧩 Usage

After these steps, you can manage your topology using the YAML file. Pods will be created according to the topology definition.

Note:
Node and network names must use lowercase letters, digits, or hyphens.
Host interface names are limited to 15 characters.
Netclab computes veth names as <release>-<network>-<hash(node)>, automatically shortening long node names for Linux compatibility.
Recommendation: keep Helm release and network names short (≤ 3 characters).

Configuration options are documented in the table below. You can override these values in your own file.

Note:
cEOS cannot be pulled, so the chart has no default image for it. Download the cEOS image from Arista Networks, import it into your cluster, and name it in ceos.image:

docker import ./cEOS64-lab-<version>.tar.xz ceos:<version>
kind load docker-image ceos:<version> -n netclab

After loading, you can verify the image with:

docker exec netclab-control-plane crictl images | grep ceos

🧱 Example topology

To make the topology and config files easy to reach:

git clone https://github.com/netclab/netclab-chart.git && cd netclab-chart

+--------+
| h01    |
|        |
|    e1  |
+--------+
    |
    b2
    |
+-----------+          +-----------+
| e1-2      |          | srl02 or  |
| or eth2   |          | frr02 or  |
|           |          | ceos02    |
|           |          |           |
|           |          |           |
|       e1-1| -- b1 -- | e1-1      |
|    or eth1|          | or eth1   |
|           |          |           |
|           |          |           |
| srl01 or  |          |           |
| frr01 or  |          |     e1-2  |
| ceos01    |          |  or eth2  |
+-----------+          +-----------+
                              |
                              b3
                              |
                         +--------+
                         |     e1 |
                         |        |
                         | h02    |
                         +--------+

Follow instructions for SRLinux or/and FRRouting or/and cEOS

Note: The topologies are independent and can run in separate Kubernetes namespaces.

🧪 A lab with Crossplane

A lab for Kubernetes-managed network configuration, such as netadopt's AVD fabric, also needs Crossplane and its packages. netclab up installs them after the chart:

uvx netclab up --namespace dc1 --values topology.yaml \
  --crossplane <version> \
  --configuration xpkg.upbound.io/netclab/configuration-avd:<version> \
  --manifest runtime.yaml --manifest providerconfig.yaml --manifest fabric.yaml

• --configuration installs the package and waits until it is healthy.
• Each --manifest is applied server-side once the cluster serves every kind in it: before the Configuration if it already does, after it otherwise, in the order given.

🧭 Future Plans

• Add support for additional containerized or virtualized routers

🤝 Contributing

Found an issue or have an idea? Open an issue or submit a PR at:
👉 https://github.com/netclab/netclab-chart