Skip to content

Commit

Permalink
docs: add doc for using rpi4 as server
Browse files Browse the repository at this point in the history
This guide explains how to use RPI4 as servers when using sidero.

Closes: siderolabs/talos#3621

Signed-off-by: Kevin Hellemun <17928966+OGKevin@users.noreply.github.com>

Co-authored-by: Andrew Rynhard <andrew@andrewrynhard.com>
  • Loading branch information
2 people authored and talos-bot committed May 31, 2021
1 parent a563284 commit 864ec57
Show file tree
Hide file tree
Showing 2 changed files with 271 additions and 1 deletion.
270 changes: 270 additions & 0 deletions website/content/docs/v0.3/Guides/rpi4-as-servers.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,270 @@
---
description: "Using Raspberrypi pi 4 as servers"
weight: 6
---

# Raspberrypi4 as servers

This guide will explain on how to use Sidero to manage Raspberrypi-4's as
servers.
This guide goes hand in hand with the [bootstrapping
guide](/docs/v0.3/guides/bootstrapping).

From the bootstrapping guide, reach "Install Sidero" and come back to this
guide.
Once you finish with this guide, you will need to go back to the
bootstrapping guide and continue with "Register the servers".

The rest of this guide goes with the assumption that you've a cluster setup with
sidero and ready to accept servers.
This guide will explain the changes that needs to be made to be able to accept RPI4 as server.

## RPI4 boot process

