Minikube logo

Minikube is a minimal Kubernetes distribution designed for local development use. It’s developed as part of the Kubernetes project and includes implementations of all major cluster features.

Minikube works on Linux, Mac, and Windows hosts. It can use containers or a virtual machine environment to run your cluster and its workloads. Here are all the supported runtimes:

  • Docker
  • Podman
  • KVM
  • Hyper-V
  • Hyperkit
  • Parallels
  • VirtualBox
  • VMware

Make sure you’ve got one of these technologies installed before continuing with this guide. The Minikube setup process will automatically detect available runtimes and apply an appropriate configuration. We’ll show you how to complete your deployment and get started using Minikube.

Installing Minikube

We’re focusing on x86 Linux systems in this guide. If you’re using Windows, Mac, or a different CPU platform, refer to the Minikube documentation to obtain the most detailed set up information. After the initial installation procedure, Minikube’s basic usage is identical across all supported systems.

Linux users can choose between a direct binary download or a Debian/RPM package. We’ll use the binary download in this example.

$ curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube-linux-amd64
$ sudo install minikube-linux-amd64 /usr/local/bin/minikube

Minikube will now be installed and ready to use.

Starting Your Kubernetes Cluster

Launch your Minikube cluster with the minikube start command:

$ minikube start
minikube v1.25.2 on Ubuntu 20.04
Automatically selected the docker driver. Other choices: kvm2, ssh
Starting control plane node minikube in cluster minikube
Pulling base image ...
Downloading Kubernetes v1.23.3 preload ...

Minikube will automatically download and start the latest Kubernetes release. This process can take several minutes to complete. The command’s output will indicate progress and show the actions Minikube’s taking. In the example above, you can see the Docker driver has been selected to host your cluster. Consult Minikube’s driver documentation if your container platform or virtualization stack isn’t automatically detected.

Using Your Cluster With Kubectl

Minikube modifies your environment so you can connect to your cluster using an existing Kubectl installation. It’ll add a minikube context to your KUBECONFIG file that targets your Minikube cluster.

Minikube also includes a bundled version of Kubectl that you can access with the minikube kubectl command. This is useful if you don’t already have Kubectl installed or your existing binary is a different version to your Minikube cluster.

# Uses the Kubectl version that's bundled with Minikube
$ minikube kubectl get pods

For the remainder of this guide, we’ll show the plain kubectl command and assume it’s targeting your Minikube cluster. You could set up a shell alias to use Minikube’s bundled Kubectl without prefixing it with minikube each time:

$ alias kubectl="minikube kubectl"

With Minikube live and Kubectl available, you can now add applications to your Kubernetes cluster:

$ kubectl create deployment nginx --image=nginx:latest
deployment.apps/nginx created
$ kubectl expose deployment nginx --type=LoadBalancer --port=80
service/nginx exposed

The minikube service command provides the exposed URL of a service:

$ minikube service nginx --url
http://192.168.49.2:31599

Paste the URL into your web browser (or run the command without the --url flag) to view your service.

image of running an NGINX container in Minikube

Accessing the Kubernetes Dashboard

Minikube provides the Kubernetes dashboard as an optional integrated feature. Run the minikube dashboard command to download the dashboard components and launch the interface in a new browser tab.

image of running the Kubernetes dashboard in Minikube

You can use the dashboard to manage your resources and visualize their activity. Keep the minikube dashboard command running in your terminal while you’re interacting with the dashboard. Terminate the command with the Ctrl+C key sequence when you’ve finished.

Enabling the Image Registry

Minikube includes an image registry as an optional addon. This lets you store your container images inside Minikube, making them available for deployment inside your cluster.

First enable the registry addon:

$ minikube addons enable registry

Next tag your image so it references the Minikube registry. The registry listens on port 5000 on the IP address provided by the minikube ip command.

$ docker tag my-image:latest $(minikube ip):5000/my-image:latest

