Single-Node Kubernetes Installation with Vagrant & CoreOS

While Kubernetes is designed to run across large clusters, it can be useful to have Kubernetes available on a single machine. This guide walks a deployer through this process using Vagrant and CoreOS. After completing this guide, a deployer will be able to interact with the Kubernetes API from their workstation using the kubectl CLI tool.

Install Prerequisites


Navigate to the Vagrant downloads page and grab the appropriate package for your system. Install the downloaded software before continuing.


kubectl is the main program for interacting with the Kubernetes API. Download kubectl from the Kubernetes release artifact site with the curl tool.

The linux kubectl binary can be fetched with a command like:

$ curl -O

On an OS X workstation, replace linux in the URL above with darwin:

$ curl -O

After downloading the binary, ensure it is executable and move it into your PATH:

$ chmod +x kubectl
$ mv kubectl /usr/local/bin/kubectl

Clone the Repository

The following commands will clone a repository that contains a "Vagrantfile", which describes the set of virtual machines that will run Kubernetes on top of CoreOS.

$ git clone
$ cd coreos-kubernetes/single-node/

Choose Container Runtime (optional)

The runtime defaults to docker. If you wish to use rkt simply edit the user-data and change the line beginning with export CONTAINER_RUNTIME to:


Enable Network Policy (Optional)

To enable network policy edit the user-data file and set USE_CALICO=true.

Start the Machine

Ensure the latest CoreOS vagrant image will be used by running vagrant box update.

Simply run vagrant up and wait for the command to succeed. Once Vagrant is finished booting and provisioning your machine, your cluster is good to go.

Configure kubectl

Once in the coreos-kubernetes/single-node/ directory, configure your local Kubernetes client using the following commands:

You can choose from one of the two following options.

  1. Use a custom KUBECONFIG path

    $ export KUBECONFIG="${KUBECONFIG}:$(pwd)/kubeconfig"
    $ kubectl config use-context vagrant-single
  2. Update the local-user kubeconfig

    $ kubectl config set-cluster vagrant-single-cluster --server= --certificate-authority=${PWD}/ssl/ca.pem
    $ kubectl config set-credentials vagrant-single-admin --certificate-authority=${PWD}/ssl/ca.pem --client-key=${PWD}/ssl/admin-key.pem --client-certificate=${PWD}/ssl/admin.pem
    $ kubectl config set-context vagrant-single --cluster=vagrant-single-cluster --user=vagrant-single-admin
    $ kubectl config use-context vagrant-single

Check that your client is configured properly by using kubectl to inspect your cluster:

$ kubectl get nodes
NAME          LABELS                               STATUS   Ready

NOTE: When the cluster is first being launched, it must download all container images for the cluster components (Kubernetes, dns, heapster, etc). Depending on the speed of your connection, it can take a few minutes before the Kubernetes api-server is available. Before the api-server is running, the kubectl command above may show output similar to:

The connection to the server was refused - did you specify the right host or port?

Is kubectl working correctly?

Now that you've got a working Kubernetes cluster with a functional CLI tool, you are free to deploy Kubernetes-ready applications. Start with a multi-tier web application from the official Kubernetes documentation to visualize how the various Kubernetes components fit together.

View the Guestbook example app