Introduction

MicroK8s is a small Kubernetes distribution aimed at local development, edge nodes, and lightweight clusters. A good configuration starts with a clean install, a few essential addons, and a kubeconfig that works with normal Kubernetes tooling.

Install and Validate the Base Cluster

On Ubuntu, the common installation path is the snap package. After installation, wait until the control plane is ready before turning on addons or deploying workloads.

1sudo snap install microk8s --classic
2sudo usermod -a -G microk8s "$USER"
3newgrp microk8s
4
5microk8s status --wait-ready
6microk8s kubectl get nodes -o wide

If the status command does not become ready, stop there and inspect the cluster before adding more moving parts. Early failures are usually easier to diagnose than later application symptoms.

Enable Only the Addons You Need

MicroK8s includes optional addons for common capabilities. For many development environments, dns, hostpath-storage, and ingress are enough.

1microk8s enable dns
2microk8s enable hostpath-storage
3microk8s enable ingress
4
5microk8s kubectl get pods -A

If you need a local image push workflow, enable the registry addon as well:

microk8s enable registry
docker tag myapp:dev localhost:32000/myapp:dev
docker push localhost:32000/myapp:dev

Keeping the addon set small reduces memory pressure and makes failures easier to isolate.

Export Kubeconfig for Standard Tools

Many tools expect a normal kubeconfig file rather than the microk8s kubectl wrapper. Export the cluster config and merge it into your existing Kubernetes config.

1mkdir -p ~/.kube
2microk8s config > /tmp/microk8s-config
3
4KUBECONFIG=~/.kube/config:/tmp/microk8s-config \
5kubectl config view --flatten > ~/.kube/config
6
7kubectl config use-context microk8s
8kubectl get nodes

After that, standard kubectl, Helm, and many IDE integrations work without special handling.

Test with a Small Deployment

Before loading real workloads, deploy something simple with explicit resource requests. That confirms scheduling, networking, DNS, and image pulling in one pass.

1apiVersion: apps/v1
2kind: Deployment
3metadata:
4  name: hello
5spec:
6  replicas: 1
7  selector:
8    matchLabels:
9      app: hello
10  template:
11    metadata:
12      labels:
13        app: hello
14    spec:
15      containers:
16        - name: hello
17          image: nginx:1.27
18          resources:
19            requests:
20              cpu: "100m"
21              memory: "128Mi"
22            limits:
23              cpu: "300m"
24              memory: "256Mi"
25---
26apiVersion: v1
27kind: Service
28metadata:
29  name: hello
30spec:
31  selector:
32    app: hello
33  ports:
34    - port: 80
35      targetPort: 80

microk8s kubectl apply -f hello.yaml
microk8s kubectl get deploy,pod,svc

This gives you a baseline cluster check before you introduce app-specific complexity.

Expand to Multi-Node Only After Single-Node Stability

MicroK8s can form a small cluster, but it is worth stabilizing one node first. When you are ready, generate a join command on the primary node and run it on the secondary node.

microk8s add-node
microk8s join 10.0.0.10:25000/abcdef1234567890
microk8s kubectl get nodes

At that point, pay attention to network reachability, hostnames, and storage assumptions. Many single-node manifests work poorly when they suddenly span multiple nodes.

Common Pitfalls

The most common issue is skipping the readiness check and enabling several addons before the base cluster is healthy. That makes the first error harder to find.

Another common problem is forgetting to add the current user to the microk8s group or not refreshing the shell session after doing so. The result looks like a permissions problem even though the cluster is fine.

Local registry workflows can also fail if Docker does not trust the registry endpoint or if image tags do not point at localhost:32000.

Finally, MicroK8s is lightweight, not magic. On small laptops or small virtual machines, too many addons or oversized workloads will create scheduling failures and evictions quickly.

Summary

• Start with a clean install and wait for microk8s status --wait-ready to succeed.
• Enable only the addons your environment actually needs.
• Export kubeconfig so standard Kubernetes tools can talk to the cluster.
• Verify the setup with a small deployment before adding real workloads.
• Treat multi-node expansion as a second step after single-node stability.