Adding user guides for federation events and ns

_data/reference.yml

@@ -245,3 +245,8 @@ toc:
     path: https://github.com/kubernetes/kubernetes/blob/release-1.3/docs/design/security_context.md
   - title: Security in Kubernetes
     path: https://github.com/kubernetes/kubernetes/blob/release-1.3/docs/design/security.md    
+
+- title: Federation
+  section:
+  - title:  User guide
+    path: /docs/user-guide/federation/

docs/user-guide/federation/events.md

@@ -0,0 +1,39 @@
+---
+---
+
+This guide explains how to use events in federation control plane to help in debugging.
+
+
+* TOC
+{:toc}
+
+## Prerequisites
+
+This guide assumes that you have a running Kubernetes Cluster
+Federation installation. If not, then head over to the
+[federation admin guide](/docs/admin/federation/) to learn how to
+bring up a cluster federation (or have your cluster administrator do
+this for you). Other tutorials, for example
+[this one](https://github.com/kelseyhightower/kubernetes-cluster-federation)
+by Kelsey Hightower, are also available to help you.
+
+You are also expected to have a basic
+[working knowledge of Kubernetes](/docs/getting-started-guides/) in
+general.
+
+## Overview
+
+Events in federation control plane (refered to as "federation events" in
+this guide) are very similar to the traditional Kubernetes
+Events providing the same functionality.
+Federation Events are stored only in federation control plane and are not passed on to the underlying kubernetes clusters.
+
+Federation controllers create events as they process API resources to surface to the
+user, the state that they are in.
+You can get all events from federation apiserver by running:
+
+```shell
+kubectl --context=federation-cluster get events
+```
+
+The standard kubectl get, update, delete commands will all work.

docs/user-guide/federation/index.md

@@ -0,0 +1,45 @@
+---
+---
+
+This guide explains how we can manage multiple kubernetes clusters using
+federation.
+[Federation proposal](https://github.com/kubernetes/kubernetes/blob/{{page.githubbranch}}/docs/proposals/federation.md)
+details the use cases motivating cluster federation.
+
+
+* TOC
+{:toc}
+
+## Setup
+
+To be able to federate multiple clusters, we first need to setup a federation
+control plane.
+Follow the [setup guide](/docs/admin/federation/) to setup the
+federation control plane.
+
+## Hybrid cloud capabilities
+
+Federations of Kubernetes Clusters can include clusters running in
+different cloud providers (e.g. Google Cloud, AWS), and on-premises
+(e.g. on OpenStack). Simply create all of the clusters that you
+require, in the appropriate cloud providers and/or locations, and
+register each cluster's API endpoint and credentials with your
+Federation API Server (See the
+[federation admin guide](/docs/admin/federation/) for details).
+
+Thereafter, your API resources can span different clusters
+and cloud providers.
+
+## API resources
+
+Once we have the control plane setup, we can start creating federation API
+resources.
+Following guides explain some of the resources in detail:
+
+* [Services](/docs/user-guide/federation/federated-services/)
+* [Events](/docs/user-guide/federation/events/)
+* [Namespaces](/docs/user-guide/federation/namespaces/)
+<!-- TODO: Add more guides here -->
+
+[API reference docs](/federation/docs/api-reference/readme/) lists all the
+resources supported by federation apiserver.

docs/user-guide/federation/namespaces.md

@@ -0,0 +1,90 @@
+---
+---
+
+This guide explains how to use namespaces in Federation control plane.
+
+
+* TOC
+{:toc}
+
+## Prerequisites
+
+This guide assumes that you have a running Kubernetes Cluster
+Federation installation. If not, then head over to the
+[federation admin guide](/docs/admin/federation/) to learn how to
+bring up a cluster federation (or have your cluster administrator do
+this for you). Other tutorials, for example
+[this one](https://github.com/kelseyhightower/kubernetes-cluster-federation)
+by Kelsey Hightower, are also available to help you.
+
+You are also expected to have a basic
+[working knowledge of Kubernetes](/docs/getting-started-guides/) in
+general and [Namespaces](/docs/user-guide/namespaces/) in particular.
+
+## Overview
+
+Namespaces in federation control plane (referred to as "federated namespaces" in
+this guide) are very similar to the traditional [Kubernetes
+Namespaces](/docs/user-guide/namespaces/) providing the same functionality.
+Creating them in the federation control plane ensures that they are synchronized
+across all the clusters in federation.
+
+
+## Creating a Federated Namespace
+
+The API for Federated Namespaces is 100% compatible with the
+API for traditional Kubernetes Namespaces. You can create a namespace by sending
+a request to the federation apiserver.
+
+You can do that using kubectl by running:
+
+``` shell
+kubectl --context=federation-cluster create -f myns.yaml
+```
+
+The '--context=federation-cluster' flag tells kubectl to submit the
+request to the Federation apiserver instead of sending it to a kubernetes
+cluster.
+
+Once a federated namespace is created, the federation control plane will create
+a matching namespace in all underlying kubernetes clusters.
+You can verify this by checking each of the underlying clusters, for example:
+
+``` shell
+kubectl --context=gce-asia-east1a get namespaces myns
+```
+
+The above assumes that you have a context named 'gce-asia-east1a'
+configured in your client for your cluster in that zone. The name and
+spec of the underlying namespace will match those of
+the Federated Namespace that you created above.
+
+
+## Updating a Federated Namespace
+
+You can update a federated namespace as you would update a Kubernetes
+namespace, just send the request to federation apiserver instead of sending it
+to a specific kubernetes cluster.
+Federation control plan will ensure that whenever the federated namespace is
+updated, it updates the corresponding namespaces in all underlying clusters to
+match it.
+
+## Deleting a Federated Namespace
+
+You can delete a federated namespace as you would delete a Kubernetes
+namespace, just send the request to federation apiserver instead of sending it
+to a specific kubernetes cluster.
+
+For example, you can do that using kubectl by running:
+
+```shell
+kubectl --context=federation-cluster delete ns myns
+```
+
+As in Kubernetes, deleting a federated namespace will delete all resources in that
+namespace from the federation control plane.
+
+Note that at this point, deleting a federated namespace will not delete the
+corresponding namespaces and resources in those namespaces from underlying clusters.
+Users are expected to delete them manually.
+We intend to fix this in the future.