Kubernetes in Docker (kind) is a tool that allows you to run Kubernetes clusters locally using Docker container "nodes". It's a great tool for developers who want to test their applications in a Kubernetes environment without the overhead of a full-scale cluster.
In this blog post, we'll walk through the steps to set up a kind cluster with a Docker registry where you can push the images and pull from in the Kubernetes cluster. This will mimic what we would do in Cloud Provider managed Kubernetes clusters i.e. pull the images from OCI registries. We will also look at how to install nginx Ingress and create a LoadBalancer service.
Prerequisites
Ensure you have the following installed on your machine:
- Docker
- kind, there are many ways to install kind, please refer the link to install as you see fit.
- kubectl, we will use this to interact with the cluster.
All the scripts discussed in this blog are uploaded to this github repository.
What are we going to create?
- Multi node kubernetes cluster with
control-planeandworkernodes. Examples of worker nodes withlabelsandtaints. - Create a local registry to push and pull locally built docker images
- Deploy
Ingressso that we can access the endpoints exposed by the services - Validate the setup by installing pods with dummy services
This setup is pretty much what you need to validate your applications locally, this setup will be extremely helpful and cost efficient while developing services for kubernetes environment.
Create k8s cluster with multiple nodes and configure cluster with containerd registry config dir
The following is the Cluster cluster-config.yaml with control-plane and worker nodes. The api-server and other control plane components will be on the node with role control-plane. And nodes with worker role will have your pods. You will observe the controller-manager, api-server, scheduler, etcd, coredns, kindnet, kube-proxy and local-path-provisioner pods will be deployed on the control-plane node by default.
The worker nodes will have kindnet and kube-proxy by default. You will also observe that we are configuring the cluster with containerd registry config.
We are also exposing ports 80/443/5678 so that localhost can hit those port from machine.
kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
name: "platformwale"
# configure cluster with containerd registry config dir enabled
containerdConfigPatches:
- |-
[plugins."io.containerd.grpc.v1.cri".registry]
config_path = "/etc/containerd/certs.d"
nodes:
# control plane node
# this comes with taint so that control-plane node will not accept any other pods by default
- role: control-plane
image: "kindest/node:v1.27.3"
# worker nodes
# worker with no node labels, so pods with no nodeSelectors will schedule here
- role: worker
image: "kindest/node:v1.27.3"
# worker with node label role=app
# pods with nodeSelectors role=app will schedule here
- role: worker
image: "kindest/node:v1.27.3"
labels:
role: app
# worker with node label role=ingress
# pods with nodeSelectors role=ingress and toleration to taint role=ingress:NoSchedule will schedule here
- role: worker
image: "kindest/node:v1.27.3"
labels:
role: ingress
# extraPortMappings allow the localhost to make requests to the Ingress controller over ports 80/443/5678
extraPortMappings:
- containerPort: 80
hostPort: 80
protocol: TCP
- containerPort: 443
hostPort: 443
protocol: TCP
- containerPort: 5678
hostPort: 5678
protocol: TCP
# add taint to the node such that only pods tolerating the taint will be scheduled on this node
kubeadmConfigPatches:
- |
kind: JoinConfiguration
nodeRegistration:
kubeletExtraArgs:
register-with-taints: "role=ingress:NoSchedule"
Create the kind cluster by submitting the cluster-config.yaml file as follows -
kind create cluster --config cluster-config.yaml
You will see something like below on successful creation of kind cluster -
$ kind create cluster --config cluster-config.yaml
Creating cluster "platformwale" ...
✓ Ensuring node image (kindest/node:v1.27.3) 🖼
✓ Preparing nodes 📦 📦 📦 📦
✓ Writing configuration 📜
✓ Starting control-plane 🕹️
✓ Installing CNI 🔌
✓ Installing StorageClass 💾
✓ Joining worker nodes 🚜
Set kubectl context to "kind-platformwale"
You can now use your cluster with:
kubectl cluster-info --context kind-platformwale
Have a question, bug, or feature request? Let us know! https://kind.sigs.k8s.io/#community 🙂
$ kubectl cluster-info --context kind-platformwale
Kubernetes control plane is running at https://127.0.0.1:58931
CoreDNS is running at https://127.0.0.1:58931/api/v1/namespaces/kube-system/services/kube-dns:dns/proxy
To further debug and diagnose cluster problems, use 'kubectl cluster-info dump'.
Validate that you can see the kind cluster you created above -
$ kind get clusters
platformwale
Validate that the nodes are created successfully -
$ kubectl get nodes
NAME STATUS ROLES AGE VERSION
platformwale-control-plane Ready control-plane 9m20s v1.27.3
platformwale-worker Ready <none> 8m55s v1.27.3
platformwale-worker2 Ready <none> 9m1s v1.27.3
platformwale-worker3 Ready <none> 8m56s v1.27.3
Please read this configurationdocumentation to learn more options to configure the KIND cluster.
Create the registry container and configure cluster nodes for the registry
Create the registry container and configure the cluster nodes for registry access as below.
This command will pull the registry container locally and will start the container. This container will be used as the local docker registry.
# start the registry container
reg_name='kind-registry'
reg_port='5001'
if [ "$(docker inspect -f '{{.State.Running}}' "${reg_name}" 2>/dev/null || true)" != 'true' ]; then
docker run \
-d --restart=always -p "127.0.0.1:${reg_port}:5000" --name "${reg_name}" \
registry:2
fi
Now add the registry config to the nodes as below. This is necessary because localhost resolves to loopback addresses that are network-namespace local. In other words, localhost in the container is not localhost on the host. We want a consistent name that works from both ends, so we tell containerd to alias localhost:${reg_port} to the registry container when pulling images.
kind_cluster_name="platformwale"
reg_port='5001'
REGISTRY_DIR="/etc/containerd/certs.d/localhost:${reg_port}"
for node in $(kind get nodes --name ${kind_cluster_name}); do
docker exec "${node}" mkdir -p "${REGISTRY_DIR}"
cat <<EOF | docker exec -i "${node}" cp /dev/stdin "${REGISTRY_DIR}/hosts.toml"
[host."http://${reg_name}:5000"]
EOF
done
Now connect the registry to the cluster network, this allows kind to bootstrap the network and ensure they are on the same network.
reg_name='kind-registry'
if [ "$(docker inspect -f='{{json .NetworkSettings.Networks.kind}}' "${reg_name}")" = 'null' ]; then
docker network connect "kind" "${reg_name}"
fi
Now document the local registry. The standard of defining the local registry is defined in detail in this doc. This is a standard way for cluster configuration tools to record how developer tools should interact with the local registry as well as a standard way for developer tools to read that information when pushing images to the cluster.
reg_port='5001'
cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: ConfigMap
metadata:
name: local-registry-hosting
namespace: kube-public
data:
localRegistryHosting.v1: |
host: "localhost:${reg_port}"
help: "https://kind.sigs.k8s.io/docs/user/local-registry/"
EOF
At this point you have finished creating the cluster as well enabled a local docker registry.
Connect to the Private Registry
We will pull a sample app from the remote docker registry, tag it and push it to the local registry we created above. We will then start the pod using the image pulled from the local registry.
Here's an example:
# pull a sample hello-app from remote registry
docker pull gcr.io/google-samples/hello-app:1.0
# tag the pulled docker image for local registry
docker tag gcr.io/google-samples/hello-app:1.0 localhost:5001/hello-app:1.0
# push the docker image to the local registry
docker push localhost:5001/hello-app:1.0
Submit following yaml to create hello-server deployment to use the hello-app docker image from the local registry.
kubectl apply -f - <<EOF
apiVersion: apps/v1
kind: Deployment
metadata:
labels:
app: hello-server
name: hello-server
namespace: default
spec:
replicas: 1
selector:
matchLabels:
app: hello-server
template:
metadata:
labels:
app: hello-server
spec:
nodeSelector:
role: app
containers:
- image: localhost:5001/hello-app:1.0
imagePullPolicy: IfNotPresent
name: hello-app
EOF
Validate that the pod is running successfully as below and it runs on platformwale-worker2 node as we have used nodeSelector: role=app -
$ kubectl get po -n default -o wide
NAME READY STATUS RESTARTS AGE IP NODE NOMINATED NODE READINESS GATES
hello-server-bfc485c98-jzxbb 1/1 Running 0 14s 10.244.2.3 platformwale-worker2 <none> <none>
This proves that we have a working kubernetes cluster with multiple nodes as well as we are able to push and pull images from local docker registry.
The local registry can also be used for bootstrapping local development environments faster. Consider you have a big local vagrant or docker-compose setup which pulls huge images, you can setup this local registry on one of the hosted machines in your office network, and then all the engineers in your team can use this registry to pull the images to setup the local environment instead of pulling from public network. This will speed up the environment setup as well as save the network bandwidth.
Deploy Ingress and validate LoadBalancer k8s service
In this section we will deploy nginx Ingress service on the ingress nodepool we created earlier. We will also deploy LoadBalancer k8s service along with sample apps to validate the nginx deployment.
We have modified the public nginx deploy.yaml to tolerate taint -> role:ingress:NoSchedule and use nodeSelector -> role=ingress to deploy the nginx pods on platformwale-worker3 node which we have configured with taints and label such that we only deploy the nginx deployments. Use the modified nginx.yaml as below -
kubectl apply -f https://raw.githubusercontent.com/piyushjajoo/kind-with-local-registry-and-ingress/master/nginx.yaml
Validate all the nginx pods are running -
$ kubectl get pods -n ingress-nginx -o wide
NAME READY STATUS RESTARTS AGE IP NODE NOMINATED NODE READINESS GATES
ingress-nginx-admission-create-4kxmk 0/1 Completed 0 34m 10.244.1.2 platformwale-worker3 <none> <none>
ingress-nginx-admission-patch-kx4zv 0/1 Completed 1 34m 10.244.1.3 platformwale-worker3 <none> <none>
ingress-nginx-controller-57d7c6cb58-g2gdf 1/1 Running 0 34m 10.244.1.4 platformwale-worker3 <none> <none>
Pull following docker image to the local registry, we will use it for the Ingress setup validation as below -
# pull docker image
docker pull hashicorp/http-echo:0.2.3
# tag the image for local registry
docker tag hashicorp/http-echo:0.2.3 localhost:5001/http-echo:0.2.3
# push the docker image
docker push localhost:5001/http-echo:0.2.3
This will also install MetalLB loadbalancer. NOTE: on On macOS and Windows, docker does not expose the docker network to the host. Because of this limitation, containers (including kind nodes) are only reachable from the host via port-forwards, however other containers/pods can reach other things running in docker including loadbalancers. If you are on Mac or Windows, you can skip installing MetalLB.
# install metallb
echo "install metallb"
kubectl apply -f https://raw.githubusercontent.com/metallb/metallb/v0.13.7/config/manifests/metallb-native.yaml
# wait until MetalLB pods (controller and speaker) are ready
echo "wait until MetalLB pods (controller and speaker) are ready"
kubectl wait --namespace metallb-system \
--for=condition=ready pod \
--selector=app=metallb \
--timeout=90s
# find the cidr range for kind network
echo "find the cidr range for the kind network"
output=$(docker network inspect -f '{{.IPAM.Config}}' kind)
ipv4_cidr=$(echo "$output" | grep -oE '([0-9]+\.[0-9]+)\.[0-9]+\.[0-9]+/[0-9]+' | head -n 1)
ipv4_parts=$(echo "$ipv4_cidr" | cut -d '.' -f 1,2)
echo "IPv4 CIDR Range (First 2 Parts): $ipv4_parts"
# configure ip address pool
echo "configuring ip address pool"
kubectl apply -f - <<EOF
apiVersion: metallb.io/v1beta1
kind: IPAddressPool
metadata:
name: example
namespace: metallb-system
spec:
addresses:
- $ipv4_parts.255.200-$ipv4_parts.255.250
---
apiVersion: metallb.io/v1beta1
kind: L2Advertisement
metadata:
name: empty
namespace: metallb-system
EOF
Validate the Ingress object using ClusterIP services as well as validate LoadBalancer type service using the script below. You can skip creating LoadBalancer type service below if you are on Mac or Windows.
The script below will deploy pods and setup Ingress object to divert the traffic to the pods based on path configured.
kubectl apply -f - <<EOF
kind: Pod
apiVersion: v1
metadata:
name: foo-app
labels:
name: foo-app
app: http-echo
spec:
containers:
- name: foo-app
image: localhost:5001/http-echo:0.2.3
args:
- "-text=foo"
---
kind: Pod
apiVersion: v1
metadata:
name: bar-app
labels:
name: bar-app
app: http-echo
spec:
containers:
- name: bar-app
image: localhost:5001/http-echo:0.2.3
args:
- "-text=bar"
---
kind: Service
apiVersion: v1
metadata:
name: foo-service
spec:
selector:
name: foo-app
ports:
# Default port used by the image
- port: 5678
---
kind: Service
apiVersion: v1
metadata:
name: bar-service
spec:
selector:
name: bar-app
ports:
# Default port used by the image
- port: 5678
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: example-ingress
annotations:
nginx.ingress.kubernetes.io/rewrite-target: /$2
spec:
rules:
- http:
paths:
- pathType: Prefix
path: /foo(/|$)(.*)
backend:
service:
name: foo-service
port:
number: 5678
- pathType: Prefix
path: /bar(/|$)(.*)
backend:
service:
name: bar-service
port:
number: 5678
---
kind: Service
apiVersion: v1
metadata:
name: foo-service-lb
spec:
type: LoadBalancer
selector:
name: foo-app
app: http-echo
ports:
# Default port used by the image
- port: 5678
---
kind: Service
apiVersion: v1
metadata:
name: bar-service-lb
spec:
type: LoadBalancer
selector:
name: bar-app
app: http-echo
ports:
# Default port used by the image
- port: 5678
EOF
Validate the Ingress as below -
# validate cluster ips via Ingress object
# should output "foo-app"
echo "validating foo-app via Ingress object"
curl localhost/foo/hostname
# should output "bar-app"
echo "validating bar-app via Ingress object"
curl localhost/bar/hostname
Validate the LoadBalancer service as below, if you are on Mac or Windows, as mentioned earlier docker doesn't expose the docker network to the host, hence you won't be able to use the LoadBalancer IP directly instead you will need to port forward the service to access.
## on linux you can validate LoadBalancer as below
# validate load balancer service
echo "validating loadbalancer, note on macOS and Windows, docker does not expose the docker network to the host. Because of this limitation, containers (including kind nodes) are only reachable from the host via port-forwards, however other containers/pods can reach other things running in docker including loadbalancers"
FOO_LB_IP=$(kubectl get svc/foo-service-lb -n default -o=jsonpath='{.status.loadBalancer.ingress[0].ip}')
BAR_LB_IP=$(kubectl get svc/bar-service-lb -n default -o=jsonpath='{.status.loadBalancer.ingress[0].ip}')
# should output foo and bar on separate lines
for _ in {1..10}; do
curl ${FOO_LB_IP}:5678
curl ${BAR_LB_IP}:5678
done
## on Mac or Windows port-forward and hit the service as below
# validate foo-service-lb
kubectl port-forward -n default svc/foo-service-lb 5678:5678
# in browser hit localhost:5678 or do curl as below, you will see foo as output
$ curl localhost:5678
foo
# validate bar-service-lb
kubectl port-forward -n default svc/bar-service-lb 5678:5678
# in browser hit localhost:5678 or do curl as below, you will see bar as output
$ curl localhost:5678
bar
To setup LoadBalancer on Mac using MetalLB refer this documentation
Cleanup
Destroy the kind cluster as well as registry as below -
# delete kind cluster
echo "deleting kind cluster"
kind delete cluster --name "platformwale"
# delete registry
echo "deleting registry"
docker rm -f $(docker ps -a | grep registry | awk -F ' ' '{print $1}')
Conclusion
And that's it! You now have a local Kubernetes development environment with a local Docker registry. This setup allows you to build, push, and deploy your Docker images without needing to push them to a public registry. This is useful in setting up local development environments faster and save network bandwidth. You also installed Ingress service to create LoadBalancer k8s service, this is useful to mimic the LoadBalancer behavior as you might need to do in an actual cloud provider.
Resources
- kind documentation
- kind resources
- All the scripts and yamls are uploaded in this github repository
- MetalLB docs
- Kind and MetalLB on mac
Author Notes
Feel free to reach out with any concerns or questions you have. I will make every effort to address your inquiries and provide resolutions. Stay tuned for the upcoming blog in this series dedicated to Platformwale (Engineers who work on Infrastructure Platform teams).
Originally published at https://platformwale.blog on Aug 15, 2023.
Top comments (0)