docs: add doc for using rpi4 as server

This guide explains how to use RPI4 as servers when using sidero. Closes: siderolabs/talos#3621 Signed-off-by: Kevin Hellemun <[email protected]> Co-authored-by: Andrew Rynhard <[email protected]>
siderolabs · May 31, 2021 · 864ec57 · 864ec57
1 parent a563284
commit 864ec57
Show file tree

Hide file tree

Showing 2 changed files with 271 additions and 1 deletion.
diff --git a/website/content/docs/v0.3/Guides/rpi4-as-servers.md b/website/content/docs/v0.3/Guides/rpi4-as-servers.md
@@ -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".
diff --git a/website/content/docs/v0.3/Guides/upgrades.md b/website/content/docs/v0.3/Guides/upgrades.md
@@ -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.