KinD (Kubernetes in Docker) Guide for Ubuntu

This guide will walk you through installing, configuring, and using KinD - a tool for running local Kubernetes clusters using Docker container nodes.

Table of Contents

• Installation
• Basic Usage
• Cluster Configuration
• Use Cases
  • Multi-Node Cluster
  • Exposing Services
  • Loading Docker Images
  • Testing Kubernetes Resources
  • CI/CD Integration
• Troubleshooting
• Additional Resources

Installation

Prerequisites

• Ubuntu operating system
• Docker installed and configured

If you don't have Docker installed yet, you can install it with:

# Update package index
sudo apt-get update

# Install prerequisites
sudo apt-get install -y \
    apt-transport-https \
    ca-certificates \
    curl \
    gnupg \
    lsb-release

# Add Docker's official GPG key
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

# Set up the stable repository
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Install Docker Engine
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io

# Add your user to the docker group to run Docker without sudo
sudo usermod -aG docker $USER

You'll need to log out and log back in for the group changes to take effect.

Install KinD

There are multiple ways to install KinD:

Option 1: Using Go:

# If you have Go 1.17+ installed:
go install sigs.k8s.io/kind@latest

Option 2: Using binary download:

# For AMD64 / x86_64
curl -Lo ./kind https://kind.sigs.k8s.io/dl/v0.20.0/kind-linux-amd64
chmod +x ./kind
sudo mv ./kind /usr/local/bin/kind

Option 3: Using brew:

# If you have Homebrew installed on Linux
brew install kind

Verify the installation:

kind version

Install kubectl

KinD requires kubectl to interact with the Kubernetes cluster:

curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
chmod +x kubectl
sudo mv kubectl /usr/local/bin/

Verify kubectl installation:

kubectl version --client

Basic Usage

Create a Cluster

The simplest way to create a cluster:

kind create cluster

This creates a single-node cluster named "kind".

To create a cluster with a specific name:

kind create cluster --name my-cluster # mine is named "sandbox"

Interact with the Cluster

KinD automatically configures kubectl to use the newly created cluster:

# List your nodes
kubectl get nodes

# Get cluster info
kubectl cluster-info

kubectl cluster-info --context kind-sandbox

# View all pods in the cluster
kubectl get pods -A

Delete a Cluster

To delete the cluster:

kind delete cluster

Or for a specific cluster:

kind delete cluster --name my-cluster

Cluster Configuration

KinD allows you to customize your clusters using YAML configuration files.

Example: Basic Config File

Create a file named kind-config.yaml:

kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
nodes:
  - role: control-plane
  - role: worker
  - role: worker

Create a cluster using this config:

kind create cluster --config kind-config.yaml

Example: Advanced Configuration

Create a file named kind-advanced-config.yaml:

kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
nodes:
  - role: control-plane
    kubeadmConfigPatches:
      - |
        kind: InitConfiguration
        nodeRegistration:
          kubeletExtraArgs:
            node-labels: "ingress-ready=true"
    extraPortMappings:
      - containerPort: 80
        hostPort: 80
        protocol: TCP
      - containerPort: 443
        hostPort: 443
        protocol: TCP
  - role: worker
  - role: worker

Create a cluster with this advanced config:

kind create cluster --config kind-advanced-config.yaml

Use Cases

Multi-Node Cluster

Create a file named multi-node.yaml:

kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
nodes:
  - role: control-plane
  - role: worker
  - role: worker
  - role: worker

Create the multi-node cluster:

kind create cluster --name multi-node-demo --config multi-node.yaml

Verify the nodes:

kubectl get nodes

Exposing Services

1. Create a cluster with port mapping:

# port-mapping.yaml
kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
nodes:
  - role: control-plane
    extraPortMappings:
      - containerPort: 30000
        hostPort: 8080

2. Create the cluster:

kind create cluster --config port-mapping.yaml

3. Deploy a sample application:

kubectl create deployment nginx --image=nginx
kubectl expose deployment nginx --port=80 --target-port=80 --type=NodePort

4. Update the NodePort to use our mapped port:

kubectl patch service nginx -p '{"spec":{"ports":[{"port":80,"nodePort":30000}]}}'

5. Access the service at http://localhost:8080

Loading Docker Images

When working with local images, you need to load them into your KinD cluster:

1. Build a Docker image:

docker build -t my-custom-app:latest .

2. Load the image into KinD:

kind load docker-image my-custom-app:latest

3. Deploy using the loaded image:

kubectl create deployment my-app --image=my-custom-app:latest

Testing Kubernetes Resources

KinD is perfect for testing Kubernetes manifests and operators:

1. Create a test cluster:

kind create cluster --name test-cluster

2. Apply your Kubernetes manifests:

kubectl apply -f my-deployment.yaml
kubectl apply -f my-service.yaml

3. Verify resources:

kubectl get all

4. Test functionality and then tear down:

kind delete cluster --name test-cluster

CI/CD Integration

Here's an example GitHub Actions workflow using KinD:

name: KinD CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  kubernetes-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Create KinD cluster
        uses: engineerd/setup-kind@v0.5.0
        with:
          version: "v0.20.0"

      - name: Test cluster
        run: |
          kubectl cluster-info
          kubectl get nodes

      - name: Build Docker image
        run: docker build -t my-app:test .

      - name: Load image to KinD
        run: kind load docker-image my-app:test

      - name: Deploy to KinD
        run: |
          kubectl apply -f k8s/deployment.yaml
          kubectl rollout status deployment/my-app

      - name: Run tests
        run: ./run-tests.sh

Troubleshooting

Cluster Creation Fails

If cluster creation fails, try:

# Check Docker status
systemctl status docker

# Make sure you have enough disk space
df -h

# View KinD logs
kind create cluster --name debug-cluster -v 1

Unable to Connect to Cluster

If kubectl can't connect to the cluster:

# Check cluster status
kind get clusters

# Re-export kubeconfig
kind export kubeconfig --name my-cluster

# Check kubectl context
kubectl config current-context

Resource Limitations

If your nodes show "NotReady":

# Check system resources
free -h
docker info

# You may need to increase Docker's memory limits

Additional Resources

• KinD Official Documentation
• KinD GitHub Repository
• Kubernetes Documentation

---

This guide covers the basics of using KinD on Ubuntu. As you get more comfortable, explore more advanced configurations and integrations with your development workflow.