Vagrant-Kubernetes-ROS2 Deployment is an open-source, reproducible lab that deploys ROS2 (Robot Operating System 2) Talker and Listener nodes on a multi-node Kubernetes cluster. The whole cluster — one control plane plus two worker nodes — is provisioned automatically from a single vagrant up, using Vagrant and VirtualBox virtual machines, Weave Net for pod networking, and a full Prometheus/Grafana monitoring stack.
Use this project when you want to run and study containerized robotics middleware (ROS2) on Kubernetes locally, without cloud costs, and analyze the cluster's resource behavior with Jupyter notebooks.
- What it is: an infrastructure-as-code template + step-by-step guide for a local ROS2-on-Kubernetes cluster.
- Who it is for: robotics and cloud-native engineers, students, and researchers learning ROS2, Kubernetes, and container orchestration.
- What it solves: it removes the manual, error-prone setup of a Kubernetes cluster capable of running ROS2's DDS-based publish/subscribe communication, and adds monitoring and data analysis out of the box.
- Different from a bare
kubeadmtutorial: it ships the networking (Weave Net with multicast for DDS), the monitoring stack (Prometheus, Grafana, Dashboard, Metrics Server), and a working ROS2 Talker/Listener example — end to end. - When NOT to use it: it is a local development/education lab, not a production or edge-robot deployment; it needs a fairly powerful host (see Prerequisites).
- Vagrant-Kubernetes-ROS2 Deployment
This project leverages Vagrant to automate the deployment of a Kubernetes cluster, configuring VirtualBox virtual machines, and setting up an extensive monitoring system. It is tailored for both development and educational purposes, particularly in robotic systems where ROS2 applications are prevalent.
ROS2 nodes communicate through DDS (Data Distribution Service), which relies on multicast. The cluster uses Weave Net as its Container Network Interface (CNI) plugin because it supports the multicast traffic that ROS2's publish/subscribe model needs across Kubernetes pods and nodes.
- One-command cluster:
vagrant upbuilds three Ubuntu 22.04 VMs (1 control plane + 2 workers) and bootstraps Kubernetes withkubeadm. - ROS2 on Kubernetes: deploy and scale ROS2 Foxy Talker/Listener nodes (
demo_nodes_cpp) and verify inter-pod DDS communication. - DDS-ready networking: Weave Net CNI configured for multicast so ROS2 discovery works across nodes.
- Full monitoring stack: Prometheus, Grafana, Kubernetes Dashboard, and Metrics Server installed via Helm and
kubectl, exposed over NodePort with persistent volumes. - Autoscaling & resource study: Horizontal Pod Autoscaler (HPA) and Vertical Pod Autoscaler (VPA) manifests plus a load-testing image (
stress-ngon top ofosrf/ros:foxy-desktop). - Data analysis: Python + Jupyter notebooks that pull metrics from the Prometheus TSDB (
prometheus-api-client) and analyze CPU/memory/network usage with pandas and matplotlib. - Reproducible: pinned component versions (see table) and scripted provisioning for repeatable results.
The Vagrantfile defines a three-node cluster on a private VirtualBox network:
| Node | Role | IP | vCPUs | Memory |
|---|---|---|---|---|
controlplane |
Kubernetes control plane | 192.168.56.10 | 14 | ~18 GB |
worker1 |
Worker node | 192.168.56.11 | 2 | ~6 GB |
worker2 |
Worker node | 192.168.56.12 | 2 | ~6 GB |
The control plane is initialized with kubeadm init --apiserver-advertise-address=192.168.56.10 --pod-network-cidr=10.244.0.0/16; workers join automatically using a generated kubeadm join token. Resource sizing is defined in the Vagrantfile and can be adjusted to fit your host.
Before beginning, ensure you have VirtualBox and Vagrant installed on your machine. Because the default cluster requests roughly 30 GB of RAM and 18 vCPUs across the three VMs, a host with ample resources is recommended; reduce the vb.memory / vb.cpus values in the Vagrantfile for smaller machines.
To install VirtualBox, run the following commands:
sudo apt update && sudo apt upgrade -y
sudo apt install virtualbox -yAlternatively, you can download and install VirtualBox from the following link:
- https://www.virtualbox.org/wiki/Linux_Downloads
- https://download.virtualbox.org/virtualbox/7.0.14/virtualbox-7.0_7.0.14-161095~Ubuntu~jammy_amd64.deb
Install Vagrant with these commands:
sudo apt update && sudo apt upgrade -y
wget -O- https://apt.releases.hashicorp.com/gpg | sudo gpg --dearmor -o /usr/share/keyrings/hashicorp-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/hashicorp-archive-keyring.gpg] https://apt.releases.hashicorp.com $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/hashicorp.list
sudo apt update && sudo apt install vagrantVerify the installation:
vagrant --versionTo create the VMs and set up the Kubernetes cluster, clone the repository and execute the following:
git clone git@github.com:MSKazemi/Vagrant-Kubernetes-ROS2-Deployment.git
cd Vagrant-Kubernetes-ROS2-Deployment
vagrant up | tee vagrant.logvagrant up reads the Vagrantfile, creates the VMs, runs all provisioning scripts (Kubernetes install, cluster init, Weave Net, monitoring), and joins the workers — no further commands are required. The tee vagrant.log captures the setup output, including the token used to log into the Kubernetes Dashboard.
Deploy the ROS2 Talker/Listener workload:
kubectl apply -f ./ROS2/ros_dep_1.yaml
kubectl scale deployment ros --replicas=3Then attach to two pods and run ros2 run demo_nodes_cpp talker in one and ros2 run demo_nodes_cpp listener in another (after source /opt/ros/foxy/setup.bash) to see DDS messages flow between them. Full details are in ROS2/README.md.
Follow the specific details provided in each subcomponent's README for detailed setup and usage guidelines.
Scripts and configurations to initialize a Kubernetes cluster. More Details
- Deploying a Kubernetes Cluster Using Vagrant and VirtualBox
- Pre-requisites and Dependencies
- Cluster VM's Lifecycle Commands
- Technical Details (Vagrantfile, Kubeadm, Kubectl, Kubelet, Container Network Interface Plugin)
Scripts to configure the network using CNI plugins like Weave Net. More Details
Configuration files and scripts for setting up Prometheus, Grafana, and Kubernetes monitoring tools. More Details
- Metrics Server
- Kubernetes Dashboard
- Dashboard Access and Security
- Prometheus and Grafana
- Helm
- Persistent Volume Configuration
- GUI Access URLs and Credentials
Deployment instructions and configurations for ROS2 Talker and Listener nodes. More Details
- ROS2 (Robot Operating System 2)
- ROS2 Nodes vs. Kubernetes Nodes
- ROS2 Talker and Listener Nodes
- Deploying the ROS2 Nodes
- Testing the ROS2 Nodes
Python and Jupyter Notebook setups for analyzing data collected from the environment. More Details
| Software | Version |
|---|---|
| Ubuntu | 22.04.4 LTS |
| Vagrant | 2.4.1 |
| VirtualBox | 7.0.14 |
| Kubernetes | v1.29.4 |
| Kubeadm | v1.29.4 |
| Kubectl | v1.29.4 |
| kubelet | v1.29.4 |
| Prometheus | v2.51.1 |
| Grafana | v10.4.1 |
| Dashboard | v2.7.0 |
| Metrics Server | v0.7.1 |
| Helm | v3.14.2 |
| Visual Studio Code | v1.89.0 |
- Learn ROS2 on Kubernetes without cloud costs, on a laptop or workstation.
- Prototype and test containerized robotics middleware and DDS communication patterns.
- Study Kubernetes autoscaling (HPA/VPA) and self-healing behavior under load with
stress-ng. - Teach cloud-native and robotics concepts with a reproducible, scripted environment.
- Collect and analyze cluster resource metrics (CPU, memory, network) from Prometheus using Python/Jupyter.
Which ROS2 distribution does this use? ROS2 Foxy, based on the osrf/ros:foxy-desktop image, running the demo_nodes_cpp Talker and Listener examples.
Why Weave Net instead of another CNI? ROS2 uses DDS, which depends on multicast for node discovery. Weave Net supports multicast across the cluster, which is required for ROS2 pods on different Kubernetes nodes to communicate.
How many nodes are created? Three VMs: one control plane and two workers, all Ubuntu 22.04 (ubuntu/jammy64).
Do I need a cloud account? No. Everything runs locally in VirtualBox VMs managed by Vagrant.
What are the default access URLs? Kubernetes Dashboard at https://192.168.56.10:30664, Prometheus at http://192.168.56.10:31334, and Grafana at http://192.168.56.10:30400 (see MonitoringSystem/README.md for credentials).
Can I run it on a smaller machine? Yes — lower the vb.memory and vb.cpus values in the Vagrantfile, though very small allocations may not run the full monitoring stack comfortably.
If you use this project or its components in your research or in developing software, we kindly request that you cite it. Here's a suggested citation format:
@misc{Vagrant-Kubernetes-ROS2,
author = {Mohsen Seyedkazemi Ardebili},
title = {Vagrant-Kubernetes-ROS2 Deployment},
year = {2024},
publisher = {GitHub},
howpublished = {\url{https://github.com/MSKazemi/Vagrant-Kubernetes-ROS2-Deployment}}
}Distributed under the Apache License 2.0. See LICENSE for more information.
Contributions are what make the open-source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated. Please open an issue or pull request to propose changes.
- Kubernetes
- Vagrant
- VirtualBox
- Prometheus
- Grafana
- ROS2
Thank you for exploring our Vagrant-Kubernetes-ROS2 Deployment repository. Dive into each component for a deeper understanding and more detailed documentation!