Merge branch 'docs/autodevops-k8s' into 'master'

Document end to end flow for Kubernetes and Auto DevOps

Closes #44455

See merge request gitlab-org/gitlab-ce!19699

1 files changed, 46 insertions, 43 deletions

diff --git a/doc/user/project/clusters/index.md b/doc/user/project/clusters/index.md
index 58a483bb3b2..20c46cafbe5 100644
--- a/doc/user/project/clusters/index.md
+++ b/doc/user/project/clusters/index.md
@@ -7,9 +7,10 @@ cluster in a few steps.
 
 ## Overview
 
-With a Kubernetes cluster associated to your project, you can use
+With one or more Kubernetes clusters associated to your project, you can use
 [Review Apps](../../../ci/review_apps/index.md), deploy your applications, run
-your pipelines, and much more, in an easy way.
+your pipelines, use it with [Auto DevOps](../../../topics/autodevops/index.md),
+and much more, all from within GitLab.
 
 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
@@ -18,59 +19,65 @@ or provide the credentials to an [existing Kubernetes cluster](#adding-an-existi
 
 ## Adding and creating a new GKE cluster via GitLab
 
+TIP: **Tip:**
+Every new Google Cloud Platform (GCP) account receives [$300 in credit upon sign up](https://console.cloud.google.com/freetrial),
+and in partnership with Google, GitLab is able to offer an additional $200 for new GCP accounts to get started with GitLab's
+Google Kubernetes Engine Integration. All you have to do is [follow this link](https://goo.gl/AaJzRW) and apply for credit.
+
 NOTE: **Note:**
-You need Maintainer [permissions] and above to access the Kubernetes page.
-
-Before proceeding, make sure the following requirements are met:
-
-- The [Google authentication integration](../../../integration/google.md) must
-  be enabled in GitLab at the instance level. If that's not the case, ask your
-  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)
-  must be set up and that you have to have permissions to access it.
-- You must have Maintainer [permissions] in order to be able to access the
-  **Kubernetes** page.
-- You must have [Cloud Billing API](https://cloud.google.com/billing/) enabled
-- You must have [Resource Manager
-  API](https://cloud.google.com/resource-manager/)
+The [Google authentication integration](../../../integration/google.md) must
+be enabled in GitLab at the instance level. If that's not the case, ask your
+GitLab administrator to enable it. On GitLab.com, this is enabled.
+
+### Requirements
+
+Before creating your first cluster on Google Kubernetes Engine with GitLab's
+integration, make sure the following requirements are met:
+
+- A [billing account](https://cloud.google.com/billing/docs/how-to/manage-billing-account)
+  is set up and you have permissions to access it.
+- The Kubernetes Engine API is enabled. Follow the steps as outlined in the
+  ["Before you begin" section of the Kubernetes Engine docs](https://cloud.google.com/kubernetes-engine/docs/quickstart#before-you-begin).
+
+### Creating the cluster
 
 If all of the above requirements are met, you can proceed to create and add a
-new Kubernetes cluster that will be hosted on GKE to your project:
+new Kubernetes cluster to your project:
 
 1. Navigate to your project's **Operations > Kubernetes** page.
+
+    NOTE: **Note:**
+    You need Maintainer [permissions] and above to access the Kubernetes page.
+
 1. Click on **Add Kubernetes cluster**.
 1. Click on **Create with Google Kubernetes Engine**.
 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:
+1. From there on, choose your cluster's settings:
   - **Kubernetes cluster name** - The name you wish to give the cluster.
   - **Environment scope** - The [associated environment](#setting-the-environment-scope) to this cluster.
-  - **Google Cloud Platform project** - The project you created in your GCP
-    console that will host the Kubernetes cluster. This must **not** be confused
-    with the project ID. 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/)
+  - **Google Cloud Platform project** - Choose the project you created in your GCP
+    console that will host the Kubernetes cluster. Learn more about
+    [Google Cloud Platform projects](https://cloud.google.com/resource-manager/docs/creating-managing-projects).
+  - **Zone** - Choose the [region 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.
+  - **Number of nodes** - Enter 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.
 1. Finally, click the **Create Kubernetes cluster** button.
 
-After a few moments, your cluster should be created. If something goes wrong,
-you will be notified.
-
-You can now proceed to install some pre-defined applications and then
-enable the Cluster integration.
+After a couple of minutes, your cluster will be ready to go. You can now proceed
+to install some [pre-defined applications](#installing-applications).
 
 ## Adding an existing Kubernetes cluster
 
-NOTE: **Note:**
-You need Maintainer [permissions] and above to access the Kubernetes page.
-
 To add an existing Kubernetes cluster to your project:
 
 1. Navigate to your project's **Operations > Kubernetes** page.
+
+    NOTE: **Note:**
+    You need Maintainer [permissions] and above to access the Kubernetes page.
+
 1. Click on **Add Kubernetes cluster**.
 1. Click on **Add an existing Kubernetes cluster** and fill in the details:
     - **Kubernetes cluster name** (required) - The name you wish to give the cluster.
@@ -91,9 +98,8 @@ To add an existing Kubernetes cluster to your project:
       to create one. You can also view or create service tokens in the
       [Kubernetes dashboard](https://kubernetes.io/docs/tasks/access-application-cluster/web-ui-dashboard/#config)
       (under **Config > Secrets**).
-    - **Project namespace** (optional) - The following apply:
-      - By default you don't have to fill it in; by leaving it blank, GitLab will
-        create one for you.
+    - **Project namespace** (optional) - You don't have to fill it in; by leaving
+      it blank, GitLab will create one for you. Also:
       - Each project should have a unique namespace.
       - The project namespace is not necessarily the namespace of the secret, if
         you're using a secret with broader permissions, like the secret from `default`.
@@ -103,11 +109,8 @@ To add an existing Kubernetes cluster to your project:
         be the same.
 1. Finally, click the **Create Kubernetes cluster** button.
 
-After a few moments, your cluster should be created. If something goes wrong,
-you will be notified.
-
-You can now proceed to install some pre-defined applications and then
-enable the Kubernetes cluster integration.
+After a couple of minutes, your cluster will be ready to go. You can now proceed
+to install some [pre-defined applications](#installing-applications).
 
 ## Security implications
 
@@ -152,9 +155,9 @@ added directly to your configured cluster. Those applications are needed for
 
 | Application | GitLab version | Description |
 | ----------- | :------------: | ----------- |
-| [Helm Tiller](https://docs.helm.sh/) | 10.2+ | Helm is a package manager for Kubernetes and is required to install all the other applications. It will be automatically installed as a dependency when you try to install a different app. It is installed in its own pod inside the cluster which can run the `helm` CLI in a safe environment. |
+| [Helm Tiller](https://docs.helm.sh/) | 10.2+ | Helm is a package manager for Kubernetes and is required to install all the other applications. It is installed in its own pod inside the cluster which can run the `helm` CLI in a safe environment. |
 | [Ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/) | 10.2+ | Ingress can provide load balancing, SSL termination, and name-based virtual hosting. It acts as a web proxy for your applications and is useful if you want to use [Auto DevOps] or deploy your own web apps. |
-| [Prometheus](https://prometheus.io/docs/introduction/overview/) | 10.4+ | Prometheus is an open-source monitoring and alerting system useful to supervise your deployed applications |
+| [Prometheus](https://prometheus.io/docs/introduction/overview/) | 10.4+ | Prometheus is an open-source monitoring and alerting system useful to supervise your deployed applications. |
 | [GitLab Runner](https://docs.gitlab.com/runner/) | 10.6+ | GitLab Runner is the open source project that is used to run your jobs and send the results back to GitLab. It is used in conjunction with [GitLab CI/CD](https://about.gitlab.com/features/gitlab-ci-cd/), the open-source continuous integration service included with GitLab that coordinates the jobs. When installing the GitLab Runner via the applications, it will run in **privileged mode** by default. Make sure you read the [security implications](#security-implications) before doing so. |
 | [JupyterHub](http://jupyter.org/) | 11.0+ | [JupyterHub](https://jupyterhub.readthedocs.io/en/stable/) is a multi-user service for managing notebooks across a team. [Jupyter Notebooks](https://jupyter-notebook.readthedocs.io/en/latest/) provide a web-based interactive programming environment used for data analysis, visualization, and machine learning. **Note**: Authentication will be enabled for any user of the GitLab server via OAuth2. HTTPS will be supported in a future release. |