blog / · updated · 16 min read

My local Kubernetes cluster in one command

A short introduction to Kubernetes, how to bring up a local cluster with kind or k3d and switch between clusters, and the two bootstrap scripts I use to get a full lab with Argo CD in one command.

kubernetesgitopsargocdk3dkindhomelab

In the Wazuh intro I promised a series where we deploy Wazuh on Kubernetes, entirely as code. Before getting there, it makes sense to explain what Kubernetes is and how to get a cluster on your laptop to play with. This post covers both. It starts by hand, with one-line clusters in kind and k3d and how to point kubectl at each one, and ends with the two bootstrap scripts I reach for every time I want a full lab.

What Kubernetes is

Kubernetes (often shortened to K8s) is an open source system that runs containers across a group of machines and keeps them running. Google open-sourced it in 2014, building on what it had learned from Borg, its internal cluster manager. Today it’s hosted by the Cloud Native Computing Foundation (CNCF).

The Kubernetes logo, a blue heptagon with a white ship’s wheel next to the word kubernetes

A handful of terms show up everywhere, so here they are.

TermWhat it means
ClusterThe whole thing, a set of machines managed as one
NodeOne machine in the cluster, physical or virtual
Control planeThe components that run the cluster, including the API server, the scheduler and etcd, the database where the cluster keeps its state
PodThe smallest unit Kubernetes runs, one or more containers sharing a network address
ManifestA YAML file describing something you want in the cluster, such as a Deployment, a Service or a Secret
NamespaceA way to group and separate things inside one cluster
Helm chartA package of manifests with variables, the closest thing Kubernetes has to an installer

What makes Kubernetes different from a script that starts containers is the idea of desired state. You tell the cluster what you want, say three copies of this app with this configuration, and controllers keep comparing that with what’s actually running. If a pod dies, they start another. If a node disappears, they move its pods somewhere else. You describe the result and Kubernetes works out the steps.

That’s also why it fits so well with infrastructure as code, which I covered in What infrastructure as code is. If the state of the cluster is a pile of YAML files, those files can live in Git.

Why a local cluster

The best reason is that you can break it. A managed cluster in the cloud (EKS, AKS or GKE) costs money from the first minute, it’s usually shared with other people, and a bad command has consequences. A local cluster runs on your laptop for free, nobody else depends on it, and when you wreck it you delete it and make a new one.

The local lab loop, where you create a cluster, try something, break it, look around, delete it and create it again

That changes how you learn. You can delete CoreDNS just to see what stops working, apply a Kyverno policy that blocks every pod, upgrade a chart three major versions at once, or stop a node container halfway through a rollout. The worst outcome is a couple of minutes waiting for a fresh cluster. I’d much rather find out what a bad kubectl delete does there than on a cluster with real users.

It’s also where I try a Helm chart before using it for real, test a change to a manifest or follow along with a series like the Wazuh one.

kind or k3d

Both run Kubernetes nodes as Docker containers on your laptop, with each container pretending to be a machine. The difference is what runs inside.

kind runs upstream Kubernetes in a control-plane container and optional worker containers, k3d runs K3s servers and agents behind a load balancer container

kindk3d
Kubernetes distributionUpstream KubernetesK3s, a lightweight certified distribution
Built-in ingressNone, you install oneTraefik included
Publishing ports to your laptopextraPortMappings in the cluster configThrough the serverlb load balancer container
Typical useTesting manifests, CI, a quick playgroundMulti-node labs, more realistic topologies

If I just want to try a chart, I use kind. If I want a control plane with more than one server, etcd snapshots or several services talking to each other, I use k3d.

Your first cluster by hand

Before any script, it’s worth doing it once by hand. You need Docker running (Docker Desktop, OrbStack or Docker Engine on Linux) and three command-line tools. On macOS or Linux with Homebrew, that’s one line.

brew install kubectl kind k3d

Without Homebrew, kind publishes release binaries, k3d has an install script and the Kubernetes docs cover kubectl for every platform.

kind

kind create cluster --name playground
kubectl get nodes

Without --name the cluster is called kind. On my laptop, with the node image already downloaded, it took about ten seconds. The first run is slower because it pulls the image. You get a single container that acts as the control plane and runs your workloads too.

NAME                       STATUS   ROLES           AGE   VERSION
playground-control-plane   Ready    control-plane   40s   v1.x.y

