ROS 2 Kubernetes architecture

Understand the layers of a local robotics infrastructure lab, from Ubuntu virtual machines and kubeadm to ROS 2 DDS discovery and monitoring, without confusing planned integrations with proven behavior.

VAGRANT CLUSTER / HISTORICALJAZZY IMAGE / SEPARATE

Layers at a glance

Read each group from the top row down: a row runs on the rows below it. Line style and the group label carry the status, not colour alone. The diagram is conceptual; it is not a live cluster view.

How to read it

Current baseline (solid outline). What the repository tests today: an image-local smoke test and a kind profile with a delivery check that its guide records running once.
Historical (dashed outline). Kept for study. Kubernetes 1.29, ROS 2 Foxy and Weave Net were not re-validated for this page.
Not established (dotted outline). No evidence is checked in, so the lab makes no claim.

Each layer with its status, the files that document it, and what not to infer
Layer	Status	Where to inspect it	Do not infer
ROS 2 Jazzy talker / listener	Current baseline	ROS2/Dockerfile, scripts/test-ros2-image.sh	Anything about clusters: the test runs two processes in one container.
kind cluster, 1 control plane + 2 workers	Current baseline · one recorded run	docs/KIND-DEMO.md, kind/ros2k8s-demo.yaml, scripts/verify-ros2.sh	That it works on your host, on arm64, macOS or Windows, or with another network plugin.
Vagrant VMs, Kubernetes 1.29, Weave Net	Historical	Vagrantfile, KubernetesClusterSetup/, Network/	That a fresh install on a modern host works.
Workload YAML: stress-ng, ROS 2 Foxy	Historical	ROS2/ (ros_dep_*.yaml, legacy/)	That a ROS 2 talker and listener start automatically.
Prometheus, Grafana, analysis notebooks	Historical	MonitoringSystem/, DataAnalysis/	Live or modern measurements.
Cross-worker DDS on the Vagrant profile	Not established	issue #14	That it works, or that it fails: nothing checked in tests it.
Production, real-time or safety-critical use	Not claimed	DISCLAIMER.md, SAFETY.md	Suitability for any real robot.

Three-node historical topology

The Vagrantfile defines a VirtualBox private network with one Kubernetes control-plane VM and two worker VMs. These are Kubernetes nodes rather than ROS 2 application nodes. The control plane initializes kubeadm and workers join using a generated command.

VM names, roles, IP addresses, vCPUs and RAM from the Vagrantfile
VM	Role	IP	vCPUs	RAM
`controlplane`	Control plane	192.168.56.10	14	18,240 MB
`worker1`	Worker	192.168.56.11	2	6,096 MB
`worker2`	Worker	192.168.56.12	2	6,096 MB

These numbers describe the checked-in Vagrant configuration. They are not minimum requirements for a future lightweight Kubernetes profile.

Topology: conceptual dependency chain

Developer workstation (VirtualBox / Vagrant)
  ├─ controlplane  192.168.56.10   → kubeadm / API
  ├─ worker1       192.168.56.11   → workloads
  └─ worker2       192.168.56.12   → workloads

Kubernetes ↔ networking/CNI ↔ application pods
                              ↳ ROS middleware / DDS discovery
Monitoring examples ↔ Prometheus / Grafana
Historical data      ↔ Python / Jupyter

Illustrates component relationships, not a verified active cluster.

ROS 2 messaging and DDS networking

ROS 2 applications exchange messages through a middleware implementation (RMW), often using DDS discovery and transport. Default multicast discovery is not guaranteed across Kubernetes CNI implementations. Discovery modes depend on your RMW and configuration; alternatives include an explicit Fast DDS Discovery Server. In the kind profile's recorded run, default multicast discovery did not deliver messages and the Discovery Server did; the findings table has the details and limits.

The original lab installs historical Weave Net. A modern networking experiment should test pod-to-pod connectivity, DNS or advertised locator reachability, discovery mode, UDP transport, namespace isolation and restart behavior on distinct worker nodes. See the repository DDS troubleshooting guide and network modernization issue #15.

Jazzy image and legacy workload manifests

The modern Dockerfile uses ROS 2 Jazzy / Ubuntu 24.04 and demo nodes. The automated smoke script checks two processes in the same container. The historical root-level Kubernetes YAML uses stress-ng and does not auto-launch a cross-worker ROS 2 talker/listener.

A smoke test is not an integration test

The image smoke test checks two processes inside one container. The separate kind profile on main adds a script that checks delivery across two workers, and its guide records one run on one host (kind demo guide). Nothing checked in tests the historical Vagrant and Weave Net profile. Open questions are tracked in #14.

Monitoring and experimentation

Monitoring scripts and configuration for Prometheus, Grafana, Metrics Server and the Kubernetes Dashboard exist as historical educational references. The separate DataAnalysis directory contains Python and Jupyter analysis over historical metrics; those plots are not measurements of a new modern cluster.

Study the source in MonitoringSystem and DataAnalysis. Security hardening, maintained UI replacements and credible end-to-end measurements remain tracked in the roadmap.

Evidence required for modern support claims

Pin and record supported ROS distribution, OS, Kubernetes, CNI, runtime and discovery configuration.
Verify a clean install on documented machine resources.
Place ROS talker and listener on different workers and record message receipt.
Test restarts and bounded failure cases with clear pass/fail output.
Require least-privilege access, no leaked tokens and reproducible raw data for performance claims.