Installation instructions for setting up a local Raspberry Pi cluster at your home desk.

• Operating System on SD Card
• Network Setup
• RPi Configuration
• SSH Config
  • Client
  • RPi Server
• Verification
• Troubleshooting
• Summary

Operating System on SD Card

1. Connect the SD card to your local machine (laptop / desktop)
2. Download Raspberry Pi OS Lite (Debian Buster) image from here
3. Flash OS image using Raspberry Pi Imager as specified in here
   
4. After flashing, eject and re-connect the SD card again to your local machine
5. Check for boot connected device
6. Mount the SD card

7. Open a terminal session and create a text file named ssh in the boot partition

   
   1
   2
   3
   4
   5
   
   # If you are working on macOS
   sudo touch /Volumes/boot/ssh
       
   # Other Unix-like operating system
   sudo touch <path-to-rpi-boot-volume>/ssh
   
   

8. Eject the SD card and connect it to the Raspberry Pi

Network Setup

1. Power up the RPi and connect directly to the home router

2. Open the router network dashboard

   Note: Your router dashboard address might differ, check with your router manufacture guide.
3. Verify under LAN settings -> Client List that there is a new raspberrypi client
4. Assign a static IP address using this guide

RPi Configuration

1. SSH into the server using ssh pi@<RPI-IP-ADDRESS> with an IP address from previous step and the default password raspberry

2. Set the GPU memory split to 16MB by editing the RPi configuration file sudo vi /boot/config.txt and appending gpu_mem=16 to it

   Note: We specify the minimum memory possible to reserve for GPU (display) since we won’t require user interface.
3. Reboot using sudo reboot for changes to take effect
4. SSH again to the RPI server and type sudo raspi-config. Edit the following settings:
   • Change the password for the pi user (recommended)
   • Set the hostname to your liking

   • Make sure SSH server is enabled

     Note: If you are planning on using this server as a Kubernetes master - name it kmaster. If it is a Kubernetes node, name it knode<number> while <number> is the next in-line number of your cluster stack.
     
5. Close the SSH session and reconnect to the RPi server again
6. Verify hostname was properly set and force manual replacement, if required. From the RPi terminal:
   • Run cat /etc/hostname and check for kmaster
   • Run cat /etc/hosts and check for 127.0.1.1 kmaster

   • Run hostname which should return kmaster, otherwise run sudo hostname kmaster and check again

     Note: Use kmaster or knode<number> respectively according to the server type if you are setting up a Kubernetes cluster.

7. Install your favourite utilities on the RPi server:

   
   1
   2
   
   # Use Vim as a text editor
   sudo apt-get -y install vim
   
   

8. Set your preferred aliases on ~/.bashrc:

   
   1
   2
   3
   4
   5
   
   # Open bash run command file for editing
   vim ~/.bashrc
      
   # List all files/directories including hidden ones with size unit suffixes 
   alias l="ls -lah"
   
   

9. (Optional) If you are planning to install the Rancher k3s version of Kubernetes, you should enable a few container features by adding them to the end of the /boot/cmdline.txt file:

   
   1
   2
   3
   4
   5
   
   # Edit file with sudo
   sudo vim /boot/cmdline.txt
      
   # Append the following
   cgroup_enable=cpuset cgroup_memory=1 cgroup_enable=memory
   
   

SSH Config

We need to configure secure shell access for client <-> RPi server communication. It will allow us to access the RPi server from client machines such as our laptop and also allow secure communication between the RPi server and our locally installed utilities.

Client

These instructions are relevant to the computer being used to connect to the RPi server:

1. Create directory ~/.ssh if it doesn’t exists and cd into it
2. Run ssh-keygen (with name kmaster OR knode<number>, no passphrase)

3. Add the private key kmaster to the ssh agent (select between permanent/temporary)

   
   1
   2
   
   ssh-add ~/.ssh/kmaster      # Add temporary to keychain
   ssh-add -K ~/.ssh/kmaster   # Add permanently to keychain
   
   

   Note: This will allow a secure communication without prompting for a password every time.

4. Copy the public key to RPi server, select one option:

   • Option 1:

     
     1
     2
     3
     4
     5
     
     # Master node
     ssh-copy-id -i ~/.ssh/kmaster.pub pi@<RPI-IP-ADDRESS>
     		
     # Worker node
     ssh-copy-id -i ~/.ssh/knode<number>.pub pi@<RPI-IP-ADDRESS>
     
     

     Important: For this step you will need to authenticate with your password. A file named ~/.ssh/authorized_keys is auto-created with the public key content on the RPi server.

   • Option 2: (Manual)

     Copy the content of kmaster.pub / knode<number>.pub directly to the RPi authorized_keys file:

     
     1
     2
     3
     4
     5
     
     # Master node
     cat ~/.ssh/kmaster.pub | ssh pi@<RPI-IP-ADDRESS> 'mkdir -p ~/.ssh && cat >> ~/.ssh/authorized_keys'
           
     # Worker node
     cat ~/.ssh/knode<number>.pub | ssh pi@<RPI-IP-ADDRESS> 'mkdir -p ~/.ssh && cat >> ~/.ssh/authorized_keys'
     
     

     Important: For this step you will need to authenticate with your password.

5. (Optional): If you have defined a static IP for the RPi server as described in here, add named hosts records on your client machine:

   
   1
   2
   3
   
    # Use names instead of IP addresses
    echo -e "192.168.1.200\tkmaster" | sudo tee -a /etc/hosts
    echo -e "192.168.1.201\tknode1" | sudo tee -a /etc/hosts
   
   

RPi Server

These instructions are intended for the RPi server to enable SSH communication:

1. Disable SSH PasswordAuthentication:

   • Edit ssh_config by sudo vim /etc/ssh/ssh_config
   • Uncomment PasswordAuthentication by removing the # prefix
   • Change its value to no
   • Make sure PasswordAuthentication is properly aligned (4 spaces)

2. Restart SSH server

   
   1
   2
   
   sudo /etc/init.d/ssh restart
   sudo /etc/init.d/ssh status   # Verify SSH server is running
   
   

Verification

To verify everything is set-up correctly, try to connect from the client machine i.e. laptop to the RPi server with the following command:

1
2

ssh pi@kmaster
ssh pi@knode<number>

Troubleshooting

Locale

What? Locale errors/warnings when connecting to a RPi server and/or running locale on a server node. These are a few example errors:

1
2
3
4

setlocale: LC_ALL: cannot change locale (en_US.UTF-8)
locale: Cannot set LC_CTYPE to default locale: No such file or directory
locale: Cannot set LC_MESSAGES to default locale: No such file or directory
locale: Cannot set LC_ALL to default locale: No such file or directory

Solution: We’ll set our locale to en_US by running the following steps:

1. SSH to the RPi server
2. Edit the locale.gen file using sudo vi /etc/locale.gen
3. Uncomment the line with en_US.UTF-8 by removing the # character (make sure there are no leading spaces)
4. Run sudo locale-gen en_US.UTF-8
5. Run sudo update-locale en_US.UTF-8
6. Run locale to make sure there are no errors/warnings

Summary

By the end of this post you should have a working headless (non-GUI) Raspberry Pi(s) connected to your home network with SSH communication available, good job !

What now? You are welcome to check back for a future blog post on how to install Kubernetes on top of your amazing RPi cluster.

Please leave your comment, suggestion or any other input you think is relevant to this post in the discussion below.

Thanks !

^{Credits: Logo by raspberrypi.org}