Running local docker images in Minikube

Fix ImagePullBackOff error and load local docker images in Minikube.

Photo by Growtika on Unsplash

While running Kubernetes locally for your custom containerized app using Minikube, you might come across the ImagePullBackOff error, which means Kubernetes could not fetch the given image, either locally or from a public repository. Here, we are focusing on the case when the image is present in the local docker registry but not available to Minikube.

By default, docker images are unavailable to Minikube because Docker and Minikube manage their container runtime and image registry separately.

There are several ways to build or load local images to Minikube. We will be discussing a few of them.

Option 1: Use Minikube Docker daemon while building images

In this approach, We build and save images in Minikube’s local repository, not inside the Docker desktop.

1. Point shell to Minikube’s Docker Daemon

# the behavior is limited to current terminal session(tab) only 
#    as the command just exports some environment variables
➜ eval $(minikube -p minikube docker-env)

2. Build image

➜ docker build -t my-app .

Now you can see the image in the Minikube image repository:

➜ minikube image ls | grep my-app

Option 2: Build images in Docker desktop and load them to Minikube

Check if the image is already built and available on the Docker desktop. If not, build the image using docker CLI.

➜ docker images | grep my-app

Now, load the image to Minikube:

# loads or overwrites the images(same tag) if present
➜ minikube image load my-app 

# check if the image has been copied
➜ minikube image ls
docker.io/library/my-app # yup, it is here :)

Option 3: Minikube Image Build

You can build images using minikube image build command which will save the image in Minikube registry. However, it does not accept flags like --platform linux/amd64.

Finally, modify the Pod definition to use the local image

• After building images and making sure it is available inside Minikube, the final step is to run our app in the K8 cluster using the image.
• Set imagePullPolicy inside Pod.containers definition to either IfNotPresent or Never to enforce Kubernetes give priority to the local image or never look into public repositories.

containers:
- name: my-app-container
  image: my-app
  imagePullPolicy: IfNotPresent # or 'Never'

Conclusion

Minikube and Docker have their separate image registries. So, we need to make sure our custom local image is available to the respective container runtimes (Docker or Minikube).