AWS Open Source Blog

Run Kubernetes on Your Laptop

A recent survey of 550 members of the Cloud Native Computing Foundation confirmed that Kubernetes is the orchestration platform of choice. The survey also reaffirmed that Amazon Web Services continues to be the leading choice for deploying Kubernetes clusters in the cloud. lists various ways you can easily create a Kubernetes cluster on AWS.

As part of your development cycle, you may also want to run Kubernetes on your local machine, so that you can start and debug your applications locally. Once you are satisfied with the local version, you can deploy the exact same application on a cluster running on AWS.

This post presents two options for running Kubernetes locally on a Mac OS X machine: commonly used Minikube and the newly-introduced Kubernetes support in Docker for Mac. Instructions for other platforms are available on the Minikube and Docker websites.

Let’s get started!

Install kubectl

Kubectl is a CLI command line interface (CLI) used to run commands against a Kubernetes cluster. Let’s install that first:

Install kubectl on Mac OS X:

brew install kubernetes-cli

If kubectl is already installed, you may want to upgrade it:

brew upgrade kubernetes-cli

Print the version information:

$ kubectl version --client --short=true
Client Version: v1.8.5

By default, the kubectl version command prints the client and the server version. --client ensures that only the client version is printed, as no cluster is running at this time. --short option allows you to print only the version number.

Now that kubectl is installed, let’s look at the two options to get a Kubernetes cluster running on the local machine.

Set Up a Kubernetes Cluster Using Minikube

Minikube runs a single-node Kubernetes cluster inside a Virtual Machine (VM) on your laptop, providing a local development and testing environment for users interested in playing with Kubernetes.

The minikube VM is provisioned using VirtualBox. If VirtualBox is not already installed on your machine, you’ll need to do that first:

brew cask install virtualbox

Now, install minikube:

brew cask install minikube

If minikube is already installed, you can upgrade it using:

brew cask reinstall minikube

Check the version of minikube:

~ $ minikube version
minikube version: v0.24.1

Start minikube:

~ $ minikube start
Starting local Kubernetes v1.8.0 cluster...
Starting VM...
Downloading Minikube ISO
140.01 MB / 140.01 MB [============================================] 100.00% 0s
Getting VM IP address...
Moving files into cluster...
Downloading localkube binary
148.25 MB / 148.25 MB [============================================] 100.00% 0s
0 B / 65 B [----------------------------------------------------------] 0.00%
65 B / 65 B [======================================================] 100.00% 0sSetting up certs...
Connecting to cluster...
Setting up kubeconfig...
Starting cluster components...
Kubectl is now configured to use the cluster.
Loading cached images from config file.

This command downloads the ISO file, creates the VM, and configures Kubernetes components to bring up the single-node cluster. By default, the cluster configuration and credentials are stored in the ~/.kube/config file. The context for different clusters can be viewed using the following command:

~ $ kubectl config get-contexts
*        minikube   minikube    minikube

As you can see here, we have created only one Kubernetes cluster so far. If multiple clusters had been created, they would all be listed by this command.

A * in the first column also indicates that this is the current context; all kubectl commands will be directed at this cluster. For example, you can check the nodes in the cluster:

~ $ kubectl get nodes
minikube Ready  <none>  1m    v1.8.0

The kubectl version command can now be used to print the client and server version:

~ $ kubectl version --short=true
Client Version: v1.8.5
Server Version: v1.8.0

All the usual kubectl commands can now be applied to this cluster.

Set Up a Kubernetes Cluster Using Docker for Mac

Docker for Mac/Docker for Windows provides a starting point for developers interested in getting started with Docker. Docker for Mac can be downloaded as a Stable or Edge release. The Stable version is fully baked and tested, and comes with the latest GA release of Docker. The Edge release, as the name indicates, offers the latest bleeding-edge features. One such feature introduced as part of the private beta for Docker CE Edge release, version 17.12.0-ce-rc2-mac41 to be specific, supports a single-node Kubernetes cluster for development and testing.

