Kubecademy
December 4, 2022

Start Kubernetes Clusters with a Single Command with Minikube

Posted on December 4, 2022  •  11 minutes  • 2335 words  • Other languages:  Deutsch

When you want to learn, develop or try out new things on Kubernetes, you need a Kubernetes cluster. With minikube you get a local Kubernetes cluster with a single command. You can use it within about a minute and stop it and delete it at the end.

In this introduction, you will learn:

Let’s get started.

How Minikube Works

minikube is a command line tool available for Linux, Macos and Windows. It has drivers which control a hypervisor or a container runtime to start a virtual machine or a container with Kubernetes inside.

minikube big picture

Installing minikube

When you look at the drivers section of the minikube documentation you see which drivers are supported. Docker is the only preferred driver that is supported on all platforms: Linux, macOS and Linux. To use it, install Docker Desktop and then download and install minikube. Installing kubectl is optional but simplifies using minikube.

Now you can start minikube clusters with minikube start --driver docker. To make docker the default driver, enter the following command:

minikube config set driver docker

After installation you can check if minikube is working by starting a cluster:

minikube start

When the Kubernetes cluster is started, you can use the minikube command line tool to manage and interact with the cluster.

Here are the basic minikube commands:

# Start a cluster
minikube start
# get cluster state
minikube status
# pause a cluster
minikube pause
# unpause a cluster
minikube unpause
# stop a cluster
minikube stop
# delete a cluster
minikube delete

kubeconfig and kubectl

minikube reconfigures the kubeconfig file on your desktop. With this, you can also manage your cluster with kubectl or other tools such as Lens . If kubectl is not installed locally, minikube makes kubectl available with the minikube kubectl subcommand. So with kubectl installed, these two commands should be equivalent:

# use local kubectl
kubectl get pods
# use minikube-provided kubectl
minikube kubectl -- get pods

Persistent Configuration

When you have installed and used minikube, you will find a .minikube folder in your home directory. In this folder, minikube keeps a persistent configuration and caches images. In the example above, we have defined docker as the default driver in the persistent configuration.

Here are basic commands to deal with the persistent configuration:

# view defined values
minikube config view
# list configurable parameters
minikube config list
# list available values for a parameter
minikube config defaults PROPERTY_NAME
# two examples
minikube config defaults driver
minikube config defaults kubernetes-version
# set a value:
minikube config set PROPERTY_NAME VALUE
# an example:
minikube config set driver virtualbox

Minikube Profiles

Minikube cluster configurations are called profiles. With profiles, you can create and manage multiple clusters. Profiles are selected with the -p command line flag on minikube commands. When you start a minikube cluster without a profile, it starts a cluster with the default minikube profile. The minikube profile subcommands provide basic management functions for profiles. minikube clusters are isolated from each other by default but you can make them available on a shared network if required.

Here are basic commands to manage and use profiles:

# minikube start creates a cluster with a default profile
minikube start
# get current profile
minikube profile
# start a second cluster with a new profile
minikube start -p cluster2 --memory=4g --cpus=2
# list profiles
minikube profile list
# set a profile
minikube profile cluster2
# deleting a cluster deletes the profile, too 
# here, cluster2 is deleted as it was selected
minikube delete

Minikube Addons

minikube also has some addons. With these, you can quickly add functionality, such as the Kubernetes Dashboard. Here is how you can activate the dashboard addon and access the dashboard:

1. See available addons

minikube addons list

2. Activate an addon with for example the Kubernetes Dashboard

minikube addons enable dashboard

It tells us to activate the metrics-server addons for all features. Let’s do it

minikube addons enable metrics-addon

3. open the dashboard

minikube dashboard

This opens the dashboard in the default browser on your system. It also creates a proxy to the service within minikube. Note that this proxy must stay open as long as you want to use the dashboard.

Tunnel Services with Minikube

Another important feature is that minikube can create a tunnel to services running in minikube. The command to open a tunnel to an individual service is minikube service. Here are some common examples:

Open a tunnel to the service demo and print the url:

minikube service demo --url

Open tunnels to all potentially reachable services:

minikube tunnel

By default, only services of type NodePort are reachable.

Cleanup orphaned tunnels:

minikube tunnel --cleanup

Tunnels can become orphaned if a cluster is stopped when a tunnel is open. In effect routes are not deleted.

Deploying an Existing App to Minikube

This tutorial is a basic walk through of minikube. You will learn how to

A prerequisite is that you have minikube installed on your system. Please refer to the minikube documention to learn how to install it.

1. start a cluster

minikube start

2. check if we have some content

minikube kubectl -- get nodes,ns

3. create a namespace

minikube kubectl -- create ns hello

4. create a deployment

kubectl -n hello create deployment hello \
  --image gcr.io/kuar-demo/kuard-arm64:purple

5. check if pods are ready

kubectl -n hello get pods

6. expose the deployment

kubectl -n hello expose deployment hello \
  --type=NodePort \
  --port=8080

7. check if service is ready

kubectl -n hello get service hello

8. open a tunnel to make this service available on your desktop

and then open the url in your browser..

minikube service -n hello hello --url

Enter ctrl+c to close the tunnel.

10. start the dashboard and open it in a browser

try to find the deployment, pod and service in the dashboard.

minikube dashboard

11. delete the namespace

kubectl delete ns hello

