Clean up READMEs and broken stuff.

Move all support for clouds that are broken with this change into an `icebox` directory. We'll move that stuff back out as we fix it up.
satnam6502 · Oct 10, 2014 · 38d5906 · 38d5906
1 parent 29e4299
commit 38d5906
Show file tree

Hide file tree

Showing 49 changed files with 118 additions and 139 deletions.
diff --git a/DESIGN.md b/DESIGN.md
@@ -123,10 +123,6 @@ Beyond just servicing REST operations, validating them and storing them in `etcd
 
 The `replicationController` type described above isn't strictly necessary for Kubernetes to be useful.  It is really a service that is layered on top of the simple `pod` API.  To enforce this layering, the logic for the replicationController is actually broken out into another server.  This server watches `etcd` for changes to `replicationController` objects and then uses the public Kubernetes API to implement the replication algorithm.
 
-## Release Process
-
-Right now "building" or "releasing" Kubernetes consists of some scripts (in `release/`) to create a `tar` of the necessary data and then uploading it to Google Cloud Storage.  In the future we will generate Docker images for the bulk of the above described components: [Issue #19](https://github.com/GoogleCloudPlatform/kubernetes/issues/19).
-
 ## GCE Cluster Configuration
 
 The scripts and data in the `cluster/` directory automates creating a set of Google Compute Engine VMs and installing all of the Kubernetes components.  There is a single master node and a set of worker (called minion) nodes.
@@ -139,9 +135,8 @@ The bootstrapping works like this:
 
 1. The `kube-up.sh` script uses the GCE [`startup-script`](https://developers.google.com/compute/docs/howtos/startupscript) mechanism for both the master node and the minion nodes.
   * For the minion, this simply configures and installs SaltStack.  The network range that this minion is assigned is baked into the startup-script for that minion (see [the networking doc](docs/networking.md) for more details).
-  * For the master, the release files are downloaded from GCS and unpacked.  Various parts (specifically the SaltStack configuration) are installed in the right places.
+  * For the master, the release files are staged and then downloaded from GCS and unpacked.  Various parts (specifically the SaltStack configuration) are installed in the right places.  Binaries are included in these tar files.
 2. SaltStack then installs the necessary servers on each node.
-  * All go code is currently downloaded to each machine and compiled at install time.
   * The custom networking bridge is configured on each minion before Docker is installed.
   * Configuration (like telling the `apiserver` the hostnames of the minions) is dynamically created during the saltstack install.
 3. After the VMs are started, the `kube-up.sh` script will call `curl` every 2 seconds until the `apiserver` starts responding.
@@ -150,7 +145,7 @@ The bootstrapping works like this:
 
 ### Cluster Security
 
-As there is no security currently built into the `apiserver`, the salt configuration will install `nginx`.  `nginx` is configured to serve HTTPS with a self signed certificate.  HTTP basic auth is used from the client to `nginx`.  `nginx` then forwards the request on to the `apiserver` over plain old HTTP.  Because a self signed certificate is used, access to the server should be safe from eavesdropping but is subject to "man in the middle" attacks.  Access via the browser will result in warnings and tools like curl will require an "--insecure" flag.
+As there is no security currently built into the `apiserver`, the salt configuration will install `nginx`.  `nginx` is configured to serve HTTPS with a self signed certificate.  HTTP basic auth is used from the client to `nginx`.  `nginx` then forwards the request on to the `apiserver` over plain old HTTP.  As part of cluster spin up, ssh is used to download both the public cert for the server and a client cert pair.  These are used for mutual authentication to nginx.
 
 All communication within the cluster (worker nodes to the master, for instance) occurs on the internal virtual network and should be safe from eavesdropping.
 

diff --git a/MAINTAINERS.md b/MAINTAINERS.md
@@ -1,6 +1,7 @@
 # Maintainers
 
-People responsible for ports of Kubernetes to different environments. CC at least one maintainer on relevant issues and PRs.
+People responsible for ports of Kubernetes to different environments. CC at
+least one maintainer on relevant issues and PRs.
 
 ## OS Distributions
 
@@ -11,8 +12,8 @@ People responsible for ports of Kubernetes to different environments. CC at leas
 
 * GCE: [Brendan Burns](https://github.com/brendandburns), [Joe Beda](https://github.com/jbeda), [Daniel Smith](https://github.com/lavalamp), [Tim Hockin](https://github.com/thockin)
 * Azure: [Jeff Mendoza](https://github.com/jeffmendoza)
-* Vsphere: [Pieter Noordhuis](https://github.com/pietern)
+* VSphere: [Pieter Noordhuis](https://github.com/pietern)
 * Rackspace: [Ryan Richard](https://github.com/doublerr)
-* Ovirt: [Federico Simoncelli](https://github.com/simon3z)
+* oVirt: [Federico Simoncelli](https://github.com/simon3z)
 * Local: [Derek Carr](https://github.com/derekwaynecarr)
-* Vagrant: [Derek Carr](https://github.com/derekwaynecarr)
+* Vagrant: [Derek Carr](https://github.com/derekwaynecarr)
diff --git a/README.md b/README.md
@@ -17,17 +17,18 @@ While the concepts and architecture in Kubernetes represent years of experience
 * Getting Started Guides
   * [Google Compute Engine](docs/getting-started-guides/gce.md)
   * [Vagrant](docs/getting-started-guides/vagrant.md)
-  * [Locally](docs/getting-started-guides/locally.md)
-  * [CoreOS](docs/getting-started-guides/coreos.md)
   * Fedora (w/ [Ansible](docs/getting-started-guides/fedora/fedora_ansible_config.md) or [manual](docs/getting-started-guides/fedora/fedora_manual_config.md))
-  * [vSphere](docs/getting-started-guides/vsphere.md)
-  * [Microsoft Azure](docs/getting-started-guides/azure.md)
-  * [Rackspace](docs/getting-started-guides/rackspace.md)
   * [Circle CI](https://circleci.com/docs/docker#google-compute-engine-and-kubernetes)
   * [Digital Ocean](https://github.com/bketelsen/coreos-kubernetes-digitalocean)
+  * [CoreOS](docs/getting-started-guides/coreos.md)
   * [OpenStack](https://developer.rackspace.com/blog/running-coreos-and-kubernetes/)
+* The following clouds are currently broken at Kubernetes head.  Please sync your client to `v0.3` (`git checkout v0.3`) to use these:
+  * [Locally](docs/getting-started-guides/locally.md)
+  * [vSphere](docs/getting-started-guides/vsphere.md)
+  * [Microsoft Azure](docs/getting-started-guides/azure.md)
+  * [Rackspace](docs/getting-started-guides/rackspace.md)
 * [Kubernetes 101](https://github.com/GoogleCloudPlatform/kubernetes/tree/master/examples/walkthrough)
-* [kubecfg command line tool](docs/cli.md)
+* [kubecfg command line tool](https://github.com/GoogleCloudPlatform/kubernetes/blob/master/docs/cli.md)
 * [Kubernetes API Documentation](http://cdn.rawgit.com/GoogleCloudPlatform/kubernetes/31a0daae3627c91bc96e1f02a6344cd76e294791/api/kubernetes.html)
 * [Kubernetes Client Libraries](docs/client-libraries.md)
 * [Discussion and Community Support](#community-discussion-and-support)
@@ -55,4 +56,3 @@ If you have questions or want to start contributing please reach out.  We don't
 The Kubernetes team is hanging out on IRC on the [#google-containers channel on freenode.net](http://webchat.freenode.net/?channels=google-containers).  We also have the [google-containers Google Groups mailing list](https://groups.google.com/forum/#!forum/google-containers) for questions and discussion as well as the [kubernetes-announce mailing list](https://groups.google.com/forum/#!forum/kubernetes-announce) for important announcements (low-traffic, no chatter).
 
 If you are a company and are looking for a more formal engagement with Google around Kubernetes and containers at Google as a whole, please fill out [this form](https://docs.google.com/a/google.com/forms/d/1_RfwC8LZU4CKe4vKq32x5xpEJI5QZ-j0ShGmZVv9cm4/viewform) and we'll be in touch.
-
diff --git a/Vagrantfile b/Vagrantfile
@@ -38,8 +38,8 @@ else # sorry Windows folks, I can't help you
   $vm_cpus = 2
 end
 
-# Give VM 1024 of RAM
-$vm_mem = 1024
+# Give VM 512MB of RAM
+$vm_mem = 512
 
 
 Vagrant.configure(VAGRANTFILE_API_VERSION) do |config|

diff --git a/build/README.md b/build/README.md
@@ -78,6 +78,9 @@ If the release script is set to upload to GCS, it'll do the following:
 
 ## TODOs
 
+These are in no particular order
+
+* [ ] Harmonize with scripts in `hack/`.  How much do we support building outside of Docker and these scripts?
 * [ ] Get a cluster up and running with the Docker images.  Perhaps start with a local cluster and move up to a GCE cluster.
 * [ ] Implement (#186)[https://github.com/GoogleCloudPlatform/kubernetes/issues/186].  This will make it easier to develop Kubernetes.
 * [ ] Deprecate/replace most of the stuff in the hack/

diff --git a/docs/development.md b/docs/development.md
@@ -1,5 +1,9 @@
 # Development Guide
 
+# Releases and Official Builds
+
+Official releases are built in Docker containers.  Details are [here](build/README.md).  You can do simple builds and development with just a local Docker installation.  If want to build go locally outside of docker, please continue below.
+
 ## Go development environment
 
 Kubernetes is written in [Go](http://golang.org) programming language. If you haven't set up Go development environment, please follow [this instruction](http://golang.org/doc/code.html) to install go tool and set up GOPATH. Ensure your version of Go is at least 1.3.

diff --git a/docs/getting-started-guides/azure.md b/docs/getting-started-guides/azure.md
@@ -1,3 +1,8 @@
+# WARNING
+These instructions are broken at git HEAD.  Please either:
+* Sync back to `v0.3` with `git checkout v0.3`
+* Download a [snapshot of `v0.3`](https://github.com/GoogleCloudPlatform/kubernetes/archive/v0.3.tar.gz)
+
 ## Getting started on Microsoft Azure
 
 ### Prerequisites

diff --git a/docs/getting-started-guides/binary_release.md b/docs/getting-started-guides/binary_release.md
@@ -0,0 +1,25 @@
+## Getting a Binary Release
+
+You can either build a release from sources or download a pre-built release.  If you don't plan on developing Kubernetes itself, we suggest a pre-built release.
+
+### Prebuilt Binary Release
+
+Soon, we will have a list of numbered and nightly releases.  Until then, you can download a development release/snapshot from [here](http://storage.googleapis.com/kubernetes-releases-56726/devel/kubernetes.tar.gz).
+
+Unpack this tar file on Linux or OS X.  Most guides assume you are in the `kubernetes/` directory.
+
+### Building from source
+
+Get the Kubernetes source.  If you are simply building a release from source there is no need to set up a full golang environment as all building happens in a Docker container.
+
+**TODO:** Change this to suggest using a numbered release once we have one with the new build scripts.
+
+Building a release is simple.
+
+```bash
+git clone https://github.com/GoogleCloudPlatform/kubernetes.git
+cd kubernetes
+build/release.sh
+```
+
+For more details on the release process see the [`build/` directory](../../build)
diff --git a/docs/getting-started-guides/gce.md b/docs/getting-started-guides/gce.md
@@ -7,55 +7,63 @@ The example below creates a Kubernetes cluster with 4 worker node Virtual Machin
 1. You need a Google Cloud Platform account with billing enabled. Visit
    [http://cloud.google.com/console](http://cloud.google.com/console) for more details.
 2. Make sure you can start up a GCE VM.  At least make sure you can do the [Create an instance](https://developers.google.com/compute/docs/quickstart#addvm) part of the GCE Quickstart.
-3. Make sure you can ssh into the VM without interactive prompts. You'll need to set up a ssh key and expose port 22 in the firewall if you choose to use a network other than the default network (`gcutil addfirewall --description "SSH allowed from anywhere" --allowed=tcp:22 default-ssh`)
-4. You need to have the Google Cloud Storage API, and the Google Cloud Storage JSON API enabled.
+3. Make sure you can ssh into the VM without interactive prompts.
+  * Your GCE SSH key must either have no passcode or you need to be using `ssh-agent`.
+  * Ensure the GCE firewall isn't blocking port 22 to your VMs.  By default, this should work but if you have edited firewall rules or created a new non-default network, you'll need to expose it: `gcutil addfirewall --network=<network-name> --description "SSH allowed from anywhere" --allowed=tcp:22 default-ssh`
+4. You need to have the Google Cloud Storage API, and the Google Cloud Storage JSON API enabled. This can be done in the Google Cloud Console.
 
 
 ### Prerequisites for your workstation
 
-1. You must have Go (version 1.2 or later) installed: [www.golang.org](http://www.golang.org).
-2. You must have the [`gcloud` components](https://developers.google.com/cloud/sdk/) installed.
+1. Be running a Linux or Mac OS X.
+2. You must have the [Google Cloud SDK](https://developers.google.com/cloud/sdk/) installed.  This will get you `gcloud`, `gcutil` and `gsutil`.
 3. Ensure that your `gcloud` components are up-to-date by running `gcloud components update`.
-4. Install godep (optional, only required when modifying package dependencies). [Instructions here](https://github.com/GoogleCloudPlatform/kubernetes#installing-godep)
-5. Get the Kubernetes source:
-      * Kubernetes 0.3 \[[.tar.gz](https://github.com/GoogleCloudPlatform/kubernetes/archive/v0.3.tar.gz)\] \[[.zip](https://github.com/GoogleCloudPlatform/kubernetes/archive/v0.3.zip)\]
+4. If you want to build your own release, you need to have [Docker
+installed](https://docs.docker.com/installation/).  On Mac OS X you can use
+boot2docker.
+5. Get or build a [binary release](binary_release.md)
 
-### Setup
+### Starting a Cluster
 
-The setup script builds Kubernetes, then creates Google Compute Engine instances, firewall rules, and routes:
-
-```
-cd kubernetes
-hack/dev-build-and-up.sh
+```bash
+cluster/kube-up.sh
 ```
 
