# 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:

```bash
devtools/setup-build-host.sh
```

Or install the minimum packages yourself:

```bash
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:

```bash
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](docs/flashing-usb.md)
- [Flash over network / TFTP](docs/flashing-network.md)

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:

```bash
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](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](docs/installing-ssh-pod.md)

---

## Upgrading

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

See:

- [OTA upgrade guide](docs/ota.md)

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:

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

Then run the build again:

```bash
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.