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

doc/topics/autodevops/index.md

 # Auto DevOps
 
-> [Introduced][ce-37115] in GitLab 10.0.
+> [Introduced][ce-37115] in GitLab 10.0. Generally available on GitLab 11.0.
 
 Auto DevOps automatically detects, builds, tests, deploys, and monitors your
 applications.
@@ -13,6 +13,12 @@ without needing to configure anything. Just push your code and GitLab takes
 care of everything else. This makes it easier to start new projects and brings
 consistency to how applications are set up throughout a company.
 
+## Quick start
+
+If you are using GitLab.com, see the [quick start guide](quick_start_guide.md)
+for using Auto DevOps with GitLab.com and a Kubernetes cluster on Google Kubernetes
+Engine.
+
 ## Comparison to application platforms and PaaS
 
 Auto DevOps provides functionality described by others as an application
@@ -34,7 +40,7 @@ in a couple of ways:
 ## Features
 
 Comprised of a set of stages, Auto DevOps brings these best practices to your
-project in an easy and automatic way:
+project in a simple and automatic way:
 
 1. [Auto Build](#auto-build)
 1. [Auto Test](#auto-test)
@@ -135,10 +141,9 @@ and `1.2.3.4` is the IP address of your load balancer; generally NGINX
 ([see requirements](#requirements)). How to set up the DNS record is beyond
 the scope of this document; you should check with your DNS provider.
 
-Alternatively you can use free public services like [nip.io](http://nip.io) or
-[nip.io](http://nip.io) which provide automatic wildcard DNS without any
-configuration. Just set the Auto DevOps base domain to `1.2.3.4.nip.io` or
-`1.2.3.4.nip.io`.
+Alternatively you can use free public services like [nip.io](http://nip.io)
+which provide automatic wildcard DNS without any configuration. Just set the
+Auto DevOps base domain to `1.2.3.4.nip.io`.
 
 Once set up, all requests will hit the load balancer, which in turn will route
 them to the Kubernetes pods that run your application(s).
@@ -198,12 +203,6 @@ and verifying that your app is deployed as a review app in the Kubernetes
 cluster with the `review/*` environment scope. Similarly, you can check the
 other environments.
 
-## Quick start
-
-If you are using GitLab.com, see our [quick start guide](quick_start_guide.md)
-for using Auto DevOps with GitLab.com and an external Kubernetes cluster on
-Google Cloud.
-
 ## Enabling Auto DevOps
 
 If you haven't done already, read the [requirements](#requirements) to make
@@ -288,7 +287,7 @@ NOTE: **Note:**
 Auto Test uses tests you already have in your application. If there are no
 tests, it's up to you to add them.
 
-### Auto Code Quality
+### Auto Code Quality **[STARTER]**
 
 Auto Code Quality uses the
 [Code Quality image](https://gitlab.com/gitlab-org/security-products/codequality) to run
@@ -323,7 +322,7 @@ to run analysis on the project dependencies and checks for potential security is
 report is created, it's uploaded as an artifact which you can later download and
 check out.
 
-In GitLab Ultimate, any security warnings are also
+Any security warnings are also
 [shown in the merge request widget](https://docs.gitlab.com/ee//user/project/merge_requests/dependency_scanning.html).
 
 ### Auto License Management **[ULTIMATE]**
@@ -331,12 +330,12 @@ In GitLab Ultimate, any security warnings are also
 > Introduced in [GitLab Ultimate][ee] 11.0.
 
 License Management uses the
-[License Management Docker image](https://gitlab.com/gitlab-org/security-products/license_management)
+[License Management Docker image](https://gitlab.com/gitlab-org/security-products/license-management)
 to search the project dependencies for their license. Once the
 report is created, it's uploaded as an artifact which you can later download and
 check out.
 
-In GitLab Ultimate, any licenses are also
+Any licenses are also
 [shown in the merge request widget](https://docs.gitlab.com/ee//user/project/merge_requests/license_management.html).
 
 ### Auto Container Scanning

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. |