To be able to boot talos on the Pi4 via network, we need to undergo a 2-step boot process.
The Pi4 has an EEPROM which contains code to boot up the Pi.
This EEPROM expects a specific boot folder structure as explained on
[this](https://www.raspberrypi.org/documentation/configuration/boot_folder.md) page.
We will use the EEPROM to boot into UEFI, which we will then use to PXE and iPXE boot into sidero & talos.

## Prerequisites

### Update EEPROM

_NOTE:_ If you've updated the EEPROM with the image that was referenced on [the talos docs](https://www.talos.dev/docs/v0.10/single-board-computers/rpi_4/#updating-the-eeprom),
you can either flash it with the one mentioned below, or visit [the EEPROM config docs](https://www.raspberrypi.org/documentation/hardware/raspberrypi/bcm2711_bootloader_config.md)
and change the boot order of EEPROM to `0xf21`.
Which means try booting from SD first, then try network.

To enable the EEPROM on the Pi to support network booting, we must update it to
the latest version.
Visit the [release](https://github.com/raspberrypi/rpi-eeprom/releases) page and grab the
latest `rpi-boot-eeprom-recovery-*-network.zip` (as of time of writing,
v2021.0v.29-138a1 was used).
Put this on a SD card and plug it into the Pi.
The
Pi's status light will flash rapidly after a few seconds, this indicates that
the EEPROM has been updated.

This operation needs to be done once per Pi.

### Serial number

Power on the Pi without an SD card in it and hook it up to a monitor, you will
be greeted with the boot screen.
On this screen you will find some information
about the Pi.
For this guide, we are only interested in the serial number.
The
first line under the Pi logo will be something like the following:

`board: xxxxxx <serial> <MAC address>`

Write down the 8 character serial.

### talos-systems/pkg

Clone the [talos-systems/pkg](https://github.com/talos-systems/pkgs) repo.
Create a new folder called `raspberrypi4-uefi` and `raspberrypi4-uefi/serials`.
Create a file `raspberrypi4-uefi/pkg.yaml` containing the following:

```yaml
name: raspberrypi4-uefi
variant: alpine
install:
- unzip
steps:
# {{ if eq .ARCH "aarch64" }} This in fact is YAML comment, but Go templating instruction is evaluated by bldr restricting build to arm64 only
- sources:
- url: https://github.com/pftf/RPi4/releases/download/v1.26/RPi4_UEFI_Firmware_v1.26.zip # <-- update version NR accordingly.
destination: RPi4_UEFI_Firmware.zip
sha256: d6db87484dd98dfbeb64eef203944623130cec8cb71e553eab21f8917e0285f7
sha512: 96a71086cdd062b51ef94726ebcbf15482b70c56262555a915499bafc04aff959d122410af37214760eda8534b58232a64f6a8a0a8bb99aba6de0f94c739fe98
prepare:
- |
unzip RPi4_UEFI_Firmware.zip
rm RPi4_UEFI_Firmware.zip
mkdir /rpi4
mv ./* /rpi4
install:
- |
mkdir /tftp
ls /pkg/serials | while read serial; do mkdir /tftp/$serial && cp -r /rpi4/* /tftp/$serial && cp -r /pkg/serials/$serial/* /tftp/$serial/; done
# {{ else }}
- install:
- |
mkdir -p /tftp
# {{ end }}
finalize:
- from: /
to: /
```

## UEFI / RPi4

Now that the EEPROM can network boot, we need to prepare the structure of our
boot folder.
Essentially what the bootloader will do is look for this folder
on the network rather than on the SD card.

Visit the [release page of RPi4](https://github.com/pftf/RPi4/releases) and grab
the latest `RPi4_UEFI_Firmware_v*.zip` (at the time of writing, v1.26 was used).
Extract the zip into a folder, the structure will look like the following:

```bash
.
├── RPI_EFI.fd
├── RPi4_UEFI_Firmware_v1.26.zip
├── Readme.md
├── bcm2711-rpi-4-b.dtb
├── bcm2711-rpi-400.dtb
├── bcm2711-rpi-cm4.dtb
├── config.txt
├── firmware
│   ├── LICENCE.txt
│   ├── Readme.txt
│   ├── brcmfmac43455-sdio.bin
│   ├── brcmfmac43455-sdio.clm_blob
│   └── brcmfmac43455-sdio.txt
├── fixup4.dat
├── overlays
│   └── miniuart-bt.dtbo
└── start4.elf
```

As a one time operation, we need to configure UEFI to do network booting by
default, remove the 3gb mem limit if it's set and optionally set the CPU clock to
max.
Take these files and put them on the SD card and boot the Pi.
You will see the Pi logo, and the option to hit `esc`.

### Remove 3GB mem limit

1. From the home page, visit "Device Manager".
2. Go down to "Raspberry Pi Configuration" and open that menu.
3. Go to "Advanced Configuration".
4. Make sure the option "Limit RAM to 3 GB" is set to `Disabled`.

### Change CPU to Max (optionally)

1. From the home page, visit "Device Manager".
2. Go down to "Raspberry Pi Configuration" and open that menu.
3. Go to "CPU Configuration".
4. Change CPU clock to `Max`.

## Change boot order

1. From the home page, visit "Boot Maintenance Manager".
2. Go to "Boot Options".
3. Go to "Change Boot Order".
4. Make sure that `UEFI PXEv4` is the first boot option.

### Persisting changes

Now that we have made the changes above, we need to persist these changes.
Go back to the home screen and hit `reset` to save the changes to disk.

When you hit `reset`, the settings will be saved to the `RPI_EFI.fd` file on the
SD card.
This is where we will run into a limitation that is explained in the
following issue: [pftf/RPi4#59](https://github.com/pftf/RPi4/issues/59).
What this mean is that we need to create a `RPI_EFI.fd` file for each Pi that we want to use as server.
This is because the MAC address is also stored in the `RPI_EFI.fd` file,
which makes it invalid when you try to use it in a different Pi.

Plug the SD card back into your computer and extract the `RPI_EFI.fd` file from
it and place it into the `raspberrypi4-uefi/serials/<serial>/`.
The dir should look like this:

```bash
raspberrypi4-uefi/
├── pkg.yaml
└── serials
└─── XXXXXXXX
└── RPI_EFI.fd
```

## Build the image with the boot folder contents

Now that we have the `RPI_EFI.fd` of our Pi in the correct location, we must now
build a docker image containing the boot folder for the EEPROM.
To do this, run the following command in the pkgs repo:

`make PLATFORM=linux/arm64 USERNAME=$USERNAME PUSH=true TARGETS=raspberrypi4-uefi`

This will build and push the following image:
`ghcr.io/$USERNAME/raspberrypi4-uefi:<tag>`

_If you need to change some other settings like registry etc, have a look in the
Makefile to see the available variables that you can override._

The content of the `/tftp` folder in the image will be the following:

```bash
XXXXXXXX
├── RPI_EFI.fd
├── Readme.md
├── bcm2711-rpi-4-b.dtb
├── bcm2711-rpi-400.dtb
├── bcm2711-rpi-cm4.dtb
├── config.txt
├── firmware
│   ├── LICENCE.txt
│   ├── Readme.txt
│   ├── brcmfmac43455-sdio.bin
│   ├── brcmfmac43455-sdio.clm_blob
│   └── brcmfmac43455-sdio.txt
├── fixup4.dat
├── overlays
│   └── miniuart-bt.dtbo
└── start4.elf
```

## Patch metal controller

To enable the 2 boot process, we need to include this EEPROM boot folder into
the sidero's tftp folder.
To achieve this, we will use an init container using
the image we created above to copy the contents of it into the tftp folder.

Create a file `patch.yaml` with the following contents:

```yaml
spec:
template:
spec:
volumes:
- name: tftp-folder
emptyDir: {}
initContainers:
- image: ghcr.io/<USER>/raspberrypi4-uefi:v<TAG> # <-- change accordingly.
imagePullPolicy: Always
name: tftp-folder-setup
command:
- cp
args:
- -r
- /tftp
- /var/lib/sidero/
volumeMounts:
- mountPath: /var/lib/sidero/tftp
name: tftp-folder
containers:
- name: manager
volumeMounts:
- mountPath: /var/lib/sidero/tftp
name: tftp-folder
```

Followed by this command to apply the patch:

```bash
kubectl -n sidero-system patch deployments.apps sidero-controller-manager --patch "$(cat patch.yaml)"
```

## Profit

With the patched metal controller, you should now be able to register the Pi4 to
sidero by just connecting it to the network.
From this point you can continue with the [bootstrapping guide](/docs/v0.3/guides/bootstrapping)
at "Register the servers".
2 changes: 1 addition & 1 deletion website/content/docs/v0.3/Guides/upgrades.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
description: "A guide describing upgrades"
weight: 3
title: "Upgrading"
weight: 5
---

Upgrading a running workload cluster or management plane is the same process as describe in the Talos documentation.
Expand Down

0 comments on commit 864ec57

Please sign in to comment.