Merge pull request #6432 from brendandburns/hyperkube

Add a docker image for hyperkube, and instructions on how to use.

docs/getting-started-guides/README.md

@@ -1,6 +1,8 @@
 If you are not sure what OSes and infrastructure is supported, the table below lists all the combinations which have
 been tested recently.
 
+For the easiest "kick the tires" experience, please try the [local docker](docker.md) guide.
+
 If you are considering contributing a new guide, please read the
 [guidelines](../../docs/devel/writing-a-getting-started-guide.md).
 
@@ -23,6 +25,7 @@ Vmware         | CoreOS       | CoreOS | flannel     | [docs](../../docs/getting
 Azure          | Saltstack    | Ubuntu | OpenVPN     | [docs](../../docs/getting-started-guides/azure.md)     | Community (@jeffmendoza)     |
 Bare-metal     | custom       | Ubuntu | _none_      | [docs](../../docs/getting-started-guides/ubuntu_single_node.md) | Community (@jainvipin)       |
 Bare-metal     | custom       | Ubuntu Cluster | flannel | [docs](../../docs/getting-started-guides/ubuntu_multinodes_cluster.md) | Community (@resouer @WIZARD-CXY) | use k8s version 0.12.0
+Docker         | custom       | N/A    | local       | [docs](docker.md) | Project (@brendandburns) | Tested @ 0.14.1 |
 Local          |              |        | _none_      | [docs](../../docs/getting-started-guides/locally.md)   | Community (@preillyme)                     |
 Ovirt          |              |        |             | [docs](../../docs/getting-started-guides/ovirt.md)     | Inactive                     |
 Rackspace      | CoreOS       | CoreOS | Rackspace   | [docs](../../docs/getting-started-guides/rackspace.md) | Inactive                     |

docs/getting-started-guides/docker.md

@@ -0,0 +1,76 @@
+## Running kubernetes locally via Docker
+
+The following instructions show you how to set up a simple, single node kubernetes cluster using Docker.
+
+### Step One: Run etcd
+```sh
+docker run --net=host -d kubernetes/etcd:2.0.5.1 /usr/local/bin/etcd --addr=127.0.0.1:4001 --bind-addr=0.0.0.0:4001 --data-dir=/var/etcd/data
+```
+
+### Step Two: Run the master
+```sh
+docker run --net=host -d -v /var/run/docker.sock:/var/run/docker.sock  gcr.io/google_containers/hyperkube:v0.14.1 /hyperkube kubelet --api_servers=http://localhost:8080 --v=2 --address=0.0.0.0 --enable_server --hostname_override=127.0.0.1 --config=/etc/kubernetes/manifests
+```
+
+This actually runs the kubelet, which in turn runs a [pod](https://github.com/GoogleCloudPlatform/kubernetes/blob/master/docs/pods.md) that contains the other master components.
+
+### Step Three: Run the service proxy
+*Note, this could be combined with master above, but it requires --privileged for iptables manipulation*
+```sh
+docker run -d --net=host --privileged gcr.io/google_containers/hyperkube:v0.14.1 /hyperkube proxy --master=http://127.0.0.1:8080 --v=2
+```
+
+### Test it out
+At this point you should have a running kubernetes cluster.  You can test this by downloading the kubectl 
+binary
+([OS X](http://storage.googleapis.com/kubernetes-release/release/v0.14.1/bin/darwin/amd64/kubectl))
+([linux](http://storage.googleapis.com/kubernetes-release/release/v0.14.1/bin/linux/amd64/kubectl))
+
+*Note:*
+On OS/X you will need to set up port forwarding via ssh:
+```sh
+boot2docker ssh -L8080:localhost:8080
+```
+
+List the nodes in your cluster by running::
+
+```sh
+kubectl get nodes
+```
+
+This should print:
+```
+NAME        LABELS    STATUS
+127.0.0.1   <none>    Ready
+```
+
+If you are running different kubernetes clusters, you may need to specify ```-s http://localhost:8080``` to select the local cluster.
+
+### Run an application
+```sh
+kubectl -s http://localhost:8080 run-container nginx --image=nginx --port=80
+```
+
+now run ```docker ps``` you should see nginx running.  You may need to wait a few minutes for the image to get pulled.
+
+### Expose it as a service:
+```sh
+kubectl expose rc nginx --port=80
+```
+
+This should print:
+```
+NAME      LABELS    SELECTOR              IP          PORT(S)
+nginx     <none>    run-container=nginx   <ip-addr>   80/TCP
+```
+
+Hit the webserver:
+```sh
+curl <insert-ip-from-above-here>
+```
+
+Note that you will need run this curl command on your boot2docker VM if you are running on OS X.
+
+### A note on turning down your cluster
+Many of these containers run under the management of the ```kubelet``` binary, which attempts to keep containers running, even if they fail.  So, in order to turn down
+the cluster, you need to first kill the kubelet container, and then any other containers.