Port the cluster docs from EE to CE

1 files changed, 132 insertions, 41 deletions

diff --git a/doc/user/project/clusters/index.md b/doc/user/project/clusters/index.md
index 130f7897b1a..f2289fcb3d1 100644
--- a/doc/user/project/clusters/index.md
+++ b/doc/user/project/clusters/index.md
@@ -1,26 +1,27 @@
 # Connecting GitLab with a Kubernetes cluster
 
-> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/35954) in 10.1.
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/35954) in GitLab 10.1.
+
+NOTE: **Note:**
+The Cluster integration will eventually supersede the
+[Kubernetes integration](../integrations/kubernetes.md).
 
 With a cluster associated to your project, you can use Review Apps, deploy your
 applications, run your pipelines, and much more, in an easy way.
 
-Connect your project to Google Kubernetes Engine (GKE) or your own Kubernetes
+Connect your project to Google Kubernetes Engine (GKE) or an existing Kubernetes
 cluster in a few steps.
 
-NOTE: **Note:**
-The Cluster integration will eventually supersede the
-[Kubernetes integration](../integrations/kubernetes.md). For the moment,
-you can create only one cluster.
-
 ## Prerequisites
 
-In order to be able to manage your GKE cluster through GitLab, the following
-prerequisites must be met:
+In order to be able to manage your Kubernetes cluster through GitLab, the
+following prerequisites must be met.
+
+**For a cluster hosted on GKE:**
 
 - The [Google authentication integration](../../../integration/google.md) must
   be enabled in GitLab at the instance level. If that's not the case, ask your
