kube-dns documentation.

docs/tutorials/federation/set-up-cluster-federation-kubefed.md

@@ -40,7 +40,7 @@ of available binaries on the [release page](https://github.com/kubernetes/kubern
 
 
 ```shell
-curl -O https://storage.googleapis.com/kubernetes-release/release/v1.5.2/kubernetes-client-linux-amd64.tar.gz
+curl -O https://storage.googleapis.com/kubernetes-release/release/v1.6.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
@@ -121,8 +121,19 @@ To use `kubefed join`, you'll need to provide the name of the cluster
 you want to add to the federation, and the `--host-cluster-context`
 for the federation control plane's host cluster.
 
+> Note: The name that you provide to the `join` command is used as the
+joining cluster's identity in federation. This name should adhere to
+the rules described in the
+[identifiers doc](/docs/user-guide/identifiers/#names). If the context
+corresponding to your joining cluster conforms to these rules then you
+can use the same name in the join command. Otherwise, you will have to
+choose a different name for your cluster's identity. For more
+information, please see the
+[naming rules and customization](#naming-rules-and-customization)
+section below.
+
 The following example command adds the cluster `gondor` to the
-federation with host cluster `rivendell`:
+federation running on host cluster `rivendell`:
 
 ```
 kubefed join gondor --host-cluster-context=rivendell
@@ -136,8 +147,9 @@ cluster.
 
 ### Naming rules and customization
 
-The cluster name you supply to `kubefed join` must be a valid RFC 1035
-label.
+The cluster name you supply to `kubefed join` must be a valid
+[RFC 1035](https://www.ietf.org/rfc/rfc1035.txt) label and are
+enumerated in the [Identifiers doc](/docs/user-guide/identifiers/#names).
 
 Furthermore, federation control plane requires credentials of the
 joined clusters to operate on them. These credentials are obtained
@@ -182,6 +194,17 @@ specification, all you need to do is supply the secret name via the
 `--secret-name` flag. `kubefed join` automatically creates the secret
 for you.
 
+### `kube-dns` configuration
+
+`kube-dns` configuration must be updated in each joining cluster to
+enable federated service discovery. If the joining Kubernetes cluster
+is version 1.5 or newer and your `kubefed` version 1.6 or later, then
+this configuration is automatically managed for you when the clusters
+are joined or unjoined using `kubefed` `join` or `unjoin` commands.
+
+In all other cases, you must update `kube-dns` configuration manually
+as described in the
+[Updating KubeDNS section of the admin guide](/docs/admin/federation/)
 
 ## Removing a cluster from a federation