Skip to content
Klutch.sh Docs

Deploying a Microk8s App

Introduction

Microk8s is a lightweight, single-node Kubernetes distribution packaged with snap. Deploying Microk8s with a Dockerfile on Klutch.sh allows you to run a compact Kubernetes control plane for demos or isolated workloads while keeping secrets managed and state persisted—all configured from klutch.sh/app. This guide covers installation, repository prep, a production-ready Dockerfile, deployment steps, Nixpacks overrides, sample API usage, and production tips.

Prerequisites

  • A Klutch.sh account (sign up)
  • A GitHub repository containing your Dockerfile (GitHub is the only supported git source)
  • Awareness that running a Kubernetes control plane inside a container is best for testing, not multi-node production
  • Domain or endpoint to reach the Kubernetes API (port 16443)

For onboarding, see the Quick Start.

Architecture and ports

  • Microk8s exposes the Kubernetes API on internal port 16443; select TCP traffic and set the internal port to 16443.
  • Worker node support and add-ons (DNS/Ingress) run inside the same container.
  • Persistent storage is required for cluster state and snapshots.

Repository layout

microk8s/
├── Dockerfile              # Must be at repo root for auto-detection
└── README.md

Keep kubeconfig and tokens out of Git; store sensitive data in Klutch.sh environment variables.

Installation (local) and starter commands

Validate locally before pushing to GitHub (Linux host recommended):

Terminal window
docker build -t microk8s-local .
docker run --privileged -p 16443:16443 microk8s-local

Dockerfile for Microk8s (production-ready)

Place this Dockerfile at the repo root; Klutch.sh auto-detects it (no Docker selection in the UI). It installs snap, Microk8s, enables core add-ons, and exposes the API server on port 16443.

FROM ubuntu:22.04


ENV DEBIAN_FRONTEND=noninteractive \
    MICROK8S_ENABLE_DNS=true \
    MICROK8S_ENABLE_INGRESS=true \
    MICROK8S_PORT=16443


RUN apt-get update && \
    apt-get install -y --no-install-recommends snapd iptables socat conntrack ca-certificates curl && \
    snap install core && \
    snap install microk8s --classic && \
    microk8s status --wait-ready && \
    microk8s enable dns && \
    microk8s enable ingress && \
    microk8s stop && \
    apt-get clean && rm -rf /var/lib/apt/lists/*


EXPOSE 16443


# Lightweight entrypoint to start Microk8s and keep the container alive
RUN printf '#!/usr/bin/env bash\nset -e\nmicrok8s start\nmicrok8s status --wait-ready\nmicrok8s kubectl cluster-info\nexec tail -f /var/snap/microk8s/common/var/log/apiserver.log\n' > /entrypoint.sh && chmod +x /entrypoint.sh


CMD ["/entrypoint.sh"]

Notes:

  • --privileged is typically required to run Kubernetes inside Docker; Klutch.sh isolates workloads, so keep the runtime expectations in mind.
  • Customize add-ons (e.g., metrics-server, storage) by appending microk8s enable <addon> in the Dockerfile.
  • Adjust the entrypoint to surface kubeconfig from /var/snap/microk8s/current/credentials/client.config.

Environment variables (Klutch.sh)

Set these in Klutch.sh before deploying:

  • MICROK8S_PORT=16443 (API server port)
  • Optional flags to toggle add-ons (if you script them in a custom entrypoint).

If you deploy without the Dockerfile and need Nixpacks overrides (not typical for Microk8s):

  • NIXPACKS_BUILD_CMD=echo "Microk8s requires snap; use Dockerfile-based deploy"
  • NIXPACKS_START_CMD=/entrypoint.sh

Attach persistent volumes

In Klutch.sh storage settings, add mount paths and sizes (no names required):

  • /var/snap/microk8s — cluster state, credentials, and add-on data.
  • /var/lib/containerd — container runtime storage if you want to persist images/cache.

Ensure these directories are writable.

Deploy Microk8s on Klutch.sh (Dockerfile workflow)

  1. Push your repository—with the Dockerfile at the root—to GitHub.
  2. Open klutch.sh/app, create a project, and add an app.
  3. Select TCP traffic and set the internal port to 16443.
  4. Add any environment variables you use for add-on toggles.
  5. Attach persistent volumes for /var/snap/microk8s (and /var/lib/containerd if desired) sized for your cluster state and images.
  6. Deploy. Access the Kubernetes API at https://example-app.klutch.sh:16443 using the kubeconfig found in /var/snap/microk8s/current/credentials/client.config.

Sample API usage

Fetch cluster info from outside (replace paths with your kubeconfig):

Terminal window
export KUBECONFIG=./client.config
kubectl cluster-info
kubectl get nodes

If you expose a proxy or bridge on port 16443, ensure your client trusts the cluster CA.

Health checks and production tips

  • Add a TCP probe on port 16443 or an HTTP probe to /readyz if you expose the API over HTTP proxy.
  • Enforce TLS; use the kubeconfig CA/certs generated by Microk8s.
  • Pin your base image and Microk8s snap channel; test upgrades in a staging app first.
  • Monitor disk usage on /var/snap/microk8s; resize before it fills.
  • This setup is best for demos and isolated control planes; for multi-node production, use a dedicated Kubernetes service.

Microk8s on Klutch.sh combines reproducible Docker builds with managed secrets, persistent storage, and flexible HTTP/TCP routing. With the Dockerfile at the repo root, API port 16443 configured, and cluster state persisted, you can run a lightweight Kubernetes control plane without extra YAML or workflow overhead.