-  administrator to enable it.
+  GitLab administrator to enable it.
 - Your associated Google account must have the right privileges to manage
   clusters on GKE. That would mean that a [billing
   account](https://cloud.google.com/billing/docs/how-to/manage-billing-account)
@@ -31,41 +32,63 @@ prerequisites must be met:
 - You must have [Resource Manager
   API](https://cloud.google.com/resource-manager/)
 
-If all of the above requirements are met, you can proceed to add a new GKE
+**For an existing Kubernetes cluster:**
+
+- Since the cluster is already created, there are no prerequisites.
+
+---
+
+If all of the above requirements are met, you can proceed to add a new Kubernetes
 cluster.
 
-## Adding a cluster
+## Adding a Kubernetes cluster
 
 NOTE: **Note:**
-You need Master [permissions] and above to add a cluster.
-
-There are two options when adding a new cluster; either use Google Kubernetes
-Engine (GKE) or provide the credentials to your own Kubernetes cluster.
-
-To add a new cluster:
-
-1. Navigate to your project's **CI/CD > Cluster** page
-1. If you want to let GitLab create a cluster on GKE for you, go through the
-   following steps, otherwise skip to the next one.
-    1. Click on **Create with GKE**
-    1. Connect your Google account if you haven't done already by clicking the
-       **Sign in with Google** button
-    1. Fill in the requested values:
-      - **Cluster name** (required) - The name you wish to give the cluster.
-      - **GCP project ID** (required) - The ID of the project you created in your GCP
-        console that will host the Kubernetes cluster. This must **not** be confused
-        with the project name. Learn more about [Google Cloud Platform projects](https://cloud.google.com/resource-manager/docs/creating-managing-projects).
-      - **Zone** - The [zone](https://cloud.google.com/compute/docs/regions-zones/)
-        under which the cluster will be created.
-      - **Number of nodes** - The number of nodes you wish the cluster to have.
-      - **Machine type** - The [machine type](https://cloud.google.com/compute/docs/machine-types)
-        of the Virtual Machine instance that the cluster will be based on.
-      - **Project namespace** - The unique namespace for this project. By default you
-        don't have to fill it in; by leaving it blank, GitLab will create one for you.
-1. If you want to use your own existing Kubernetes cluster, click on
-   **Add an existing cluster** and fill in the details as described in the
-   [Kubernetes integration](../integrations/kubernetes.md) documentation.
-1. Finally, click the **Create cluster** button
+You need Master [permissions] and above to access the Clusters page.
+
+There are two options when adding a new cluster to your project; either associate
+your account with Google Kubernetes Engine (GKE) so that you can create new
+clusters from within GitLab, or provide the credentials to an existing
+Kubernetes cluster.
+
+Before proceeding to either method, make sure all [prerequisites](#prerequisites)
+are met.
+
+**To add a new cluster hosted on GKE to your project:**
+
+1. Navigate to your project's **CI/CD > Clusters** page.
+1. Click on **Add cluster**.
+1. Click on **Create with GKE**.
+1. Connect your Google account if you haven't done already by clicking the
+   **Sign in with Google** button.
+1. Fill in the requested values:
+  - **Cluster name** (required) - The name you wish to give the cluster.
+  - **GCP project ID** (required) - The ID of the project you created in your GCP
+    console that will host the Kubernetes cluster. This must **not** be confused
+    with the project name. Learn more about [Google Cloud Platform projects](https://cloud.google.com/resource-manager/docs/creating-managing-projects).
+  - **Zone** - The [zone](https://cloud.google.com/compute/docs/regions-zones/)
+    under which the cluster will be created.
+  - **Number of nodes** - The number of nodes you wish the cluster to have.
+  - **Machine type** - The [machine type](https://cloud.google.com/compute/docs/machine-types)
+    of the Virtual Machine instance that the cluster will be based on.
+  - **Project namespace** - The unique namespace for this project. By default you
+    don't have to fill it in; by leaving it blank, GitLab will create one for you.
+  - **Environment scope** - The [associated environment](#setting-the-environment-scope) to this cluster.
+1. Finally, click the **Create cluster** button.
+
+---
+
+**To add an existing cluster to your project:**
+
+1. Navigate to your project's **CI/CD > Clusters** page.
+1. Click on **Add cluster**.
+1. Click on **Add an existing cluster** and fill in the details as described
+   in the [Kubernetes integration](../integrations/kubernetes.md#configuration)
+   documentation.
+1. Select the [environment scope](#setting-the-environment-scope).
+1. Finally, click the **Create cluster** button.
+
+---
 
 After a few moments, your cluster should be created. If something goes wrong,
 you will be notified.
@@ -111,4 +134,72 @@ To remove the Cluster integration from your project, simply click on the
 **Remove integration** button. You will then be able to follow the procedure
 and [add a cluster](#adding-a-cluster) again.
 
+## Multiple Kubernetes clusters
+
+> Introduced in [GitLab Enterprise Edition Premium][ee] 10.3.
+
+With GitLab EEP, you can associate more than one Kubernetes clusters to your
+project. That way you can have different clusters for different environments,
+like dev, staging, production, etc.
+
+To add another cluster, follow the same steps as described in [adding a
+Kubernetes cluster](#adding-a-kubernetes-cluster) and make sure to
+[set an environment scope](#setting-the-environment-scope) that will
+differentiate the new cluster with the rest.
+
+## Setting the environment scope
+
+When adding more than one clusters, you need to differentiate them with an
+environment scope. The environment scope associates clusters and
+[environments](../../../ci/environments.md) in an 1:1 relationship similar to how the
+[environment-specific variables](../../../ci/variables/README.md#limiting-environment-scopes-of-secret-variables)
+work.
+
+The default environment scope is `*`, which means all jobs, regardless of their
+environment, will use that cluster. Each scope can only be used by a single
+cluster in a project, and a validation error will occur if otherwise.
+
+---
+
+For example, let's say the following clusters exist in a project:
+
+| Cluster    | Environment scope   |
+| ---------- | ------------------- |
+| Development| `*`                 |
+| Staging    | `staging/*`         |
+| Production | `production/*`      |
+
+And the following environments are set in [`.gitlab-ci.yml`](../../../ci/yaml/README.md):
+
+```yaml
+stages:
+- test
+- deploy
+
+test:
+  stage: test
+  script: sh test
+
+deploy to staging:
+  stage: deploy
+  script: make deploy
+  environment:
+    name: staging/$CI_COMMIT_REF_NAME
+    url: https://staging.example.com/
+
+deploy to production:
+  stage: deploy
+  script: make deploy
+  environment:
+    name: production/$CI_COMMIT_REF_NAME
+    url: https://example.com/
+```
+
+The result will then be:
+
+- The development cluster will be used for the "test" job.
+- The staging cluster will be used for the "deploy to staging" job.
+- The production cluster will be used for the "deploy to production" job.
+
 [permissions]: ../../permissions.md
+[ee]: https://about.gitlab.com/gitlab-ee/