Integration Testing with kind: Kubernetes in Docker

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 version

You 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-test

A 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: worker

This 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.yaml

Loading 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-test

After 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: Never

This 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=90s

With 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=120s

Your 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=100

The 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_NAME

Using 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
fi

This 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 load instead of registry pulls)
  • sleep instead of kubectl 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.

Read more

Start now free