Using Minikube as a local Kubernetes test and development environment on macOS

Minikube lets you create a single-node Kubernetes cluster locally. This makes for a great development and test environment. On macOS, you can be up and running with a local virtual machine in a matter of minutes.

In this article you will learn how to:

  • install Minikube to set up a local cluster
  • install kubectl to interact with the local cluster
  • create a containerized app using a local docker image

Step 1: Install kubectl

We recommend installing kubectl first. By doing so, the context for kubectl will be automatically set to use your Minikube cluster when you bring the cluster up.

First download the latest release tarball of Kubernetes from GitHub.

Unarchive the tarball with the command:

> cd ~/Downloads
> tar zxvf kubernetes.tar.gz

Next, use the following commands to move kubectl to /usr/local/bin/ and make it executable.

> sudo cp kubernetes/platforms/darwin/amd64/kubectl /usr/local/bin/kubectl
> sudo chmod +x /usr/local/bin/kubectl

You can validate the install with the command:

> kubectl version

You can also refer to this guide for detailed instructions on setting up kubectl.

Step 2: Install Minikube

Before completing this step, you should have VirtualBox installed on your mac. VirtualBox provides the local virtualization environment that Minikube will use when setting up the local cluster. Please note that Minikube will also work with VMWare Fusion.

Use this command to download Minikube, make it executable and move it to /usr/local/bin

> curl -Lo minikube https://storage.googleapis.com/minikube/releases/v0.10.0/minikube-darwin-amd64 && chmod +x minikube && sudo mv minikube /usr/local/bin/

You can validate the install with the command:

> minikube version

You can also refer to this guide for detailed setup instructions for Minikube.

Step 3: Install Docker for Mac

Since we will want to build a local Docker image to use with our local cluster, install Docker for Mac or Docker Toolbox. See the following guide for detailed instructions.

Once completed, you can validate the install with the command:

> docker version

If you have installed Docker for Mac, you should ensure that Docker for Mac is not running, to avoid conflicts. From the Docker toolbar item, choose Quit Docker.

Step 4: Start up Minikube

Now that all the prerequisites are installed, we can start up Minikube.

To start up Minikube, use the command

> minikube start

Once Minikube has started, you can check out the Kubernetes dashboard with the command:

> minikube dashboard

This command will open the Kubernetes dashboard in a browser.

Step 5: Create a containerized app using the Dashboard.

Let's start with something simple and create an nginx web server using the nginx:latest image.

In the dashboard, click on the + CREATE link in the top right corner of the dashboard.

Specify the following app details:

  • App Name: static-web
  • Container image: nginx:latest
  • Number of pods: 1
  • Service: External
  • Port: 80
  • Target Port: 80

Now click on the Deploy button.

This will create:

  • one pod
  • one replication controller called static-web
  • one service called static-web

You can view the running web server in a browser window by using the command:

> minikube service static-web

You will see the default Welcome to nginx! test page in a browser window. Note that the url will include the port assigned by Minikube (it will be a port nubmer greater than 30000).

Step 6: Create a second containerized app using a local Docker image.

To make this truly useful as a development environment, we will want to be able to run applications based on local Docker images.

The first step is to set the Docker environment variables so that the Docker client talks to the Docker daemon inside of the Minikube cluster. To do so, use the command:

> eval $(minikube docker-env)

After issuing this command, you can use the command:

> docker ps

You will see a number of Kubernetes-related containers as well as the nginx container that we launched in the previous step.

Now let's create a new local image based on nginx:latest with some custom static content.

To do this, create a new directory called static-web2.

> mdkir static-web
> cd static-web
> mkdir html

Create a new file called Dockerfile and copy it to the static-web directory. Enter or copy the following content into Dockerfile:

FROM nginx

COPY html /usr/share/nginx/html

VOLUME /usr/share/nginx/html

Create a new file called index.html and copy it to the static-web/html directory. Enter or copy the following content (or any valid HTML that you'd like) into index.html.

<html>
  <head>
  </head>
  <body>
    <h1>Local docker image deployed on Minikube!</h1>
  </body>
</html>

Now, run the following command to build and tag the local Docker image:

docker build -t static-web2:v1 .

Note: it is critical that you provide a tag in the image name. Kubernetes will try to look for your image in a repository if it is asked to get the :latest image (or if you don't provide any tag).

Finally, we can create a new app called static-web2 using our new local Docker image:

In the dashboard, click on the + CREATE link in the top right corner of the dashboard.

Specify the following app details:

  • App Name: static-web2
  • Container image: static-web2:v1
  • Number of pods: 1
  • Service: External
  • Port: 80
  • Target Port: 80

Now click on the Deploy button.

After a few moments the new application's replication controller and pod will be up.

You can view the new application by using the command:

> minikube service static-web2

Conclusion

The setup described in this article is a great way to get familiar with Kubernetes. You should note that while Minikube provides most Kubernetes functionality, features that depend on a Cloud Provider (i.e. LoadBalancers, PersistentVolumes and Ingress) are not available.

Now that you have a functioning development and test environment, you can learn more about the kubectl and minikube clients with the following resources: