Setting Up a Raspberry Pi Cluster with ClusterHAT (Part 1: OS Installation & SSH Setup)
Building a Raspberry Pi cluster with a ClusterHAT is a fantastic way to experiment with distributed systems, automation, and Kubernetes at a low cost. While installing the hardware is straightforward, the software setup can feel under-documented. This guide fills that gap.
In this first part, we’ll focus on:
- Installing operating systems on all nodes
- Preparing access credentials
- Setting up SSH for seamless cluster management
Later, we’ll build on this foundation with Ansible automation and Kubernetes deployment.
Step 1: Prepare Boot Configuration Files
Start by creating a working directory (e.g., dir) containing the following files:
ssh(empty file to enable SSH)userconfig.txt
Edit userconfig.txt with your desired username and password using this format:
<username>:<encrypted_password>
To generate the encrypted password, run:
echo 'mypassword' | openssl passwd -6 -stdin
If you're scripting this step, double-check the generated hash before copying it—mistakes here can lock you out later.
Step 2: Download and Flash the OS
Download the ClusterHAT-compatible OS images from:
https://clusterctrl.com/setup-software
For this setup, the CNAT Lite versions are a good lightweight choice.
Flash each SD card with the appropriate image. After flashing:
- Reinsert the SD card
- Mount the boot partition (
bootfs) - Copy your prepared files:
cp /dir/* /path/to/bootfs/
Step 3: Boot the Controller Node
Insert the controller’s SD card and power it on.
- Allow time for initial setup to complete
- Log in and verify everything is working
- If something fails, recheck the boot partition files
Patience matters here—first boot can take a minute.
Step 4: Boot and Assign Worker Nodes
Insert the correct SD cards into each Raspberry Pi Zero connected via ClusterHAT.
Power on each node individually using:
clusterctrl on p1
If the wrong node powers on:
clusterctrl off p1
Correct the issue and retry.
Repeat this process until all nodes (p1–p4) are powered and correctly mapped.
Step 5: Set Up SSH Key-Based Access
SSH keys make cluster management dramatically easier.
Generate Your SSH Key
Run:
ssh-keygen -t rsa -b 4096
Configure SSH Client
Edit your SSH config:
nano ~/.ssh/config
Add:
Host controller <controller_ip>
HostName <controller_ip>
User <username>
IdentityFile ~/.ssh/id_rsa
Host p1 <p1_ip>
HostName <p1_ip>
User <username>
ProxyCommand ssh <username>@<controller_ip> -W %h:%p
IdentityFile ~/.ssh/id_rsa
Host p2 <p2_ip>
HostName <p2_ip>
User <username>
ProxyCommand ssh <username>@<controller_ip> -W %h:%p
IdentityFile ~/.ssh/id_rsa
Host p3 <p3_ip>
HostName <p3_ip>
User <username>
ProxyCommand ssh <username>@<controller_ip> -W %h:%p
IdentityFile ~/.ssh/id_rsa
Host p4 <p4_ip>
HostName <p4_ip>
User <username>
ProxyCommand ssh <username>@<controller_ip> -W %h:%p
IdentityFile ~/.ssh/id_rsa
Copy SSH Keys to Controller
Run:
ssh-copy-id -i <identity file> <username>@<controller_ip>
Update Controller Hosts File
On the controller, edit:
sudo nano /etc/hosts
Add:
172.19.181.1 p1
172.19.181.2 p2
172.19.181.3 p3
172.19.181.4 p4
Copy Keys to Worker Nodes
From your local machine:
ssh-copy-id -i ~/.ssh/id_rsa p1
ssh-copy-id -i ~/.ssh/id_rsa p2
ssh-copy-id -i ~/.ssh/id_rsa p3
ssh-copy-id -i ~/.ssh/id_rsa p4
Once complete, verify you can SSH into each node without a password.
What’s Next?
Your Raspberry Pi cluster is now:
- Fully imaged
- Networked
- Accessible via SSH
In Part 2, we’ll use Ansible to automate configuration and provisioning across the cluster.
In Part 3 , we’ll deploy Kubernetes and turn this into a fully functional container orchestration platform.
Additional Resources
If you’re looking for more background on ClusterHAT setups, this guide is worth a read:
- The Missing ClusterHAT Tutorial https://medium.com/@dhuck/the-missing-clusterhat-tutorial-45ad2241d738
Stay tuned for the next part—this is where things start to scale.
Discussion in the ATmosphere