monok8s

This is an Alpine-based Kubernetes image for Mono's Gateway Development Kit.

It gives you a ready-to-boot Kubernetes control-plane image so you can get your device running first, then learn and customize from there.

Project/device docs: https://docs.mono.si/gateway-development-kit/getting-started

---

What you get

The default image boots into a small Kubernetes control-plane environment with:

• Alpine Linux
• Kubernetes initialized through kubeadm
• read-only root filesystem layout
• A/B rootfs layout for safer OS upgrades
• a Kubernetes-style OS upgrade path through OSUpgrade

You do not need to know Go or understand the internal build system to try the image.

---

Before you start

You need:

• a Linux build machine or VM
• Docker
• make
• basic command-line comfort

If you are building on a fresh Debian machine, you can install the usual build dependencies with:

devtools/setup-build-host.sh

Or install the minimum packages yourself:

sudo apt-get update
sudo apt-get install -y docker.io make qemu-user-static binfmt-support

Make sure your user can run Docker, or use sudo where needed.

---

Fast path: build an image

Download the project tarball, extract it, then run:

make release

When the build finishes, check the out/ directory for the generated image artifacts.

That is the main path most users should try first.

---

Flash the image

After building, flash the generated image to your device.

Start with one of these guides:

• Flash over USB
• Flash over network / TFTP

USB flashing is usually the easiest path when you are setting up the device for the first time.

---

First boot

The default configuration is intended to boot as a first-time Kubernetes control-plane node.

Default-style control-plane configuration looks like this:

make cluster-config \
	MKS_HOSTNAME=monok8s-master \
	MKS_CLUSTER_ROLE=control-plane \
	MKS_INIT_CONTROL_PLANE=true \
	MKS_MGMT_ADDRESS=10.0.0.10/24 \
	MKS_APISERVER_ADVERTISE_ADDRESS=10.0.0.10

If you are just trying the image for the first time, start with the default control-plane setup. Worker-node setup is still incomplete.

For all available configuration values, see:

• configs/cluster.env.default

For worker node

make cluster-config \
	MKS_HOSTNAME=monok8s-worker \
	MKS_CLUSTER_ROLE=worker \
	MKS_INIT_CONTROL_PLANE=no \
	MKS_MGMT_ADDRESS=10.0.0.10/24 \
	MKS_APISERVER_ADVERTISE_ADDRESS=10.0.0.10 \
	MKS_API_SERVER_ENDPOINT=10.0.0.1:6443 \
	MKS_CNI_PLUGIN=none \
	MKS_BOOTSTRAP_TOKEN=abcd12.ef3456789abcdef0 \
	MKS_DISCOVERY_TOKEN_CA_CERT_HASH=sha256:9f1c2b3a4d5e6f7890abc1234567890abcdef1234567890abcdef1234567890ab

---

Getting shell access

For first-time setup, UART is the most direct option because it is already part of the flashing process.

After the device is running, the recommended path is:

• Install an SSH pod

---

Upgrading

monok8s includes a Kubernetes-style OS upgrade flow using the OSUpgrade custom resource.

See:

• OTA upgrade guide

The currently tested upgrade chain is:

• 1.33.3 -> 1.33.10
• 1.33.10 -> 1.34.6
• 1.34.6 -> 1.35.3

Tested worker node upgrade chain:

• 1.33.3 -> 1.34.1
• 1.33.1 -> 1.35.3

---

Current status

This project is usable for experimenting with a single control-plane device image, but it is still a development project.

Working today:

• initramfs boot flow
• Alpine boot
• Kubernetes control-plane bootstrap
• Kubernetes worker-node
• default bridge CNI
• Cilium

Still in progress:

• VPP/DPAA networking experiments

---

Common build issue

chroot: failed to run command '/bin/sh': Exec format error

This usually means the build host cannot run ARM64 binaries.

On Debian, install ARM64 emulation support:

sudo apt-get install -y qemu-user-static binfmt-support

Then run the build again:

make release

---

Notes

This is not a general-purpose Linux distribution. It is a device image for experimenting with Kubernetes on Mono's Gateway Development Kit.

The safest path is:

1. build the default image,
2. flash it,
3. boot the control-plane,
4. confirm Kubernetes is running,
5. customize only after the base image works.