Guide to Running Kubernetes with Kind

Introduction

Kind is an open-source tool for running a Kubernetes cluster locally, using Docker containers as cluster nodes. While its primary purpose is enabling users to test Kubernetes on a single machine, developers also use Kind for local development and Continuous Integration (CI).

This tutorial shows you how to install Kind on Linux, macOS, and Windows. It also provides instructions for setting up a development environment with Kind and offers tips for managing your Kind clusters.

Prerequisites

• Go 1.17 or newer installed.
• Docker installed.
• Administrative access to the system.

How to Install Kind

Kind supports all major operating systems – Linux, macOS, and Windows. Below you can find the installation steps for each OS.

Install Kind on Linux

1. Use the curl command to download Kind.

curl -Lo ./kind https://kind.sigs.k8s.io/dl/v0.14.0/kind-linux-amd64

When curl completes the download, the command prompt appears again:

2. Change the binary’s permissions to make it executable.

chmod +x ./kind

3. Move kind to an application directory, such as /bin:

sudo mv ./kind /bin/kind

Install Kind on macOS

1. Kind has two different macOS versions, depending on the CPU’s architecture. If you are installing on an Intel Mac, use the following command to download the correct binary:

[ $(uname -m) = x86_64 ]&& curl -Lo ./kind https://kind.sigs.k8s.io/dl/v0.14.0/kind-darwin-amd64

To deploy on M1 Macs, use the command below:

[ $(uname -m) = arm64 ] && curl -Lo ./kind https://kind.sigs.k8s.io/dl/v0.14.0/kind-darwin-arm64

2. Use chmod to make the binary executable:

chmod +x ./kind

3. Move kind to the recommended directory for user-installed apps:

mv ./kind /usr/local/bin/kind

4. Change the ownership of the directory to provide permissions for your user:

sudo chown -R /usr/local

Install Kind on Windows

1. Download the Windows version of Kind using curl in PowerShell:

curl.exe -Lo kind-windows-amd64.exe https://kind.sigs.k8s.io/dl/v0.14.0/kind-windows-amd64

2. Move the executable to a directory of your choice.

Move-Item .\kind-windows-amd64.exe c:\Kind\kind.exe

Using Kind to Create a Development Environment

With Kind installed on the system, proceed to create a Kubernetes cluster and configure it according to your needs.

The sections below explain how to set up a cluster, connect it to the local development environment and internet, and deploy a service locally.

Create a Cluster

Cluster management options in Kind are accessible through the kind command. Create a cluster by typing:

kind create cluster

The output shows the progress of the operation. When the cluster successfully initiates, the command prompt appears.

The command above bootstraps a Kubernetes cluster named kind. It uses a pre-built node image to create the control plane node.

To create a cluster with a different name, use the --name option.

kind create cluster --name=[cluster-name]

To use a custom node image for the cluster, use the --image option:

kind create cluster --image=[image]

Create Cluster with Worker Nodes

By default, Kind creates the cluster with only one node, which acts as a control plane. If you want to create a multi-node cluster with additional worker nodes, or need three for high availability (HA), follow the steps below:

1. Create a YAML manifest with a text editor.

nano workerNodes.yaml

2. Write the cluster configuration file. In the nodes section, define the node role for each of the nodes. For example, the file below creates a two-node cluster with one control plane and one worker node:

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

Save the file and exit.

3. When creating the cluster, use the --config option to introduce the new cluster configuration:

kind create cluster --name=nodes-test --config=workerNodes.yaml

Kind creates the nodes from the YAML file.

Confirm the cluster deployment with kubectl:

kubectl get nodes

The list shows the nodes are ready.

Check the Created Cluster with get

To see the list of running clusters, run the following command:

kind get clusters

The output is a list of all the clusters you created. The example below shows two clusters, named kind and pnap-test:

Check Cluster Details

To get further details for each cluster, use the cluster-info command and specify the cluster with the --context option.

kubectl cluster-info --context kind-[cluster-name]

The information shown relates to the IP addresses and ports of the control plane and Core DNS.

Delete the Cluster

Delete a Kind-created cluster with the following command:

kind delete cluster

The command above deletes the cluster named kind. To specify the cluster you want to delete, use the --name option.

kind delete cluster --name [cluster-name]

Configure and Deploy an ingress Controller

To enable communication between the cluster and the local environment, the cluster configuration file needs to include declarations that enable an ingress controller.

Follow the steps below to deploy an ingress controller in Kind.

1. Create a YAML file in a text editor.

nano newConfig.yaml

2. Provide the configuration for the cluster. The example manifest below creates a cluster with one control-plane node. Ingress is enabled with the ingress-ready=true statement in the node-labels field. Additionally, container ports are mapped to host ports in the extraPortMappings section.

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

3. Create a cluster with the new configuration.

kind create cluster --config newConfig.yaml

4. Apply the ingress NGINX controller with the following command:

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

The command creates multiple Kubernetes objects. In this configuration, ingress works as the cluster’s reverse proxy and load balancer.

Deploy a Service Locally

When you finish setting up the cluster, test it by deploying a service. The example below shows how to deploy a simple HTTP echo server.

1. Create a YAML manifest.

nano test-deployment.yaml

2. Define the necessary configuration.

kind: Pod
apiVersion: v1
metadata:
  name: test-app
  labels:
    app: test-app
spec:
  containers:
  - name: test-app
    image: hashicorp/http-echo:latest
    args:
    - "-text=The test has been successful!"
---
kind: Service
apiVersion: v1
metadata:
  name: test-service
spec:
  selector:
    app: test-app
  ports:
  - port: 5678
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: test-ingress
spec:
  rules:
  - http:
      paths:
      - pathType: Prefix
        path: "/app"
        backend:
          service:
            name: test-service
            port:
              number: 5678

The example YAML above contains three sections:

• The Pod section provides the name and the Docker image for the pods. The args field contains arguments to run in the container.
• The Service section defines the service and the port it uses.
• The Ingress section sets up networking for the service.

3. Use kubectl to apply the configuration.

kubectl apply -f test-deployment.yaml

The output shows three new objects have been created.

4. Set up port forwarding for the service.

kubectl port-forward service/test-service 5678:5678

5. Open another terminal window and test the deployment by typing:

curl localhost:5678

Kubernetes kind Cheat Sheet

Below you can find some commonly used kind commands for cluster management. The commands are listed for quick reference.

1. Create a cluster:

kind create cluster

2. Use a custom name for the cluster:

kind create cluster --name=[cluster-name]

3. Create a cluster with a custom node image:

kind create cluster --image=[image]

4. Use a custom configuration for the cluster:

kind create cluster --config=[config-yaml]

5. When creating a cluster, assign a waiting time for the control plane to go up:

kind create cluster --wait [time-interval]

6. View the list of the running clusters:

kind get clusters

7. View information about a cluster:

kubectl cluster-info --context kind-[cluster-name]

8. Load a Docker image into a cluster:

kind load docker-image [docker-image-name]

9. Load an image archive into a cluster:

kind load image-archive [tar-archive-location]

10. Export logs:

kind export logs

11. Delete a cluster:

kind delete cluster --name [cluster-name]

Conclusion

After completing this tutorial, you should be able to use Kind to create a local Kubernetes cluster for testing and development purposes.

The article covered the installation process for each operating system Kind supports and provided instructions for setting up and managing a local Kubernetes cluster.