Cluster preparation: MicroK8s on a single host
From a bare Ubuntu host to a Kubernetes cluster that can run FewBox. Suited to evaluation, POC, and single-host delivery; skip this entire chapter when the customer already has a production cluster.
This chapter does one thing only: make kubectl get nodes return Ready, and make images pullable. When you are done, continue with
Install Istio → Configure the database → Edge nginx.
1. When this setup applies
| Scenario | Use this setup | Notes |
|---|---|---|
| Presales demo / feature acceptance | Yes | A single machine runs every service; sufficient for demos and acceptance |
| Private POC (trial install in the customer's data center) | Yes | Use the machine the customer provides, or bring one along |
| Customer already has production K8s | No | Read the prerequisites in Deployment overview, then start from One-click deployment |
| Production single host | Not recommended | No replicas, no multiple availability zones; tolerates only single-machine failure |
2. Hardware: memory runs out first, not CPU
The reference environment is one 4 vCPU / 8 GiB Ubuntu 22.04 cloud host, with all 21 services up and Istio injection enabled:
| Metric | Measured | Verdict |
|---|---|---|
| CPU | About 8% used (idle, no conversations) | Plenty of headroom; model calls do not use local CPU |
| Memory | About 65% used (5.1 / 7.9 GiB) | Close to the limit; this is the bottleneck |
| Pod count | 21 business Pods + istiod + ingressgateway | With injection on, every business Pod is 2/2 — one Pod, two containers (app + istio-proxy), not two replicas; without Istio or with injection off, 1/1 |
The 21 business Pods (each including its
istio-proxy) add up to about 2.0 GiB; the remaining ~3 GiB is host-side overhead such as kubelet and containerd plus page cache — every machine has it whatever is installed, so size capacity against the whole host.
Why memory fills first: every business Pod carries an istio-proxy sidecar (the second container in 2/2);
the 21 of them add up to about 750 MiB, roughly 36 MiB each. On top of that comes each service's own runtime
(Next.js and .NET are the heaviest, at about 100 MiB / 280 MiB). CPU does not have this
problem — it is almost idle when nothing is running.
Conclusion:
- 4C/8G: sufficient for demos and single-person acceptance; do not run concurrency stress tests or real multi-tenant use on it;
- 8C/16G: the recommended POC size, leaving headroom for model-side concurrency and bursts;
- Disk: images +
hostpathstorage ≥ 100 GB SSD..NETand Node images are large, and every re-tag keeps a copy of the old layers (see section 7 of this document).
3. Install MicroK8s
# snap
sudo apt update
sudo apt install snapd
# microk8s
sudo snap install microk8s --classic
sudo microk8s start
sudo microk8s status
After installation, add the current user to the microk8s group. Without it, the microk8s commands later in
this document that carry no sudo (kubectl version, get nodes, ctr images ls, and so on) fail with:
Insufficient permissions to access MicroK8s.
You can either try again with sudo or add the user <user> to the 'microk8s' group
sudo usermod -a -G microk8s $USER
newgrp microk8s
newgrp makes the new group take effect in the current shell; skip it and you have to log in again.
Which addons to enable
sudo microk8s enable dns
sudo microk8s enable hostpath-storage
sudo microk8s enable metrics-server
| addon | Required | What happens if not enabled |
|---|---|---|
dns |
Yes | Service short names do not resolve, so every http://<service> call fails |
hostpath-storage |
Yes | There is no default StorageClass; workloads that declare a PVC stay Pending forever |
metrics-server |
Strongly recommended | kubectl top shows no CPU/memory, so you cannot see resource usage while troubleshooting; HPA cannot work either |
community |
Only when using community addons | Only with it enabled do you see the community-maintained plugin list |
Do not use
microk8s enable istio. That addon's Istio version follows the snap and cannot be pinned; differences in behavior across versions show up as "routes that mysteriously 404". Install Istio separately with the official installer, see Install Istio.
If the host cannot pull images from
docker.ioand the like (typically on a mainland China network), complete Mainland China network first, then continue with the chapters that follow.
4. Hand cluster credentials to external tools
MicroK8s credentials are not in ~/.kube/config by default. istioctl, helm, and a manually installed kubectl all read the default
path, so they report a connection failure:
mkdir -p ~/.kube
sudo microk8s config > ~/.kube/config
microk8s kubectl is unaffected — it connects directly to the credentials inside the snap. Both work, but do not mix them while troubleshooting:
when one reports a connection failure and the other works, it is almost always the credentials path.
5. Verify these five items after install
microk8s kubectl version
microk8s kubectl get nodes
microk8s kubectl describe node <node-name> | grep -A6 "Allocated resources"
microk8s kubectl get pods -A
microk8s kubectl get sc
Expected results:
- The node is
Ready, version v1.28–v1.33 (v1.33 in the reference environment); - Requests under
Allocated resourcesstay below 60% of capacity — above that, new Pods fail to schedule and stayPending; - Under
kube-system,coredns,calico-node,hostpath-provisioner, andmetrics-serverare allRunning; get schas one line marked(default), namelymicrok8s-hostpath.
microk8s-hostpathuses the Delete reclaim policy and does not support expansion. Deleting a PVC deletes the data, and when the disk fills up the only option is to create a larger volume and migrate — one of the reasons backup is mandatory.
6. Known problem: an expired Calico token prevents Pods from starting
Symptom: Pods in some namespace are stuck in ContainerCreating, and the last lines of describe read:
plugin type="calico" failed (add): error getting ClusterInformation:
connection is unauthorized: Unauthorized
The cause is not a network policy: the ServiceAccount token in the kubeconfig that Calico CNI wrote to the node disk has expired (it happens after long uptime or a certificate rotation). Do this in order:
# 1. Restart Calico itself
microk8s kubectl rollout restart ds/calico-node -n kube-system
microk8s kubectl rollout restart deploy/calico-kube-controllers -n kube-system
microk8s kubectl get pods -n kube-system -l k8s-app=calico-node -w # wait for 1/1 Running
# 2. Retry the Pods that are still stuck
microk8s kubectl delete pod -n <namespace> --all --grace-period=0 --force
If that does not help, restart the service on the whole machine — this rewrites the CNI credential file:
sudo microk8s stop
sudo microk8s start
sudo microk8s status --wait-ready
What makes this failure hard to spot is that it only affects newly created Pods: services already running keep working, and the logs show nothing unusual; only a new deployment or a rolling restart exposes it. When you see
Unauthorized, troubleshoot the CNI first, not NetworkPolicy.
7. Disk cleanup
Besides microk8s-hostpath, containerd itself caches every image layer it has pulled. After repeatedly rebuilding the same tag,
old layers are not reclaimed automatically:
microk8s ctr images ls | grep <your-image-prefix>
microk8s ctr images rm <full-image-ref>
The typical symptom of a full disk is every new Pod goes Evicted or ImagePullBackOff, while kubectl get nodes
still says Ready. Check df -h /var/snap/microk8s regularly.
Next steps
Once the cluster is ready, continue in this order; on a mainland China network, complete Mainland China network first:
- Install Istio — ingress, routing, and sidecar injection are all in that chapter;
- Configure the database — one PostgreSQL instance, isolated by schema;
- Edge nginx — TLS, real IP, and timeouts;
- Deployment overview → One-click deployment.