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

CMM

Based on vendor's ASK

See:

• Running cmm

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
• default bridge CNI
• control-plane OS upgrade path

Still in progress:

• Kubernetes worker-node support
• Cilium support
• 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.