Flatcar Setup on Raspberry Pi

Overview

Setup Flatcar Container Linux on a Raspberry Pi.

Flatcar is best suited for the Raspberry Pi 4. Be sure to read the firmware developers initial notice.

Firmware is still in active development for the Raspberry Pi 5, refer to the status tables on GitHub. The installation process for the Raspberry Pi 5 is still documented here for those interested.

Flatcar will boot-loop on the Raspberry Pi 3. This is likely an issue with the bootloader, and is noted in a closed issue on GitHub. The installation process for the Raspberry Pi 3 is still documented here for those interested, maybe you can solve the issue.

It is recommended to install Flatcar on a USB drive instead of an SD card; this requires enabling USB boot mode for the Pi.

Download Flatcar Installer

Download the Flatcar installer from the Flatcar System Initialization GitHub Repository to your local system.

wget https://raw.githubusercontent.com/flatcar/init/flatcar-master/bin/flatcar-install --directory-prefix=/tmp/

Modify the Flatcar installer permissions so it is executable by the user only.

chmod 700 /tmp/flatcar-install

Generate SSH Key

Generate a new RSA 4096 or Ed25519 SSH key pair using ssh-keygen.

RSA 4096:

ssh-keygen -t rsa -b 4096 -C "[email protected]"

Ed25519:

ssh-keygen -t ed25519 -C "[email protected]"

When prompted, specify a filename and enter a secure password to encrypt the private key with. The key will be generated and two files will be created with your chosen filename (id_rsa by default).

• id_rsa - Private key used for authentication. Store in a secure location and do not share it.
• id_rsa.pub - Public key. Placed on the server to verify the private key when opening a connection.

Verify the private key can only be accessed by the user.

chmod go= id_rsa

Create Ignition Configuration

Create an Ignition file to configure the system on boot.

nano /tmp/config.json

Use the following configuration from the Flatcar documentation¹. Replace <Insert_your_SSH_Keys_here> with the SSH public key generated in the previous step (the contents of id_rsa.pub). Note the username core for connecting later.

Example key definition, include quotes: "ssh-ed25519 GENERATED-KEY-HERE [email protected]".

{
  "ignition": {
    "config": {},
    "security": {
      "tls": {}
    },
    "timeouts": {},
    "version": "2.3.0"
  },
  "networkd": {},
  "passwd": {
    "users": [
      {
        "name": "core",
        "sshAuthorizedKeys": [
          <Insert_your_SSH_Keys_here>
        ]
      }
    ]
  },
  "storage": {
    "files": [
      {
        "filesystem": "OEM",
        "path": "/grub.cfg",
        "append": true,
        "contents": {
          "source": "data:,set%20linux_console%3D%22console%3DttyAMA0%2C115200n8%20console%3Dtty1%22%0Aset%20linux_append%3D%22flatcar.autologin%20usbcore.autosuspend%3D-1%22%0A",
          "verification": {}
        },
        "mode": 420
      }
    ],
    "filesystems": [
      {
        "mount": {
          "device": "/dev/disk/by-label/OEM",
          "format": "btrfs"
        },
        "name": "OEM"
      }
    ]
  },
  "systemd": {}
}

Install Flatcar

Verify the device you want to install Flatcar on, either USB or SD, is connected to your computer. Determine the device identifier using lsblk.

lsblk

The output will list all connected storage devices. For this example, device sdb is the one to install Flatcar on.

NAME           MAJ:MIN RM   SIZE RO TYPE  MOUNTPOINTS
sdb              8:1    1  42.0G  0 disk  
└─sdb1           8:2    1  42.0G  0 part  

Install Flatcar to the drive with the following command. Replace /dev/sdb with the correct device identifier, and verify the config.json path is correct.

sudo /tmp/flatcar-install -d /dev/sdb -C stable -B arm64-usr -o '' -i /tmp/config.json

The installation process will start and it will notify you when completed.

