From b6b5c42866c575258f2094762521e3b2e41f8736 Mon Sep 17 00:00:00 2001
From: jackgr <jackgr@google.com>
Date: Thu, 5 Nov 2015 18:11:04 -0800
Subject: [PATCH] Streamline getting started.

---
 .gitignore                   |   2 +-
 README.md                    |  87 +++++++++++----------
 examples/bootstrap/README.md |  67 ++++++++++++++++
 install.yaml                 | 145 +++++++++++++++++++++++++++++++++++
 4 files changed, 259 insertions(+), 42 deletions(-)
 create mode 100644 examples/bootstrap/README.md
 create mode 100644 install.yaml

diff --git a/.gitignore b/.gitignore
index c55c24e6b..8583018ea 100644
--- a/.gitignore
+++ b/.gitignore
@@ -3,4 +3,4 @@ expandybird/expansion/*.pyc
 resourcifier/pkg/*
 resourcifier/bin/*
 manager/pkg/*
-
+.project
diff --git a/README.md b/README.md
index 764467239..1b0210a9a 100644
--- a/README.md
+++ b/README.md
@@ -21,65 +21,68 @@ Kubernetes configuration SIG.
 
 ## Getting started
 
-For the following steps, it is assumed that you have a Kubernetes cluster up
-and running, and that you can run kubectl commands against it. It is also
-assumed that you're working with a clone of the repository installed in the src
-folder of your GOPATH, and that your PATH contains $GOPATH/bin, per convention.
+There are two ways to get started...
 
-Since Deployment Manager uses Python and will be running locally on your
-machine, you will first need to make sure the necessary Python packages are
-installed. This assumes that you have already installed the pip package
-management system on your machine.
+* The quick way simply installs Deployment Manager in your cluster using
+kubectl. This is the fastest way to get started and takes only a few seconds.
 
-```
-pip install -r expandybird/requirements.txt
-```
+* The interesting way bootstraps Deployment Manager, by building and running a
+local instance on your machine, and then using it to install another instance
+in your cluster. You might want to go this way if you're interested in contributing
+to Deployment Manager.
 
-Next, you'll build and install the binaries, and bootstrap Deployment Manager
-into the cluster. Finally, you'll deploy an example application on the
-cluster using Deployment Manager.
+Both assume that you have a Kubernetes cluster up and running, and that you can
+run `kubectl` commands against it. They both also assume that that you're working
+with a clone of the repository installed in the src folder of your GOPATH, per
+convention.
 
-### Building and installing the binaries
+Instructions for the quick install follow here. Instructions for bootstrapping
+Deployment Manager can be found in [examples/bootstrap/README.md](examples/bootstrap/README.md).
 
-In this step, you're going to build and install the Deployment Manager binaries.
-You can do this by running make in the repository root.
+### Quick Install
+
+For the quick install, you're going to use `kubectl` to create the replication
+controllers and services that comprise a Deployment Manager instance from a predefined
+configuration file, as follows:
 
 ```
-make
+kubectl create -f install.yaml
 ```
 
-### Bootstrapping Deployment Manager
-
-In this step, you're going to bootstrap Deployment Manager into the cluster.
-
-Next, start the three Deployment Manager binaries on localhost using the supplied
-bootstrap script.
+That's it. You should now be able to see Deployment Manager running in your cluster
+using:
 
 ```
-./examples/bootstrap/bootstrap.sh
+kubectl get pod,rc,service
 ```
 
-The script starts the following binaries:
-* manager (frontend service) running on port 8080
-* expandybird (expands templates) running on port 8081
-* resourcifier (reifies primitive Kubernetes resources) running on port 8082
+If you see replication controllers named expandybird-rc, manager-rc and resourcifier-rc
+with pods that are READY, and services with corresponding names, then Deployment
+Manager is up and running.
+
+Note that you can also tear down Deployment Manager using the same file, with:
 
-It also starts kubectl proxy on port 8001.
+```
+kubectl delete -f install.yaml
+```
 
-Next, use the Deployment Manager running on localhost to deploy itself onto the
-cluster using the supplied command line tool and template.
+The easiest way to interact with Deployment Manager, now that it's up and running,
+is to use a `kubectl` proxy:
 
 ```
-client --name test --service=http://localhost:8080 examples/bootstrap/bootstrap.yaml
+kubectl proxy --port=8001 &
 ```
 
-You should now have Deployment Manager running on your cluster, and it should be
-visible using kubectl (kubectl get pod,rc,service).
+This command will start a proxy that lets you interact with the Kubernetes api
+server through port 8001 on you local host. However, there are other ways to access
+Deployment Manager. We won't go into them here, but if you know how to access
+services running on Kubernetes, you should be able to use any of the supported
+methods to access Deployment Manager.
 
 ### Deploying your first application (Guestbook)
 
-In this step, you're going to deploy the canonical guestbook example to your
-Kubernetes cluster.
+Next, you're going to deploy the canonical guestbook example to your Kubernetes
+cluster.
 
 ```
 client --name guestbook --service=http://localhost:8001/api/v1/proxy/namespaces/default/services/manager-service:manager examples/guestbook/guestbook.yaml
@@ -94,7 +97,7 @@ kubectl get service
 
 You should see frontend-service running. If your cluster supports external
 load balancing, it will have an external IP assigned to it, and you should be 
-able to navigate to it to see the guestbook in action.
+able to navigate to it in your browser to see the guestbook in action.
 
 ## Building the container images
 
@@ -113,12 +116,14 @@ make push
 
 ## Design of Deployment Manager
 
-There is a more detailed [design document](https://github.com/kubernetes/deployment-manager/blob/master/docs/design/design.md)
+There is a more detailed [design document](docs/design/design.md)
 available.
 
 ## Status of the project
 
-The project is still in a very active development mode so you might run into issues,
-please don't be shy about letting us know when you run into issues.
+The project is still under active development, so you might run into issues. If
+you do, please don't be shy about letting us know, or better yet, contributing a
+fix or feature. We use the same contribution conventions as the main Kubernetes
+repository.
 
 
diff --git a/examples/bootstrap/README.md b/examples/bootstrap/README.md
new file mode 100644
index 000000000..e6ae37311
--- /dev/null
+++ b/examples/bootstrap/README.md
@@ -0,0 +1,67 @@
+# Bootstrapping Deployment Manager
+
+Welcome to the bootstrap example. The instructions below will step you through
+the process of building and running a local instance of Deployment Manager on
+your local machine, and then using it to deploy another instance in your cluster.
+
+This example provides insights into how Deployment Manager works, and is
+recommended for anyone interested in contributing to the project.
+
+The instructions below assume that you have a Kubernetes cluster up and running,
+and that you can run `kubectl` commands against it. They also assume that that
+you're working with a clone of the repository installed in the src folder of your 
+GOPATH and that your PATH contains `$GOPATH/bin`, per convention.
+
+## Installing required python packages
+
+Since Deployment Manager uses Python and will be running locally on your
+machine, you will first need to make sure the necessary Python packages are
+installed. This assumes that you have already installed the pip package
+management system on your machine.
+
+```
+sudo pip install -r expandybird/requirements.txt
+```
+
+## Building and installing the binaries
+
+Next, you're going to build and install the Deployment Manager binaries. You can
+do this by running make in the repository root.
+
+```
+make
+```
+
+## Bootstrapping Deployment Manager
+
+Now, you're ready to bootstrap Deployment Manager into the cluster.
+
+### Start Deployment Manager on localhost
+
+First, start the three Deployment Manager binaries on localhost using the supplied
+bootstrap script.
+
+```
+./examples/bootstrap/bootstrap.sh
+```
+
+The script starts the following binaries:
+* manager (frontend service) running on port 8080
+* expandybird (expands templates) running on port 8081
+* resourcifier (reifies primitive Kubernetes resources) running on port 8082
+
+It also starts kubectl proxy on port 8001.
+
+### Deploy Deployment Manager into your cluster
+
+Next, use the Deployment Manager running on localhost to deploy itself onto the
+cluster using the supplied command line tool and template.
+
+```
+client --name test --service=http://localhost:8080 examples/bootstrap/bootstrap.yaml
+```
+
+You should now have Deployment Manager running on your cluster, and it should be
+visible using kubectl (kubectl get pod,rc,service).
+
+
diff --git a/install.yaml b/install.yaml
new file mode 100644
index 000000000..18e3fa90e
--- /dev/null
+++ b/install.yaml
@@ -0,0 +1,145 @@
+######################################################################
+# Copyright 2015 The Kubernetes Authors All rights reserved.
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#     http://www.apache.org/licenses/LICENSE-2.0
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+######################################################################
+
+---
+apiVersion: v1
+kind: Service
+metadata:
+  labels:
+    app: dm
+    name: expandybird-service
+  name: expandybird-service
+namespace: default
+spec:
+  ports:
+  - name: expandybird
+    port: 8081
+    targetPort: 8080
+  selector:
+    app: dm
+    name: expandybird
+---
+apiVersion: v1
+kind: ReplicationController
+metadata:
+  labels:
+    app: dm
+    name: expandybird-rc
+  name: expandybird-rc
+namespace: default
+spec:
+  replicas: 2
+  selector:
+    app: dm
+    name: expandybird
+  template:
+    metadata:
+      labels:
+        app: dm
+        name: expandybird
+    spec:
+      containers:
+      - env: []
+        image: gcr.io/dm-k8s-testing/expandybird:latest
+        name: expandybird
+        ports:
+        - containerPort: 8080
+          name: expandybird
+---
+apiVersion: v1
+kind: Service
+metadata:
+  labels:
+    app: dm
+    name: resourcifier-service
+  name: resourcifier-service
+namespace: default
+spec:
+  ports:
+  - name: resourcifier
+    port: 8082
+    targetPort: 8080
+  selector:
+    app: dm
+    name: resourcifier
+---
+apiVersion: v1
+kind: ReplicationController
+metadata:
+  labels:
+    app: dm
+    name: resourcifier-rc
+  name: resourcifier-rc
+namespace: default
+spec:
+  replicas: 2
+  selector:
+    app: dm
+    name: resourcifier
+  template:
+    metadata:
+      labels:
+        app: dm
+        name: resourcifier
+    spec:
+      containers:
+      - env: []
+        image: gcr.io/dm-k8s-testing/resourcifier:latest
+        name: resourcifier
+        ports:
+        - containerPort: 8080
+          name: resourcifier
+---
+apiVersion: v1
+kind: Service
+metadata:
+  labels:
+    app: dm
+    name: manager-service
+  name: manager-service
+namespace: default
+spec:
+  ports:
+  - name: manager
+    port: 8080
+    targetPort: 8080
+  selector:
+    app: dm
+    name: manager
+---
+apiVersion: v1
+kind: ReplicationController
+metadata:
+  labels:
+    app: dm
+    name: manager-rc
+  name: manager-rc
+namespace: default
+spec:
+  replicas: 1
+  selector:
+    app: dm
+    name: manager
+  template:
+    metadata:
+      labels:
+        app: dm
+        name: manager
+    spec:
+      containers:
+      - env: []
+        image: gcr.io/dm-k8s-testing/manager:latest
+        name: manager
+        ports:
+        - containerPort: 8080
+          name: manager