Merge pull request #68 from jarrpa/doc-update

Major documentation update

README.md

@@ -1,17 +1,29 @@
 # gluster-kubernetes
 
-## Dynamic, persistent storage for Kubernetes with GlusterFS
+## Hyper-converged GlusterFS + heketi on Kubernetes
 
-This is the home of the **gluster-kubernetes** project,
-a new project which brings dynamically provisioned persistent
-storage volumes to kubernetes, using a hyperconverged Gluster
-deployment scheme.
+**gluster-kubernetes** is a project to provide Kubernetes administrators a
+mechanism to easily deploy a hyper-converged GlusterFS cluster along with with
+heketi onto an existing Kubernetes cluster. This is a convenient way to unlock
+the power of dynamically provisioned, persistent GlusterFS volumes in
+Kubernetes.
 
-### The components in this project are:
+### Component Projects
 
-* **Kubernetes** (https://github.com/kubernetes/kubernetes/), the container management system.
-* **GlusterFS** (https://www.gluster.org/), the scale-out storage system, running as pods inside the kubernetes cluster.
-* **heketi** (https://github.com/heketi/heketi), Gluster's volume management service interface, running in a pod inside kubernetes.
+* **[Kubernetes](http://kubernetes.io/)**, the container management system.
+* **[GlusterFS](https://www.gluster.org/)**, the scale-out storage system.
+* **[heketi](https://github.com/heketi/heketi)**, the RESTful volume management
+  interface for GlusterFS.
+
+### Demo
+
+**>>> [Video demo of the technology!](https://drive.google.com/file/d/0B667S2caJiy7QVpzVVFNQVdyaVE/view?usp=sharing) <<<**
+
+### Documentation
+
+* [Quickstart](#quickstart)
+* [Setup Guide](./docs/setup-guide.md)
+* [Hello World with GlusterFS Dynamic Provisioning](./docs/examples/hello_world/README.md)
 
 ### Quickstart
 
@@ -51,15 +63,16 @@ $ vagrant ssh master
 [vagrant@master]$ mv topology.json.sample topology.json
 ```
 
-The following commands are meant to be run with administrative privileges.
+The following commands are meant to be run with administrative privileges
+(e.g. `sudo su` beforehand).
 
 For ease of use in the the vagrant setup, we recommend you run the following:
 
 ```bash
 $ export KUBECONFIG="/etc/kubernetes/admin.conf"
 ```
-
-To verify the Kubernetes installation, run the following command:
+At this point, verify the Kubernetes installation by making sure all nodes are
+Ready:
 
 ```bash
 $ kubectl get nodes
@@ -70,73 +83,58 @@ node1     Ready     22h
 node2     Ready     22h
 ```
 
-***NOTE***: To see the version of Kubernetes (which will change based on latest official releases) simply do `kubectl version`
+***NOTE***: To see the version of Kubernetes (which will change based on
+latest official releases) simply do `kubectl version`. This will help in
+troubleshooting.
 
+For ease of use in the the vagrant setup, we recommend you run the following:
+
+```bash
+$ export KUBECONFIG="/etc/kubernetes/admin.conf"
+```
 
-Next, to deploy heketi, run the following:
+Next, to deploy heketi and GlusterFS, run the following:
 
 ```bash
 $ ./gk-deploy -g
 ```
 
-If you already have GlusterFS deployed in your cluster, you do not need the
+If you already have a pre-existing GlusterFS cluster, you do not need the
 `-g` option.
 
-
-After this completes, to aid in testing and following the rest of the examples, the following export 
-should be run and will set the HEKETI_CLI_SERVER env variable and will also give an
-easy means to echo the REST URL for the Heketi Server
+After this completes, GlusterFS and heketi should now be installed and ready
+to go. You can set the `HEKETI_CLI_SERVER` environment variable as follows so
+that it can be read directly by `heketi-cli` or sent to something like `curl`:
 
 ```bash
 $ export HEKETI_CLI_SERVER=$(kubectl describe svc/heketi | grep "Endpoints:" | awk '{print "http://"$2}')
 
 $ echo $HEKETI_CLI_SERVER
 http://10.42.0.0:8080
+
+$ curl $HEKETI_CLI_SERVER/hello
+Hello from Heketi
 ```
 
-kubernetes and heketi should now be installed and ready to go. 
-To verify Kubernetes installation fun the following commands:
+Your Kubernetes cluster should look something like this:
 
 ```bash
-$ kubectl get nodes
+$ kubectl get nodes,pods
 NAME      STATUS    AGE
 master    Ready     22h
 node0     Ready     22h
 node1     Ready     22h
 node2     Ready     22h
-
-$ kubectl get pods
 NAME                               READY     STATUS              RESTARTS   AGE
 glusterfs-node0-2509304327-vpce1   1/1       Running             0          1d
 glusterfs-node1-3290690057-hhq92   1/1       Running             0          1d
 glusterfs-node2-4072075787-okzjv   1/1       Running             0          1d
 heketi-3017632314-yyngh            1/1       Running             0          1d
 ```
 
-Notice that we have 3 gluster pods running and 1 heketi pod running
-
-To verify Heketi installation and REST Url is working:
-```bash
-curl <result of echo of $HEKETI_CLI_SERVER>/hello
-
-$ curl http://10.42.0.0:8080/hello
-Hello from Heketi
-```
-
-### Try It Out
-
-* Continue to an example of the [Hello World application using GlusterFS Dynamic Provisioning](./docs/examples/hello_world/README.md)
+You should now also be able to use `heketi-cli` or any other client of the
+heketi REST API (like the GlusterFS volume plugin) to create/manage volumes and
+then mount those volumes to verify they're working. To see an example of how
+to use this with a Kubernetes application, see the following:
 
-Alternatively, you should now also be able to use `heketi-cli` to create/manage volumes and then mount
-those volumes to verify they're working.
-
-### Demo
-
-**>>> [Video demo of the technology!](https://drive.google.com/file/d/0B667S2caJiy7QVpzVVFNQVdyaVE/view?usp=sharing) <<<**
-
-
-### Documentation
-
-* [Setup Guide](./docs/setup-guide.md)
-
-* [Hello World with GlusterFS Dynamic Provisioning](./docs/examples/hello_world/README.md)
+[Hello World application using GlusterFS Dynamic Provisioning](./docs/examples/hello_world/README.md)