Challenge
DifficultyMedium
Learner activity1 solved of 1 attempt

Connect a Local Container Registry to a kind Cluster

A local registry and a kind cluster run on the same Docker host but on separate networks. Learn how to connect them by attaching a running container to an additional Docker network.

The kind tool runs local Kubernetes clusters in Docker containers, with one container per node. To make locally built images available to a kind cluster, you can run a local registry on the same Docker host. You push images to the registry from the host, and the cluster's nodes pull them from it.

The dev-01 workstation already runs a registry in the local-registry container. It holds several images:

curl http://local-registry:5000/v2/_catalog
{"repositories":["api","web"]}

On the workstation, /etc/hosts maps local-registry to 127.0.0.1, where the registry publishes port 5000. The cluster's node needs to resolve the same name to the registry container's IP address. This lets you use an image name such as local-registry:5000/web:v2 both on the workstation and when deploying to the cluster.

A single-node kind cluster is also running, and kubectl is already configured to use it:

kubectl get nodes
NAME                 STATUS   ROLES           AGE   VERSION
kind-control-plane   Ready    control-plane   2m    v1.37.0
Note

The node's container runtime is already configured to pull images from local-registry:5000 over plain HTTP. You can inspect this configuration in /etc/containerd/certs.d/local-registry:5000/hosts.toml inside the kind-control-plane container.

However, the node cannot reach the registry yet. When kind created the cluster, it created a user-defined bridge network and attached the node's container to it. The registry was started earlier, before that network existed, and remains on Docker's default bridge network.

With the current network setup, the node cannot resolve the registry's container name or connect directly to its container IP. The registry's published port is bound to the workstation's loopback address, so it does not provide an alternative endpoint for the node either.

You need to connect the existing registry to the cluster's network. Keep both containers running: the registry holds the only copies of these images, and there is no need to recreate it or the cluster to change their network connectivity.

Your task is to attach the running local-registry container to the cluster's network, then deploy local-registry:5000/web:v2 to the cluster.

Connect the registry to the cluster's network

Hint 1

Start by identifying the Docker network of the kind's node container. Use docker network ls to list the networks on the workstation, and docker inspect kind-control-plane to check which network the node's container uses.

Hint 2

A container can be connected to several networks at once. On each bridge network, it gets a separate network interface and IP address. Containers that share a user-defined bridge network can reach each other by name.

The docker network command includes subcommands for connecting and disconnecting existing containers. Run docker network --help to find them.

Hint 3

Use docker network connect to attach an existing container to an additional network:

docker network connect NETWORK CONTAINER

The container does not need to be stopped or recreated.

Hint 4

Check whether the node can resolve the registry's name and reach its API:

docker exec kind-control-plane curl -sS http://local-registry:5000/v2/_catalog

You should see the same repository list as on the workstation. A Could not resolve host error means that name resolution still isn't working.

Run the app in the cluster

Once the node can reach the registry, its container runtime can pull the images stored there. Create a Deployment named web using the local-registry:5000/web:v2 image:

kubectl create deployment web --image=local-registry:5000/web:v2
Hint 5

If the pod tried to pull its image before you connected the registry, it may remain in ImagePullBackOff for a few minutes. The kubelet increases the delay between failed attempts, up to five minutes.

You can delete the pod to trigger another attempt immediately:

kubectl delete pod -l app=web

The Deployment creates a replacement pod, which attempts to pull the image again.

Problem
Solution
Start
Black Friday 2026