This is the second article in the series on running the ClickHouse® database on Kubernetes with the Altinity® Kubernetes Operator. The first article covered the concepts; this one gives you a real cluster to use them on, running on your own computer, with no cloud account and nothing to pay.
Two tools cover the job: minikube and k3s. You need only one to follow the series, but it is worth recognizing both.
Why run Kubernetes locally
A paid cloud cluster is a stressful place to learn, and the meter never stops. A local cluster lives entirely on your laptop: it is free, it resets in seconds, and it behaves enough like the real thing that everything you learn carries straight over. It will host a single ClickHouse node in the next article and a full replicated cluster later on.
Prerequisites
You need a machine with at least 4 CPU cores and 8 GB of RAM (ClickHouse is happier with more) and a container runtime. For minikube, the easiest runtime is Docker Desktop on macOS or Windows, or Docker Engine on Linux. Install Docker first and confirm it works with docker run hello-world.
Step 1: Install kubectl
kubectl is the command-line tool for talking to any Kubernetes cluster. Install it from the official instructions for your operating system, then verify:
kubectl version --clientA printed client version means you are set.
Step 2: Install minikube
minikube runs a single-node Kubernetes cluster inside a container or virtual machine on your computer. As of mid-2026 the current release is v1.38.x, and it ships a recent Kubernetes (1.3x) by default.
On macOS with Homebrew:
brew install minikubeOn Linux (x86-64):
curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube-latest-amd64.deb
sudo dpkg -i minikube-latest-amd64.debOn Windows, install with choco install minikube or download the installer from the minikube site. Confirm it is installed:
minikube versionStep 3: Start your cluster
Start a cluster on the Docker driver, with generous resources since ClickHouse will move in shortly:
minikube start --driver=docker --cpus=4 --memory=6gThe first run downloads a base image and takes a few minutes. When it finishes, minikube points kubectl at the new cluster for you. Check the node is ready:
kubectl get nodesNAME STATUS ROLES AGE VERSION
minikube Ready control-plane 60s v1.35.xOne node acting as both control plane and worker is exactly right for learning.
Step 4: Run your first pod
Confirm the cluster actually runs workloads. Create a small deployment and look at it:
kubectl create deployment hello --image=kicbase/echo-server:1.0
kubectl get podsWithin a few seconds the pod reaches Running. You have just scheduled a container onto Kubernetes. Tidy up:
kubectl delete deployment helloStep 5: Enable the add-ons you will need
minikube ships some add-ons switched off by default. Two matter for ClickHouse.
The storage provisioner, which hands PersistentVolumeClaims real disks automatically, is on by default in minikube, so storage just works. Confirm the default StorageClass exists:
kubectl get storageclassNAME PROVISIONER RECLAIMPOLICY ...
standard (default) k8s.io/minikube-hostpath Delete ...The standard class marked (default) is what ClickHouse will request storage from later.
For services that need an external address, run minikube tunnel in a separate terminal. That makes LoadBalancer services reachable from your machine, which you will use to connect to ClickHouse from outside the cluster.
The alternative: k3s
minikube is the friendliest option on macOS and Windows. On Linux, k3s is an excellent lightweight alternative: a fully certified Kubernetes distribution packaged as a single small binary, tracking Kubernetes 1.36 as of mid-2026. Install and start it with one command:
curl -sfL https://get.k3s.io | sh -Check the node is ready (k3s bundles its own kubectl):
sudo k3s kubectl get nodek3s is convenient because it includes a default storage provisioner and a service load balancer out of the box, which makes it production-capable on modest hardware. To use your normal kubectl with it, copy its config from /etc/rancher/k3s/k3s.yaml. To remove k3s completely, run the uninstall script it left at /usr/local/bin/k3s-uninstall.sh.
minikube or k3s: which should you use
Either one works for this series. Pick minikube on macOS or Windows, or when you want a throwaway cluster you reset often with minikube delete. Pick k3s on Linux when you want something closer to a small production cluster, or when you are on very lightweight hardware. The ClickHouse manifests we write later are standard Kubernetes and run identically on both.
Cleaning up
To stop minikube without deleting it, run minikube stop; to delete it and reclaim the space, run minikube delete. For k3s, use the uninstall script above. Resetting and starting fresh is cheap, so experiment freely.
What is next
You have a working Kubernetes cluster on your own machine. In the next article we deploy a single ClickHouse node onto it by hand, writing the StatefulSet, Service, and storage ourselves. Doing it the manual way first is what makes the value of the Altinity Kubernetes Operator obvious when we introduce it.
