Address review comments.

madhusudancs · madhusudancs · commit af2976b66532 · 2016-09-22T01:53:56.000-07:00
diff --git a/docs/admin/federation/index.md b/docs/admin/federation/index.md
@@ -13,10 +13,10 @@ This guide explains how to set up cluster federation that lets us control multip
 
 ## Prerequisites
 
-This guide assumes that we have a running Kubernetes cluster.
+This guide assumes that you have a running Kubernetes cluster.
 If not, then head over to the [getting started guides](/docs/getting-started-guides/) to bring up a cluster.
 
-This guide also assumes that we have a Kubernetes release
+This guide also assumes that you have a Kubernetes release
 [downloaded from here](/docs/getting-started-guides/binary_release/),
 extracted into a directory and all the commands in this guide are run from
 that directory.
@@ -34,7 +34,7 @@ guide.
 
 Setting up federation requires running the federation control plane which
 consists of etcd, federation-apiserver (via the hyperkube binary) and
-federation-controller-manager (also via the hyperkube binary). We can run
+federation-controller-manager (also via the hyperkube binary). You can run
 these binaries as pods on an existing Kubernetes cluster.
 
 Note: This is a new mechanism to turn up Kubernetes Cluster Federation. If
@@ -61,7 +61,7 @@ Initialize the setup.
 $ federation/deploy/deploy.sh init
 ```
 
-Optionally we can create/edit `${FEDERATION_OUTPUT_ROOT}/values.yaml` to
+Optionally, you can create/edit `${FEDERATION_OUTPUT_ROOT}/values.yaml` to
 customize any value in
 [federation/federation/manifests/federation/values.yaml](https://github.com/madhusudancs/kubernetes-anywhere/blob/federation/federation/manifests/federation/values.yaml). Example:
 
@@ -72,38 +72,38 @@ controllerManagerRegistry: "gcr.io/myrepository"
 controllerManagerVersion: "v1.5.0-alpha.0.1010+892a6d7af59c0b"
 ```
 
-Assuming we have built and pushed the `hyperkube` image to the repository
+Assuming you have built and pushed the `hyperkube` image to the repository
 with the given tag in the example above.
 
 ### Getting images
 
-To run the federation control plane components as pods, we first need the
-images for all the components. We can either use the official release
-images or we can build them ourselves from HEAD.
+To run the federation control plane components as pods, you first need the
+images for all the components. You can either use the official release
+images or you can build them yourself from HEAD.
 
 ### Using official release images
 
 As part of every Kubernetes release, official release images are pushed to
-`gcr.io/google_containers`. To use the images in this repository, we can
-just set the container image fields in the following configs to point
-to the images in this repository. `gcr.io/google_containers/hyperkube`
-image includes the federation-apiserver and federation-controller-manager
-binaries, so we can point the corresponding configs for those components
+`gcr.io/google_containers`. To use the images in this repository, you can
+set the container image fields in the following configs to point to the
+images in this repository. `gcr.io/google_containers/hyperkube` image
+includes the federation-apiserver and federation-controller-manager
+binaries, so you can point the corresponding configs for those components
 to the hyperkube image.
 
 ### Building and pushing images from HEAD
 
