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 TESTVAGRANT / HISTORICAL PROFILE

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/ros2-kubernetes-lab.git
cd ros2-kubernetes-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 — 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.