Before you can push, Docker needs to be configured to accept the URL as an insecure registry. Add it to the insecure-registries field inside your /etc/docker/daemon.json file so Docker allows HTTP access.

{
    "insecure-registries": ["192.168.49.2:5000"]
}

Replace the IP address with the one shown by your minikube ip command. Restart Docker with the systemctl restart docker command.

Now you can push your image into your Minikube registry:

$ docker push $(minikube ip):5000/my-image:latest

A final step’s required before Pods in your cluster can consume this image. Minikube’s container runtime must also be configured to allow insecure access to the registry. You can enable this by including the --insecure-registry flag when you run minikube start. The IP address needs to refer to the default cluster IP of your Minikube installation. You can get this by running kubectl get services and looking at the CLUSTER-IP for the kubernetes service. Then stop Minikube and restart it with the extra flag.

$ kubectl get service
NAME              TYPE           CLUSTER-IP      EXTERNAL-IP   PORT(S)          AGE
kubernetes        ClusterIP      10.96.0.1       <none>        443/TCP          63m

$ minikube stop
$ minikube start --insecure-registry 10.96.0.1/24

Changing Kubernetes Version

Minikube defaults to using the newest available Kubernetes release. To switch to a specific version, include the --kubernetes-version flag when you start your cluster:

$ minikube start --kubernetes-version=v1.23.0

You can run multiple clusters at the same time, each with different Kubernetes versions, by creating several distinct profiles. The --profile flag selects the profile to target for a particular command.

$ minikube start --profile v1.22 --kubernetes-version=v1.22.0
$ minikube start --profile v1.23 --kubernetes-version=v1.23.0
$ minikube --profile v1.22 kubectl get pods

Using Multiple Nodes

Minikube supports multiple virtual Nodes. This lets you test how your application scales across available Nodes without deploying new physical hardware.

This example creates a cluster with three Nodes:

$ minikube start --nodes 3

You can verify that multiple Nodes are available by listing them with Kubectl:

$ kubectl get nodes
NAME           STATUS   ROLES                  AGE   VERSION
minikube       Ready    control-plane,master   71m   v1.23.3
minikube-m02   Ready    <none>                 71m   v1.23.3
minikube-m03   Ready    <none>                 71m   v1.23.3

Enabling Remote Access

Minikube doesn’t accept incoming traffic by default. It’s designed for local use and isn’t hardened to serve external requests. You can still enable remote access to workloads in your cluster by changing the control plane’s listening address. Only do this after fully assessing the risks – your network will be exposed to the outside world.

$ minikube start --listen-address=0.0.0.0

Port forwarding is a safer solution when you need to open up access to a specific service. Use Kubectl’s port-forward command to create a route from a host port to one of your services:

$ kubectl port-forward service/nginx 8080:80

You can now visit localhost:8080 to access the NGINX service created earlier in this guide. Port 8080 on your host is bound to the service’s port 80.

Removing Minikube

One of the advantages of Minikube is its ease of removal. If you decide Minikube’s not for you, run the delete command to remove everything it added to your system:

$ minikube delete

A less destructive option is minikube stop which will stop your cluster but leave all resources intact. You can restart your cluster using the minikube start command.

Conclusion

Minikube is a self-contained Kubernetes distribution that uses containers or virtualization to run a cluster on your local machine. It’s supported by the upstream Kubernetes project. Minikube is a feature-complete Kubernetes implementation that bundles the Kubernetes dashboard, networking support, persistent storage, and interchangeable container runtimes.

You can learn more about Minikube in the official documentation. Alternatively, start using familiar Kubectl commands to manage your cluster and deploy new workloads. You’ve now got a fully functioning local Kubernetes environment for building and testing your applications.

Profile Photo for James Walker James Walker
James Walker is a contributor to How-To Geek DevOps. He is the founder of Heron Web, a UK-based digital agency providing bespoke software development services to SMEs. He has experience managing complete end-to-end web development workflows, using technologies including Linux, GitLab, Docker, and Kubernetes.
Read Full Bio »