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

Docs: Refactor Auto DevOps See merge request gitlab-org/gitlab!65772

Merge branch 'docs-readability-auto-devops' into 'master'
Docs: Refactor Auto DevOps See merge request gitlab-org/gitlab!65772
d10fd759 · Marcia Ramos · 1c0e82ef · 886b1e23 · d10fd759 · d10fd759
Commit d10fd759 authored Jul 28, 2021 by Marcia Ramos
8 changed files
--- a/app/views/clusters/clusters/_multiple_clusters_message.html.haml
+++ b/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

--- a/doc/topics/autodevops/customize.md
+++ b/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).

--- a/doc/topics/autodevops/index.md
+++ b/doc/topics/autodevops/index.md
@@ -6,320 +6,269 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 # Auto DevOps **(FREE)**
-> - Introduced in GitLab 11.0 for general availability.
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/38366) in GitLab 11.0.
-GitLab Auto DevOps helps to reduce the complexity of software delivery by
+GitLab Auto DevOps is a collection of pre-configured features and integrations
-setting up pipelines and integrations for you. Auto DevOps configures
+that work together to support your software delivery process.
-GitLab CI/CD pipelines including security auditing and vulnerability
-testing.
-Using Auto DevOps, you can:
+Auto DevOps features and integrations:
- Detect the language of your code.
+- Detect your code's language.
- Automatically build, test, and measure code quality.
+- Build and test your application.
- Scan for potential vulnerabilities, security flaws, and licensing issues.
+- Measure code quality.
- Monitor in real-time.
+- Scan for vulnerabilities and security flaws.
+- Check for licensing issues.
+- Monitor in real time.
 - Deploy your application.
-The functionality of Auto DevOps is based on default CI/CD templates that
-auto-discover your source code. These templates enable GitLab to provide
-consistency across your projects, seamless management of processes, and faster
-creation of new projects. Leveraging [CI/CD best practices](../../ci/pipelines/pipeline_efficiency.md)
-and tools, Auto DevOps lets you push your code, with GitLab doing the rest,
-improving your productivity and efficiency.
 <i class="fa fa-youtube-play youtube" aria-hidden="true"></i>
