This is the second article in our series on running the ClickHouse® database on Kubernetes with the Altinity® Kubernetes Operator. In the first article we learned the concepts. Now we build a real Kubernetes cluster on your own computer so you have a safe place to practice everything that follows. No cloud account and no cost required.
We cover two popular tools, minikube and k3s. You only need one to follow the series, but it helps to know both.
Why run Kubernetes locally
Learning Kubernetes on a paid cloud cluster is stressful and can run up a bill. A local cluster runs entirely on your laptop, is free, resets in seconds, and behaves enough like a real cluster that everything you learn transfers directly. We will use it to run a single ClickHouse node next, and a full replicated cluster later.
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 choice 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 you use to talk to any Kubernetes cluster. Install it by following the official instructions for your operating system, then verify:
kubectl version --clientYou should see a client version printed. If the command is found, you are ready.
Step 2: Install minikube
minikube is a tool that 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 using the Docker driver. We give it generous resources because ClickHouse will live here soon:
minikube start --driver=docker --cpus=4 --memory=6gThe first run downloads a base image and takes a few minutes. When it finishes, minikube automatically points kubectl at the new cluster. Verify the node is ready:
kubectl get nodesNAME STATUS ROLES AGE VERSION
minikube Ready control-plane 60s v1.35.xA single node that is both control plane and worker is exactly what we want for learning.
Step 4: Run your first pod
Let us confirm the cluster actually runs workloads. Create a simple deployment and look at it:
kubectl create deployment hello --image=kicbase/echo-server:1.0
kubectl get podsWithin a few seconds the pod's status becomes Running. You just scheduled a container onto Kubernetes. Clean it up:
kubectl delete deployment helloStep 5: Enable the add-ons you will need
minikube ships add-ons that are off by default. Two matter for ClickHouse.
The storage provisioner, which lets PersistentVolumeClaims get real disks automatically, is enabled by default in minikube, so storage will just work. You can 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 use to request storage later.
For services that need an external address, run minikube tunnel in a separate terminal. This makes LoadBalancer services reachable from your machine, which we will use when connecting to ClickHouse from outside the cluster.
The alternative: k3s
minikube is the friendliest option on macOS and Windows. On Linux, k3s is a great lightweight alternative. It is a fully certified Kubernetes distribution packaged as a single small binary, and as of mid-2026 the current release tracks Kubernetes 1.36. 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 handy because it includes a default storage provisioner and a service load balancer out of the box, so it is 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 installed, /usr/local/bin/k3s-uninstall.sh.
minikube or k3s: which should you use
For this series, either works. Choose minikube if you are on macOS or Windows, or want a throwaway cluster you reset often with minikube delete. Choose k3s if you are on Linux and want something closer to a small production cluster, or you are running on a very lightweight machine. 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 entirely and reclaim the space, run minikube delete. For k3s, use the uninstall script mentioned above. Resetting and starting fresh is cheap, so do not be afraid to experiment.
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 manually first is what makes the value of the Altinity Kubernetes Operator obvious when we introduce it.
