Skip to main content

Containers and Kubernetes · Beginner · 14 min

How to Run Your First Kubernetes Cluster Locally with kind

By Padding · Updated 15 Nov 2026
Kubernetes 1.37 · kind 0.33 · Docker Engine 29

You will create a one-node Kubernetes 1.37 cluster inside Docker with kind, talk to it with kubectl, run a pod from a public image and from an image built on your own machine, and delete the cluster when you are done.

On this page

Kubernetes runs containers across many machines and keeps them running. You do not need many machines to learn it. kind (Kubernetes in Docker) starts each Kubernetes node as a Docker container, so a full cluster fits on a laptop and disappears with one command. It is built for testing and learning, not for production traffic.

In this tutorial you will install kind and kubectl, create a cluster, look at what is running in it, start a pod, and load a locally built image into the cluster. It is the fourth tutorial in the series From Docker to Kubernetes.

Step 1 · Install kind and kubectl

You need two programs. kind creates the cluster. kubectl is the command-line client for any Kubernetes cluster. Both are single files, so you can download them from the projects' release pages. Binaries installed this way get no automatic updates from your package manager; to upgrade, download the newer file the same way.

On macOS, Homebrew installs both with brew install kind kubectl. On Linux, download the files. The version numbers below are the ones this tutorial was written against: kind 0.33.0 and kubectl 1.37.2. Pick amd64 or arm64 to match uname -m (x86_64 is amd64, aarch64 is arm64):

Bash
ARCH=amd64   # or arm64
curl -fsSLo kind "https://kind.sigs.k8s.io/dl/v0.33.0/kind-linux-$ARCH"
curl -fsSLo kubectl "https://dl.k8s.io/release/v1.37.2/bin/linux/$ARCH/kubectl"
sudo install -m 0755 kind kubectl /usr/local/bin/
rm kind kubectl

The install command copies both files into /usr/local/bin with the right permissions. The project pages publish checksums next to each download (.sha256sum for kind, .sha256 for kubectl) if you want to verify the files.

Check it worked

Bash
kind version
kubectl version --client

kind version prints kind v0.33.0 followed by the Go version and platform. kubectl version --client prints Client Version: v1.37.2. It may also print a Kustomize version.

Step 2 · Create a cluster

The next command downloads a node image of about a gigabyte the first time you run it, so allow a few minutes. It then starts a container, which acts as the cluster's one node, and writes the connection details into ~/.kube/config. If you already have clusters in that file, kind adds an entry and switches kubectl to it. The command pins the node image so that the Kubernetes version does not change under you:

Bash
kind create cluster --name demo --image kindest/node:v1.37.0 --wait 120s

--name demo names the cluster, and its kubectl context is kind-demo. --wait 120s holds the command until the control plane reports ready. kind 0.33's default node image is this same v1.37.0, so omitting --image gives the same result today; naming it makes the version part of your notes.

Check it worked

Bash
kubectl cluster-info --context kind-demo
kubectl get nodes
docker ps --filter name=demo-control-plane --format '{{.Names}}  {{.Status}}'

kubectl get nodes lists one node, demo-control-plane, with status Ready and version v1.37.0. The last command shows the Docker container behind it. That is all a kind node is.

Troubleshooting

  • ERROR: failed to create cluster: ... Cannot connect to the Docker daemon: Docker is not running, or your user may not use it. Start Docker, and on Linux check docker ps works without sudo.
  • The command hangs or fails with timeouts on a small machine: Docker needs the 2 CPUs and 4 GB of memory listed in the prerequisites for one node. On Docker Desktop or Colima, raise the resources.
  • kubectl talks to a different cluster: run kubectl config current-context. Switch with kubectl config use-context kind-demo, or add --context kind-demo to each command.
  • Use kind get clusters to list clusters and kind delete cluster --name demo to remove one that failed halfway.

Step 3 · Look around the cluster

Kubernetes keeps its own components running as pods in a namespace called kube-system. List them:

Bash
kubectl get pods --namespace kube-system

