197 lines
4.3 KiB
Markdown
197 lines
4.3 KiB
Markdown
# 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
|
|
- 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:
|
|
|
|
```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.
|