To list and remove kind clusters, use these.

kind get clusters
kind delete cluster --name playground

k3d

k3d cluster create lab
kubectl get nodes

That gives you one K3s server plus a load balancer container. To get a few nodes, ask for them.

k3d cluster create lab --servers 1 --agents 2
k3d cluster list
k3d cluster delete lab

Break it on purpose

Here’s a first experiment that shows desired state in action. Create a deployment with three copies of nginx, then delete all its pods.

kubectl create deployment hello --image=nginx --replicas=3
kubectl rollout status deployment/hello
kubectl delete pod -l app=hello
kubectl get pods -l app=hello

A few seconds later you have three new pods with different names. The deployment still says three replicas, so the controller replaced them. Try it with --replicas=0, scale it up again, delete the deployment itself, or docker stop one of the node containers in the k3d cluster and watch what happens to its pods. When you get bored, delete the cluster.

Connecting to your clusters

Every kubectl command reads a file called kubeconfig (by default ~/.kube/config) to find out which API server to talk to and which credentials to use. That file holds three kinds of entries.

  • Clusters, with the API server address and its CA certificate
  • Users, with the credentials, usually a client certificate or a token
  • Contexts, each one pairing a cluster with a user and, optionally, a default namespace

One field, current-context, decides where your commands go.

kubectl reads the kubeconfig file, where each context pairs a cluster with a user, and current-context decides which cluster your commands reach

Both tools write to that file when they create a cluster and switch you to the new context straight away. kind names the context kind-<cluster> and k3d names it k3d-<cluster>, so the two clusters above are kind-playground and k3d-lab. That’s why kubectl get nodes worked right after creating them. The catch is that the last cluster you created quietly becomes the active one, and if you also have work clusters in the same file, it’s easy to lose track of where you are.

The kubectl way

Everything you need is under kubectl config.

kubectl config get-contexts              # list contexts, the active one has a *
kubectl config current-context           # print the active context
kubectl config use-context k3d-lab       # switch to another context
kubectl get pods --context kind-playground   # run one command against another context

The default namespace lives in the context too. To stop typing -n argocd all the time, set it on the current context.

kubectl config set-context --current --namespace=argocd

The comfortable way, kubectx and kubens

kubectx is a small tool that does the same with less typing, and it comes with a sibling, kubens, for namespaces. I use both every day.

brew install kubectx      # installs kubectx and kubens

kubectx                   # list contexts, the active one is highlighted
kubectx k3d-lab           # switch
kubectx -                 # go back to the previous context
kubens argocd             # change the default namespace
kubens -                  # back to the previous namespace

If you also have fzf installed, running kubectx or kubens with no arguments opens an interactive picker. The habit I recommend is to run kubectx -c (or keep the context in your shell prompt) before anything destructive. A local lab makes it safe to break things, as long as the command really lands on the local lab.

Bootstrap Argo CD and let Git do the rest

A bare cluster like the ones above looks nothing like a real one. Real clusters have ingress (the entry point that routes HTTP traffic to the right app), certificates, secrets management, monitoring and a repeatable way to deploy things. Setting all that up by hand every time is slow and easy to get wrong, so I automated it. Twice, in fact, because I ended up with two flavours for two different jobs. Both are public on GitHub under the MIT licence.

  • kind-bootstrap-script is a quick playground on kind, a cluster called k8s-playground with one control plane and one worker.
  • k3d-bootstrap-script is a K3s lab on k3d called k3s-lab, with two servers, two agents, Vault, monitoring and a demo app. I built it for a lab in my cybersecurity specialisation course.

I wanted the same four things from both.

  • One command from zero to a working cluster
  • Everything declarative and in Git
  • Disposable, so I can delete it and rebuild without fear
  • Close enough to production to learn something useful

Both repos rely on Argo CD, so here’s a quick look at what it does.

What Argo CD does

Argo CD is a GitOps tool. GitOps means the desired state of the cluster lives in Git, and an agent running inside the cluster keeps pulling it and applying it. Nobody runs kubectl apply by hand and no CI job pushes changes in. You commit, and the cluster catches up on its own.

