From fbcc2e9fdec7086f99c431209e8aa7443e488684 Mon Sep 17 00:00:00 2001
From: Henrique Truta <henrique@lsd.ufcg.edu.br>
Date: Wed, 10 May 2017 14:22:12 -0300
Subject: [PATCH] Add cluster resource federation page

Adds a page in Federation resources list describing
clusters.
---
 _data/tasks.yml                               |  1 +
 .../cluster-administration/federation.md      |  1 +
 docs/tasks/administer-federation/cluster.md   | 79 +++++++++++++++++++
 3 files changed, 81 insertions(+)
 create mode 100644 docs/tasks/administer-federation/cluster.md

diff --git a/_data/tasks.yml b/_data/tasks.yml
index ba26c355ae..3170da003c 100644
--- a/_data/tasks.yml
+++ b/_data/tasks.yml
@@ -133,6 +133,7 @@ toc:
   - docs/tasks/federation/federation-service-discovery.md
   - docs/tasks/federation/set-up-cluster-federation-kubefed.md
   - docs/tasks/federation/set-up-coredns-provider-federation.md
+  - docs/tasks/administer-federation/cluster.md
   - docs/tasks/administer-federation/configmap.md
   - docs/tasks/administer-federation/daemonset.md
   - docs/tasks/administer-federation/deployment.md
diff --git a/docs/concepts/cluster-administration/federation.md b/docs/concepts/cluster-administration/federation.md
index 080d482bf6..a60099c65f 100644
--- a/docs/concepts/cluster-administration/federation.md
+++ b/docs/concepts/cluster-administration/federation.md
@@ -93,6 +93,7 @@ Once you have the control plane set up, you can start creating federation API
 resources.
 The following guides explain some of the resources in detail:
 
+* [Cluster](/docs/tasks/administer-federation/cluster/)
 * [ConfigMap](/docs/tasks/administer-federation/configmap/)
 * [DaemonSets](/docs/tasks/administer-federation/daemonset/)
 * [Deployment](/docs/tasks/administer-federation/deployment/)
diff --git a/docs/tasks/administer-federation/cluster.md b/docs/tasks/administer-federation/cluster.md
new file mode 100644
index 0000000000..53318349a6
--- /dev/null
+++ b/docs/tasks/administer-federation/cluster.md
@@ -0,0 +1,79 @@
+---
+title: Federated Cluster
+redirect_from:
+- "/docs/user-guide/federation/cluster/"
+- "/docs/user-guide/federation/cluster.html"
+---
+
+{% capture overview %}
+
+This guide explains how to use Clusters API resource in a Federation control plane.
+
+Different than other Kuberentes resources, such as Deployments, Services and ConfigMaps,
+clusters only exist in the federation context, i.e. those requests must be submitted to the
+federation api-server.
+
+{% endcapture %}
+
+{% capture prerequisites %}
+
+* {% include federated-task-tutorial-prereqs.md %}
+* You should also have a basic [working knowledge of Kubernetes](/docs/setup/pick-right-solution/) in
+general.
+
+{% endcapture %}
+
+{% capture steps %}
+
+## Listing Clusters
+
+To list the clusters available in your federation, you can use [kubectl](/docs/user-guide/kubectl/) by
+running:
+
+``` shell
+kubectl --context=federation get clusters
+```
+
+The `--context=federation` flag tells kubectl to submit the
+request to the Federation apiserver instead of sending it to a Kubernetes
+cluster. If you submit it to a k8s cluster, you will receive an error saying
+`the server doesn't have a resource type "clusters"`
+
+If you passed the correct Federation context but received a message error saying
+`No resources found.`, it means that you haven't
+added any cluster to the Federation yet.
+
+## Creating a Federated Cluster
+
+Creating a `cluster` resource in federation means joining it to the federation. To do so, you can use
+`kubefed join`. Basically, you need to give the new cluster a name and say what is the name of the
+context that corresponds to a cluster that hosts the federation. The following example command adds
+the cluster `gondor` to the federation running on host cluster `rivendell`:
+
+``` shell
+kubefed join gondor --host-cluster-context=rivendell
+```
+
+You can find more details on how to do that in the respective section in the
+[kubefed guide](/docs/tutorials/federation/set-up-cluster-federation-kubefed/#adding-a-cluster-to-a-federation).
+
+## Deleting a Federated Cluster
+
+Converse to creating a cluster, deleting a cluster means unjoining this cluster from the
+federation. This can be done with `kubefed unjoin` command. To remove the `gondor` cluster, just do:
+
+``` shell
+kubefed unjoin gondor --host-cluster-context=rivendell
+```
+
+You can find more details on unjoin in the
+[kubefed guide](/docs/tutorials/federation/set-up-cluster-federation-kubefed/#removing-a-cluster-from-a-federation).
+
+## Clusters API reference
+
+The full clusters API reference is currently in `federation/v1beta1` and more details can be found in details in the
+[Federation API reference page](https://kubernetes.io/docs/reference/federation/).
+
+{% endcapture %}
+
+{% include templates/task.md %}