You see pods for the API server, the scheduler, the controller manager, etcd (the cluster's database), the DNS service (coredns), the network proxy (kube-proxy) and kind's networking and storage helpers. All are Running; a pod such as coredns may show 0/1 ready for a few seconds after the cluster starts. Your own work goes into the default namespace, which is empty:

Bash
kubectl get pods
kubectl get namespaces

The first command prints No resources found in default namespace.. The second lists default, kube-system, kube-public, kube-node-lease and one namespace added by kind for its storage helper.

Step 4 · Run a pod

A pod is the smallest thing Kubernetes runs: one or more containers that share a network address. Start one from a public image. kubectl run creates a pod, and --port only records the port the container uses:

Bash
kubectl run web --image=nginx:1.30-alpine --port=80
kubectl wait --for=condition=Ready pod/web --timeout=120s
kubectl get pod web -o wide

The pod is Running with 1/1 containers ready and has an IP address from the cluster's private network. That address is not reachable from your computer. To reach the pod without exposing it, forward a local port to it:

Bash
kubectl port-forward pod/web 8080:80

The command keeps running and prints Forwarding from 127.0.0.1:8080 -> 80. Open http://127.0.0.1:8080/ in a browser, or run curl -s http://127.0.0.1:8080/ in a second terminal, and stop the forwarding with Ctrl+C.

The reply is the Nginx welcome page. port-forward listens on 127.0.0.1 by default, so only your computer can use it. Read the pod's logs and events, which are the first places to look when something fails:

Bash
kubectl logs web
kubectl describe pod web | tail -n 8

Delete the pod. A bare pod like this one is not recreated when it is deleted. The next tutorial, /tutorials/deploy-and-expose-an-app-on-kubernetes, uses a Deployment, which restarts pods for you.

Bash
kubectl delete pod web

Step 5 · Load an image from your own machine

The cluster node has its own image store and cannot see the images in your Docker. For a real registry you would push and pull. For a quick test, kind load docker-image copies an image into the node. Here the example builds a tiny image of its own, a stand-in for the one you built in /tutorials/write-a-dockerfile-for-a-node-app, and loads it:

Bash
mkdir my-site
cat > my-site/Dockerfile <<'DOCKER'
FROM nginx:1.30-alpine
RUN echo 'Hello from my own image' > /usr/share/nginx/html/index.html
DOCKER
docker build -t my-site:1 my-site

The image exists only in your Docker. Copy it into the cluster, and start a pod from it:

Bash
kind load docker-image my-site:1 --name demo
kubectl run mine --image=my-site:1 --image-pull-policy=Never
kubectl wait --for=condition=Ready pod/mine --timeout=120s
kubectl get pod mine
kubectl exec mine -- cat /usr/share/nginx/html/index.html

The last command prints Hello from my own image, the line your Dockerfile wrote, which proves the pod runs your image and not the public one.

kind load docker-image has one limit worth knowing: with Docker's containerd image store, an image that you only pulled, and never built, can fail to load with ctr: content digest ... not found. Images that you build yourself, as here, load fine. --image-pull-policy=Never tells the node never to contact a registry for this image, so the pod either uses the loaded copy or fails with ErrImagePull or ErrImageNeverPull. Without the flag, a tag other than latest defaults to using the local copy when present, and latest defaults to always pulling, which fails for an image that exists only on your machine. If you change the image and rebuild, load it again, and use a new tag, because a node does not notice a changed image behind the same tag.

Step 6 · Delete the cluster

Deleting a cluster removes its node container and its entry in ~/.kube/config. Everything you created inside it goes with it:

Bash
kind delete cluster --name demo
kubectl config get-contexts
docker rmi my-site:1

The cluster is gone and kind-demo no longer appears in the context list. The node image stays in Docker for next time. Remove it with docker rmi kindest/node:v1.37.0 if you want the disk space.

Next steps

  • Deploy an app that restarts itself and give it a stable address: /tutorials/deploy-and-expose-an-app-on-kubernetes.
  • Configure an app without rebuilding its image: /tutorials/kubernetes-configmaps-and-secrets.
  • The kind documentation is at kind.sigs.k8s.io, and the kubectl reference is at kubernetes.io/docs/reference/kubectl/.

Need this done for you?

Padding does this work for growing companies, from the first diagnosis to a system that keeps working.

Platform Engineering

Get new tutorials

New tutorials, about twice a month.