The main object is the Application. It says where the manifests come from (a folder in a Git repo, or a Helm chart and its version) and where they go (a cluster and a namespace). This is roughly what one of the files in argocd/ looks like.

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: cert-manager
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://charts.jetstack.io   # where it comes from
    chart: cert-manager
    targetRevision: v1.21.3
  destination:
    server: https://kubernetes.default.svc   # where it goes
    namespace: cert-manager
  syncPolicy:
    automated:
      prune: true      # delete what was removed from Git
      selfHeal: true   # undo manual changes in the cluster
    syncOptions: [CreateNamespace=true]

Argo CD keeps comparing what that source renders with what’s actually running and shows the result as two statuses. Sync status says whether the cluster matches Git (Synced) or has drifted from it (OutOfSync). Health status says whether the resources work, from Healthy through Progressing to Degraded or Missing.

With automated sync, Argo CD applies changes as soon as they land in Git. selfHeal goes a step further and reverts anything changed by hand in the cluster, and prune deletes resources you removed from the repo. Both are off unless you turn them on.

That makes another good thing to break on purpose. Headlamp has selfHeal on in both labs, so delete its deployment and watch Argo CD put it back a few seconds later.

kubectl -n headlamp delete deployment headlamp
kubectl -n headlamp get deployment headlamp -w

Argo CD also comes with a web UI that shows every application, its status and the tree of resources it created. This is the kind playground right after the bootstrap.

The Argo CD UI listing the applications of the kind playground, all Synced and Healthy All green. Enjoy it while it lasts.

Click on an application and you get the tree of everything it owns. Here’s Headlamp, with its service, secret, role binding and the deployment down to the running pod. The deployment is two minutes younger than the rest because I’d just deleted it, and Argo CD had already put it back.

The Argo CD resource tree of the Headlamp application, from the Application down to the deployment, replica set and pod Headlamp, back from the dead and green again before I’d finished typing.

Back to the bootstrap scripts

There’s a lot more to Argo CD (projects, sync waves, the app of apps pattern, ApplicationSets), and it will get a post of its own. For this one, the idea above is enough, so back to the scripts.

Bootstrap flow, where a script creates the cluster and installs Argo CD, then Argo CD installs every platform app from Git

Both repos follow the same steps.

  1. A script creates the cluster from a config file (config/kind-config.yaml or config/k3d-config.yaml) and switches kubectl to its context.
  2. The script installs Argo CD from a manifest stored in the repo and waits until all its components are ready. The script has to run this step itself, because Argo CD Application objects can’t exist before Argo CD does.
  3. The script applies one Argo CD Application per platform component, from the argocd/ directory.
  4. From then on, Git is the source of truth. To change the cluster, I change the repo.

So the only fixed part is a basic cluster with Argo CD on top. Everything after that is a list I picked for my own experiments, and you can swap it for whatever you want to learn, whether that’s metrics, operators or your own applications. Empty the apps array and you get a bare cluster with Argo CD, ready for the next thing.

Adding a new component takes two steps. Drop an Application manifest in argocd/ and add its name (the file name without .yaml) to the apps array at the top of start-cluster.sh.

The kind playground

git clone https://github.com/pixelotes/kind-bootstrap-script.git
cd kind-bootstrap-script
./start-cluster.sh    # cluster, Argo CD and every app
./stop-cluster.sh     # delete it all

It installs these by default.

  • external-secrets-operator, which syncs secrets from an external store into Kubernetes
  • cert-manager, which issues and renews certificates
  • metrics-server, so kubectl top and autoscaling work
  • Traefik as the ingress controller, since kind ships without one
  • Falco, which watches system calls for suspicious behaviour at runtime
  • VictoriaMetrics and VictoriaLogs, to store metrics and logs
  • Kyverno, a policy engine that can check or block manifests before they reach the cluster
  • Headlamp as the cluster UI

The first version of the playground used ingress-nginx and the Kubernetes Dashboard. I swapped both while writing this post. The Kubernetes project retired ingress-nginx in March 2026, so it gets no more releases or security fixes, and the official advice is to move to the Gateway API or another controller. The Kubernetes Dashboard repository is archived, and its README points people to Headlamp.

The kind config publishes a few ports on your laptop, so once Argo CD has finished you get these addresses.

ServiceURL
Argo CDhttps://localhost:30080 (user admin, self-signed certificate)
Headlamphttp://localhost:30090
Your own Ingresseshttp://<name>.localhost:8080, through Traefik

The script prints the Argo CD admin password at the end. With everything running, the two nodes used about 4 GB of memory on my laptop.

The k3d lab