-To run the code from HEAD, we need to build and push our own images.
-Assuming that we have checked out the
-[Kuberntes repository](https://github.com/kubernetes/kubernetes) and
-running these commands from the root of the source directory, we can
-build the binaries using the following command:
+To run the code from HEAD, you need to build and push your own images.
+Check out the
+[Kubernetes repository](https://github.com/kubernetes/kubernetes)
+and run the following commands from the root of the source directory.
+To build the binaries, run the following command:
 
 ```shell
 $ federation/develop/develop.sh build_binaries
 ```
 
-We can build the image and push it to the repository by running:
+To build the image and push it to the repository run:
 
 ```shell
 $ KUBE_REGISTRY="gcr.io/myrepository" federation/develop/develop.sh build_image
@@ -119,15 +119,15 @@ images from source.
 
 ### Running the federation control plane
 
-Once we have the images, we can turn up the federation control plane by
+Once you have the images, you can turn up the federation control plane by
 running:
 
 ```shell
 $ federation/deploy/deploy.sh deploy_federation
 ```
 
 This spins up the federation control components as pods managed by
-[`Deployments`](http://kubernetes.io/docs/user-guide/deployments/) on our
+[`Deployments`](http://kubernetes.io/docs/user-guide/deployments/) on your
 existing Kubernetes cluster. It also starts a
 [`type: LoadBalancer`](http://kubernetes.io/docs/user-guide/services/#type-loadbalancer)
 [`Service`](http://kubernetes.io/docs/user-guide/services/) for the
@@ -137,7 +137,7 @@ by a dynamically provisioned
 [`PV`](http://kubernetes.io/docs/user-guide/persistent-volumes/) for
  `etcd`. All these components are created in the `federation` namespace.
 
-We can verify that the pods are available by running the following
+You can verify that the pods are available by running the following
 command:
 
 ```shell
@@ -147,8 +147,8 @@ federation-apiserver            1         1         1            1           1m
 federation-controller-manager   1         1         1            1           1m
 ```
 
-Running `deploy.sh` also creates a new record in our kubeconfig for us
-to be able to talk to federation apiserver. We can view this by running
+Running `deploy.sh` also creates a new record in your kubeconfig for us
+to be able to talk to federation apiserver. You can view this by running
 `kubectl config view`.
 
 Note: Dynamic provisioning for persistent volume currently works only on
@@ -157,19 +157,19 @@ your needs, if required.
 
 ## Registering Kubernetes clusters with federation
 
-Now that we have the federation control plane up and running, we can start registering Kubernetes clusters.
+Now that you have the federation control plane up and running, you can start registering Kubernetes clusters.
 
-First of all, we need to create a secret containing kubeconfig for that Kubernetes cluster, which federation control plane will use to talk to that Kubernetes cluster.
-For now, we create this secret in the host Kubernetes cluster (that hosts federation control plane). When we start supporting secrets in federation control plane, we will create this secret there.
-Suppose that our kubeconfig for Kubernetes cluster is at `/cluster1/kubeconfig`, we can run the following command to create the secret:
+First of all, you need to create a secret containing kubeconfig for that Kubernetes cluster, which federation control plane will use to talk to that Kubernetes cluster.
+For now, you can create this secret in the host Kubernetes cluster (that hosts federation control plane). When federation starts supporting secrets, you will be able to create this secret there.
+Suppose that your kubeconfig for Kubernetes cluster is at `/cluster1/kubeconfig`, you can run the following command to create the secret:
 
 ```shell
 $ kubectl create secret generic cluster1 --namespace=federation --from-file=/cluster1/kubeconfig
 ```
 
 Note that the file name should be `kubeconfig` since file name determines the name of the key in the secret.
 
-Now that the secret is created, we are ready to register the cluster. The YAML file for cluster will look like:
+Now that the secret is created, you are ready to register the cluster. The YAML file for cluster will look like:
 
 ```yaml
 apiVersion: federation/v1beta1
@@ -184,25 +184,25 @@ spec:
     name: <secret-name>
 ```
 
-We need to insert the appropriate values for `<client-cidr>`, `<apiserver-address>` and `<secret-name>`.
-`<secret-name>` here is name of the secret that we just created.
+You need to insert the appropriate values for `<client-cidr>`, `<apiserver-address>` and `<secret-name>`.
+`<secret-name>` here is name of the secret that you just created.
 serverAddressByClientCIDRs contains the various server addresses that clients
-can use as per their CIDR. We can set the server's public IP address with CIDR
-`"0.0.0.0/0"` which all clients will match. In addition, if we want internal
-clients to use server's clusterIP, we can set that as serverAddress. The client
+can use as per their CIDR. You can set the server's public IP address with CIDR
+`"0.0.0.0/0"` which all clients will match. In addition, if you want internal
+clients to use server's clusterIP, you can set that as serverAddress. The client
 CIDR in that case will be a CIDR that only matches IPs of pods running in that
 cluster.
 
-Assuming our YAML file is located at `/cluster1/cluster.yaml`, we can run the following command to register this cluster:
+Assuming your YAML file is located at `/cluster1/cluster.yaml`, you can run the following command to register this cluster:
 
 <!-- TODO(madhusudancs): Make the kubeconfig context configurable with default set to `federation` -->
 ```shell
 $ kubectl create -f /cluster1/cluster.yaml --context=federation-cluster
 
 ```
 
-By specifying `--context=federation-cluster`, we direct the request to
-federation apiserver. We can ensure that the cluster registration was
+By specifying `--context=federation-cluster`, you direct the request to
+federation apiserver. You can ensure that the cluster registration was
 successful by running:
 
 ```shell
@@ -213,16 +213,16 @@ cluster1   Ready               3m
 
 ## Updating KubeDNS
 
-Once the cluster is registered with the federation, we are all ready to use it.
-But for the cluster to be able to route federation service requests, we need to restart
+Once the cluster is registered with the federation, you are all set to use it.
+But for the cluster to be able to route federation service requests, you need to restart
 KubeDNS and pass it a `--federations` flag which tells it about valid federation DNS hostnames.
 Format of the flag is like this:
 
 ```
 --federations=${FEDERATION_NAME}=${DNS_DOMAIN_NAME}
 ```
 
-To update KubeDNS with federations flag, we can edit the existing kubedns replication controller to
+To update KubeDNS with federations flag, you can edit the existing kubedns replication controller to
 include that flag in pod template spec and then delete the existing pod. Replication controller will
 recreate the pod with updated template.
 
@@ -253,7 +253,7 @@ And then delete it by running:
 $ kubectl delete pods <pod-name> --namespace=kube-system
 ```
 
-We are now all set to start using federation.
+You are now all set to start using federation.
 
 ## Turn down
 
@@ -274,29 +274,29 @@ why the new mechanism doesn't work for your case by filing an issue here -
 
 ### Getting images
 
-To run these as pods, we first need images for all the components. We can use
-official release images or we can build from HEAD.
+To run these as pods, you first need images for all the components. You can use
+official release images or you can build from HEAD.
 
 #### Using official release images
 
 As part of every release, images are pushed to `gcr.io/google_containers`. To use
-these images, we set env var `FEDERATION_PUSH_REPO_BASE=gcr.io/google_containers`
+these images, set env var `FEDERATION_PUSH_REPO_BASE=gcr.io/google_containers`
 This will always use the latest image.
 To use the hyperkube image which includes federation-apiserver and
-federation-controller-manager from a specific release, we can set
-`FEDERATION_IMAGE_TAG`.
+federation-controller-manager from a specific release, set the
+`FEDERATION_IMAGE_TAG` environment variable.
 
 #### Building and pushing images from HEAD
 
-To run the code from HEAD, we need to build and push our own images.
-We can build the images using the following command:
+To run the code from HEAD, you need to build and push your own images.
+You can build the images using the following command:
 
 ```shell
 $ FEDERATION=true KUBE_RELEASE_RUN_TESTS=n make quick-release
 ```
 
-Next, we need to push these images to a registry such as Google Container Registry or Docker Hub, so that our cluster can pull them.
-If Kubernetes cluster is running on Google Compute Engine (GCE), then we can push the images to `gcr.io/<gce-project-name>`.
+Next, you need to push these images to a registry such as Google Container Registry or Docker Hub, so that your cluster can pull them.
+If Kubernetes cluster is running on Google Compute Engine (GCE), then you can push the images to `gcr.io/<gce-project-name>`.
 The command to push the images will look like:
 
 ```shell
@@ -305,7 +305,7 @@ $ FEDERATION=true FEDERATION_PUSH_REPO_BASE=gcr.io/<gce-project-name> ./build/pu
 
 ### Running the federation control plane
 
-Once we have the images, we can run these as pods on our existing kubernetes cluster.
+Once you have the images, you can run these as pods on your existing kubernetes cluster.
 The command to run these pods on an existing GCE cluster will look like:
 
 ```shell
@@ -320,14 +320,14 @@ This is used to resolve DNS requests for federation services. The service
 controller keeps DNS records with the provider updated as services/pods are
 updated in underlying kubernetes clusters.
 
-`FEDERATION_NAME` is a name we can choose for our federation. This is the name that will appear in DNS routes.
+`FEDERATION_NAME` is a name you can choose for your federation. This is the name that will appear in DNS routes.
 
-`DNS_ZONE_NAME` is the domain to be used for DNS records. This is a domain that we
+`DNS_ZONE_NAME` is the domain to be used for DNS records. This is a domain that you
 need to buy and then configure it such that DNS queries for that domain are
 routed to the appropriate provider as per `FEDERATION_DNS_PROVIDER`.
 
 Running that command creates a namespace `federation` and creates 2 deployments: `federation-apiserver` and `federation-controller-manager`.
-We can verify that the pods are available by running the following command:
+You can verify that the pods are available by running the following command:
 
 ```shell
 $ kubectl get deployments --namespace=federation
@@ -336,8 +336,8 @@ federation-apiserver            1         1         1            1           1m
 federation-controller-manager   1         1         1            1           1m
 ```
 
-Running `federation-up.sh` also creates a new record in our kubeconfig for us
-to be able to talk to federation apiserver. We can view this by running
+Running `federation-up.sh` also creates a new record in your kubeconfig for us
+to be able to talk to federation apiserver. You can view this by running
 `kubectl config view`.
 
 Note: `federation-up.sh` creates the federation-apiserver pod with an etcd
