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

5 files changed, 159 insertions, 12 deletions

diff --git a/doc/ci/environments/deployment_safety.md b/doc/ci/environments/deployment_safety.md
new file mode 100644
index 00000000000..055baa78743
--- /dev/null
+++ b/doc/ci/environments/deployment_safety.md
@@ -0,0 +1,106 @@
+# Deployment safety
+
+Deployment jobs can be more sensitive than other jobs in a pipeline,
+and might need to be treated with extra care. GitLab has several features
+that help maintain deployment security and stability.
+
+You can:
+
+- [Restrict write-access to a critical environment](#restrict-write-access-to-a-critical-environment)
+- [Restrict deployments for a particular period](#restrict-deployments-for-a-particular-period)
+
+If you are using a continuous deployment workflow and want to ensure that concurrent deployments to the same environment do not happen, you should enable the following options:
+
+- [Ensure only one deployment job runs at a time](#ensure-only-one-deployment-job-runs-at-a-time)
+- [Skip outdated deployment jobs](#skip-outdated-deployment-jobs)
+
+## Restrict write access to a critical environment
+
+By default, environments can be modified by any team member that has [Developer permission or higher](../../user/permissions.md#project-members-permissions).
+If you want to restrict write access to a critical environment (for example a `production` environment),
+you can set up [protected environments](protected_environments.md).
+
+## Ensure only one deployment job runs at a time
+
+Pipeline jobs in GitLab CI/CD run in parallel, so it's possible that two deployment
+jobs in two different pipelines attempt to deploy to the same environment at the same
+time. This is not desired behavior as deployments should happen sequentially.
+
+You can ensure only one deployment job runs at a time with the [`resource_group` keyword](../yaml/README.md#resource_group) keyword in your `.gitlab-ci.yml`.
+
+For example:
+
+```yaml
+deploy:
+  script: deploy-to-prod
+  resource_group: prod
+```
+
+Example of a problematic pipeline flow **before** using the resource group:
+
+1. `deploy` job in Pipeline-A starts running.
+1. `deploy` job in Pipeline-B starts running. *This is a concurrent deployment that could cause an unexpected result.*
+1. `deploy` job in Pipeline-A finished.
+1. `deploy` job in Pipeline-B finished.
+
+The improved pipeline flow **after** using the resource group:
+
+1. `deploy` job in Pipeline-A starts running.
+1. `deploy` job in Pipeline-B attempts to start, but waits for the first `deploy` job to finish.
+1. `deploy` job in Pipeline-A finishes.
+1. `deploy` job in Pipeline-B starts running.
+
+For more information, see [`resource_group` keyword in `.gitlab-ci.yml`](../yaml/README.md#resource_group).
+
+## Skip outdated deployment jobs
+
+The execution order of pipeline jobs can vary from run to run, which could cause
+undesired behavior. For example, a deployment job in a newer pipeline could
+finish before a deployment job in an older pipeline.
+This creates a race condition where the older deployment finished later,
+overwriting the "newer" deployment.
+
+You can ensure that older deployment jobs are cancelled automatically when a newer deployment
+runs by enabling the [Skip outdated deployment jobs](../pipelines/settings.md#skip-outdated-deployment-jobs) feature.
+
+Example of a problematic pipeline flow **before** enabling Skip outdated deployment jobs:
+
+1. Pipeline-A is created on the master branch.
+1. Later, Pipeline-B is created on the master branch (with a newer commit SHA).
+1. The `deploy` job in Pipeline-B finishes first, and deploys the newer code.
+1. The `deploy` job in Pipeline-A finished later, and deploys the older code, **overwriting** the newer (latest) deployment.
+
+The improved pipeline flow **after** enabling Skip outdated deployment jobs:
+
+1. Pipeline-A is created on the `master` branch.
+1. Later, Pipeline-B is created on the `master` branch (with a newer SHA).
+1. The `deploy` job in Pipeline-B finishes first, and deploys the newer code.
+1. The `deploy` job in Pipeline-A is automatically cancelled, so that it doesn't overwrite the deployment from the newer pipeline.
+
+## Restrict deployments for a particular period
+
+If you want to prevent deployments for a particular period, for example during a planned
+vacation period when most employees are out, you can set up a [Deploy Freeze](../../user/project/releases/index.md#set-a-deploy-freeze).
+During a deploy freeze period, no deployment can be executed. This is helpful to
+ensure that deployments do not happen unexpectedly.
+
+## Troubleshooting
+
+### Pipelines jobs fail with `The deployment job is older than the previously succeeded deployment job...`
+
+This is caused by the [Skip outdated deployment jobs](../pipelines/settings.md#skip-outdated-deployment-jobs) feature.
+If you have multiple jobs for the same environment (including non-deployment jobs), you might encounter this problem, for example:
+
+```yaml
+build:service-a:
+  environment:
+    name: production
+
+build:service-b:
+  environment:
+    name: production
+```
+
+The [Skip outdated deployment jobs](../pipelines/settings.md#skip-outdated-deployment-jobs) might not work well with this configuration, and will need to be disabled.
+
+There is a [plan to introduce a new annotation for environments](https://gitlab.com/gitlab-org/gitlab/-/issues/208655) to address this issue.
diff --git a/doc/ci/environments/environments_dashboard.md b/doc/ci/environments/environments_dashboard.md
index 4a72c0d6d62..e920e0d2400 100644
--- a/doc/ci/environments/environments_dashboard.md
+++ b/doc/ci/environments/environments_dashboard.md
@@ -7,7 +7,7 @@ type: reference
 
 # Environments Dashboard **(PREMIUM)**
 
-> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/3713) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.5.
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3713) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.5.
 
 The Environments Dashboard provides a cross-project
 environment-based view that lets you see the big picture
diff --git a/doc/ci/environments/incremental_rollouts.md b/doc/ci/environments/incremental_rollouts.md
index 016a6ac7cad..5da5c8e0a87 100644
--- a/doc/ci/environments/incremental_rollouts.md
+++ b/doc/ci/environments/incremental_rollouts.md
@@ -1,4 +1,7 @@
 ---
+stage: Release
+group: Progressive Delivery
+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/#designated-technical-writers
 type: concepts, howto
 ---
 
@@ -34,7 +37,7 @@ use as examples to build your own:
 
 ## Manual Rollouts
 
-> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/5415) in GitLab 10.8.
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5415) in GitLab 10.8.
 
 It is possible to configure GitLab to do incremental rollouts manually through `.gitlab-ci.yml`. Manual configuration
 allows more control over the this feature. The steps in an incremental rollout depend on the
@@ -74,7 +77,7 @@ available, demonstrating manually triggered incremental rollouts.
 
 ## Timed Rollouts
 
-> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/7545) in GitLab 11.4.
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7545) in GitLab 11.4.
 
 Timed rollouts behave in the same way as manual rollouts, except that each job is defined with a delay
 in minutes before it will deploy. Clicking on the job will reveal the countdown.
@@ -111,3 +114,26 @@ timed rollout 30%:
 
 A [deployable application](https://gitlab.com/gl-release/timed-rollout-example) is
 available, [demonstrating configuration of timed rollouts](https://gitlab.com/gl-release/timed-rollout-example/blob/master/.gitlab-ci.yml#L86-95).
+
+## Blue-Green Deployment
+
+Also sometimes known as A/B deployment or red-black deployment, this technique is used to reduce
+downtime and risk during a deployment. When combined with incremental rollouts, you can
+minimize the impact of a deployment causing an issue.
+
+With this technique there are two deployments ("blue" and "green", but any naming can be used).
+Only one of these deployments is live at any given time, except during an incremental rollout.
+
+For example, your blue deployment can be currently active on production, while the
+green deployment is "live" for testing, but not deployed to production. If issues
+are found, the green deployment can be updated without affecting the production
+deployment (currently blue). If testing finds no issues, you switch production to the green
+deployment, and blue is now available to test the next release.
+
+This process reduces downtime as there is no need to take down the production deployment
+to switch to a different deployment. Both deployments are running in parallel, and
+can be switched to at any time.
+
+An [example deployable application](https://gitlab.com/gl-release/blue-green-example)
+is available, with a [`gitlab-ci.yml` CI/CD configuration file](https://gitlab.com/gl-release/blue-green-example/blob/master/.gitlab-ci.yml)
+that demonstrates blue-green deployments.
diff --git a/doc/ci/environments/index.md b/doc/ci/environments/index.md
index b6ec30b5571..84480b836f8 100644
--- a/doc/ci/environments/index.md
+++ b/doc/ci/environments/index.md
@@ -162,7 +162,7 @@ Starting with GitLab 9.3, the environment URL is exposed to the Runner via
 
 #### Set dynamic environment URLs after a job finishes
 
-> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/17066) in GitLab 12.9.
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/17066) in GitLab 12.9.
 
 In a job script, you can specify a static [environment URL](#using-the-environment-url).
 However, there may be times when you want a dynamic URL. For example,
@@ -384,7 +384,7 @@ feature.
 
 ### Configuring Kubernetes deployments
 
-> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/27630) in GitLab 12.6.
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27630) in GitLab 12.6.
 
 If you are deploying to a [Kubernetes cluster](../../user/project/clusters/index.md)
 associated with your project, you can configure these deployments from your
@@ -421,7 +421,18 @@ NOTE: **Note:**
 Kubernetes configuration is not supported for Kubernetes clusters
 that are [managed by GitLab](../../user/project/clusters/index.md#gitlab-managed-clusters).
 To follow progress on support for GitLab-managed clusters, see the
-[relevant issue](https://gitlab.com/gitlab-org/gitlab/issues/38054).
+[relevant issue](https://gitlab.com/gitlab-org/gitlab/-/issues/38054).
+
+### Deployment safety
+
+Deployment jobs can be more sensitive than other jobs in a pipeline,
+and might need to be treated with an extra care. There are multiple features
+in GitLab that helps maintain deployment security and stability.
+
+- [Restrict write-access to a critical environment](deployment_safety.md#restrict-write-access-to-a-critical-environment)
+- [Limit the job-concurrency for deployment jobs](deployment_safety.md#ensure-only-one-deployment-job-runs-at-a-time)
+- [Skip outdated deployment jobs](deployment_safety.md#skip-outdated-deployment-jobs)
+- [Restrict deployments for a particular period](deployment_safety.md#restrict-deployments-for-a-particular-period)
 
 ### Complete example
 
@@ -699,11 +710,17 @@ stop action when the associated branch is deleted. The `stop_review` job must
 be in the same `stage` as the `deploy_review` job in order for the environment
 to automatically stop.
 
+Additionally, both jobs should have matching [`rules`](../yaml/README.md#onlyexcept-basic)
+or [`only/except`](../yaml/README.md#onlyexcept-basic) configuration. In the example
+above, if the configuration is not identical, the `stop_review` job might not be
+included in all pipelines that include the `deploy_review` job, and it will not be
+possible to trigger the `action: stop` to stop the environment automatically.
+
 You can read more in the [`.gitlab-ci.yml` reference](../yaml/README.md#environmenton_stop).
 
 #### Environments auto-stop
 
-> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/20956) in GitLab 12.8.
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/20956) in GitLab 12.8.
 
 You can set a expiry time to environments and stop them automatically after a certain period.
 
@@ -849,10 +866,6 @@ versions of the app, all without leaving GitLab.
 
 ![Monitoring dashboard](../img/environments_monitoring.png)
 
-#### Linking to external dashboard
-
-Add a [button to the Monitoring dashboard](../../user/project/operations/linking_to_an_external_dashboard.md) linking directly to your existing external dashboards.
-
 #### Embedding metrics in GitLab Flavored Markdown
 
 Metric charts can be embedded within GitLab Flavored Markdown. See [Embedding Metrics within GitLab Flavored Markdown](../../user/project/integrations/prometheus.md#embedding-metric-charts-within-gitlab-flavored-markdown) for more details.
@@ -912,7 +925,7 @@ fetch = +refs/environments/*:refs/remotes/origin/environments/*
 ### Scoping environments with specs
 
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/2112) in [GitLab Premium](https://about.gitlab.com/pricing/) 9.4.
-> - [Scoping for environment variables was moved to Core](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/30779) to Core in GitLab 12.2.
+> - [Scoping for environment variables was moved to Core](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/30779) in GitLab 12.2.
 
 You can limit the environment scope of a variable by
 defining which environments it can be available for.
diff --git a/doc/ci/environments/protected_environments.md b/doc/ci/environments/protected_environments.md
index 43ac42ea0c7..3a44fcfb182 100644
--- a/doc/ci/environments/protected_environments.md
+++ b/doc/ci/environments/protected_environments.md
@@ -55,6 +55,8 @@ Maintainers can:
   **Allowed to Deploy** dropdown menu.
 - Unprotect a protected environment by clicking the **Unprotect** button for that environment.
 
+For more information, see [Deployment safety](deployment_safety.md).
+
 <!-- ## Troubleshooting
 
 Include any troubleshooting steps that you can foresee. If you know beforehand what issues