Skip to content

Instantly share code, notes, and snippets.

@kingand

kingand/rpizero-container-agent-setup.md

Last active April 2, 2025 03:48
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save kingand/2b6ff9562c74c3b4ac89c3f370c8542a to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save kingand/2b6ff9562c74c3b4ac89c3f370c8542a to your computer and use it in GitHub Desktop.
Download ZIP
Raw
rpizero-container-agent-setup.md

RPi Zero (1W) Setup as Container Agent

Prerequisites

SSH Key Setup

Windows Client

  1. Generate SSH key using ED25519 algorithm.

    ssh-keygen

  2. Enable the SSH Agent and set it to start up automatically.

    Get-Service ssh-agent | Set-Service -StartupType Automatic

  3. Start the SSH Agent manually.

    Start-Service ssh-agent

  4. Verify the SSH Agent is running.

    Get-Service ssh-agent

  5. Add the SSH Private Key to the SSH Agent.

    ssh-add $env:USERPROFILE\.ssh\id_ed25519

  6. Backup the SSH Private Key (e.g., to LastPass or somewhere secure).

  7. Delete the SSH Private Key from the local file system.

    rm $env:USERPROFILE\.ssh\id_ed25519

  8. Copy the SSH Public Key to the clipboard.

    cat $env:USERPROFILE\.ssh\id_ed25519.pub | clip

  9. Add the SSH Public Key to the remote server's Authorized Clients.

Ref.: https://learn.microsoft.com/en-us/windows-server/administration/openssh/openssh_keymanagement#user-key-generation

MacOS Client

  1. Generate SSH key using ED25519 algorithm.

    ssh-keygen

  2. Copy the SSH Public Key to the clipboard.

    cat $env:USERPROFILE\.ssh\id_ed25519.pub | pbcopy

  3. Add the SSH Public Key to the remote server's Authorized Clients.

TODO: Need steps for adding to keychain?

Raspberry Pi OS Installation

Format OS Disk

  1. Install Raspberry Pi Imager on machine with internet access (e.g., desktop).
  2. Insert microSD card into desktop.
  3. Launch Raspberry Pi Imager.
  4. Choose device type (e.g., Raspberry Pi Zero W).
  5. Choose OS (e.g., Raspberry Pi OS Lite 32-bit).
  6. Choose storage (e.g., microSD card).
  7. Customize OS Settins.
    1. Set hostname (e.g., pizero1.local).
    2. Set username/password.
    3. Set WiFi SSID/password.
    4. Set locale.
    5. Enable SSH.
      1. Use public-key authentication only.
      2. Enter SSH Public Key from client.
    6. Disable telemetry.
  8. Write OS to microSD card.
  9. Eject microSD card.

Verify OS Disk

  1. Insert microSD card into Raspberry Pi.

  2. Insert power cable into Raspberry Pi.

  3. Login to RaspberryPi from Desktop via SSH.

    ssh [email protected]

Container Runtime Setup

  1. Enable cgroups

    1. Append cgroup_memory=1 cgroup_enable=memory to /boot/firmware/cmdline.txt

    2. Reboot to apply the cgroups changes

      shutdown -r

  2. Install containerd, runc, rootlesskit, and containernetworking-plugins

    sudo apt install -y containerd runc rootlesskit containernetworking-plugins

  3. Register containerd as a service for automatic startup

    1. Create systemd directory if it does not already exist

      sudo mkdir -P /usr/local/lib/systemd/system/

    2. Download the containerd.service file and place it into the /usr/local/lib/systemd/system/ directory

      sudo curl https://raw.githubusercontent.com/containerd/containerd/main/containerd.service -o /usr/local/lib/systemd/system/containerd.service

    3. Refresh systemd

      sudo systemctl daemon-reload

    4. Enable the containerd service

      sudo systemctl enable --now containerd

    5. Verify the containerd service is running normally

      systemctl status containerd

  4. Install nerdctl by building from source (no existing binary for armv6l CPU)

    1. Install golang

      1. Download the latest golang binary for armv6l (e.g., v1.23.8)

        curl -LO https://go.dev/dl/go1.23.8.linux-arm6l.tar.gz

      2. Extract the golang binary into /usr/local

        sudo tar -C /usr/local -xzf go1.23.8.linux-armv6l.tar.gz

      3. Add the /usr/local/go/bin directory to PATH be appending the following line to ~/.bashrc

        export PATH=$PATH:/usr/local/go/bin

      4. Refresh the current shell

        source ~/.bashrc

    2. Install git

      sudo apt install git

    3. Download the nerdctl source repository from GitHub

      git clone https://github.com/containerd/nerdctl.git

    4. Change to the directory containing the nerdctl source code

      cd nerdctl

    5. Checkout the latest release tag (e.g., v2.0.4)

      git checkout -b v2.0.4 v2.0.4

    6. Compile nerdctl

      make

      1. If necessary, fix the build errors...
        1. Edit nerdctl/Makefile, search for the GO_BUILD variable definition, and delete the -C ... flag from the command definition. Switch to the directory containing the Makefile before running the make command.
        2. Edit the nerdctl/go.mod file, search for the line go <version>, and remove the patch number from the version string (e.g., 1.23 not 1.23.0).

    7. Install nerdctl

      sudo make install

  5. Install containerd-rootless

    containerd-rootless-setup.sh install

  6. Verify nerdctl setup

    nerdctl version

  7. Change the default port forwarder to slirp4netns

    1. Create the directory ~/.config/systemd/user/containerd.service.d

      mkdir -P ~/.config/systemd/user/containerd.service.d

    2. Create a new file named override.conf in the ~/.config/systemd/user/containerd.service.d directory

      touch ~/.config/systemd/user/containerd.service.d/override.conf

    3. Add the following content to the ~/.config/systemd/user/containerd.service.d/override.conf file

      [Service]
Environment="CONTAINERD_ROOTLESS_ROOTLESSKIT_PORT_DRIVER=slirp4netns"

    4. Reload the service configuration

      systemctl --user daemon-reload

    5. Restart the service

      systemctl --user restart containerd

  8. Allow non-root users to listen on TCP and UDP ports below 1024

    1. Create the file /etc/sysctl.d/99-rootless.conf if it does not already exist

      touch /etc/sysctl.d/99-rootless.conf

    2. Append the following line to the /etc/sysctl.d/99-rootless.conf file

      net.ipv4.ip_unprivileged_port_start=0

    3. Reload the sysctl configuration

      sudo sysctl --system

Refs.:

  1. https://github.com/containerd/containerd/blob/main/docs/getting-started.md
  2. https://github.com/containerd/nerdctl?tab=readme-ov-file#install
  3. https://github.com/containerd/nerdctl?tab=readme-ov-file#compiling-nerdctl-from-source
  4. https://github.com/containerd/nerdctl/blob/main/docs/rootless.md
  5. https://rootlesscontaine.rs/getting-started/containerd/#changing-the-port-forwarder
  6. https://rootlesscontaine.rs/getting-started/common/sysctl/#allowing-listening-on-tcp--udp-ports-below-1024
  7. https://docs.k3s.io/installation/requirements?os=pi
  8. https://some-natalie.dev/blog/raspberry-pi-kubernetes/
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment