[Federation] Document simplified federation control plane deployment …

…via kubefed.

_data/guides.yml

@@ -274,8 +274,6 @@ toc:
     path: /docs/admin/cluster-components/
   - title: Configuring Kubernetes Use of etcd
     path: /docs/admin/etcd/
-  - title: Federating Clusters
-    path: /docs/admin/federation/
   - title: Using Multiple Clusters
     path: /docs/admin/multi-cluster/
   - title: Changing Cluster Size
@@ -304,3 +302,10 @@ toc:
     path: /docs/admin/node-problem/
   - title: AppArmor
     path: /docs/admin/apparmor/
+
+- title: Administering Federation
+  section:
+  - title: Using `kubefed`
+    path: /docs/admin/federation/kubfed/
+  - title: Using `federation-up` and `deploy.sh`
+    path: /docs/admin/federation/

docs/admin/federation/kubefed.md

@@ -0,0 +1,168 @@
+---
+assignees:
+- madhusudancs
+
+---
+Kubernetes v1.5 introduced a new command line tool called `kubefed`
+to facilitate the administration of cluster federations. `kubefed`
+stands for "Kubernetes Federate". It aids in both deploying a
+Kubernetes Cluster Federation control plane and adding/removing
+clusters from it. 
+
+This guide explains how to administer a Kubernetes Cluster Federation
+using `kubefed`.
+
+`kubefed` is considered alpha in Kubernetes v1.5.
+
+* TOC
+{:toc}
+
+## Prerequisites
+
+This guide assumes that you have a running Kubernetes cluster. Please
+see one of the [getting started](/docs/getting-started-guides/) guides
+for installation instructions for your platform.
+
+## Getting `kubefed`
+
+Download the Kubernetes client tarball corresponding to a release
+[from the release page](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG.md),
+extract the binaries in the tarball to one of the directories
+in your `$PATH` and set the executable permission on those binaries.
+
+```shell
+curl -O https://storage.googleapis.com/kubernetes-release/release/v1.5.0/kubernetes-client-linux-amd64.tar.gz
+tar -xzvf kubernetes-client-linux-amd64.tar.gz
+sudo cp kubernetes/client/bin/kubefed /usr/local/bin
+sudo chmod +x /usr/local/bin/kubefed
+sudo cp kubernetes/client/bin/kubectl /usr/local/bin
+sudo chmod +x /usr/local/bin/kubectl
+```
+
+## Choosing a host cluster.
+
+Choose one of your Kubernetes clusters as a cluster where you want to
+host the federation control plane components. We refer to this cluster
+as a "host cluster" henceforth. Ensure that you have a kubeconfig entry
+in your local kubeconfig corresponding to this cluster. You can verify
+this by running:
+
+```shell
+kubectl config get-contexts
+```
+
+and ensuring that there is a context corresponding to your host
+cluster.
+
+Please also make a note of this context because you will need it next.
+
+
+## Deploying a federation control plane.
+
+Deploying a federation control plane on your host cluster is as simple
+as running:
+
+```shell
+kubefed init fellowship --host-cluster-context=rivendell  --dns-zone-name="example.com"
+```
+
+where `fellowship` is the name of the federation, `rivendell` is the
+host cluster context from the previous step and `example.com` is the
+domain name suffix that you want for your federated services. This has
+to be a real domain that you control over and is programmable by your
+DNS provider.
+
+`kubefed init` sets up the federation control plane in the host
+cluster and also adds an entry for the federation API server in your
+local kubeconfig. However, in this alpha release it does not
+automatically set the current context to the newly deployed federation.
+You can set this by running:
+
+```shell
+kubectl config use-context fellowship
+```
+
+where `fellowship` is the name of your federation.
+
+## Joining a cluster
+
+Cluster Federation allows you to manage your workload across multiple
+clusters. In order to do that, a federation control plane must be
+aware of the clusters that it is responsible for managing. You can
+teach the federation control plane about a cluster by joining that
+cluster to the federation.
+
+Joining a cluster to a federation is as simple as running:
+
+```
+kubfed join gondor --host-cluster-context=rivendell
+```
+
+where `gondor` is the name of the cluster you are joining and
+`rivendell` is the federation control plane's host cluster.
+
+### Naming rules and customization
+
+#### Cluster name
+
+Cluster name supplied to `kubefed join` must be a valid RFC 1035 label.
+
+Furthermore, federation control plane requires credentials of the
+joined clusters to operate on them. These credentials are obtained
+from the local kubeconfig. `kubefed join` uses the cluster name
+specified as the argument to look for the cluster's context in the
+local kubeconfig. If it fails to find a matching context, it exits
+with an error.
+
+It is particularly a problem in the cases where context names
+for the clusters don't follow RFC 1035 label naming rules. In these
+cases, you could specify a cluster name that conforms to the RFC 1035
+label naming rules and specify the cluster context using the
+`--cluster-context` flag. For example, if context of the cluster your
+are joining is `gondor_has_no_king-gondor_needs_no_king`, then you can
+join the cluster by running:
+
+```shell
+kubfed join gondor --host-cluster-context=rivendell --cluster-context=gondor_has_no_king-gondor_needs_no_king
+```
+
+#### Secret name
+
+Cluster credentials required by the federation control plane as described above are stored as a secret in the host cluster. The name of the secret is also derived from the cluster name. 
+
+However, the name of a secret object in Kubernetes should conform
+to the subdomain name specification described in RFC 1123. If this isn't case, you can pass the secret name to `kubefed join` using the
+`--secret-name` flag. For example, if the cluster name is `noldor` and
+the secret name is `11kingdom`, you can join the cluster by running:
+
+```shell
+kubfed join noldor --host-cluster-context=rivendell --secret-name=11kingdom
+```
+
+## Unjoining a cluster:
+
+Unjoining a cluster from federation is as simple as running:
+
+```
+kubfed unjoin gondor --host-cluster-context=rivendell
+```
+
+where `gondor` is the cluster name you specified while joining the
+cluster and `rivendell` is the federation control plane's host cluster.
+
+## Turning down the federation control plane:
+
+Proper cleanup of federation control plane is not fully implemented in
+this alpha release of `kubefed`. However, for the time being, deleting
+the federation system namespace should remove all the resources except
+the persistent storage volume dynamically provisioned for the
+federation control plane's etcd. This can be accomplished by running:
+
+```
+$ kubectl delete ns federation-system
+```
+
+Also, you might not want to delete the storage volume that stores
+the state of your federation control plane. You can then use that
+storage volume to resume your federation control plane. We are
+evaluating various alternatives to handle this case correctly and that's the reason for not implementing federation control plane turn down in this alpha release.