a local, all-in-one k8s cluster for dev & testing
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
addons/dns init commit Jul 26, 2016
lib feat(updates): bump k8s to v1.4.3 Oct 21, 2016
manifests init commit Jul 26, 2016
templates feat(updates): bump k8s to v1.4.3 Oct 21, 2016
vars Honor some env var on startup Dec 14, 2016
README.md fix(readme): fix order of installs Oct 21, 2016
cleanup.sh feat(updates): bump k8s to v1.4.3 Oct 21, 2016
install_deps.sh feat(updates): bump k8s to v1.4.3 Oct 21, 2016
make-ca-cert.sh create & use separate client certs for admin & Node Aug 5, 2016
nanokube.sh init commit Jul 26, 2016



nanokube is a simple tool to quickly bring up a local, all-in-one Kubernetes cluster. It is used during app development, testing or experimentation with the k8s project.


  • It can create the cluster locally on the machine (the cluster does not need to run in VM's)
  • Docker is the primary requirement of the machine.
  • The cluster created includes: etcd, flannel, and the respective k8s Master & Node components
  • The cluster is configured with sensible defaults similar to what one would find in a production-grade cluster.

Kudos: to the k8s.io community and CoreOS, as this project draws from k8s' local-up-cluster.sh and coreos-kubernetes


System Requirements

nanokube has only been tested on a system with the following specs:

  • Ubuntu 16.04 x86_64
  • 8 GB of RAM
  • 8 CPU cores
  • Docker v1.11.2
  • Capable of using docker run --privileged (for a Self-Hosted install)
  • Capable of reconfiguring Docker networking to use flannel
  • 2 network interfaces (PublicNet @ eth0, and PrivateNet @ eth1)

What's Included?

  • Installed Components
    • etcd - v2.3.7
    • flannel - v0.6.1
    • Kubernetes - v1.4.3
      • Master components (kube-apiserver, kube-controller-manager, kube-scheduler)
      • Node components (kubelet, kube-proxy)
      • hyperkube binary & Docker image
      • kubectl CLI
  • The ability to set a particular version of k8s to use (in ./vars)
  • The option to install an all-in-one k8s cluster using traditional system-hosted binaries, or the self-hosted k8s model
  • Sensible defaults & configuration settings for the k8s Master & Node components
    • These defaults are intended to provide insight into how a k8s cluster should be configured, as well as, what addons can & should be added
  • TLS for cluster communication using self-signed certs
  • Cluster Addons
    • DNS using kube-dns

Installation Models

The two installation models intend to serve as examples for how to properly configure k8s in a production-like environment.

Either model works, and collectively they showcase different ways to manage the Kubernetes components that comprise a cluster.

  • Traditional/Binary

    In this model, the k8s components are delivered using the following artifacts:

    • System-Hosted Binaries
      • flannel
      • kube-apiserver
      • kube-controller-manager
      • kube-scheduler
      • kubelet
      • kube-proxy
    • System-Hosted Docker Containers
      • etcd
  • Self-Hosted

    In this model, the k8s components are delivered using the following artifacts:

    • System-Hosted Binaries
      • flannel
    • System-Hosted Docker Containers
      • etcd
      • kubelet (requires privileged mode)
        • The kubelet here doubles as the instantiator of both the Self-Hosted static k8s Pods, and user Pods
    • Self-Hosted k8s Static Pods (running atop the kubelet)
      • kube-apiserver
      • kube-controller-manager
      • kube-scheduler
      • kube-proxy

Setup & Use nanokube

0. Clone nanokube

git clone https://github.com/metral/nanokube
cd nanokube

// Install basic dependencies

1. Install Dependencies

  • Dependencies
// Enable AUFS
apt-get update && apt-get install linux-image-extra-$(uname -r) -y && modprobe aufs
  • Docker (Skip this if already installed)
apt-get install apt-transport-https ca-certificates
apt-key adv --keyserver hkp://p80.pool.sks-keyservers.net:80 --recv-keys 58118E89F3A912897C070ADBF76221572C52609D
echo "deb https://apt.dockerproject.org/repo ubuntu-xenial main" > /etc/apt/sources.list.d/docker.list
apt-get update && apt-get install docker-engine=1.11.2-0~xenial -y

Note: Installing Docker with the previous command on a systemd-enabled distro requires this fix to be applied.

2. Configure settings

If desired, tweaking the settings of the cluster is possible by altering the variable files in /vars.

If you are unsure about changing the settings, or you simply want to just get k8s up & running, you can skip this step for now.

3. Choose an installation model

Each installation model will start all of the cluster components & sleep until a SIGTERM is sent to nanokube.

  • Traditional/Binary

    ./nanokube.sh -t
  • Self-Hosted

    ./nanokube.sh -s

4. Accessing the k8s Cluster

Once nanokube has created the cluster, you can begin using k8s through the kubectl CLI by either backgrounding the nanokube process or opening up a new terminal.

By default in nanokube, the k8s Master is configured to advertise itself to the cluster on the eth1 interface using TLS, however, the cluster is also accessible on localhost:8080; therefore, one can access the cluster in a couple of ways:

  • By providing a kubeconfig file specifying the server & creds to kubectl, or
  • By leveraging defaults in kubectl to operate over localhost:8080


kubectl --kubeconfig=/etc/kubernetes/ssl/kubeconfig get pods


kubectl get pods

The kubeconfig isn't required for nanokube - it merely is called out here to demonstrate an alternate way to access a cluster that may not be on localhost.

To access the nanokube cluster, simply use kubectl [command]. See kubectl -h for help.

5. Verify Cluster Health

The health of the cluster is reported in nanokube, but to verify the components are running we can run a couple of commands ourselves.

Verify that the Master is running

kubectl cluster-info
kubectl version

Check component statuses

kubectl get cs

Check that the Nodes are ready

kubectl get nodes

Check that the DNS Pods & Service are running

The pods replicas must all be running and the Service IP must be assigned.

kubectl get pods,svc --namespace=kube-system -l k8s-app=kube-dns

6. Run an example

With an operational cluster, lets test that Kubernetes is working by running the guestbook example:

  • Create guestbook in k8s

    kubectl create -f https://raw.githubusercontent.com/kubernetes/kubernetes/master/examples/guestbook/all-in-one/guestbook-all-in-one.yaml
  • Check the status of the guestbook creation

    kubectl get pods,svc

Once all pods are running and the frontend, redis-master and redis-slave all have a Service IP, hit the frontend's Service IP to verify that the guestbook is running

curl <frontend_service_ip>


kubectl delete -f https://raw.githubusercontent.com/kubernetes/kubernetes/master/examples/guestbook/all-in-one/guestbook-all-in-one.yaml
  • Check the status of the guestbook deletion

    kubectl get pods,svc