From 616eab029622a46d1bb40d8e4e7669bc938b12a3 Mon Sep 17 00:00:00 2001
From: "Madhusudan.C.S" <madhusudancs@google.com>
Date: Sat, 23 Jul 2016 17:28:56 -0700
Subject: [PATCH] Add a README.md file for cluster federation.

---
 federation/README.md | 58 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 58 insertions(+)
 create mode 100644 federation/README.md

diff --git a/federation/README.md b/federation/README.md
new file mode 100644
index 00000000000..771dfccda3d
--- /dev/null
+++ b/federation/README.md
@@ -0,0 +1,58 @@
+# Cluster Federation
+
+Kubernetes Cluster Federation enables users to federate multiple
+Kubernetes clusters. Please see the [user guide](http://kubernetes.io/docs/admin/federation/)
+and the [admin guide](http://kubernetes.io/docs/user-guide/federation/federated-services/)
+for more details about setting up and using the Cluster Federation.
+
+# Building Kubernetes Cluster Federation
+
+Please see the [Kubernetes Development Guide](https://github.com/kubernetes/kubernetes/blob/master/docs/devel/development.md)
+for initial setup. Once you have the development environment setup
+as explained in that guide, you also need to install [`jq`](https://stedolan.github.io/jq/download/)
+
+Building cluster federation should be as simple as running:
+
+```shell
+make build do=gen
+```
+
+To deploy clusters and install federation components, edit the
+`config.default.json` file to describe your clusters and run
+
+```shell
+make build do=deploy
+```
+
+To turn down the federation components and tear down the clusters run:
+
+```shell
+make build do=destroy
+```
+
+# Ideas for improvement
+
+1. Split the `build` phase (make recipe) into multiple phases:
+    1. `init`: pull installer images
+    2. `build-binaries`
+    3. `build-docker`
+    4. `build`: build-binary + build-docker
+    5. `push`: to push the built images
+    6. `genconfig`
+    7. `deploy-clusters`
+    8. `deploy-federation`
+    9. `deploy`: deploy-clusters + deploy-federation
+    10. `destroy-federation`
+    11. `destroy-clusters`
+    12. `destroy`: destroy-federation + destroy-clusters
+    13. `redeploy-federation`: just redeploys the federation components.
+
+2. Add a `release` phase to run as part of Kubernetes release process
+   that copies only a part of the `build.sh` script that's relevant to
+   the users into the release.
+
+3. Continue with `destroy` phase even in the face of errors.
+
+   The bash script sets `set -e errexit` which causes the script to exit
+   at the very first error. This should be the default mode for deploying
+   components but not for destroying/cleanup.