Kind (Kubernetes in Docker)

intermediate

Run local Kubernetes clusters using Docker containers.

Overview

Kind (Kubernetes in Docker) is a tool for running local Kubernetes clusters using Docker container nodes. Originally developed by the Kubernetes community for testing Kubernetes itself, kind creates fully functional Kubernetes clusters where each node runs inside a Docker container. This approach eliminates the need for virtual machines or complex local setups while providing an authentic Kubernetes environment for development and testing. The kindest/node image contains all necessary Kubernetes components including kubelet, kubeadm, and containerd runtime. This Docker Compose configuration deploys a single-node Kubernetes cluster using the kindest/node container image with privileged access and necessary system mounts. The setup exposes the Kubernetes API server on port 6443 and reserves a range of NodePort services (30000-30100) for application access. The container requires privileged mode and access to kernel modules to properly simulate a Kubernetes node environment, making it ideal for local development workflows that need authentic Kubernetes behavior. Developers building Kubernetes-native applications, platform engineers testing operators, and DevOps teams validating deployment manifests will find this stack invaluable. Unlike minikube or microk8s, kind excels at creating reproducible clusters that can be easily created, destroyed, and version-controlled through configuration files. The containerized approach means multiple isolated clusters can run simultaneously, each with different Kubernetes versions or configurations, making it perfect for testing compatibility across Kubernetes releases.

Key Features

Multi-version Kubernetes support with kindest/node images for different K8s releases
Privileged container execution enabling full kubelet and container runtime functionality
Kernel module access through /lib/modules mount for networking and storage drivers
NodePort service range (30000-30100) exposure for testing external application access
Persistent cluster state storage via Docker volume for node configuration and etcd data
Kubernetes API server accessibility on standard port 6443 for kubectl and client connections
Container runtime isolation using seccomp=unconfined for authentic Kubernetes behavior
Compatible with kind CLI for advanced cluster management and image loading operations

Common Use Cases

1Local development of Kubernetes operators and custom resource definitions
2CI/CD pipeline testing for Kubernetes manifests and Helm charts before production deployment
3Multi-cluster application testing by running several isolated kind instances simultaneously
4Kubernetes version compatibility validation across different release channels
5Educational environments for learning Kubernetes concepts without cloud costs
6Integration testing for applications that require authentic Kubernetes APIs and behavior
7Development of Kubernetes-native tools requiring real cluster interactions

Prerequisites

Docker Desktop or Docker Engine with at least 4GB RAM allocated for container operations
Kind CLI tool installed locally for cluster management and configuration
Kubectl client configured for Kubernetes cluster interaction and resource management
Host system with sufficient disk space (minimum 2GB) for Kubernetes node image and data
Understanding of Kubernetes concepts including pods, services, and basic cluster architecture
Administrative privileges for Docker daemon access and privileged container execution

For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

docker-compose.yml

1services: 
2  kind-control-plane: 
3    image: kindest/node:v1.29.0
4    container_name: kind-control-plane
5    hostname: kind-control-plane
6    restart: unless-stopped
7    privileged: true
8    security_opt: 
9      - seccomp=unconfined
10    volumes: 
11      - /lib/modules:/lib/modules:ro
12      - kind_data:/var
13    ports: 
14      - "6443:6443"
15      - "30000-30100:30000-30100"
16
17volumes: 
18  kind_data:

.env Template

.env

1# Use kind CLI for full cluster management
2# This provides the base node image

Usage Notes

1Docs: https://kind.sigs.k8s.io/docs/
2Install CLI: brew install kind (or download binary)
3Create cluster: kind create cluster --name my-cluster
4Multi-node: kind create cluster --config kind-config.yaml
5Load local images: kind load docker-image myimage:tag --name my-cluster
6Preferred tool for K8s CI testing - used by Kubernetes itself

Quick Start

terminal

1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  kind-control-plane:
5    image: kindest/node:v1.29.0
6    container_name: kind-control-plane
7    hostname: kind-control-plane
8    restart: unless-stopped
9    privileged: true
10    security_opt:
11      - seccomp=unconfined
12    volumes:
13      - /lib/modules:/lib/modules:ro
14      - kind_data:/var
15    ports:
16      - "6443:6443"
17      - "30000-30100:30000-30100"
18
19volumes:
20  kind_data:
21EOF
22
23# 2. Create the .env file
24cat > .env << 'EOF'
25# Use kind CLI for full cluster management
26# This provides the base node image
27EOF
28
29# 3. Start the services
30docker compose up -d
31
32# 4. View logs
33docker compose logs -f

One-Liner

Run this command to download and set up the recipe in one step:

terminal

1curl -fsSL https://docker.recipes/api/recipes/kind/run | bash

Troubleshooting

kind-control-plane container exits with 'failed to create cluster': Ensure Docker has sufficient memory allocation and restart Docker daemon
kubectl connection refused on port 6443: Wait for cluster initialization to complete or check if kubeconfig context points to correct endpoint
NodePort services unreachable from host: Verify port range 30000-30100 is not blocked by firewall or conflicting with other services
Container stuck in 'starting' state: Check Docker logs for missing kernel modules or insufficient container privileges
kind load docker-image fails with permission denied: Ensure kind CLI version matches cluster version and Docker daemon is accessible
Persistent volume claims stuck pending: Restart container to reinitialize local storage provisioner in the kindest/node

Community Notes

Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

Components

kind

Related Recipes

Ad Space

Shortcuts: C CopyF FavoriteD Download