Mastering Kind: Build, Configure, and Scale Kubernetes Clusters with Docker

What Is Kind?

Kind is a convenient tool for creating Kubernetes test clusters using Docker containers as nodes, allowing you to run Kubernetes locally for testing purposes.

Kind Architecture

Kind runs a Docker container that acts as a Kubernetes node and installs the necessary Kubernetes components inside that container.

The network model connects each virtual machine and Kind node via a Docker bridge, enabling communication between multiple nodes.

Network Details

Inside a Kind node, the default point‑to‑point (ptp) model uses a veth pair for container‑to‑node communication.

# docker network ls
NETWORK ID          NAME                DRIVER              SCOPE
0912809efeab        bridge              bridge              local
3b3ab0cdd358        host                host                local
198d0909f9cf        kind                bridge              local
b0e304ef061c        none                null                local

# cat /etc/cni/net.d/10-kindnet.conflist
{
  "cniVersion": "0.3.1",
  "name": "kindnet",
  "plugins": [
    {
      "type": "ptp",
      "ipMasq": false,
      "ipam": {
        "type": "host-local",
        "dataDir": "/run/cni-ipam-state",
        "routes": [{"dst": "0.0.0.0/0"}],
        "ranges": [[{"subnet": "10.244.0.0/24"}]]
      }
    },
    {
      "type": "portmap",
      "capabilities": {"portMappings": true}
    }
  ]
}

# ip route
default via 172.18.0.1 dev eth0
10.244.0.2 dev vethc85f5947 scope host
10.244.0.3 dev vetheb946a41 scope host
10.244.0.4 dev veth46c994ce scope host
172.18.0.0/16 dev eth0 proto kernel scope link src 172.18.0.2

Creating a Cluster

Install kubectl.

Install the kind binary:

curl -Lo ./kind https://kind.sigs.k8s.io/dl/v0.9.0/kind-linux-amd64
chmod +x ./kind
mv ./kind /usr/local/bin/kind

Create a cluster (default name kind): kind create cluster Use --name to specify a custom name, e.g., kind create cluster --name mycluster.

Specify a node image for offline installs:

kind create cluster --image kindest/node:latest

Interacting with Clusters

List clusters:

# kind get clusters
kind
kind-2

Switch context:

# kubectl cluster-info --context kind-kind
# kubectl cluster-info --context kind-kind-2

Loading Images into Kind Nodes

Because Kind nodes use their own Docker images, you must load images manually when the node cannot pull from the internet:

# kind load docker-image nginx --name kind

Configuring Kind Clusters

You can provide a YAML configuration file with --config to customize the cluster.

Multi‑Node Cluster

Using the official kind-config.yaml you can create a control‑plane node plus three worker nodes:

kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
kubeadmConfigPatches:
- |
  apiVersion: kubelet.config.k8s.io/v1beta1
  kind: KubeletConfiguration
  evictionHard:
    nodefs.available: "0%"
kubeadmConfigPatchesJSON6902:
- group: kubeadm.k8s.io
  version: v1beta2
  kind: ClusterConfiguration
  patch: |
    - op: add
      path: /apiServer/certSANs/-
      value: my-hostname
nodes:
- role: control-plane
- role: worker
- role: worker
- role: worker

# kind create cluster --name multi-node --config=kind-config.yaml

# kubectl cluster-info --context kind-multi-node

# kubectl get node
NAME                       STATUS   ROLES    AGE     VERSION
multi-node-control-plane   Ready    master   7m57s   v1.19.1
multi-node-worker          Ready    <none>   7m21s   v1.19.1
multi-node-worker2         Ready    <none>   7m21s   v1.19.1
multi-node-worker3         Ready    <none>   7m21s   v1.19.1

Multi‑Control‑Plane

For high‑availability you can create three control‑plane nodes and three workers:

# kind create cluster --config=multi-controlplane.yaml

# kubectl get node
NAME                  STATUS   ROLES    AGE   VERSION
kind-control-plane    Ready    master   15m   v1.19.1
kind-control-plane2   Ready    master   14m   v1.19.1
kind-control-plane3   Ready    master   13m   v1.19.1
kind-worker           Ready    <none>   12m   v1.19.1
kind-worker2          Ready    <none>   12m   v1.19.1
kind-worker3          Ready    <none>   12m   v1.19.1

Specifying Kubernetes Version

Choose a node image tag that includes the desired Kubernetes version, e.g.:

kindest/node:v1.19.1@sha256:98cf5288864662e37115e362b23e4369c8c4a408f99cbc06e58ac30ddc721600

kind:
  Cluster
apiVersion: kind.x-k8s.io/v1alpha4
nodes:
- role: control-plane
  image: kindest/node:v1.16.4@sha256:b91a2c2317a000f3a783489dfb755064177dbc3a0b2f4147d50f04825d016f55
- role: worker
  image: kindest/node:v1.16.4@sha256:b91a2c2317a000f3a783489dfb755064177dbc3a0b2f4147d50f04825d016f55

Mapping Node Ports to the Host

Expose container ports on the host using extraPortMappings:

kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
nodes:
- role: control-plane
  extraPortMappings:
  - containerPort: 80
    hostPort: 80
    listenAddress: "0.0.0.0"
    protocol: tcp

Ingress Deployment

Kind can forward host traffic to an ingress controller via extraPortMappings. Supported ingress controllers include Ambassador, Contour, and NGINX.

Deploy NGINX Ingress

kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/static/provider/kind/deploy.yaml

If the ingress-nginx-admission secret cannot be created, load the required images manually with kind load docker-image and re‑apply the manifest.

Testing Ingress

Create sample applications and services, then an Ingress resource:

kind: Pod
apiVersion: v1
metadata:
  name: foo-app
  labels:
    app: foo
spec:
  containers:
  - name: foo-app
    image: hashicorp/http-echo:0.2.3
    args: ["-text=foo"]
---
kind: Service
apiVersion: v1
metadata:
  name: foo-service
spec:
  selector:
    app: foo
  ports:
  - port: 5678
---
kind: Ingress
apiVersion: networking.k8s.io/v1beta1
metadata:
  name: example-ingress
spec:
  rules:
  - http:
      paths:
      - path: /foo
        backend:
          serviceName: foo-service
          servicePort: 5678

After applying, you can reach the services from the host, e.g.:

curl 192.168.100.11/foo   # returns "foo"
curl 192.168.100.11/bar   # returns "bar"

Summary

Kind is a fast, Docker‑based Kubernetes deployment tool that simplifies creating single‑node or multi‑node clusters, supports custom configurations, multi‑control‑plane setups, and ingress testing. Its limitations include lack of in‑place upgrades and the need to manually load images for offline environments.

FAQ

Cluster switching error: If you see “The connection to the server localhost:8080 was refused”, verify the context name in ~/.kube/config and switch with kubectl config use-context kind‑kind .

Changing the API server address: By default Kind uses 127.0.0.1. To expose it externally, set apiServerAddress and optionally apiServerPort in the cluster config.

Network conflicts: Ensure no other Docker networks interfere with Kind’s bridge network.