-For an introduction to Auto DevOps, watch [AutoDevOps in GitLab 11.0](https://youtu.be/0Tc0YYBxqi4) or see this [overview](https://about.gitlab.com/stages-devops-lifecycle/auto-devops/).
+For an introduction to Auto DevOps, watch [Auto DevOps in GitLab 11.0](https://youtu.be/0Tc0YYBxqi4).
-For requirements, read [Requirements for Auto DevOps](requirements.md) for more information.
+## Auto DevOps features
-For GitLab contributors, see the [Auto DevOps development guide](../../development/auto_devops.md).
+Based on the DevOps [stages](stages.md), use Auto DevOps to:
-## Enable or disable Auto DevOps
+**Build your app:**
-Auto DevOps is enabled by default for all projects in self-managed instances
+- [Auto Build](stages.md#auto-build)
-(as of [GitLab 11.3](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/41729)),
+- [Auto Dependency Scanning](stages.md#auto-dependency-scanning)
-but not for GitLab SaaS instances.
-When first using Auto DevOps, review the [requirements](requirements.md) to
+**Test your app:**
-ensure all the necessary components to make full use of Auto DevOps are
-available. First-time users should follow the [quick start guide](quick_start_guide.md).
-Depending on your instance type, you can enable or disable Auto DevOps at the
+- [Auto Test](stages.md#auto-test)
-following levels:
+- [Auto Browser Performance Testing](stages.md#auto-browser-performance-testing)
+- [Auto Code Intelligence](stages.md#auto-code-intelligence)
+- [Auto Code Quality](stages.md#auto-code-quality)
+- [Auto Container Scanning](stages.md#auto-container-scanning)
+- [Auto License Compliance](stages.md#auto-license-compliance)
-| Instance type       | [Project](#at-the-project-level) | [Group](#at-the-group-level) | [Instance](#at-the-instance-level) (Admin Area)  |
+**Deploy your app:**
-|---------------------|------------------------|------------------------|------------------------|
-| GitLab SaaS         | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| GitLab self-managed | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes |
-When you enable Auto DevOps for your instance, it attempts to run on all
+- [Auto Review Apps](stages.md#auto-review-apps)
-pipelines in each project. The Auto DevOps setting automatically disables itself for individual
+- [Auto Deploy](stages.md#auto-deploy)
-projects on their first pipeline failure. An instance administrator can enable
-or disable this default in the [Auto DevOps settings](../../user/admin_area/settings/continuous_integration.md#auto-devops).
-[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/26655) in GitLab 12.7,
+**Monitor your app:**
-Auto DevOps runs on pipelines automatically only if a [`Dockerfile` or matching buildpack](stages.md#auto-build)
-exists.
-If a [CI/CD configuration file](../../ci/yaml/index.md) is present in the
+- [Auto Monitoring](stages.md#auto-monitoring)
-project, it remains unchanged and Auto DevOps doesn't affect it.
-### At the project level
+**Secure your app:**
-When you enable Auto DevOps for a project, ensure that your project does not have a `.gitlab-ci.yml` present. If it exists, remove it before enabling Auto DevOps.
+- [Auto Dynamic Application Security Testing (DAST)](stages.md#auto-dast)
+- [Auto Static Application Security Testing (SAST)](stages.md#auto-sast)
+- [Auto Secret Detection](stages.md#auto-secret-detection)
-To enable it:
+### How it works
-1. Go to your project's **Settings > CI/CD > Auto DevOps**.
+Auto DevOps detects your code language and uses [CI/CD templates](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/gitlab/ci/templates)
-1. Select the **Default to Auto DevOps pipeline** checkbox to enable it.
+to create and run default pipelines. All you need to kick it off is to
-1. (Optional, but recommended) When enabling, you can add in the
+[enable](#enable-or-disable-auto-devops) it.
-   [base domain](#auto-devops-base-domain) Auto DevOps uses to
-   [deploy your application](stages.md#auto-deploy),
-   and choose the [deployment strategy](#deployment-strategy).
-1. Click **Save changes** for the changes to take effect.
-After enabling the feature, an Auto DevOps pipeline is triggered on the default branch.
+Auto DevOps starts by building and testing your application. Then, based on your
+[predefined deployment configuration](requirements.md),
+creates the necessary jobs to deploy your apps to staging
+and/or production. It also sets up [Review Apps](stages.md#auto-review-apps)
+so that you can preview your changes in a per-branch basis.
-### At the group level
+Note that you don't need to set up the deployment upfront. Auto DevOps
+still builds and tests your application. You can define the deployment later.
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/52447) in GitLab 11.10.
+Auto DevOps avoids the hassle of having to create entire pipelines manually.
+Keep it simple and facilitate an iterative approach: ship your app first,
+then explore the [customizations](customize.md) later.
+You can also [manage Auto DevOps with APIs](customize.md#extend-auto-devops-with-the-api).
-Only administrators and group owners can enable or disable Auto DevOps at the group level.
+Some of the benefits of using Auto DevOps as part of your workflow are:
-When you enable Auto DevOps at group level, the subgroups and projects in that group inherit the configuration. Auto DevOps
+- Consistency: always start from default templates.
-can be specifically enabled or disabled individually for projects and subgroups.
+- Simplicity: create your pipeline with the default settings first, iterate later.
+- Productivity: deploy multiple apps in a short period of time.
+- Efficiency: get things done fast.
-To enable or disable Auto DevOps at the group level:
+### Comparison to application platforms and PaaS
-1. Go to your group's **Settings > CI/CD > Auto DevOps** page.
+Auto DevOps provides features often included in an application
-1. Select the **Default to Auto DevOps pipeline** checkbox to enable it.
+platform or in a Platform as a Service (PaaS).
-1. Click **Save changes** for the changes to take effect.
-### At the instance level **(FREE SELF)**
+Inspired by [Heroku](https://www.heroku.com/), Auto DevOps goes beyond it
+in multiple ways:
-Even when disabled at the instance level, group owners and project maintainers
+- Auto DevOps works with any Kubernetes cluster.
-can still enable Auto DevOps at the group and project level, respectively.
+- There is no additional cost.
+- You can use a cluster hosted by yourself or on any public cloud.
+- Auto DevOps offers an incremental graduation path. If you need to [customize](customize.md), start by changing the templates and evolve from there.
-1. As an administrator, on the top bar, select **Menu >** **{admin}** **Admin**.
+## Get started with Auto DevOps
-1. Go to **Settings > CI/CD > Continuous Integration and Deployment**.
-1. Select **Default to Auto DevOps pipeline for all projects** to enable it.
-1. (Optional) You can set up the Auto DevOps [base domain](#auto-devops-base-domain),
-   for Auto Deploy and Auto Review Apps to use.
-1. Click **Save changes** for the changes to take effect.
-### Deployment strategy
+To get started, you only need to [enable Auto DevOps](#enable-or-disable-auto-devops).
+This is enough to run an Auto DevOps pipeline to build and
+test your application.
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/38542) in GitLab 11.0.
+If you want to build, test, and deploy your app:
-You can change the deployment strategy used by Auto DevOps by visiting your
+1. See the [requirements for deployment](requirements.md).
-project's **Settings > CI/CD > Auto DevOps**. The following options
+1. [Enable Auto DevOps](#enable-or-disable-auto-devops).
-are available:
+1. Follow the [quick start guide](#quick-start).
- **Continuous deployment to production**: Enables [Auto Deploy](stages.md#auto-deploy)
+As Auto DevOps relies on many components, be familiar with:
-  with the default branch directly deployed 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`. Production deployments execute with a 5 minute delay between
-  each increment in rollout.
- **Automatic deployment to staging, manual deployment to production**: Sets the
-  [`STAGING_ENABLED`](customize.md#deploy-policy-for-staging-and-production-environments) and
-  [`INCREMENTAL_ROLLOUT_MODE`](customize.md#incremental-rollout-to-production) variables
-  to `1` and `manual`. This means:
-  - The default branch is directly deployed to staging.
+- [Continuous methodologies](../../ci/introduction/index.md)
-  - Manual actions are provided for incremental rollout to production.
+- [Docker](https://docs.docker.com)
+- [GitLab Runner](https://docs.gitlab.com/runner/)
-NOTE:
+When deploying to a Kubernetes cluster make sure you're also familiar with:
-Use the [blue-green deployment](../../ci/environments/incremental_rollouts.md#blue-green-deployment) technique
-to minimize downtime and risk.
-## Quick start
+- [Kubernetes](https://kubernetes.io/docs/home/)
+- [Helm](https://helm.sh/docs/)
+- [Prometheus](https://prometheus.io/docs/introduction/overview/)
-For GitLab.com users, see the [quick start guide](quick_start_guide.md)
+### Enable or disable Auto DevOps
-for setting up Auto DevOps deploying to a Kubernetes cluster on Google Kubernetes
-Engine (GKE).
-If you use a self-managed instance of GitLab, you must configure the
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/41729) in GitLab 11.3, Auto DevOps is enabled by default.
-[Google OAuth 2.0 OmniAuth Provider](../../integration/google.md) before
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/26655) GitLab 12.7, Auto DevOps runs pipelines automatically only if a [`Dockerfile` or matching buildpack](stages.md#auto-build) exists.
-configuring a cluster on GKE. After configuring the provider, you can follow
-the steps in the [quick start guide](quick_start_guide.md) to get started.
-In [GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/issues/208132) and later, it is
+Depending on your instance type, you can enable or disable Auto DevOps at the
-possible to leverage Auto DevOps to deploy to [AWS ECS](requirements.md#auto-devops-requirements-for-amazon-ecs).
+following levels:
-## Comparison to application platforms and PaaS
+| Instance type       | [Project](#at-the-project-level) | [Group](#at-the-group-level) | [Instance](#at-the-instance-level) (Admin Area)  |
+|---------------------|------------------------|------------------------|------------------------|
+| GitLab SaaS         | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
+| GitLab self-managed | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes |
-Auto DevOps provides features often included in an application
+Before enabling Auto DevOps, consider [preparing it for deployment](requirements.md). If you don't, Auto DevOps can build and test your app,
-platform or a Platform as a Service (PaaS). It takes inspiration from the
+but cannot deploy it.
-innovative work done by [Heroku](https://www.heroku.com/) and goes beyond it
-in multiple ways:
- Auto DevOps works with any Kubernetes cluster; you're not limited to running
+#### At the project level
-  on infrastructure managed by GitLab. (Note that many features also work without Kubernetes).
- There is no additional cost (no markup on the infrastructure costs), and you
-  can use a Kubernetes cluster you host or Containers as a Service on any
-  public cloud (for example, [Google Kubernetes Engine](https://cloud.google.com/kubernetes-engine/)).
- Auto DevOps has more features including security testing, performance testing,
-  and code quality testing.
- Auto DevOps offers an incremental graduation path. If you need advanced customizations,
-  you can start modifying the templates without starting over on a
-  completely different platform. Review the [customizing](customize.md) documentation for more information.
-## Features
+To use Auto DevOps for individual projects, you can enable it in a
+project-by-project basis. If you intend to use it for more projects,
+you can enable it for a [group](#at-the-group-level) or an
+[instance](#at-the-instance-level). This can save you the time of
+enabling it one by one.
-NOTE:
+Only project Maintainers can enable or disable Auto DevOps at the project level.
-Depending on your target platform, some features might not be available to you.
-Comprised of a set of [stages](stages.md), Auto DevOps brings these best practices to your
+Before enabling Auto DevOps, ensure that your project does not have a
-project automatically:
+`.gitlab-ci.yml` present. If present, your CI/CD configuration takes
+precedence over the Auto DevOps pipeline.
- [Auto Browser Performance Testing](stages.md#auto-browser-performance-testing)
+To enable Auto DevOps for a project:
- [Auto Build](stages.md#auto-build)
- [Auto Code Intelligence](stages.md#auto-code-intelligence)
- [Auto Code Quality](stages.md#auto-code-quality)
- [Auto Container Scanning](stages.md#auto-container-scanning)
- [Auto DAST (Dynamic Application Security Testing)](stages.md#auto-dast)
- [Auto Dependency Scanning](stages.md#auto-dependency-scanning)
- [Auto Deploy](stages.md#auto-deploy)
- [Auto License Compliance](stages.md#auto-license-compliance)
- [Auto Monitoring](stages.md#auto-monitoring)
- [Auto Review Apps](stages.md#auto-review-apps)
- [Auto SAST (Static Application Security Testing)](stages.md#auto-sast)
- [Auto Secret Detection](stages.md#auto-secret-detection)
- [Auto Test](stages.md#auto-test)
-As Auto DevOps relies on many different components, you should have a basic
+1. Go to your project's **Settings > CI/CD > Auto DevOps**.
-knowledge of the following:
+1. Select the **Default to Auto DevOps pipeline**.
+1. (Recommended) Add the [base domain](requirements.md#auto-devops-base-domain).
+1. (Recommended) Choose the [deployment strategy](requirements.md#auto-devops-deployment-strategy).
+1. Select **Save changes**.
- [Kubernetes](https://kubernetes.io/docs/home/)
+GitLab triggers the Auto DevOps pipeline on the default branch.
- [Helm](https://helm.sh/docs/)
- [Docker](https://docs.docker.com)
- [GitLab Runner](https://docs.gitlab.com/runner/)
- [Prometheus](https://prometheus.io/docs/introduction/overview/)
-Auto DevOps provides great defaults for all the stages and makes use of
+To disable it, follow the same process and deselect **Default to Auto
-[CI templates](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/gitlab/ci/templates). You can, however,
+DevOps pipeline**.
-[customize](customize.md) almost everything to your needs, and
-[manage Auto DevOps with GitLab APIs](customize.md#extend-auto-devops-with-the-api).
-For an overview on the creation of Auto DevOps, read more
+#### At the group level
-[in this blog post](https://about.gitlab.com/blog/2017/06/29/whats-next-for-gitlab-ci/).
-NOTE:
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/52447) in GitLab 11.10.
-Kubernetes clusters can [be used without](../../user/project/clusters/index.md)
-Auto DevOps.
-## Kubernetes requirements
+When you enable Auto DevOps at group level, the subgroups and projects in that
+group inherit the configuration. This saves you time by batch-enabling it
+rather than enabling individually for each subgroup or project.
-See [Auto DevOps requirements for Kubernetes](requirements.md#auto-devops-requirements-for-kubernetes).
+When enabled for a group, you can still disable Auto DevOps
+for the subgroups and projects where you don't want to use it.
-## Auto DevOps base domain
+Only GitLab administrators and group owners can enable or disable Auto DevOps
+at the group level.
-The Auto DevOps base domain is required to use
+To enable Auto DevOps for a group:
-[Auto Review Apps](stages.md#auto-review-apps), [Auto Deploy](stages.md#auto-deploy), and
-[Auto Monitoring](stages.md#auto-monitoring). You can define the base domain in
-any of the following places:
- Either under the cluster's settings, whether for an instance,
+1. Go to your group's **Settings > CI/CD > Auto DevOps**.
-  [projects](../../user/project/clusters/gitlab_managed_clusters.md#base-domain) or
+1. Select **Default to Auto DevOps pipeline**.
-  [groups](../../user/group/clusters/index.md#base-domain)
+1. Select **Save changes**.
- Or at the project level as a variable: `KUBE_INGRESS_BASE_DOMAIN`
- Or at the group level as a variable: `KUBE_INGRESS_BASE_DOMAIN`
- Or as an instance-wide fallback in **Menu >** **{admin}** **Admin >**
-  **Settings > CI/CD** under the **Continuous Integration and Delivery** section.
-The base domain variable `KUBE_INGRESS_BASE_DOMAIN` follows the same order of precedence
+After enabling Auto DevOps at the group level, you can trigger the
-as other environment [variables](../../ci/variables/index.md#cicd-variable-precedence).
+Auto DevOps pipeline for any project that belongs to that group. To do so:
-If this variable isn't set and the cluster setting is left blank, the instance-wide domain is used if set for your instance.
-Auto DevOps requires a wildcard DNS A record matching the base domain(s). For
+1. Go to the project's homepage.
-a base domain of `example.com`, you'd need a DNS entry like:
+1. Make sure the project doesn't contain a `.gitlab-ci.yml` file.
+1. From the project's sidebar, go to **CI/CD > Pipelines**.
+1. Select **Run pipeline** to trigger the Auto DevOps pipeline.
-```plaintext
+To disable Auto DevOps on the group level, follow the same process and
-*.example.com   3600     A     1.2.3.4
+deselect **Default to Auto DevOps pipeline**.
-```
-In this case, the deployed applications are served from `example.com`, and `1.2.3.4`
+#### At the instance level **(FREE SELF)**
-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)
+By enabling Auto DevOps in the instance level, all projects created in that
-which provide automatic wildcard DNS without any configuration. For [nip.io](https://nip.io),
+instance become enabled. This is convenient when you want to run Auto DevOps by
-set the Auto DevOps base domain to `1.2.3.4.nip.io`.
+default for all projects. You can still disable Auto DevOps individually for
+the groups and projects where you don't want to run it.
-After completing setup, all requests hit the load balancer, which routes requests
+Only GitLab administrators can enable or disable Auto DevOps in the instance
-to the Kubernetes pods running your application.
+level.
-### AWS ECS
+Even when disabled for an instance, group owners and project maintainers
+can still enable Auto DevOps at the group and project levels.
-See [Auto DevOps requirements for Amazon ECS](requirements.md#auto-devops-requirements-for-amazon-ecs).
+To enable Auto DevOps for your instance:
-## Use multiple Kubernetes clusters
+1. From the top bar, select **Menu >** **{admin}** **Admin**.
+1. Go to **Settings > CI/CD > Continuous Integration and Deployment**.
+1. Select **Default to Auto DevOps pipeline**.
+1. (Optional) Add the Auto DevOps [base domain](requirements.md#auto-devops-base-domain).
+1. Select **Save changes**.
-When using Auto DevOps, you can deploy different environments to
+When enabled, it attempts to run Auto DevOps pipelines in every project. If the
-different Kubernetes clusters, due to the 1:1 connection
+pipeline fails in a particular project, it disables itself.
-[existing between them](../../user/project/clusters/multiple_kubernetes_clusters.md).
+GitLab administrators can change this in the [Auto DevOps settings](../../user/admin_area/settings/continuous_integration.md#auto-devops).
-The [Deploy Job template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Jobs/Deploy.gitlab-ci.yml)
+If a [CI/CD configuration file](../../ci/yaml/index.md) is present,
-used by Auto DevOps defines 3 environment names:
+it remains unchanged and Auto DevOps doesn't affect it.
- `review/` (every environment starting with `review/`)
+To disable Auto DevOps in the instance level, follow the same process
- `staging`
+and deselect the **Default to Auto DevOps pipeline** checkbox.
- `production`
-Those environments are tied to jobs using [Auto Deploy](stages.md#auto-deploy), so
+### Quick start
-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:
+To guide your through the process of setting up Auto DevOps to deploy to a Kubernetes cluster on
+Google Kubernetes Engine (GKE), see the [quick start guide](quick_start_guide.md).
-| Cluster name | Cluster environment scope | `KUBE_INGRESS_BASE_DOMAIN` variable value | Variable environment scope | Notes |
+You can also follow the quick start for the general steps, but deploy to
-|--------------|---------------------------|-------------------------------------------|----------------------------|---|
+[AWS ECS](requirements.md#auto-devops-requirements-for-amazon-ecs) instead.
-| 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:
+If you're a self-managed user, before deploying to GKE, a GitLab administrator needs to:
-1. Navigate to your project's **Infrastructure > Kubernetes clusters**.
+1. Configure the [Google OAuth 2.0 OmniAuth Provider](../../integration/google.md).
-1. Create the Kubernetes clusters with their respective environment scope, as
+1. Configure a cluster on GKE.
-   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](#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.
+## Upgrade Auto DevOps dependencies when updating GitLab
-Verify whether your application deployed as a Review App in the Kubernetes
-cluster with the `review/*` environment scope. Similarly, you can check the
-other environments.
-[Cluster environment scope isn't respected](https://gitlab.com/gitlab-org/gitlab/-/issues/20351)
+When updating GitLab, you may need to upgrade Auto DevOps dependencies to
-when checking for active Kubernetes clusters. For multi-cluster setup to work with Auto DevOps,
+match your new GitLab version:
-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.
-## Limitations
+- [Upgrading Auto DevOps resources](upgrading_auto_deploy_dependencies.md):
+  - Auto DevOps template.
+  - Auto Deploy template.
+  - Auto Deploy image.
+  - Helm.
+  - Kubernetes.
+  - Environment variables.
+- [Upgrading PostgreSQL](upgrading_postgresql.md).
-The following restrictions apply.
+## Limitations
 ### Private registry support
-No documented way of using private container registry with Auto DevOps exists.
+We cannot guarantee that you can use a private container registry with Auto DevOps.
-We strongly advise using GitLab Container Registry with Auto DevOps to
+We strongly advise you to use GitLab Container Registry with Auto DevOps to
 simplify configuration and prevent any unforeseen issues.
 ### Install applications behind a proxy
 The GitLab integration with Helm does not support installing applications when
-behind a proxy. Users who want to do so must inject their proxy settings
+behind a proxy.
-into the installation pods at runtime, such as by using a
-[`PodPreset`](https://v1-19.docs.kubernetes.io/docs/concepts/workloads/pods/podpreset/):
+To do so, inject proxy settings into the installation pods at runtime.
+For example, you can use a [`PodPreset`](https://v1-19.docs.kubernetes.io/docs/concepts/workloads/pods/podpreset/):
 ```yaml
 apiVersion: settings.k8s.io/v1alpha1
@@ -335,23 +284,6 @@ spec:
      value: "PUT_YOUR_HTTPS_PROXY_HERE"
 ```
-## Upgrade Auto DevOps dependencies when updating GitLab
-When updating GitLab, you may need to upgrade Auto DevOps dependencies to
-match your new GitLab version:
- [Upgrading Auto DevOps resources](upgrading_auto_deploy_dependencies.md):
-  - Auto DevOps template.
-  - Auto Deploy template.
-  - Auto Deploy image.
-  - Helm.
-  - Kubernetes.
-  - Environment variables.
- [Upgrading PostgreSQL](upgrading_postgresql.md).
 ## Troubleshooting
 See [troubleshooting Auto DevOps](troubleshooting.md).
-<!-- DO NOT ADD TROUBLESHOOTING INFO HERE -->
-<!-- Troubleshooting information has moved to troubleshooting.md -->
--- a/doc/topics/autodevops/multiple_clusters_auto_devops.md
+++ b/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.
--- a/doc/topics/autodevops/prepare_deployment.md
+++ b/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.
--- a/doc/topics/autodevops/quick_start_guide.md
+++ b/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)

--- a/doc/topics/autodevops/requirements.md
+++ b/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),
+Before enabling [Auto DevOps](index.md), we recommend you to prepare it for
-[Amazon Elastic Container Service (ECS)](#auto-devops-requirements-for-amazon-ecs),
+deployment. If you don't, you can use it to build and test your apps, and
-or [Amazon Cloud Compute](#auto-devops-requirements-for-amazon-ecs).
+then configure the deployment later.
-For more information about Auto DevOps, see [the main Auto DevOps page](index.md)
-or the [quick start guide](quick_start_guide.md).
+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.

--- a/doc/user/admin_area/settings/continuous_integration.md
+++ b/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.