Merge pull request #451 from medinatiger/dev

Add more information to the landing page

cluster-api/README.md

@@ -1,7 +1,23 @@
-Note that cluster-api effort is still in the prototype stage. All the code here is for experimental and demo-purpose, and under rapid change.
+## What is cluster-api
 
-### How to build
+It's a declarative way to create, configure, and manage a cluster. It provides an optional, additive functionality on
+top of core Kubernetes.
+
+Note that cluster-api effort is still in the prototype stage. All the code here is for experimental and demo-purpose,
+and under rapid change.
+
+## How is it implemented
+We use custom resource type (CRD) to model new machine and cluster object. Just like other resources in kubernetes,
+a [machine controller](machine-controller/README.md) is running as regular pod to reconcile the actual machine state vs desired state.
+
+## How to run
+### Prerequisite
+
+* `kubectl` is required, see [here](http://kubernetes.io/docs/user-guide/prereqs/).
+* `Google Cloud SDK` is installed if you are creating cluster on GCP, see [here](https://cloud.google.com/sdk/downloads).
+* You need to have an account on Google Cloud Platform which have enough quota for the resource.
 
+### How to build
 ```bash
 $ cd $GOPATH/src/k8s.io/
 $ git clone [email protected]:kubernetes/kube-deploy.git
@@ -10,10 +26,19 @@ $ go build
 ```
 
 ### How to run
+
 1) Follow steps mentioned above and build cluster-api.
 2) Update cluster.yaml with cluster name.
 3) Update machines.yaml with google cloud project name.
 4) Run `gcloud auth application-default login` to get default credentials.
 5) Create cluster: `./cluster-api create -c cluster.yaml -m machines.yaml`
 6) Add new nodes: update new-machines.yaml with cloud project name and run `./cluster-api add -m new-machines.yaml`
-7) Delete cluster: `./cluster-api delete`
+7) Delete cluster: `./cluster-api delete`
+
+### How to use the API
+
+To see how we can use API to build toolings on top of cluster API, please check out a few examples below.
+
+* [Upgrade](upgrader/README.md)
+* [Repair](repair/README.md)
+* [Scaling](examples/machineset/README.md)

cluster-api/examples/machineset/README.md

@@ -0,0 +1,15 @@
+# Machineset
+Machineset is client side implementation for machine set concept. It allows scale up/down the nodes in the cluster.
+
+## Build
+
+```bash
+$ cd $GOPATH/src/k8s.io/
+$ git clone [email protected]:kubernetes/kube-deploy.git
+$ cd kube-deploy/cluster-api/examples/machineset
+$ go build
+```
+
+## Run
+1) Spin up a cluster using cluster-api
+2) To scale up or down the nodes to N, run `./machineset scale set=node --replicas N`

cluster-api/repair/README.md

@@ -0,0 +1,16 @@
+# Cluster Repair
+Cluster repair is an standalone tool to repair the problematic nodes in the cluster
+
+## Build
+
+```bash
+$ cd $GOPATH/src/k8s.io/
+$ git clone [email protected]:kubernetes/kube-deploy.git
+$ cd kube-deploy/cluster-api/repair
+$ go build
+```
+
+## Run
+1) Spin up a cluster using cluster-api
+2) To repair the nodes in cluster, run `./repair`
+3) To do a dryrun to see what will happen, run `./repair --dryrun true`

cluster-api/upgrader/README.md

@@ -0,0 +1,15 @@
+# Cluster Upgrader
+Cluster upgrader is an standalone tool to upgrade the entire cluster including the control plan and nodes. It will only exercise cluster api w/o any cloud-specific logic.
+
+## Build
+
+```bash
+$ cd $GOPATH/src/k8s.io/
+$ git clone [email protected]:kubernetes/kube-deploy.git
+$ cd kube-deploy/cluster-api/upgrader
+$ go build
+```
+
+## Run
+1) Spin up a cluster using cluster-api (the default version should be 1.7.4)
+2) To update the entire cluster to v1.8.3, run `./upgrader -v 1.8.3`