This means that you can use the same Docker for Mac to create your Docker images, enable a Kubernetes cluster, and deploy pods, without any need for an additional tool such as minikube. At the time of writing, this is only supported on Docker for Mac, and Docker for Windows in Q1. (Kubernetes is also available in Docker Enterprise Edition.)

Let’s take a look at how you can use Docker for Mac to set up a local Kubernetes cluster.

To get Kubernetes access from Docker for Mac, you’ll need to sign up for the Docker Beta program. After your Docker ID is approved for Kubernetes access, you will be sent a link to download and install the Edge version of Docker for Mac. Make sure that About Docker shows the version as 12.12.0-ce-rc2-mac31 or later. A new tab that allows you to configure a Kubernetes cluster is now shown in the Preferences dialog box.

Select Enable Kubernetes, then click on Apply & Restart to start a single-node Kubernetes cluster.

In a few moments, the status bar will be updated to reflect that Kubernetes is running, in addition to Docker.

This also creates a configuration for the cluster in the default file at ~/.kube/config. The kubectl CLI shows the configuration as:

~ $ kubectl config get-contexts
CURRENT  NAME               CLUSTER                    AUTHINFO            NAMESPACE
*        minikube           minikube                   minikube
         docker-for-desktop docker-for-desktop-cluster docker-for-desktop

Change the context to be used by kubectl, verify the current context, and get the list of nodes:

~ $ kubectl config use-context docker-for-desktop
Switched to context "docker-for-desktop".
~ $ kubectl config get-contexts 
CURRENT NAME               CLUSTER                     AUTHINFO NAMESPACE 
*       docker-for-desktop docker-for-desktop-cluster  docker-for-desktop 
        minikube           minikube                    minikube 
~ $ kubectl get nodes 
NAME               STATUS  ROLES    AGE   VERSION 
docker-for-desktop Ready   master   23h   v1.8.2

Now the docker version command shows Kubernetes as the orchestrator:

~ $ docker version
 Version: 17.12.0-rc1-kube_beta
 API version: 1.35
 Go version: go1.9.2
 Git commit: a36c9215a7f8d5da5231d2cca353375bcb27efe3
 Built: Thu Dec 7 17:33:49 2017
 OS/Arch: darwin/amd64
 Orchestrator: kubernetes
  Version: 17.12.0-ce-rc2
  API version: 1.35 (minimum version 1.12)
  Go version: go1.9.2
  Git commit: f9cde63
  Built: Tue Dec 12 06:45:30 2017
  OS/Arch: linux/amd64
  Experimental: true

Notice, kubernetes is shown as the orchestrator, as opposed to the default swarm.

You now have the latest Kubernetes scheduler with the latest Docker runtime, with a single tool!

Let’s check the client and server version using the kubectl version command:

~ $ kubectl version --short=true
Client Version: v1.8.2
Server Version: v1.8.0

Once again, all the usual kubectl commands will work on this cluster.

In addition to using all the familiar kubectl commands, you can also deploy Docker Compose stacks as first-class Kubernetes applications. More on this later, but in the meantime you can check out this video:

Once you’ve done the initial development and testing of your application on a local Kubernetes cluster, our Kubernetes workshop will guide you through how to create a Kubernetes cluster on AWS and deploy your applications on that cluster.


Arun Gupta

Arun Gupta

Arun Gupta is a former a Principal Open Source Technologist at Amazon Web Services. He has built and led developer communities for 12+ years at Sun, Oracle, Red Hat, and Couchbase. He has extensive speaking experience in more than 40 countries on myriad topics and is a JavaOne Rock Star for four years in a row. Gupta also founded the Devoxx4Kids chapter in the US and continues to promote technology education among children. A prolific blogger, author of several books, an avid runner, a globe trotter, a Docker Captain, a Java Champion, a JUG leader, NetBeans Dream Team member, he is easily accessible at @arungupta.