git clone https://github.com/pixelotes/k3d-bootstrap-script.git
cd k3d-bootstrap-script
./start-cluster.sh

Besides Docker, kubectl and k3d, the Vault step needs jq. By default start-cluster.sh does the whole thing. It creates the cluster, installs Argo CD, hands Argo CD five applications and runs the Vault setup at the end.

  • Headlamp as the cluster UI
  • cert-manager
  • kube-prometheus-stack, with Prometheus, Grafana and Alertmanager
  • Vault in HA mode, with Raft storage and three replicas
  • friendlyhello, a small Flask and Redis demo app deployed from a Helm chart in the same repo, which reads a secret from Vault

Traefik comes with K3s and handles ingress on host port 8080. Once everything is up, these are the addresses.

ServiceURL
Argo CDhttps://localhost:30080
Headlamphttp://localhost:30090
Grafanahttp://grafana.localhost:8080
friendlyhellohttp://friendlyhello.localhost:8080

In both labs Headlamp logs in by itself with a lab-only service account that has cluster-admin rights. That’s convenient on a laptop and a terrible idea anywhere else.

On a laptop with less memory, empty the apps array and bring things up one by one with deploy.sh. It applies an application and waits until Argo CD reports it as Healthy before it returns, so you see a stuck chart straight away.

./deploy.sh cert-manager
./deploy.sh kube-prometheus-stack
./deploy.sh vault
./scripts/vault-setup.sh    # init, unseal, KV v2, Kubernetes auth, demo secret
./deploy.sh friendlyhello

The same script can also deploy a few extras that aren’t in the default list, like Ollama and Open WebUI.

Vault starts sealed, which means it can’t read its own data until someone unlocks it with the unseal keys. vault-setup.sh initialises it, unseals the three replicas, turns on the KV secrets engine and Kubernetes authentication, and writes a demo secret. After that, the Vault demo is one Git commit away. You set vault.enabled to true in the friendlyhello chart values, commit, and Argo CD redeploys the app with a Vault Agent sidecar (a helper container in the same pod) that fetches the secret. Argo CD watches my repository, so to do this yourself, fork it first and change repoURL in argocd/friendlyhello.yaml to point at your fork.

The lab also covers taking an etcd snapshot of the K3s control plane.

docker exec k3d-k3s-lab-server-0 k3s etcd-snapshot save --name lab-snap \
  --dir /var/lib/rancher/k3s/server/db/snapshots

If you take the topology as a model, keep one detail in mind. Two servers are enough to practise with a multi-server control plane, and high availability needs three. etcd needs a majority of its members to agree, and with two members a majority is both of them, so losing either one stops the cluster. That’s why production control planes use three or five, and k3d prints a warning about it when you create the lab.

Design decisions

I use GitOps even on my laptop. It’s the same workflow I use on real clusters, so I practise it every day and the habits are already there when it matters.

Each Argo CD Application lives in its own file. That makes them easy to read, add and remove, and the file name doubles as the app name in the scripts.

The Argo CD manifest and the chart versions are pinned in the repo. The bootstrap doesn’t download whatever the latest version happens to be that day, so the lab comes up the same way every time. The flip side is that pinned versions get old, and every now and then I have to bump them by hand.

Charts that bring their own CRDs (custom resource definitions, the way a chart teaches Kubernetes new kinds of object), like cert-manager and Prometheus, can fail in creative ways if everything lands at once. Argo CD retries until things settle, and deploy.sh is there for the times I want to watch each step.

Secrets stay out of Git. Vault’s unseal keys and root token go to ~/k3s-lab-vault-init.json, outside the repo. Lose that file and the Vault is gone for good, which is exactly what would happen in production.

What broke along the way

Most of my bootstrap failures were about order. CRDs have to exist before the resources that use them, controllers before their configuration, and Vault has to be unsealed before anything asks it for a secret. Waiting for each piece is slower than firing everything at once and hoping, and it’s far more reliable.

A laptop also has limits. Two servers, two agents, Prometheus and three Vault replicas need a fair amount of memory, so I size the lab to the experiment.

Once rebuilding takes a few minutes, I stop worrying about breaking things, and that’s when a lab gets used.

Next

The next part of the Wazuh series starts from the same pattern, with a kind cluster and Argo CD, and then deploys a whole SIEM from Git. In the meantime, both repos are yours to fork. Change the apps array and make them your own.


Sources

Share on LinkedIn

← All posts · Archive