Getting started

Begin with a clearly scoped experiment. The modern Jazzy image can be tested without starting a Kubernetes cluster; the historical Vagrant setup is a separate, higher-resource path.

IMAGE-LOCAL ROS 2 TESTKIND PROFILE / ONE RECORDED RUNVAGRANT / HISTORICAL PROFILE

Choose your starting point

STUDENT

New to ROS 2 or Kubernetes

You only need Docker. Run one container test, then see where each piece sits.

RESEARCHER

DDS, placement, resilience

Reproduce the cross-worker check yourself, read what failed on the way, then pick an open question.

CONTRIBUTOR

Improve the lab

Pick a focused issue. Every claim in a pull request needs a command you ran and its output.

Path A — ROS 2 Jazzy container test

Requirements: Docker Engine/Desktop, a host able to run a Linux AMD64 container, sufficient disk capacity and access to the required image repositories. The CI image test checks the ROS 2 demo executables and the delivery of a local talker/listener message.

Clone the public repository

All commands in this guide assume you are in the checked-out repository root.

Build the Jazzy image

The Dockerfile uses a digest-pinned ROS 2 Jazzy / Ubuntu 24.04 base.

Run the image-local smoke test

The script fails when the listener receives no message within its timeout.

git clone https://github.com/MSKazemi/robo-resilience-lab.git
cd robo-resilience-lab

docker build --platform linux/amd64 --file ROS2/Dockerfile --tag ros-jazzy-lab:local .
docker run --rm -i --platform linux/amd64 ros-jazzy-lab:local bash -s < scripts/test-ros2-image.sh

What passing means

The test demonstrates talker/listener communication inside the tested container image. It does not validate a Kubernetes cluster, DDS discovery between pods on separate workers, arm64 builds, or real-time performance. See the full Jazzy guide.

Path B — lightweight kind cluster (three Docker containers)

Requirements: Linux on amd64 (the only platform its write-up reports testing), a Docker daemon you can use without sudo, kind v0.33.0 or newer, kubectl, make and bash. The first run downloads container images, so it needs internet access. This path does not start Vagrant or VirtualBox. Use a checkout of the main branch, which carries the kind demo guide.

make help      # prerequisites and targets
make demo      # build the image, create the kind cluster, deploy discovery server, talker and listener
make verify    # exit code 0 only if the listener hears the talker from a different worker
make clean     # delete the cluster and the image that make demo built

What passing means, and what it does not

make verify runs scripts/verify-ros2.sh. It checks that the pods are Ready, that talker and listener run on different nodes, and that the listener's I heard counter keeps advancing. The guide records one run on one Linux amd64 host; it also reports that default multicast discovery did not work on that cluster's network plugin, so the profile uses a Fast DDS Discovery Server. A pass shows delivery on your cluster at that moment. It says nothing about other network plugins, arm64, macOS or Windows, the Vagrant profile, performance or real-time behavior. This page was written from those documents and scripts and did not re-run them.

Path C — historical three-node Vagrant lab

This profile is useful for studying the checked-in infrastructure design, but it has old dependencies. The Vagrantfile defines three Ubuntu 22.04 VMs with a combined allocation near 30 GB RAM and 18 vCPUs. You need a host capable of providing those resources, VirtualBox, Vagrant and the appropriate host networking support.

# Run on your host, in the repository directory
vagrant up
vagrant ssh controlplane

# Inside the control-plane VM after provisioning
kubectl get nodes -o wide
kubectl get pods -A

This is not a modern verified quickstart

Historical Kubernetes 1.29, ROS 2 Foxy and Weave Net may require repair. No ROS talker/listener pair starts just because vagrant up completes; the original workload YAML starts stress-ng. Never post VM logs, service tokens or kubeconfig contents publicly.

Troubleshooting and evidence

Docker build failed? Check host architecture, free disk space, networking and the complete build log. Report error context without credentials.
Legacy VM cannot start? Check virtualization support, available memory, VirtualBox/Vagrant compatibility and conflicting host hypervisors.
Nodes not ready? Inspect Kubernetes events and historical CNI status. Avoid assuming multicast passes through all Kubernetes networking stacks.
No messages across workers? That is a research/test gap, not a documented successful feature; follow issue #14.

Stopping local VMs

vagrant status
vagrant halt
# Destructive: deletes the three VM disks and cluster state
vagrant destroy -f

Do not use the destructive cleanup command without checking whether data in those VMs is needed.