Merge branch 'docs-readability-auto-devops' into 'master'

Docs: Refactor Auto DevOps

See merge request gitlab-org/gitlab!65772

app/views/clusters/clusters/_multiple_clusters_message.html.haml

-- autodevops_help_url = help_page_path('topics/autodevops/index.md', anchor: 'use-multiple-kubernetes-clusters')
+- autodevops_help_url = help_page_path('topics/autodevops/multiple_clusters_auto_devops.md')
 - help_link_start = '<a href="%{url}" target="_blank" rel="noopener noreferrer">'.html_safe
 - help_link_end = '</a>'.html_safe
 

doc/topics/autodevops/customize.md

@@ -208,6 +208,10 @@ If you need to specifically remove a part of the file, you can also copy and pas
 [Auto DevOps template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Auto-DevOps.gitlab-ci.yml)
 into your project and edit it as needed.
 
+## Use multiple Kubernetes clusters
+
+See [Multiple Kubernetes clusters for Auto DevOps](multiple_clusters_auto_devops.md).
+
 ## Customizing the Kubernetes namespace
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27630) in GitLab 12.6.
@@ -587,7 +591,7 @@ service:
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ci-yml/-/merge_requests/160) in GitLab 10.8.
 
 NOTE:
-You can also set this inside your [project's settings](index.md#deployment-strategy).
+You can also set this inside your [project's settings](requirements.md#auto-devops-deployment-strategy).
 
 The normal behavior of Auto DevOps is to use continuous deployment, pushing
 automatically to the `production` environment every time a new pipeline is run
@@ -616,7 +620,7 @@ If you define `CANARY_ENABLED` with a non-empty value, then two manual jobs are
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5415) in GitLab 10.8.
 
 NOTE:
-You can also set this inside your [project's settings](index.md#deployment-strategy).
+You can also set this inside your [project's settings](requirements.md#auto-devops-deployment-strategy).
 
 When you're ready to deploy a new version of your app to production, you may want
 to use an incremental rollout to replace just a few pods with the latest code to
@@ -673,7 +677,7 @@ removed in the future.
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7545) in GitLab 11.4.
 
 NOTE:
-You can also set this inside your [project's settings](index.md#deployment-strategy).
+You can also set this inside your [project's settings](requirements.md#auto-devops-deployment-strategy).
 
 This configuration is based on
 [incremental rollout to production](#incremental-rollout-to-production).

doc/topics/autodevops/multiple_clusters_auto_devops.md

+---
+stage: Configure
+group: Configure
+info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
+---
+
+# Multiple Kubernetes clusters for Auto DevOps **(FREE)**
+
+When using Auto DevOps, you can deploy different environments to
+different Kubernetes clusters, due to the 1:1 connection
+[existing between them](../../user/project/clusters/multiple_kubernetes_clusters.md).
+
+The [Deploy Job template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Jobs/Deploy.gitlab-ci.yml)
+used by Auto DevOps defines 3 environment names:
+
+- `review/` (every environment starting with `review/`)
+- `staging`
+- `production`
+
+Those environments are tied to jobs using [Auto Deploy](stages.md#auto-deploy), so
+except for the environment scope, they must have a different deployment domain.
+You must define a separate `KUBE_INGRESS_BASE_DOMAIN` variable for each of the above
+[based on the environment](../../ci/variables/index.md#limit-the-environment-scope-of-a-cicd-variable).
+
+The following table is an example of how to configure the three different clusters:
+
+| Cluster name | Cluster environment scope | `KUBE_INGRESS_BASE_DOMAIN` variable value | Variable environment scope | Notes |
+|--------------|---------------------------|-------------------------------------------|----------------------------|---|
+| review       | `review/*`                | `review.example.com`                      | `review/*`                 | The review cluster which runs all [Review Apps](../../ci/review_apps/index.md). `*` is a wildcard, used by every environment name starting with `review/`. |
+| staging      | `staging`                 | `staging.example.com`                     | `staging`                  | (Optional) The staging cluster which runs the deployments of the staging environments. You must [enable it first](customize.md#deploy-policy-for-staging-and-production-environments). |
+| production   | `production`              | `example.com`                             | `production`               | The production cluster which runs the production environment deployments. You can use [incremental rollouts](customize.md#incremental-rollout-to-production). |
+
+To add a different cluster for each environment:
+
+1. Navigate to your project's **Infrastructure > Kubernetes clusters**.
+1. Create the Kubernetes clusters with their respective environment scope, as
+   described from the table above.
+1. After creating the clusters, navigate to each cluster and [install
+   Ingress](quick_start_guide.md#install-ingress). Wait for the Ingress IP address to be assigned.
+1. Make sure you've [configured your DNS](requirements.md#auto-devops-base-domain) with the
+   specified Auto DevOps domains.
+1. Navigate to each cluster's page, through **Infrastructure > Kubernetes clusters**,
+   and add the domain based on its Ingress IP address.
+
+After completing configuration, test your setup by creating a merge request.
+Verify whether your application deployed as a Review App in the Kubernetes
+cluster with the `review/*` environment scope. Similarly, check the
+other environments.
+
+[Cluster environment scope isn't respected](https://gitlab.com/gitlab-org/gitlab/-/issues/20351)
+when checking for active Kubernetes clusters. For multi-cluster setup to work with Auto DevOps,
+create a fallback cluster with **Cluster environment scope** set to `*`. A new cluster isn't
+required. You can use any of the clusters already added.

doc/topics/autodevops/prepare_deployment.md

+---
+stage: Configure
+group: Configure
+info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
+---
+
+# Prepare Auto DevOps for deployment **(FREE)**
+
+If you enable Auto DevOps without setting the base domain and deployment
+strategy, GitLab can't deploy your application directly. Therefore, we
+recommend that you prepare them before enabling Auto DevOps.
+
+## Deployment strategy
+
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/38542) in GitLab 11.0.
+
+When using Auto DevOps to deploy your applications, choose the
+[continuous deployment strategy](../../ci/introduction/index.md)
+that works best for your needs:
+
+| Deployment strategy | Setup | Methodology |
+|--|--|--|
+| **Continuous deployment to production** | Enables [Auto Deploy](stages.md#auto-deploy) with the default branch continuously deployed to production. | Continuous deployment to production.|
+| **Continuous deployment to production using timed incremental rollout** | Sets the [`INCREMENTAL_ROLLOUT_MODE`](customize.md#timed-incremental-rollout-to-production) variable to `timed`. | Continuously deploy to production with a 5 minutes delay between rollouts. |
+| **Automatic deployment to staging, manual deployment to production** | Sets [`STAGING_ENABLED`](customize.md#deploy-policy-for-staging-and-production-environments) to `1` and [`INCREMENTAL_ROLLOUT_MODE`](customize.md#incremental-rollout-to-production) to `manual`. | The default branch is continuously deployed to staging and continuously delivered to production. |
+
+You can choose the deployment method when enabling Auto DevOps or later:
+
+1. In GitLab, go to your project's **Settings > CI/CD > Auto DevOps**.
+1. Choose the deployment strategy.
+1. Select **Save changes**.
+
+NOTE:
+Use the [blue-green deployment](../../ci/environments/incremental_rollouts.md#blue-green-deployment) technique
+to minimize downtime and risk.
+
+## Auto DevOps base domain
+
+The Auto DevOps base domain is required to use
+[Auto Review Apps](stages.md#auto-review-apps), [Auto Deploy](stages.md#auto-deploy), and
+[Auto Monitoring](stages.md#auto-monitoring).
+
+To define the base domain, either:
+
+- In the project, group, or instance level: go to your cluster settings and add it there.
+- In the project or group level: add it as an environment variable: `KUBE_INGRESS_BASE_DOMAIN`.
+- In the instance level: go to **Menu >** **{admin}** **Admin > Settings > CI/CD> Continuous Integration and Delivery** and add it there.
+
+The base domain variable `KUBE_INGRESS_BASE_DOMAIN` follows the same order of precedence
+as other environment [variables](../../ci/variables/index.md#cicd-variable-precedence).
+
+If you don't specify the base domain in your projects and groups, Auto DevOps uses the instance-wide **Auto DevOps domain**.
+
+Auto DevOps requires a wildcard DNS A record matching the base domain(s). For
+a base domain of `example.com`, you'd need a DNS entry like:
+
+```plaintext
+*.example.com   3600     A     1.2.3.4
+```
+
+In this case, the deployed applications are served from `example.com`, and `1.2.3.4`
+is the IP address of your load balancer, generally NGINX ([see requirements](requirements.md)).
+Setting up the DNS record is beyond the scope of this document; check with your
+DNS provider for information.
+
+Alternatively, you can use free public services like [nip.io](https://nip.io)
+which provide automatic wildcard DNS without any configuration. For [nip.io](https://nip.io),
+set the Auto DevOps base domain to `1.2.3.4.nip.io`.
+
+After completing setup, all requests hit the load balancer, which routes requests
+to the Kubernetes pods running your application.

doc/topics/autodevops/quick_start_guide.md

@@ -154,7 +154,7 @@ these steps to enable Auto DevOps if it's disabled:
 
 1. Navigate to **Settings > CI/CD > Auto DevOps**, and click **Expand**.
 1. Select **Default to Auto DevOps pipeline** to display more options.
-1. In **Deployment strategy**, select your desired [continuous deployment strategy](index.md#deployment-strategy)
+1. In **Deployment strategy**, select your desired [continuous deployment strategy](requirements.md#auto-devops-deployment-strategy)
    to deploy the application to production after the pipeline successfully runs on the default branch.
 1. Click **Save changes**.
 
@@ -314,7 +314,7 @@ all in GitLab. Despite its automatic nature, Auto DevOps can also be configured
 and customized to fit your workflow. Here are some helpful resources for further reading:
 
 1. [Auto DevOps](index.md)
-1. [Multiple Kubernetes clusters](index.md#use-multiple-kubernetes-clusters)
+1. [Multiple Kubernetes clusters](multiple_clusters_auto_devops.md)
 1. [Incremental rollout to production](customize.md#incremental-rollout-to-production) **(PREMIUM)**
 1. [Disable jobs you don't need with CI/CD variables](customize.md#cicd-variables)
 1. [Use your own buildpacks to build your application](customize.md#custom-buildpacks)

doc/topics/autodevops/requirements.md

@@ -6,11 +6,85 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 
 # Requirements for Auto DevOps **(FREE)**
 
-You can set up Auto DevOps for [Kubernetes](#auto-devops-requirements-for-kubernetes),
-[Amazon Elastic Container Service (ECS)](#auto-devops-requirements-for-amazon-ecs),
-or [Amazon Cloud Compute](#auto-devops-requirements-for-amazon-ecs).
-For more information about Auto DevOps, see [the main Auto DevOps page](index.md)
-or the [quick start guide](quick_start_guide.md).
+Before enabling [Auto DevOps](index.md), we recommend you to prepare it for
+deployment. If you don't, you can use it to build and test your apps, and
+then configure the deployment later.
+
+To prepare the deployment:
+
+1. Define the [deployment strategy](#auto-devops-deployment-strategy).
+1. Prepare the [base domain](#auto-devops-base-domain).
+1. Define where you want to deploy it to:
+
+   1. [Kubernetes](#auto-devops-requirements-for-kubernetes).
+   1. [Amazon Elastic Container Service (ECS)](#auto-devops-requirements-for-amazon-ecs).
+   1. [Amazon EC2](#auto-devops-requirements-for-amazon-ec2).
+   1. [Bare metal](#auto-devops-requirements-for-bare-metal).
+
+When done:
+
+1. [Enable Auto DevOps](index.md#enable-or-disable-auto-devops).
+1. See the [quick start](quick_start_guide.md) process.
+
+## Auto DevOps deployment strategy
+
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/38542) in GitLab 11.0.
+
+When using Auto DevOps to deploy your applications, choose the
+[continuous deployment strategy](../../ci/introduction/index.md)
+that works best for your needs:
+
+| Deployment strategy | Setup | Methodology |
+|--|--|--|
+| **Continuous deployment to production** | Enables [Auto Deploy](stages.md#auto-deploy) with the default branch continuously deployed to production. | Continuous deployment to production.|
+| **Continuous deployment to production using timed incremental rollout** | Sets the [`INCREMENTAL_ROLLOUT_MODE`](customize.md#timed-incremental-rollout-to-production) variable to `timed`. | Continuously deploy to production with a 5 minutes delay between rollouts. |
+| **Automatic deployment to staging, manual deployment to production** | Sets [`STAGING_ENABLED`](customize.md#deploy-policy-for-staging-and-production-environments) to `1` and [`INCREMENTAL_ROLLOUT_MODE`](customize.md#incremental-rollout-to-production) to `manual`. | The default branch is continuously deployed to staging and continuously delivered to production. |
+
+You can choose the deployment method when enabling Auto DevOps or later:
+
+1. In GitLab, go to your project's **Settings > CI/CD > Auto DevOps**.
+1. Choose the deployment strategy.
+1. Select **Save changes**.
+
+NOTE:
+Use the [blue-green deployment](../../ci/environments/incremental_rollouts.md#blue-green-deployment) technique
+to minimize downtime and risk.
+
+## Auto DevOps base domain
+
+The Auto DevOps base domain is required to use
+[Auto Review Apps](stages.md#auto-review-apps), [Auto Deploy](stages.md#auto-deploy), and
+[Auto Monitoring](stages.md#auto-monitoring).
+
+To define the base domain, either:
+
+- In the project, group, or instance level: go to your cluster settings and add it there.
+- In the project or group level: add it as an environment variable: `KUBE_INGRESS_BASE_DOMAIN`.
+- In the instance level: go to **Menu >** **{admin}** **Admin > Settings > CI/CD> Continuous Integration and Delivery** and add it there.
+
+The base domain variable `KUBE_INGRESS_BASE_DOMAIN` follows the same order of precedence
+as other environment [variables](../../ci/variables/index.md#cicd-variable-precedence).
+
+If you don't specify the base domain in your projects and groups, Auto DevOps uses the instance-wide **Auto DevOps domain**.
+
+Auto DevOps requires a wildcard DNS A record matching the base domain(s). For
+a base domain of `example.com`, you'd need a DNS entry like:
+
+```plaintext
+*.example.com   3600     A     1.2.3.4
+```
+
+In this case, the deployed applications are served from `example.com`, and `1.2.3.4`
+is the IP address of your load balancer, generally NGINX ([see requirements](requirements.md)).
+Setting up the DNS record is beyond the scope of this document; check with your
+DNS provider for information.
+
+Alternatively, you can use free public services like [nip.io](https://nip.io)
+which provide automatic wildcard DNS without any configuration. For [nip.io](https://nip.io),
+set the Auto DevOps base domain to `1.2.3.4.nip.io`.
+
+After completing setup, all requests hit the load balancer, which routes requests
+to the Kubernetes pods running your application.
 
 ## Auto DevOps requirements for Kubernetes
 
@@ -49,7 +123,7 @@ To make full use of Auto DevOps with Kubernetes, you need:
 - **Base domain** (for [Auto Review Apps](stages.md#auto-review-apps),
   [Auto Deploy](stages.md#auto-deploy), and [Auto Monitoring](stages.md#auto-monitoring))
 
-  You must [specify the Auto DevOps base domain](index.md#auto-devops-base-domain),
+  You must [specify the Auto DevOps base domain](#auto-devops-base-domain),
   which all of your Auto DevOps applications use. This domain must be configured
   with wildcard DNS.
 

doc/user/admin_area/settings/continuous_integration.md

@@ -18,7 +18,7 @@ for all projects:
 1. On the top bar, select **Menu >** **{admin}** **Admin**.
 1. On the left sidebar, select **Settings > CI/CD**.
 1. Check (or uncheck to disable) the box that says **Default to Auto DevOps pipeline for all projects**.
-1. Optionally, set up the [Auto DevOps base domain](../../../topics/autodevops/index.md#auto-devops-base-domain)
+1. Optionally, set up the [Auto DevOps base domain](../../../topics/autodevops/requirements.md#auto-devops-base-domain)
    which is used for Auto Deploy and Auto Review Apps.
 1. Hit **Save changes** for the changes to take effect.