Add latest changes from gitlab-org/gitlab@13-2-stable-ee

7 files changed, 219 insertions, 63 deletions

diff --git a/doc/topics/autodevops/customize.md b/doc/topics/autodevops/customize.md
index 253d5e56463..2d6da4d322b 100644
--- a/doc/topics/autodevops/customize.md
+++ b/doc/topics/autodevops/customize.md
@@ -41,11 +41,16 @@ If your goal is to use only a single custom buildpack, you should provide the pr
 
 ## Custom `Dockerfile`
 
+> Support for `DOCKERFILE_PATH` was [added in GitLab 13.2](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/35662)
+
 If your project has a `Dockerfile` in the root of the project repository, Auto DevOps
 builds a Docker image based on the Dockerfile, rather than using buildpacks.
 This can be much faster and result in smaller images, especially if your
 Dockerfile is based on [Alpine](https://hub.docker.com/_/alpine/).
 
+If you set the `DOCKERFILE_PATH` CI variable, Auto Build looks for a Dockerfile there
+instead.
+
 ## Passing arguments to `docker build`
 
 Arguments can be passed to the `docker build` command using the
@@ -213,7 +218,7 @@ include:
 
 See the [Auto DevOps template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Auto-DevOps.gitlab-ci.yml) for information on available jobs.
 
-CAUTION: **Deprecation**
+CAUTION: **Deprecation:**
 Auto DevOps templates using the [`only`](../../ci/yaml/README.md#onlyexcept-basic) or
 [`except`](../../ci/yaml/README.md#onlyexcept-basic) syntax will switch
 to the [`rules`](../../ci/yaml/README.md#rules) syntax, starting in
@@ -238,7 +243,7 @@ postgres://user:password@postgres-host:postgres-port/postgres-database
 
 ### Upgrading PostgresSQL
 
-CAUTION: **Deprecation**
+CAUTION: **Deprecation:**
 The variable `AUTO_DEVOPS_POSTGRES_CHANNEL` that controls default provisioned
 PostgreSQL was changed to `2` in [GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/issues/210499).
 To keep using the old PostgreSQL, set the `AUTO_DEVOPS_POSTGRES_CHANNEL` variable to
@@ -306,11 +311,13 @@ applications.
 | `AUTO_DEVOPS_CHART_REPOSITORY_USERNAME` | From GitLab 11.11, used to set a username to connect to the Helm repository. Defaults to no credentials. Also set `AUTO_DEVOPS_CHART_REPOSITORY_PASSWORD`. |
 | `AUTO_DEVOPS_CHART_REPOSITORY_PASSWORD` | From GitLab 11.11, used to set a password to connect to the Helm repository. Defaults to no credentials. Also set `AUTO_DEVOPS_CHART_REPOSITORY_USERNAME`. |
 | `AUTO_DEVOPS_DEPLOY_DEBUG`              | From GitLab 13.1, if this variable is present, Helm will output debug logs. |
+| `AUTO_DEVOPS_ALLOW_TO_FORCE_DEPLOY_V<N>` | From [auto-deploy-image](https://gitlab.com/gitlab-org/cluster-integration/auto-deploy-image) v1.0.0, if this variable is present, a new major version of chart is forcibly deployed. [More details](upgrading_chart.md#ignore-warning-and-continue-deploying) |
 | `AUTO_DEVOPS_MODSECURITY_SEC_RULE_ENGINE` | From GitLab 12.5, used in combination with [ModSecurity feature flag](../../user/clusters/applications.md#web-application-firewall-modsecurity) to toggle [ModSecurity's `SecRuleEngine`](https://github.com/SpiderLabs/ModSecurity/wiki/Reference-Manual-(v2.x)#SecRuleEngine) behavior. Defaults to `DetectionOnly`. |
 | `BUILDPACK_URL`                         | Buildpack's full URL. Can point to either [a Git repository URL or a tarball URL](#custom-buildpacks). |
 | `CANARY_ENABLED`                        | From GitLab 11.0, used to define a [deploy policy for canary environments](#deploy-policy-for-canary-environments-premium). |
 | `CANARY_PRODUCTION_REPLICAS`            | Number of canary replicas to deploy for [Canary Deployments](../../user/project/canary_deployments.md) in the production environment. Takes precedence over `CANARY_REPLICAS`. Defaults to 1. |
 | `CANARY_REPLICAS`                       | Number of canary replicas to deploy for [Canary Deployments](../../user/project/canary_deployments.md). Defaults to 1. |
+| `DOCKERFILE_PATH`                       | From GitLab 13.2, allows overriding the [default Dockerfile path for the build stage](#custom-dockerfile) |
 | `HELM_RELEASE_NAME`                     | From GitLab 12.1, allows the `helm` release name to be overridden. Can be used to assign unique release names when deploying multiple projects to a single namespace. |
 | `HELM_UPGRADE_VALUES_FILE`              | From GitLab 12.6, allows the `helm upgrade` values file to be overridden. Defaults to `.gitlab/auto-deploy-values.yaml`. |
 | `HELM_UPGRADE_EXTRA_ARGS`               | From GitLab 11.11, allows extra arguments in `helm` commands when deploying the application. Note that using quotes won't prevent word splitting. |
@@ -358,7 +365,8 @@ The following table lists variables used to disable jobs.
 | `DAST_DISABLED`                         | From GitLab 11.0, used to disable the `dast` job. If the variable is present, the job won't be created. |
 | `DEPENDENCY_SCANNING_DISABLED`          | From GitLab 11.0, used to disable the `dependency_scanning` job. If the variable is present, the job won't be created. |
 | `LICENSE_MANAGEMENT_DISABLED`           | From GitLab 11.0, used to disable the `license_management` job. If the variable is present, the job won't be created. |
-| `PERFORMANCE_DISABLED`                  | From GitLab 11.0, used to disable the `performance` job. If the variable is present, the job won't be created. |
+| `PERFORMANCE_DISABLED`                  | From GitLab 11.0, used to disable the browser `performance` job. If the variable is present, the job won't be created. |
+| `LOAD_PERFORMANCE_DISABLED`             | From GitLab 13.2, used to disable the `load_performance` job. If the variable is present, the job won't be created. |
 | `REVIEW_DISABLED`                       | From GitLab 11.0, used to disable the `review` and the manual `review:stop` job. If the variable is present, these jobs won't be created. |
 | `SAST_DISABLED`                         | From GitLab 11.0, used to disable the `sast` job. If the variable is present, the job won't be created. |
 | `TEST_DISABLED`                         | From GitLab 11.0, used to disable the `test` job. If the variable is present, the job won't be created. |
@@ -445,7 +453,7 @@ QA testing:
   environment:
     name: qa
   script:
-  - deploy foo
+    - deploy foo
 ```
 
 The track `foo` being referenced must also be defined in the application's Helm chart, like:
diff --git a/doc/topics/autodevops/index.md b/doc/topics/autodevops/index.md
index 767ea5ee7b7..01e61095fe2 100644
--- a/doc/topics/autodevops/index.md
+++ b/doc/topics/autodevops/index.md
@@ -104,16 +104,20 @@ knowledge of the following:
 - [GitLab Runner](https://docs.gitlab.com/runner/)
 - [Prometheus](https://prometheus.io/docs/introduction/overview/)
 
-Auto DevOps provides great defaults for all the stages; you can, however,
+Auto DevOps provides great defaults for all the stages and makes use of [CI templates](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/gitlab/ci/templates); you can, however,
 [customize](customize.md) almost everything to your needs.
 
 For an overview on the creation of Auto DevOps, read more
 [in this blog post](https://about.gitlab.com/blog/2017/06/29/whats-next-for-gitlab-ci/).
 
-NOTE: **Note**
+NOTE: **Note:**
 Kubernetes clusters can [be used without](../../user/project/clusters/index.md)
 Auto DevOps.
 
+## Kubernetes requirements
+
+See [Auto DevOps requirements for Kubernetes](requirements.md#auto-devops-requirements-for-kubernetes).
+
 ## Auto DevOps base domain
 
 The Auto DevOps base domain is required to use
@@ -163,6 +167,10 @@ 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.
 
+### AWS ECS
+
+See [Auto DevOps requirements for Amazon ECS](requirements.md#auto-devops-requirements-for-amazon-ecs).
+
 ## Enabling/Disabling Auto DevOps
 
 When first using Auto DevOps, review the [requirements](#requirements) to ensure
@@ -185,7 +193,7 @@ If enabling, check that your project does not have a `.gitlab-ci.yml`, or if one
    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.
+After enabling the feature, an Auto DevOps pipeline is triggered on the `master` branch.
 
 ### At the group level
 
@@ -240,11 +248,11 @@ TIP: **Tip:**
 Use the [blue-green deployment](../../ci/environments/incremental_rollouts.md#blue-green-deployment) technique
 to minimize downtime and risk.
 
-## Using multiple Kubernetes clusters **(PREMIUM)**
+## Using multiple Kubernetes clusters
 
 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/index.md#multiple-kubernetes-clusters-premium).
+[existing between them](../../user/project/clusters/index.md#multiple-kubernetes-clusters).
 
 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 currently defines 3 environment names:
@@ -271,8 +279,8 @@ To add a different cluster for each environment:
 1. Navigate to your project's **{cloud-gear}** **Operations > Kubernetes**.
 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 Helm Tiller
-   and Ingress. Wait for the Ingress IP address to be assigned.
+1. After creating the clusters, navigate to each cluster and 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 **{cloud-gear}** **Operations > Kubernetes**,
@@ -293,9 +301,9 @@ No documented way of using private container registry with Auto DevOps exists.
 We strongly advise using GitLab Container Registry with Auto DevOps to
 simplify configuration and prevent any unforeseen issues.
 
-### Installing Helm behind a proxy
+### Install applications behind a proxy
 
-GitLab does not support installing [Helm as a GitLab-managed App](../../user/clusters/applications.md#helm) when
+GitLab's Helm integration does not support installing applications when
 behind a proxy. Users who want to do so must inject their proxy settings
 into the installation pods at runtime, such as by using a
 [`PodPreset`](https://kubernetes.io/docs/concepts/workloads/pods/podpreset/):
@@ -358,6 +366,55 @@ Auto Deploy will fail if GitLab can't create a Kubernetes namespace and
 service account for your project. For help debugging this issue, see
 [Troubleshooting failed deployment jobs](../../user/project/clusters/index.md#troubleshooting).
 
+### Detected an existing PostgreSQL database
+
+After upgrading to GitLab 13.0, you may encounter this message when deploying
+with Auto DevOps:
+
+```plaintext
+Detected an existing PostgreSQL database installed on the
+deprecated channel 1, but the current channel is set to 2. The default
+channel changed to 2 in of GitLab 13.0.
+[...]
+```
+
+Auto DevOps, by default, installs an in-cluster PostgreSQL database alongside
+your application. The default installation method changed in GitLab 13.0, and
+upgrading existing databases requires user involvement. The two installation
+methods are:
+
+- **channel 1 (deprecated):** Pulls in the database as a dependency of the associated
+  Helm chart. Only supports Kubernetes versions up to version 1.15.
+- **channel 2 (current):** Installs the database as an independent Helm chart. Required
+  for using the in-cluster database feature with Kubernetes versions 1.16 and greater.
+
+If you receive this error, you can do one of the following actions:
+
+- You can *safely* ignore the warning and continue using the channel 1 PostgreSQL
+  database by setting `AUTO_DEVOPS_POSTGRES_CHANNEL` to `1` and redeploying.
+
+- You can delete the channel 1 PostgreSQL database and install a fresh channel 2
+  database by setting `AUTO_DEVOPS_POSTGRES_DELETE_V1` to a non-empty value and
+  redeploying.
+
+  DANGER: **Danger:**
+  Deleting the channel 1 PostgreSQL database permanently deletes the existing
+  channel 1 database and all its data. See
+  [Upgrading PostgreSQL](upgrading_postgresql.md)
+  for more information on backing up and upgrading your database.
+
+- If you are not using the in-cluster database, you can set
+  `POSTGRES_ENABLED` to `false` and re-deploy. This option is especially relevant to
+  users of *custom charts without the in-chart PostgreSQL dependency*.
+  Database auto-detection is based on the `postgresql.enabled` Helm value for
+  your release. This value is set based on the `POSTGRES_ENABLED` CI variable
+  and persisted by Helm, regardless of whether or not your chart uses the
+  variable.
+
+DANGER: **Danger:**
+Setting `POSTGRES_ENABLED` to `false` permanently deletes any existing
+channel 1 database for your environment.
+
 ## Development guides
 
 [Development guide for Auto DevOps](../../development/auto_devops.md)
diff --git a/doc/topics/autodevops/quick_start_guide.md b/doc/topics/autodevops/quick_start_guide.md
index ec5191dd4ac..4f8074f047e 100644
--- a/doc/topics/autodevops/quick_start_guide.md
+++ b/doc/topics/autodevops/quick_start_guide.md
@@ -98,24 +98,10 @@ status on your [GCP dashboard](https://console.cloud.google.com/kubernetes).
 Next, you will install some applications on your cluster that are needed
 to take full advantage of Auto DevOps.
 
-## Install the package manager
-
-After creating your Kubernetes cluster, GitLab's Kubernetes integration provides
-[pre-defined applications](../../user/project/clusters/index.md#installing-applications)
-for you to install. To install them, you must next install Helm Tiller, the
-Kubernetes package manager for Kubernetes, to enable the installation of other applications.
-
-Next to **Helm Tiller**, click **Install**.
-
-![Cluster applications](img/guide_cluster_apps_v12_3.png)
-
-After installation completes, the page reloads, and you can install other
-applications.
-
 ## Install Ingress and Prometheus
 
-After installing **Helm Tiller**, you can install other applications that rely on it,
-including Ingress and Prometheus, which we will install in this quick start guide:
+After your cluster is running, you can install your first applications.
+In this guide, we will install Ingress and Prometheus:
 
 - Ingress - Provides load balancing, SSL termination, and name-based virtual hosting,
   using NGINX behind the scenes.
@@ -305,7 +291,7 @@ all within GitLab. Despite its automatic nature, Auto DevOps can also be configu
 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#using-multiple-kubernetes-clusters-premium) **(PREMIUM)**
+1. [Multiple Kubernetes clusters](index.md#using-multiple-kubernetes-clusters)
 1. [Incremental rollout to production](customize.md#incremental-rollout-to-production-premium) **(PREMIUM)**
 1. [Disable jobs you don't need with environment variables](customize.md#environment-variables)
 1. [Use a static IP for your cluster](../../user/clusters/applications.md#using-a-static-ip)
diff --git a/doc/topics/autodevops/requirements.md b/doc/topics/autodevops/requirements.md
index b09a571fd16..33db94be97e 100644
--- a/doc/topics/autodevops/requirements.md
+++ b/doc/topics/autodevops/requirements.md
@@ -103,22 +103,26 @@ After all requirements are met, you can [enable Auto DevOps](index.md#enablingdi
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/208132) in GitLab 13.0.
 
-You can choose to target [Amazon Elastic Container Service (ECS)](../../ci/cloud_deployment/index.md) as a deployment platform instead of using Kubernetes.
+You can choose to target [AWS ECS](../../ci/cloud_deployment/index.md) as a deployment platform instead of using Kubernetes.
 
-To get started on Auto DevOps to Amazon ECS, you'll have to add a specific Environment
+To get started on Auto DevOps to AWS ECS, you'll have to add a specific Environment
 Variable. To do so, follow these steps:
 
 1. In your project, go to **Settings > CI / CD** and expand the **Variables**
    section.
 
 1. Specify which AWS platform to target during the Auto DevOps deployment
-   by adding the `AUTO_DEVOPS_PLATFORM_TARGET` variable.
+   by adding the `AUTO_DEVOPS_PLATFORM_TARGET` variable with one of the following values:
+   - `FARGATE` if the service you're targeting must be of launch type FARGATE.
+   - `ECS` if you're not enforcing any launch type check when deploying to ECS.
 
-1. Give this variable the value `ECS` before saving it.
-
-When you trigger a pipeline, if Auto DevOps is enabled and if you've correctly
+When you trigger a pipeline, if you have Auto DevOps enabled and if you have correctly
 [entered AWS credentials as environment variables](../../ci/cloud_deployment/index.md#deploy-your-application-to-the-aws-elastic-container-service-ecs),
-your application will be deployed to Amazon ECS.
+your application will be deployed to AWS ECS.
+
+NOTE: **Note:**
+[GitLab Managed Apps](../../user/clusters/applications.md) are not available when deploying to AWS ECS.
+You must manually configure your application (such as Ingress or Help) on AWS ECS.
 
 NOTE: **Note:**
 If you have both a valid `AUTO_DEVOPS_PLATFORM_TARGET` variable and a Kubernetes cluster tied to your project,
@@ -130,5 +134,5 @@ defined in the [`Jobs/Deploy/ECS.gitlab-ci.yml` template](https://gitlab.com/git
 However, it's not recommended to [include](../../ci/yaml/README.md#includetemplate)
 it on its own. This template is designed to be used with Auto DevOps only. It may change
 unexpectedly causing your pipeline to fail if included on its own. Also, the job
-names within this template may also change. Don't override these jobs' names in your
+names within this template may also change. Do not override these jobs' names in your
 own pipeline, as the override will stop working when the name changes.
diff --git a/doc/topics/autodevops/stages.md b/doc/topics/autodevops/stages.md
index 0c7c4919431..bf1594130f4 100644
--- a/doc/topics/autodevops/stages.md
+++ b/doc/topics/autodevops/stages.md
@@ -72,7 +72,8 @@ Heroku buildpacks, with the following caveats:
 - The `/bin/herokuish` command is not present in the resulting image, and prefixing
   commands with `/bin/herokuish procfile exec` is no longer required (nor possible).
 
-NOTE: **Note**: Auto Test still uses Herokuish, as test suite detection is not
+NOTE: **Note:**
+Auto Test still uses Herokuish, as test suite detection is not
 yet part of the Cloud Native Buildpack specification. For more information, see
 [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/212689).
 
@@ -294,7 +295,8 @@ You can disable DAST:
 
 > Introduced in [GitLab Premium](https://about.gitlab.com/pricing/) 10.4.
 
-Auto Browser Performance Testing measures the performance of a web page with the
+Auto [Browser Performance Testing](../../user/project/merge_requests/browser_performance_testing.md)
+measures the browser performance of a web page with the
 [Sitespeed.io container](https://hub.docker.com/r/sitespeedio/sitespeed.io/),
 creates a JSON report including the overall performance score for each page, and
 uploads the report as an artifact. By default, it tests the root page of your Review and
@@ -307,9 +309,26 @@ file named `.gitlab-urls.txt` in the root directory, one file per line. For exam
 /direction
 ```
 
-Any performance differences between the source and target branches are also
+Any browser performance differences between the source and target branches are also
 [shown in the merge request widget](../../user/project/merge_requests/browser_performance_testing.md).
 
+## Auto Load Performance Testing **(PREMIUM)**
+
+> Introduced in [GitLab Premium](https://about.gitlab.com/pricing/) 13.2.
+
+Auto [Load Performance Testing](../../user/project/merge_requests/load_performance_testing.md)
+measures the server performance of an application with the
+[k6 container](https://hub.docker.com/r/loadimpact/k6/),
+creates a JSON report including several key result metrics, and
+uploads the report as an artifact.
+
+Some initial setup is required. A [k6](https://k6.io/) test needs to be
+written that's tailored to your specific application. The test also needs to be
+configured so it can pick up the environment's dynamic URL via an environment variable.
+
+Any load performance test result differences between the source and target branches are also
+[shown in the merge request widget](../../user/project/merge_requests/load_performance_testing.md).
+
 ## Auto Deploy
 
 This is an optional step, since many projects don't have a Kubernetes cluster
@@ -372,7 +391,7 @@ as it attempts to fetch the image using `CI_REGISTRY_PASSWORD`.
 > - Support for deploying a PostgreSQL version that supports Kubernetes 1.16+ was [introduced](https://gitlab.com/gitlab-org/cluster-integration/auto-deploy-image/-/merge_requests/49) in GitLab 12.9.
 > - Supported out of the box for new deployments as of GitLab 13.0.
 
-CAUTION: **Deprecation**
+CAUTION: **Deprecation:**
 The default value for the `deploymentApiVersion` setting was changed from
 `extensions/v1beta` to `apps/v1` in [GitLab 13.0](https://gitlab.com/gitlab-org/charts/auto-deploy-app/-/issues/47).
 
@@ -398,7 +417,8 @@ To use Auto Deploy on a Kubernetes 1.16+ cluster:
 1. If you are deploying your application for the first time and are using
    GitLab 12.9 or 12.10, set `AUTO_DEVOPS_POSTGRES_CHANNEL` to `2`.
 
-DANGER: **Danger:** On GitLab 12.9 and 12.10, opting into
+DANGER: **Danger:**
+On GitLab 12.9 and 12.10, opting into
 `AUTO_DEVOPS_POSTGRES_CHANNEL` version `2` deletes the version `1` PostgreSQL
 database. Follow the [guide to upgrading PostgreSQL](upgrading_postgresql.md)
 to back up and restore your database before opting into version `2` (On
@@ -437,6 +457,10 @@ Herokuish, and you must prefix commands run in these images with
 `/bin/herokuish procfile exec` to replicate the environment where your application
 will run.
 
+### Upgrade auto-deploy-app Chart
+
+You can upgrade auto-deploy-app chart by following the [upgrade guide](upgrading_chart.md).
+
 ### Workers
 
 Some web applications must run extra deployments for "worker processes". For
@@ -469,16 +493,16 @@ workers:
   sidekiq:
     replicaCount: 1
     command:
-    - /bin/herokuish
-    - procfile
-    - exec
-    - sidekiq
+      - /bin/herokuish
+      - procfile
+      - exec
+      - sidekiq
     preStopCommand:
-    - /bin/herokuish
-    - procfile
-    - exec
-    - sidekiqctl
-    - quiet
+      - /bin/herokuish
+      - procfile
+      - exec
+      - sidekiqctl
+      - quiet
     terminationGracePeriodSeconds: 60
 ```
 
@@ -524,12 +548,12 @@ networkPolicy:
       matchLabels:
         app.gitlab.com/env: staging
     ingress:
-    - from:
-      - podSelector:
-          matchLabels: {}
-      - namespaceSelector:
-          matchLabels:
-            app.gitlab.com/managed_by: gitlab
+      - from:
+        - podSelector:
+            matchLabels: {}
+        - namespaceSelector:
+            matchLabels:
+              app.gitlab.com/managed_by: gitlab
 ```
 
 For more information on installing Network Policies, see
diff --git a/doc/topics/autodevops/upgrading_chart.md b/doc/topics/autodevops/upgrading_chart.md
new file mode 100644
index 00000000000..e4dacdfcf5b
--- /dev/null
+++ b/doc/topics/autodevops/upgrading_chart.md
@@ -0,0 +1,72 @@
+# Upgrading auto-deploy-app chart for Auto DevOps
+
+Auto DevOps provides the auto-deploy-app chart for deploying your application to the
+Kubernetes cluster with Helm/Tiller. Major version changes of this chart could have
+a significantly different resource architecture, and may not be backwards compatible.
+
+This guide provides instructions on how to upgrade your deployments to use the latest
+chart and resource architecture.
+
+## Compatibility
+
+The following table lists the version compatibility between GitLab and [auto-deploy-image](https://gitlab.com/gitlab-org/cluster-integration/auto-deploy-image) (with the [auto-deploy-app chart](https://gitlab.com/gitlab-org/cluster-integration/auto-deploy-image/-/tree/master/assets/auto-deploy-app)).
+
+| GitLab version   | auto-deploy-image version | Notes                                      |
+|------------------|---------------------------|--------------------------------------------|
+| v10.0 and higher | v0.1.0 and higher         | v0 and v1 charts are backwards compatible. |
+
+## Upgrade Guide
+
+The Auto DevOps project must use the unmodified chart managed by GitLab.
+[Customized charts](customize.md#custom-helm-chart) are unsupported.
+
+### v1 chart
+
+The v1 chart is backward compatible with the v0 chart, so no configuration changes are needed.
+
+## Troubleshooting
+
+### Major version mismatch warning
+
+If deploying a chart that has a major version that is different from the previous one,
+the new chart might not be correctly deployed. This could be due to an architectural
+change. If that happens, the deployment job fails with a message similar to:
+
+```plaintext
+*************************************************************************************
+                                   [WARNING]
+Detected a major version difference between the the chart that is currently deploying (auto-deploy-app-v0.7.0), and the previously deployed chart (auto-deploy-app-v1.0.0).
+A new major version might not be backward compatible with the current release (production). The deployment could fail or be stuck in an unrecoverable status.
+...
+```
+
+To clear this error message and resume deployments, you must do one of the following:
+
+- Manually [upgrade the chart version](#upgrade-guide).
+- [Use a specific chart version](#use-a-specific-chart-version).
+
+#### Use a specific chart version
+
+To use a specific chart version, you must specify a corresponding version of [auto-deploy-image](https://gitlab.com/gitlab-org/cluster-integration/auto-deploy-image).
+Do this by [customizing the image in your `.gitlab-ci.yml`](customize.md#customizing-gitlab-ciyml).
+
+For example, create the following `.gitlab-ci.yml` file in the project. It configures Auto DevOps
+to use [auto-deploy-image](https://gitlab.com/gitlab-org/cluster-integration/auto-deploy-image) version `v0.17.0`
+for deployment jobs. It will download the chart from [chart repository](https://charts.gitlab.io/):
+
+```yaml
+include:
+  - template: Auto-DevOps.gitlab-ci.yml
+
+.auto-deploy:
+  image: "registry.gitlab.com/gitlab-org/cluster-integration/auto-deploy-image:v0.17.0"
+```
+
+### Ignore warning and continue deploying
+
+If you are certain that the new chart version is safe to be deployed,
+you can add the `AUTO_DEVOPS_ALLOW_TO_FORCE_DEPLOY_V<N>` [environment variable](customize.md#build-and-deployment)
+to force the deployment to continue, where `<N>` is the major version.
+
+For example, if you want to deploy the v2.0.0 chart on a deployment that previously
+used the v0.17.0 chart, add `AUTO_DEVOPS_ALLOW_TO_FORCE_DEPLOY_V2`.
diff --git a/doc/topics/autodevops/upgrading_postgresql.md b/doc/topics/autodevops/upgrading_postgresql.md
index 893f7ba7cde..2ebe362280f 100644
--- a/doc/topics/autodevops/upgrading_postgresql.md
+++ b/doc/topics/autodevops/upgrading_postgresql.md
@@ -26,8 +26,12 @@ involves:
    This varies based on Kubernetes providers.
 1. Prepare for downtime. The steps below include taking the application offline
    so that the in-cluster database does not get modified after the database dump is created.
+1. Ensure you have not set `POSTGRES_ENABLED` to `false`, as this setting deletes
+   any existing channel 1 database. For more information, see
+   [Detected an existing PostgreSQL database](index.md#detected-an-existing-postgresql-database).
 
-TIP: **Tip:** If you have configured Auto DevOps to have staging,
+TIP: **Tip:**
+If you have configured Auto DevOps to have staging,
 consider trying out the backup and restore steps on staging first, or
 trying this out on a review app.
 
@@ -158,12 +162,13 @@ pvc-9085e3d3-5239-11ea-9c8d-42010a8e0096   8Gi        RWO            Retain
 
 ## Install new PostgreSQL
 
-CAUTION: **Caution:** Using the newer version of PostgreSQL will delete
+CAUTION: **Caution:**
+Using the newer version of PostgreSQL will delete
 the older 0.7.1 PostgreSQL. To prevent the underlying data from being
-deleted, you can choose to retain the [persistent
-volume](#retain-persistent-volumes).
+deleted, you can choose to retain the [persistent volume](#retain-persistent-volumes).
 
-TIP: **Tip:** You can also
+TIP: **Tip:**
+You can also
 [scope](../../ci/environments/index.md#scoping-environments-with-specs) the
 `AUTO_DEVOPS_POSTGRES_CHANNEL`, `AUTO_DEVOPS_POSTGRES_DELETE_V1` and
 `POSTGRES_VERSION` variables to specific environments, e.g. `staging`.