Integration Testing with kind: Kubernetes in Docker
kind (Kubernetes IN Docker) runs a real Kubernetes cluster inside Docker containers. It is the standard tool for Kubernetes integration testing in CI — fast to create, cheap to run, identical to production API behavior. This post shows how to use it effectively.
Unit testing Kubernetes manifests with helm-unittest or kuttl dry-runs is fast and catches configuration bugs. But there is a class of problem that only surfaces when you actually deploy your workload to a running cluster: RBAC misconfiguration, missing CRDs, service discovery failures, admission webhook rejections, PodDisruptionBudgets blocking updates. For these, you need a real Kubernetes API server.
kind (Kubernetes IN Docker) gives you exactly that, without the cost or complexity of a cloud cluster. It runs multi-node Kubernetes clusters as Docker containers on your laptop or in CI. The entire control plane — API server, etcd, controller manager, scheduler — runs in a single container or across multiple containers. Cluster creation takes 60–90 seconds. Teardown is instant.
Why kind Over Alternatives
Minikube spins up a VM (or Docker container in recent versions). It is heavier and slower to provision than kind, and the single-node architecture makes it harder to test scheduling behavior.
k3s/k3d is production-grade Kubernetes with a smaller footprint. Good for edge deployments, but its stripped-down API surface means some standard Kubernetes behavior is different from upstream.
Cloud clusters (EKS, GKE, AKS) are real production clusters. Use them for final validation and production deployments, not for every PR build. Cost, network latency, and provisioning time make them impractical as a CI feedback loop.
kind runs upstream Kubernetes. The API is identical to what you'd get from EKS or GKE. It is maintained by the Kubernetes SIGs team and used for Kubernetes conformance testing itself.
Installing kind
# macOS
brew install kind
# Linux
curl -Lo ./kind https://kind.sigs.k8s.io/dl/v0.23.0/kind-linux-amd64
chmod +x ./kind
sudo mv ./kind /usr/local/bin/kind
# Verify
kind versionYou also need Docker running and kubectl installed.
Creating and Destroying Clusters
Basic usage:
# Create a cluster with default settings
kind create cluster
# Create with a specific name (useful in CI for parallel runs)
kind create cluster --name integration-test
# List clusters
kind get clusters
# Delete
kind delete cluster --name integration-testA cluster is ready to use immediately after create returns. kubectl is automatically configured to talk to it via a context named kind-<clustername>.
Cluster Configuration
For integration testing, you often want more control over the cluster topology and settings. Use a kind-config.yaml:
# kind-config.yaml
kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
name: integration-test
nodes:
- role: control-plane
kubeadmConfigPatches:
- |
kind: InitConfiguration
nodeRegistration:
kubeletExtraArgs:
node-labels: "ingress-ready=true"
extraPortMappings:
- containerPort: 80
hostPort: 8080
protocol: TCP
- containerPort: 443
hostPort: 8443
protocol: TCP
- role: worker
- role: workerThis gives you a 3-node cluster (1 control-plane, 2 workers) with port mappings for an ingress controller.
Create it:
kind create cluster --config kind-config.yamlLoading Local Images
In CI, you build Docker images locally and need to push them into the kind cluster without going through a registry. kind provides a direct load mechanism:
# Build your image
docker build -t myapp:test .
# Load it into the kind cluster
kind load docker-image myapp:test --name integration-testAfter loading, you can reference myapp:test in your manifests with imagePullPolicy: Never (to prevent Kubernetes from trying to pull from a registry):
containers:
- name: app
image: myapp:test
imagePullPolicy: NeverThis is faster than pushing to a registry and pulling back, and it works entirely offline.
Setting Up NGINX Ingress in kind
Most integration tests need an ingress controller to test HTTP routing. Install NGINX ingress configured for kind:
kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/deploy/static/provider/kind/deploy.yaml
# Wait for it to be ready
kubectl wait --namespace ingress-nginx \
--for=condition=ready pod \
--selector=app.kubernetes.io/component=controller \
--timeout=90sWith the port mapping in the cluster config, requests to localhost:8080 reach the ingress controller.
Deploying and Testing Your Application
Here is a complete integration test flow using shell scripts:
#!/bin/bash
set -e
CLUSTER_NAME=integration-test
IMAGE_TAG=myapp:test-$(git rev-parse --short HEAD)
echo "=== Building image ==="
docker build -t $IMAGE_TAG .
echo "=== Creating kind cluster ==="
kind create cluster --name $CLUSTER_NAME --config kind-config.yaml
# Ensure cleanup on exit
trap "kind delete cluster --name $CLUSTER_NAME" EXIT
echo "=== Loading image ==="
kind load docker-image $IMAGE_TAG --name $CLUSTER_NAME
echo "=== Deploying application ==="
# Substitute image tag in manifests
sed "s|IMAGE_TAG|$IMAGE_TAG|g" k8s/deployment.yaml | kubectl apply -f -
kubectl apply -f k8s/service.yaml
kubectl apply -f k8s/ingress.yaml
echo "=== Waiting for deployment ==="
kubectl wait deployment/myapp \
--for=condition=Available \
--timeout=120s
echo "=== Running integration tests ==="
# Your test runner here
go test ./integration/... -tags integration -v
echo "=== All tests passed ==="A Multi-Service Integration Test
Integration tests shine when you have multiple services that need to talk to each other. Here is a more realistic example with an API server, a background worker, and a PostgreSQL database:
# k8s/postgres.yaml
apiVersion: v1
kind: Service
metadata:
name: postgres
spec:
selector:
app: postgres
ports:
- port: 5432
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: postgres
spec:
replicas: 1
selector:
matchLabels:
app: postgres
template:
metadata:
labels:
app: postgres
spec:
containers:
- name: postgres
image: postgres:16
env:
- name: POSTGRES_DB
value: testdb
- name: POSTGRES_USER
value: test
- name: POSTGRES_PASSWORD
value: test
readinessProbe:
exec:
command: ["pg_isready", "-U", "test"]
periodSeconds: 2# Wait for postgres to be ready before deploying app
kubectl wait deployment/postgres \
--for=condition=Available \
--timeout=60s
# Deploy the API server (which depends on postgres)
kubectl apply -f k8s/api-server.yaml
kubectl wait deployment/api-server \
--for=condition=Available \
--timeout=120sYour integration tests then run against localhost:8080 (via the ingress port mapping) and exercise the full stack.
GitHub Actions Workflow
This is a production-ready GitHub Actions workflow for kind-based integration testing:
name: Integration Tests
on:
push:
branches: [main]
pull_request:
jobs:
integration-test:
runs-on: ubuntu-latest
timeout-minutes: 20
steps:
- uses: actions/checkout@v4
- name: Set up Go
uses: actions/setup-go@v5
with:
go-version: '1.22'
- name: Set up kind
uses: helm/kind-action@v1.10.0
with:
cluster_name: integration-test
config: kind-config.yaml
version: v0.23.0
- name: Build Docker image
run: |
docker build -t myapp:ci .
- name: Load image into kind
run: |
kind load docker-image myapp:ci --name integration-test
- name: Install NGINX Ingress
run: |
kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/deploy/static/provider/kind/deploy.yaml
kubectl wait --namespace ingress-nginx \
--for=condition=ready pod \
--selector=app.kubernetes.io/component=controller \
--timeout=90s
- name: Deploy application
run: |
kubectl apply -f k8s/
kubectl wait deployment/myapp \
--for=condition=Available \
--timeout=120s
- name: Run integration tests
run: go test ./integration/... -tags integration -v -timeout 10m
- name: Collect logs on failure
if: failure()
run: |
kubectl get pods -A
kubectl describe pods -l app=myapp
kubectl logs -l app=myapp --tail=100The helm/kind-action handles kind installation and cluster creation. On failure, the workflow collects pod logs — essential for debugging CI failures without SSH access.
Parallel Test Isolation
When multiple PRs run in parallel, cluster names must be unique to avoid conflicts:
- name: Set cluster name
run: echo "CLUSTER_NAME=ci-${{ github.run_id }}-${{ github.run_attempt }}" >> $GITHUB_ENV
- name: Create cluster
run: kind create cluster --name $CLUSTER_NAME
- name: Delete cluster
if: always()
run: kind delete cluster --name $CLUSTER_NAMEUsing github.run_id and github.run_attempt ensures uniqueness across concurrent runs and reruns.
Testing RBAC
kind is excellent for testing RBAC configurations because you can create ServiceAccounts and verify their permissions:
# Create a service account for your app
kubectl create serviceaccount myapp-sa
# Apply RBAC rules
kubectl apply -f k8s/rbac.yaml
# Test that the service account has expected permissions
kubectl auth can-i get pods --as=system:serviceaccount:default:myapp-sa
kubectl auth can-i delete pods --as=system:serviceaccount:default:myapp-sa
# Should print "no" — if it prints "yes", RBAC is too permissive
# Test that it lacks unexpected permissions
RESULT=$(kubectl auth can-i create deployments \
--as=system:serviceaccount:default:myapp-sa 2>&1)
if [ "$RESULT" = "no" ]; then
echo "PASS: service account cannot create deployments"
else
echo "FAIL: service account has unexpected create permission"
exit 1
fiThis catches privilege escalation bugs that static analysis tools miss.
Resource and Performance Considerations
kind clusters are lightweight but not free. In CI:
- A 1-node cluster uses ~500MB RAM and starts in ~60 seconds
- A 3-node cluster uses ~1.2GB RAM and starts in ~90 seconds
- GitHub Actions free tier has 7GB RAM — easily fits 2–3 concurrent kind clusters
If your integration tests are slow, profile what's taking time. Common culprits:
- Image pulls (use
kind loadinstead of registry pulls) sleepinstead ofkubectl wait(replace with wait conditions)- Sequential test setup (parallelize with namespaces per test suite)
- Cluster recreation for every test (reuse the cluster, use namespaces for isolation)
Summary
kind gives you a real Kubernetes environment with zero cloud cost and 90-second startup. Use it for any test that requires actual Kubernetes behavior: RBAC validation, admission webhooks, service discovery, multi-service integration, ingress routing. The GitHub Actions integration is straightforward. The cluster is ephemeral by design — create it, test in it, delete it. There is no shared state to pollute between runs.