Installing Ignition config config.json...
Success! Flatcar Container Linux stable 3815.2.1 is installed on /dev/sdb

Install Raspberry Pi Firmware

Community firmware is required to boot Flatcar using UEFI. The firmware will be installed to the EFI partition of the device that Flatcar was just insatalled on.

Mount EFI Partition

Create a new directory to mount the EFI partition to.

mkdir /tmp/efipartition

Mount the EFI partition from the Flatcar device. Replace /dev/sdb with the device identifier, used earlier to install Flatcar.

efipartition=$(lsblk /dev/sdb -oLABEL,PATH | awk '$1 == "EFI-SYSTEM" {print $2}') &&\
sudo mount ${efipartition} /tmp/efipartition

Install RPi 4 Firmware

If using a Raspberry Pi 4, download the latest firmware from the Raspberry Pi 4 UEFI Firmware GitHub page. At the time of writing this was version 1.38.

wget https://github.com/pftf/RPi4/releases/download/v1.38/RPi4_UEFI_Firmware_v1.38.zip --directory-prefix=/tmp/

Extract the downloaded Raspberry Pi Firmware to the mounted EFI partition.

sudo unzip /tmp/RPi4_UEFI_Firmware_v1.38.zip -d /tmp/efipartition

Review the firmware developer’s initial notice. The following is a quote from that section.

• “A 3 GB RAM limit is enforced by default, even if you are using a Raspberry Pi 4 model that has 4 GB or 8 GB of RAM, on account that the OS must patch DMA access, to work around a hardware bug that is present in the Broadcom SoC. For Linux this usually translates to using a recent kernel (version 5.8 or later) and for Windows this requires the installation of a filter driver. If you are running an OS that has been adequately patched, you can disable the 3 GB limit by going to Device Manager > Raspberry Pi Configuration > Advanced Settings in the UEFI settings.”

Install RPi 5 Firmware

If using a Raspberry Pi 5, download the latest firmware from the Windows on R Raspberry Pi 5 UEFI GitHub page. At the time of writing this was version 0.3.

wget https://github.com/worproject/rpi5-uefi/releases/download/v0.3/RPi5_UEFI_Release_v0.3.zip --directory-prefix=/tmp/

Extract the downloaded Raspberry Pi Firmware to the mounted EFI partition.

sudo unzip /tmp/RPi5_UEFI_Release_v0.3.zip -d /tmp/efipartition

Install RPi 3 Firmware

If using a Raspberry Pi 3, download the latest firmware from the Raspberry Pi 3 UEFI Firmware GitHub page. At the time of writing this was version 1.39.

wget https://github.com/pftf/RPi3/releases/download/v1.39/RPi3_UEFI_Firmware_v1.39.zip --directory-prefix=/tmp/

Extract the downloaded Raspberry Pi Firmware to the mounted EFI partition.

sudo unzip /tmp/RPi4_UEFI_Firmware_v1.39.zip -d /tmp/efipartition

Unmount EFI Partition

Unmount the EFI partition and remove the device from the local system.

sudo umount /tmp/efipartition

Boot Raspberry Pi

Connect the created Flatcar drive to the Raspberry Pi. Verify an ethernet cable is connected. Power on, or connect the power cable, to boot the device.

If, optionally, a monitor is plugged into the device, you will be presented with the Flatcar login prompt after the initial boot process is completed. In the Ignition configuration, we only configured SSH keys, so will not be able to login at the prompt. Connect via SSH on your local system.

Connect To Flatcar

Connect to Flatcar using SSH. Define the SSH private key to use when connecting.

ssh [email protected] -p 22 -i /path/to/id_rsa

SSH Config

Optionally, add an SSH configuration for the Flatcar system.

nano $HOME/.ssh/config

Define the Flatcar Raspberry Pi values.

Host flatcar-pi
        HostName 192.168.1.199
        Port 22
        User core
        IdentityFile /path/to/id_rsa

Then connect via SSH using the defined host.

ssh flatcar-pi

References

^{2 3 1 4}