-The script above relies on Google Storage to deploy the software to instances running in GCE. It uses the Google Storage APIs so the "Google Cloud Storage JSON API" setting must be enabled for the project in the Google Developers Console (https://cloud.google.com/console#/project).
+The script above relies on Google Storage to stage the kuberntes release. It
+then will start (by default) a single master VM along with 4 worker VMs.  You
+can tweak some of these parameters by editing `cluster/gce/config-default.sh`
+
+The instances must be able to connect to each other using their private IP. The
+script uses the "default" network which should have a firewall rule called
+"default-allow-internal" which allows traffic on any port on the private IPs.
+If this rule is missing from the default network or if you change the network
+being used in `cluster/config-default.sh` create a new rule with the following
+field values:
 
-The instances must also be able to connect to each other using their private IP. The script uses the "default" network which should have a firewall rule called "default-allow-internal" which allows traffic on any port on the private IPs.
-If this rule is missing from the default network or if you change the network being used in `cluster/config-default.sh` create a new rule with the following field values:
-* Source Ranges: 10.0.0.0/8
-* Allowed Protocols or Port: tcp:1-65535;udp:1-65535;icmp
+* Source Ranges: `10.0.0.0/8`
+* Allowed Protocols and Port: `tcp:1-65535;udp:1-65535;icmp`
 
 ### Running a container (simple version)
 
 Once you have your instances up and running, the `build-go.sh` script sets up
 your Go workspace and builds the Go components.
 
-The `kubecfg.sh` script spins up two containers, running [Nginx](http://nginx.org/en/) and with port 80 mapped to 8080:
+The `kubecfg.sh` line below spins up two containers running
+[Nginx](http://nginx.org/en/) with port 80 mapped to 8080:
 
-```
-cd kubernetes
-hack/build-go.sh
+```bash
 cluster/kubecfg.sh -p 8080:80 run dockerfile/nginx 2 myNginx
 ```
 
 To stop the containers:
-```
+
+```bash
 cluster/kubecfg.sh stop myNginx
 ```
 
 To delete the containers:
-```
+
+```bash
 cluster/kubecfg.sh rm myNginx
 ```
 
@@ -66,14 +74,14 @@ Assuming you've run `hack/dev-build-and-up.sh` and `hack/build-go.sh`, you
 can create a pod like this:
 
 
-```
+```bash
 cd kubernetes
 cluster/kubecfg.sh -c api/examples/pod.json create /pods
 ```
 
 Where pod.json contains something like:
 
-```
+```json
 {
   "id": "php",
   "kind": "Pod",
@@ -109,20 +117,20 @@ Where pod.json contains something like:
 
 You can see your cluster's pods:
 
-```
+```bash
 cluster/kubecfg.sh list pods
 ```
 
 and delete the pod you just created:
 
-```
+```bash
 cluster/kubecfg.sh delete pods/php
 ```
 
-Look in `api/examples/` for more examples
+Look in `examples/` for more examples
 
 ### Tearing down the cluster
-```
+```bash
 cd kubernetes
 cluster/kube-down.sh
 ```
diff --git a/docs/getting-started-guides/rackspace.md b/docs/getting-started-guides/rackspace.md
@@ -1,3 +1,8 @@
+# WARNING
+These instructions are broken at git HEAD.  Please either:
+* Sync back to `v0.3` with `git checkout v0.3`
+* Download a [snapshot of `v0.3`](https://github.com/GoogleCloudPlatform/kubernetes/archive/v0.3.tar.gz)
+
 # Rackspace
 In general, the dev-build-and-up.sh workflow for Rackspace is the similar to GCE. The specific implementation is different mainly due to network differences between the providers:
 

diff --git a/docs/getting-started-guides/vagrant.md b/docs/getting-started-guides/vagrant.md
@@ -3,8 +3,7 @@
 ### Prerequisites
 1. Install latest version >= 1.6.2 of vagrant from http://www.vagrantup.com/downloads.html
 2. Install latest version of Virtual Box from https://www.virtualbox.org/wiki/Downloads
-3. Get the Kubernetes source:
-   * Kubernetes 0.3 [tar.gz](https://github.com/GoogleCloudPlatform/kubernetes/archive/v0.3.tar.gz) or [zip](https://github.com/GoogleCloudPlatform/kubernetes/archive/v0.3.zip)
+3. Get or build a [binary release](binary_release.md)
 
 ### Setup
 
@@ -15,7 +14,7 @@ cd kubernetes
 vagrant up
 ```
 
-Vagrant will provision each machine in the cluster with all the necessary components to build and run Kubernetes.  The initial setup can take a few minutes to complete on each machine.
+Vagrant will provision each machine in the cluster with all the necessary components to run Kubernetes.  The initial setup can take a few minutes to complete on each machine.
 
 By default, each VM in the cluster is running Fedora, and all of the Kubernetes services are installed into systemd.
 
@@ -102,7 +101,7 @@ cluster/kube-up.sh
 ```
 
 Destroy the vagrant cluster
- 
+
 ```
 cluster/kube-down.sh
 ```
@@ -200,10 +199,10 @@ Once the docker image for nginx has been downloaded, the container will start an
 ```
 $ sudo docker ps
 CONTAINER ID        IMAGE                     COMMAND                CREATED             STATUS              PORTS                    NAMES
-dbe79bf6e25b        dockerfile/nginx:latest   "nginx"                21 seconds ago      Up 19 seconds                                k8s--mynginx.8c5b8a3a--7813c8bd_-_3ffe_-_11e4_-_9036_-_0800279696e1.etcd--7813c8bd_-_3ffe_-_11e4_-_9036_-_0800279696e1--fcfa837f   
-fa0e29c94501        kubernetes/pause:latest   "/pause"               8 minutes ago       Up 8 minutes        0.0.0.0:8080->80/tcp     k8s--net.a90e7ce4--7813c8bd_-_3ffe_-_11e4_-_9036_-_0800279696e1.etcd--7813c8bd_-_3ffe_-_11e4_-_9036_-_0800279696e1--baf5b21b       
-aa2ee3ed844a        google/cadvisor:latest    "/usr/bin/cadvisor -   38 minutes ago      Up 38 minutes                                k8s--cadvisor.9e90d182--cadvisor_-_agent.file--4626b3a2                                                                            
-65a3a926f357        kubernetes/pause:latest   "/pause"               39 minutes ago      Up 39 minutes       0.0.0.0:4194->8080/tcp   k8s--net.c5ba7f0e--cadvisor_-_agent.file--342fd561                                                               
+dbe79bf6e25b        dockerfile/nginx:latest   "nginx"                21 seconds ago      Up 19 seconds                                k8s--mynginx.8c5b8a3a--7813c8bd_-_3ffe_-_11e4_-_9036_-_0800279696e1.etcd--7813c8bd_-_3ffe_-_11e4_-_9036_-_0800279696e1--fcfa837f
+fa0e29c94501        kubernetes/pause:latest   "/pause"               8 minutes ago       Up 8 minutes        0.0.0.0:8080->80/tcp     k8s--net.a90e7ce4--7813c8bd_-_3ffe_-_11e4_-_9036_-_0800279696e1.etcd--7813c8bd_-_3ffe_-_11e4_-_9036_-_0800279696e1--baf5b21b
+aa2ee3ed844a        google/cadvisor:latest    "/usr/bin/cadvisor -   38 minutes ago      Up 38 minutes                                k8s--cadvisor.9e90d182--cadvisor_-_agent.file--4626b3a2
+65a3a926f357        kubernetes/pause:latest   "/pause"               39 minutes ago      Up 39 minutes       0.0.0.0:4194->8080/tcp   k8s--net.c5ba7f0e--cadvisor_-_agent.file--342fd561
 ```
 
 Going back to listing the pods, services and replicationControllers, you now have:
@@ -262,7 +261,7 @@ rm ~/.kubernetes_auth_vagrant
 After using kubecfg.sh make sure that the correct credentials are set:
 
 ```
-cat ~/.kubernetes_vagrant_auth 
+cat ~/.kubernetes_vagrant_auth
 {
   "User": "vagrant",
   "Password": "vagrant"