vpp-containerlab/BUILDING.md

Building vpp-containerlab

This document describes how to build, test and release the vpp-containerlab Docker image. The image is built natively on two machines and combined into a multi-arch manifest:

• summer — amd64, Linux (local machine)
• jessica-orb — arm64, OrbStack VM on macOS, reachable via ssh jessica-orb

The pipeline sideloads locally-built VPP .deb packages rather than pulling from packagecloud, so VPP must be compiled on both machines before building the image.

Prerequisites

SSH access to jessica-orb

The Docker daemon on jessica runs inside OrbStack's Linux VM. OrbStack listens on 127.0.0.1:32222; add a jump-host entry to ~/.ssh/config on summer to reach it:

Host jessica-orb
    HostName 127.0.0.1
    Port 32222
    User pim
    ProxyCommand ssh jessica -W 127.0.0.1:32222
    IdentityFile ~/.ssh/jessica-orb-key
    IdentitiesOnly yes
    UserKnownHostsFile /dev/null
    StrictHostKeyChecking no

Copy OrbStack's SSH key from jessica to summer:

scp jessica:~/.orbstack/ssh/id_ed25519 ~/.ssh/jessica-orb-key
chmod 600 ~/.ssh/jessica-orb-key

Verify the full chain works:

ssh jessica-orb 'uname -m && docker info | head -3'
# expected: aarch64

One-time setup

Install the Robot Framework venv for running tests:

make venv

This only needs to be re-run if tests/requirements.txt changes.

Before every release

Build VPP on both machines (make pkg-deb in your VPP source tree on both summer and the OrbStack VM on jessica), then verify both machines have a consistent set of .deb packages:

make preflight

This checks that ~/src/vpp/build-root on each machine contains exactly one version of each required package and that the version on summer matches the version on jessica-orb. Override the path if your build root is elsewhere:

make preflight VPPDEBS=~/src/vpp/other-build-root

Release pipeline

The full pipeline runs in this order:

preflight → build → test → push → release

Run everything in one shot:

make all

Or step through it manually:

Step	Command	What it does
1	make preflight	Validate VPP debs on summer and jessica-orb
2	make build-amd64	Build image locally for amd64
3	make test-amd64	Run e2e tests against the amd64 image
4	make sync-arm64	Rsync working tree to jessica-orb
5	make build-arm64	Build image on jessica-orb for arm64
6	make test-arm64	Run e2e tests on jessica-orb against the arm64 image
7	make push-amd64	Tag and push :latest-amd64 to the registry
8	make push-arm64	Tag and push :latest-arm64 to the registry
9	make release	Combine into a single :latest multi-arch manifest

Convenience targets:

make build    # steps 2+4+5 (both platforms)
make test     # steps 3+6 (both platforms)
make push     # steps 7+8 (both platforms)

Promoting to :stable

:stable is only promoted after a successful make all — meaning both amd64 and arm64 have been built, tested, pushed and combined into :latest. Do not run make stable unless the full pipeline completed without errors.

make all && make stable

make stable points :stable at the same manifest as the current :latest-amd64 and :latest-arm64, so it is always in sync with a fully tested release.

Running a single test suite

Pass TEST= to restrict which suite is run:

make test-amd64 TEST=tests/01-vpp-ospf
make test       TEST=tests/02-vpp-frr

The default is tests/ (all suites).

Debugging test failures

Read the HTML log — written after every run regardless of outcome:

xdg-open tests/out/tests-docker-log.html

Deploy the topology manually to keep containers running for inspection:

IMAGE=git.ipng.ch/ipng/vpp-containerlab:latest-amd64-test \
  containerlab deploy -t tests/01-vpp-ospf/e2e-lab/vpp.clab.yml

Then inspect live state:

# OSPF neighbour state
containerlab exec -t tests/01-vpp-ospf/e2e-lab/vpp.clab.yml \
  --label clab-node-name=vpp1 --cmd "birdc show ospf neighbor"

# Manual ping
containerlab exec -t tests/01-vpp-ospf/e2e-lab/vpp.clab.yml \
  --label clab-node-name=client1 --cmd "ping -c 5 10.82.98.82"

# Tear down when done
containerlab destroy -t tests/01-vpp-ospf/e2e-lab/vpp.clab.yml --cleanup

Common cause — OSPF convergence time: 100% ping loss usually means routing is not up yet. Tune the Sleep duration in the relevant .robot file by deploying manually and watching birdc show ospf neighbor (or vtysh -c "show ip ospf neighbor" for FRR) until all neighbours reach state Full.

Increase robot verbosity: add --loglevel DEBUG to the robot invocation in tests/rf-run.sh temporarily.