How to get started, and achieve tasks, using Kubernetes

Edit This Page

Running Kubernetes Locally with No VM



Not running Linux? Consider running Linux in a local virtual machine with vagrant, or on a cloud provider like Google Compute Engine


At least Docker 1.8.3+. Ensure the Docker daemon is running and can be contacted (try docker ps). Some of the Kubernetes components need to run as root, which normally works fine with docker.


You need an etcd in your path, please make sure it is installed and in your $PATH.


You need go at least 1.3+ in your path, please make sure it is installed and in your $PATH.

Starting the cluster

First, you need to download Kubernetes. Then open a separate tab of your terminal and run the following (since one needs sudo access to start/stop Kubernetes daemons, it is easier to run the entire script as root):

cd kubernetes

This will build and start a lightweight local cluster, consisting of a master and a single node. Type Control-C to shut it down.

You can use the cluster/ script to interact with the local cluster. hack/ will print the commands to run to point kubectl at the local cluster.

Running a container

Your cluster is running, and you want to start running containers!

You can now use any of the cluster/ commands to interact with your local setup.

cluster/ get pods
cluster/ get services
cluster/ get deployments
cluster/ run my-nginx --image=nginx --replicas=2 --port=80

## begin wait for provision to complete, you can monitor the docker pull by opening a new terminal
  sudo docker images
  ## you should see it pulling the nginx image, once the above command returns it
  sudo docker ps
  ## you should see your container running!
## end wait

## introspect Kubernetes!
cluster/ get pods
cluster/ get services
cluster/ get deployments

Running a user defined pod

Note the difference between a container and a pod. Since you only asked for the former, Kubernetes will create a wrapper pod for you. However you cannot view the nginx start page on localhost. To verify that nginx is running you need to run curl within the docker container (try docker exec).

You can control the specifications of a pod via a user defined manifest, and reach nginx through your browser on the port specified therein:

cluster/ create -f docs/user-guide/pod.yaml



I cannot reach service IPs on the network.

Some firewall software that uses iptables may not interact well with kubernetes. If you have trouble around networking, try disabling any firewall or other iptables-using systems, first. Also, you can check if SELinux is blocking anything by running a command such as journalctl --since yesterday | grep avc.

By default the IP range for service cluster IPs is 10.0.. - depending on your docker installation, this may conflict with IPs for containers. If you find containers running with IPs in this range, edit hack/ and change the service-cluster-ip-range flag to something else.

I changed Kubernetes code, how do I run it?

cd kubernetes

kubectl claims to start a container but get pods and docker ps don’t show it.

One or more of the Kubernetes daemons might’ve crashed. Tail the logs of each in /tmp.

$ ls /tmp/kube*.log
$ tail -f /tmp/kube-apiserver.log

The pods fail to connect to the services by host names

The script doesn’t start a DNS service. Similar situation can be found here. You can start a manually. Related documents can be found here