Note: As we have created all objects of the example app in its own namespaces we were able to delete everything with a single simple command.

Working with Container Images in Minikube

Minikube supports multiple ways of pushing images to a cluster . One of theses ways are provided by the minikube image subcommands. They forward the command to the container runtime that is provided by minikube. This simplifies working with images in minikube.

Here are examples of what you can do with the minikube image subcommands:

# download a container image directly from a remote registry
minikube image pull busybox
# upload a container image directly to a remote registry
minikube image push busybox
# take an image that is available as an archive
# and make it available in the cluster
minikube image load myimage.tar
# save an image into an archive
minikube image save myimage myimage.tar
# build a new image based on a build context
# ie. a directory with Dockerfile in the cluster
minikube image build -t myimage .
# tag an image
minikube image tag myimage:latest myimage:1.0.0
# list images
minikube image ls
# remove an image
minikube image rm myimage
# see list of available image commands
minikube image --help
# get help for a command
minikube image build --help

The minikube image subcommands can be used to build and deploy a self-developed application to minikube as is shown in the next tutorial.

Build and Test a self-developed Application with Minikube

This tutorial shows how to use minikube to build and test an application.

1. clone an example application

git clone github.com/mitja/flask-example

2. change into the flask-demo directory

cd flask-example

3. Build an image

minikube image build -t flask-example .

4. Deploy the image

Note: in the deployment.yml, imagePullPolicy: Never is necessary to run the image without pushing it to a container registry, otherwise deploying would fail as the container runtime cannot pull the image.

minikube kubectl -- apply -f deployment.yml

5. expose the service and check that its running

minikube service flask-example-service --url

Where does the service come from?

If you take a look at deployment.yml you will notice that this file not only defines a deployment but also a service. This is not uncommon in examples or to make installations more convenient.

6. start a shell container to check the service from within the cluster

minikube kubectl -- \
  run my-shell --rm -i --tty \
  --image curlimages/curl -- sh

8. in the pod shell, use curl to test the service

curl flask-example-service:5000

9. exit the shell

exit

Why is the pod automatically deleted when we exit the terminal session?

The pod is automatically deleted on exit due to the --rm option.

Publishing a Web Service with an Ingress Controller

This tutorial shows how to publish a service with Ingress. Ingress is a special Kubernetes API resource. You can use it to publish http services. An Ingress must be implemented by an ingress controller . Kubernetes does not come with a default ingress controller, but there are many common ingress controllers available. Minikube for example provides ingress-nginx as an addon .

An Ingress is like a reverse proxy which you can configure with the standard Ingress resource definition in Kubernetes. Like a reverse proxy, an Ingress can terminate TLS and route traffic to upstream services based on http attributes such as hostnames and URL path segments.

An ingress provides an additional layer of security: Instead of exposing application services directly on the internet, you only expose the ingress service. To further improve security, ingresses can also implement Web Application Firewall (WAF) functionality and rate limiting among other features. You can use just one ingress to publish many different services without giving each service its own NodePort. Finally you can run the ingress on different nodes than the backend applications.

1. Activate the ingress addon

minikube addons enable ingress

2. Check the ingress services and pods

The pods and services for ingress are deployed in the ingress-nginx namespace:

kubectl get pod,service -n ingress-nginx

3. deploy an example app

kubectl create deployment web --image=gcr.io/google-samples/hello-app:1.0

4. expose the app as a service of type NodePort

kubectl expose deployment web --type=NodePort --port=8080

5. check the service

open a minikube tunnel and view the service in the browser (open the url provided as output of this command):

minikube service web --url

6. create an ingress definition

Create the file example-ingress.yaml with this content:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: example-ingress
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /$1
spec:
  rules:
    - host: hello-world.info
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: web
                port:
                  number: 8080

apply it to your cluster:

kubectl apply -f example-ingress.yaml

A note about the annotation:

Any substrings within the request URI that need to be passed to the rewritten path must explicitly be defined in a capture group. As we do not use rewriting in this example, I think this is not required. It can and often is used in path rewriting: A special base path on the external domain can for example be rewritten to a root path of the internal service.

Another important rewrite annotation is a redirect from http to https.

The rule says:

Minikube needs a tunnel to reach the ingress from your desktop. In addition, the ingress routs based on hostnames. So you will need to add the hostname to your hosts file.

7. See where the ingress address is located

kubectl get ingress

In our example it is identical to the ip of the (single-node) minikube cluster:

minikube ip

These are the IPs of the VM or container in your hypervisor or docker network. To reach the service with minikube, you need to tunnel it.

8. add following line to your /etc/hosts file

127.0.0.1 hello-world.info

Why don’t we use the minikube ip in the hosts file?

We do not use the minikube ip since the minikube tunnel exposes the service on 127.0.0.1.

9. start the minikube tunnel

Note that you need admin rights to start a tunnel for the ingress service which is listening on port 80 and 443.

minikube tunnel

10. open the example app in the browser

open http://hello-world.info in your browser. You shoud see the example app.

If you have curl, you can also run the following command to test it.

curl hello-world.info

Cleaning up and Summary

This concludes this tutorial and introduction to minikube. To clean up:

1. delete the cluster

minikube delete

2. delete the following entry in /etc/hosts:

127.0.0.1 hello-world.info

If you want to learn more about minikube, go to the Minikube Homepage and Docs .

Here are some other examples of what you can do with minikube: