Add latest changes from gitlab-org/gitlab@master

24 files changed, 144 insertions, 112 deletions

diff --git a/doc/administration/instance_limits.md b/doc/administration/instance_limits.md
index ef0126a2c17..2742df0ce8d 100644
--- a/doc/administration/instance_limits.md
+++ b/doc/administration/instance_limits.md
@@ -684,7 +684,7 @@ indexed, which have a separate limit. For more information, read
 - For self-managed installations, the field length is unlimited by default.
 
 You can configure this limit for self-managed installations when you
-[enable Elasticsearch](../integration/elasticsearch.md#enabling-advanced-search).
+[enable Elasticsearch](../integration/elasticsearch.md#enable-advanced-search).
 Set the limit to `0` to disable it.
 
 ## Wiki limits
diff --git a/doc/api/scim.md b/doc/api/scim.md
index 42580ba65b6..2d9cc148412 100644
--- a/doc/api/scim.md
+++ b/doc/api/scim.md
@@ -7,7 +7,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 
 # SCIM API (SYSTEM ONLY) **(PREMIUM SAAS)**
 
-> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/9388) in GitLab Premium 11.10.
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/9388) in GitLab 11.10.
 
 The SCIM API implements the [RFC7644 protocol](https://tools.ietf.org/html/rfc7644). As this API is for
 **system** use for SCIM provider integration, it is subject to change without notice.
diff --git a/doc/api/services.md b/doc/api/services.md
index a311814ca0f..cf6c5ec511b 100644
--- a/doc/api/services.md
+++ b/doc/api/services.md
@@ -659,7 +659,7 @@ PUT /projects/:id/services/hangouts-chat
 ```
 
 NOTE:
-Specific event parameters (for example, `push_events` flag) were [introduced in v10.4](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/11435)
+Specific event parameters (for example, `push_events` flag) were [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/11435) in GitLab 10.4.
 
 Parameters:
 
@@ -1119,7 +1119,7 @@ PUT /projects/:id/services/slack
 ```
 
 NOTE:
-Specific event parameters (for example, `push_events` flag and `push_channel`) were [introduced in v10.4](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/11435)
+Specific event parameters (for example, `push_events` flag and `push_channel`) were [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/11435) in GitLab 10.4.
 
 Parameters:
 
@@ -1231,7 +1231,7 @@ PUT /projects/:id/services/mattermost
 ```
 
 NOTE:
-Specific event parameters (for example, `push_events` flag and `push_channel`) were [introduced in v10.4](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/11435)
+Specific event parameters (for example, `push_events` flag and `push_channel`) were [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/11435) in GitLab 10.4.
 
 Parameters:
 
@@ -1365,7 +1365,7 @@ GET /projects/:id/services/jenkins
 A continuous integration and build server
 
 NOTE:
-This service was [removed in v13.0](https://gitlab.com/gitlab-org/gitlab/-/issues/1600)
+This service was [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/1600) in GitLab 13.0.
 
 ### Create/Edit Jenkins CI (Deprecated) service
 
diff --git a/doc/api/settings.md b/doc/api/settings.md
index 4388e9bd646..147bb67a7b7 100644
--- a/doc/api/settings.md
+++ b/doc/api/settings.md
@@ -96,7 +96,7 @@ Example response:
 }
 ```
 
-Users on GitLab [Premium or Ultimate](https://about.gitlab.com/pricing/) may also see
+Users on [GitLab Premium or Ultimate](https://about.gitlab.com/pricing/) may also see
 the `file_template_project_id`, `delayed_project_deletion`, `deletion_adjourned_period`, or the `geo_node_allowed_ips` parameters:
 
 ```json
@@ -197,7 +197,7 @@ Example response:
 }
 ```
 
-Users on GitLab [Premium or Ultimate](https://about.gitlab.com/pricing/) may also see
+Users on [GitLab Premium or Ultimate](https://about.gitlab.com/pricing/) may also see
 these parameters:
 
 - `file_template_project_id`
diff --git a/doc/api/statistics.md b/doc/api/statistics.md
index a57838e6496..75dfa0de705 100644
--- a/doc/api/statistics.md
+++ b/doc/api/statistics.md
@@ -4,7 +4,7 @@ group: Access
 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
 ---
 
-# Application statistics API
+# Application statistics API **(FREE SELF)**
 
 ## Get current application statistics
 
diff --git a/doc/api/status_checks.md b/doc/api/status_checks.md
index 2d4f09e6069..0c72ee37348 100644
--- a/doc/api/status_checks.md
+++ b/doc/api/status_checks.md
@@ -62,7 +62,7 @@ POST /projects/:id/merge_requests/:merge_request_iid/status_check_responses
 NOTE:
 `sha` must be the SHA at the `HEAD` of the merge request's source branch.
 
-## Get project external status checks **(ULTIMATE)**
+## Get project external status checks
 
 You can request information about a project's external status checks using the following endpoint:
 
@@ -97,7 +97,7 @@ GET /projects/:id/external_status_checks
 ]
 ```
 
-## Create external status check **(ULTIMATE)**
+## Create external status check
 
 You can create a new external status check for a project using the following endpoint:
 
@@ -116,7 +116,7 @@ defined external service. This includes confidential merge requests.
 | `external_url`         | string           | yes      | URL of status check resource                   |
 | `protected_branch_ids` | `array<Integer>` | no       | IDs of protected branches to scope the rule by |
 
-## Delete external status check **(ULTIMATE)**
+## Delete external status check
 
 You can delete an external status check for a project using the following endpoint:
 
@@ -129,7 +129,7 @@ DELETE /projects/:id/external_status_checks/:check_id
 | `rule_id`              | integer        | yes      | ID of an status check |
 | `id`                   | integer        | yes      | ID of a project       |
 
-## Update external status check **(ULTIMATE)**
+## Update external status check
 
 You can update an existing external status check for a project using the following endpoint:
 
diff --git a/doc/api/system_hooks.md b/doc/api/system_hooks.md
index 85756107d19..3587016ac6b 100644
--- a/doc/api/system_hooks.md
+++ b/doc/api/system_hooks.md
@@ -4,7 +4,7 @@ group: Integrations
 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
 ---
 
-# System hooks API
+# System hooks API **(FREE SELF)**
 
 All methods require administrator authorization.
 
diff --git a/doc/development/adding_service_component.md b/doc/development/adding_service_component.md
index 503d1b7e55b..f5acf0d26eb 100644
--- a/doc/development/adding_service_component.md
+++ b/doc/development/adding_service_component.md
@@ -47,8 +47,7 @@ Adding a new service follows the same [merge request workflow](contributing/merg
 
 The first iteration should be to add the ability to connect and use the service as an externally installed component. Often this involves providing settings in GitLab to connect to the service, or allow connections from it. And then shipping documentation on how to install and configure the service with GitLab.
 
-NOTE:
-[Elasticsearch](../integration/elasticsearch.md#installing-elasticsearch) is an example of a service that has been integrated this way. And many of the other services, including internal projects like Gitaly, started off as separately installed alternatives.
+[Elasticsearch](../integration/elasticsearch.md#install-elasticsearch) is an example of a service that has been integrated this way. Many of the other services, including internal projects like Gitaly, started off as separately installed alternatives.
 
 **For services that depend on the existing GitLab codebase:**
 
diff --git a/doc/development/background_migrations.md b/doc/development/background_migrations.md
index 123583dc9db..c93b5b448f0 100644
--- a/doc/development/background_migrations.md
+++ b/doc/development/background_migrations.md
@@ -507,3 +507,16 @@ end
 ```
 
 See [`db/post_migrate/20210604070207_retry_backfill_traversal_ids.rb`](https://gitlab.com/gitlab-org/gitlab/blob/master/db/post_migrate/20210604070207_retry_backfill_traversal_ids.rb) for a full example.
+
+### Viewing failure error logs
+
+After running a background migration, if any jobs have failed, you can view the logs in [Kibana](https://log.gprd.gitlab.net/goto/3afc1393447c401d7602c1874793e2f6).
+View the production Sidekiq log and filter for:
+
+- `json.class: BackgroundMigrationWorker`
+- `json.job_status: fail`
+- `json.args: <MyBackgroundMigrationClassName>`
+
+Looking at the `json.error_class`, `json.error_message` and `json.error_backtrace` values may be helpful in understanding why the jobs failed.
+
+Depending on when and how the failure occurred, you may find other helpful information by filtering with `json.class: <MyBackgroundMigrationClassName>`.
diff --git a/doc/development/cascading_settings.md b/doc/development/cascading_settings.md
index f5562206654..0fa0e220ba9 100644
--- a/doc/development/cascading_settings.md
+++ b/doc/development/cascading_settings.md
@@ -41,6 +41,8 @@ Settings are not cascading by default. To define a cascading setting, take the f
     class AddDelayedProjectRemovalCascadingSetting < Gitlab::Database::Migration[1.0]
       include Gitlab::Database::MigrationHelpers::CascadingNamespaceSettings
 
+      enable_lock_retries!
+
       def up
         add_cascading_namespace_setting :delayed_project_removal, :boolean, default: false, null: false
       end
diff --git a/doc/development/elasticsearch.md b/doc/development/elasticsearch.md
index 4b87f1c28f1..6d3388d521f 100644
--- a/doc/development/elasticsearch.md
+++ b/doc/development/elasticsearch.md
@@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 This area is to maintain a compendium of useful information when working with Elasticsearch.
 
 Information on how to enable Elasticsearch and perform the initial indexing is in
-the [Elasticsearch integration documentation](../integration/elasticsearch.md#enabling-advanced-search).
+the [Elasticsearch integration documentation](../integration/elasticsearch.md#enable-advanced-search).
 
 ## Deep Dive
 
diff --git a/doc/development/migration_style_guide.md b/doc/development/migration_style_guide.md
index f6f7cfcdd6c..c0ea4bda003 100644
--- a/doc/development/migration_style_guide.md
+++ b/doc/development/migration_style_guide.md
@@ -219,6 +219,8 @@ In case you need to insert, update, or delete a significant amount of data, you:
 
 ## Migration helpers and versioning
 
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/339115) in GitLab 14.3.
+
 Various helper methods are available for many common patterns in database migrations. Those
 helpers can be found in `Gitlab::Database::MigrationHelpers` and related modules.
 
@@ -240,15 +242,14 @@ class TestMigration < Gitlab::Database::Migration[1.0]
 end
 ```
 
-NOTE:
-It is discouraged to include `Gitlab::Database::MigrationHelpers` directly into a
-migration. Instead, the latest version of `Gitlab::Database::Migration` will expose the latest
+Do not include `Gitlab::Database::MigrationHelpers` directly into a
+migration. Instead, use the latest version of `Gitlab::Database::Migration`, which exposes the latest
 version of migration helpers automatically.
 
-NOTE:
-Migration helpers and versioning are available starting from [14.3](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/68986).
-For merge requests targeting previous stable branches, the old format needs to be used and we continue
-to inherit from `ActiveRecord::Migration[6.1]` instead of `Gitlab::Database::Migration[1.0]` for those.
+Migration helpers and versioning were [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/68986)
+in GitLab 14.3.
+For merge requests targeting previous stable branches, use the old format and still inherit from
+`ActiveRecord::Migration[6.1]` instead of `Gitlab::Database::Migration[1.0]`.
 
 ## Retry mechanism when acquiring database locks
 
diff --git a/doc/development/secure_coding_guidelines.md b/doc/development/secure_coding_guidelines.md
index fc60c1d7d7f..0f13b8ecae9 100644
--- a/doc/development/secure_coding_guidelines.md
+++ b/doc/development/secure_coding_guidelines.md
@@ -295,6 +295,8 @@ The injected client-side code is executed on the victim's browser in the context
 
 Much of the impact is contingent upon the function of the application and the capabilities of the victim's session. For further impact possibilities, please check out [the beef project](https://beefproject.com/).
 
+For a demonstration of the impact on GitLab with a realistic attack scenario, see [this video on the GitLab Unfiltered channel](https://www.youtube.com/watch?v=t4PzHNycoKo) (internal, it requires being logged in with the GitLab Unfiltered account).
+
 ### When to consider?
 
 When user submitted data is included in responses to end users, which is just about anywhere.
diff --git a/doc/development/service_ping/metrics_dictionary.md b/doc/development/service_ping/metrics_dictionary.md
index 56c564ee41a..341f2a875d3 100644
--- a/doc/development/service_ping/metrics_dictionary.md
+++ b/doc/development/service_ping/metrics_dictionary.md
@@ -218,7 +218,7 @@ The [Redis HLL metrics](implement.md#known-events-are-added-automatically-in-ser
 
 A YAML metric definition is required for each metric. A dedicated generator is provided to create metric definitions for Redis HLL events.
 
-The generator takes `category` and `event` arguments, as the root key will be `redis_hll_counters`, and creates two metric definitions for weekly and monthly timeframes:
+The generator takes `category` and `event` arguments, as the root key is `redis_hll_counters`, and creates two metric definitions for weekly and monthly time frames:
 
 ```shell
 bundle exec rails generate gitlab:usage_metric_definition:redis_hll issues i_closed
diff --git a/doc/development/service_ping/metrics_instrumentation.md b/doc/development/service_ping/metrics_instrumentation.md
index 8ad1ae9cce2..6fdbd1eea31 100644
--- a/doc/development/service_ping/metrics_instrumentation.md
+++ b/doc/development/service_ping/metrics_instrumentation.md
@@ -115,13 +115,13 @@ There is support for:
 - [Redis HLL metrics](#redis-hyperloglog-metrics).
 - [Generic metrics](#generic-metrics), which are metrics based on settings or configurations.
 
-Currently, there is no support for:
+There is no support for:
 
 - `add`, `sum`, `histogram` for database metrics.
 
 You can [track the progress to support these](https://gitlab.com/groups/gitlab-org/-/epics/6118).
 
-## Creating a new metric instrumentation class
+## Create a new metric instrumentation class
 
 To create a stub instrumentation for a Service Ping metric, you can use a dedicated [generator](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/generators/gitlab/usage_metric_generator.rb):
 
diff --git a/doc/development/service_ping/metrics_lifecycle.md b/doc/development/service_ping/metrics_lifecycle.md
index 98be22c200e..c0446aece8b 100644
--- a/doc/development/service_ping/metrics_lifecycle.md
+++ b/doc/development/service_ping/metrics_lifecycle.md
@@ -39,7 +39,7 @@ For GitLab 12.6, the metric was changed to filter out archived projects:
 }
 ```
 
-In this scenario all instances running up to GitLab 12.5 continue to report `example_metric`,
+In this scenario, all instances running up to GitLab 12.5 continue to report `example_metric`,
 including all archived projects, while all instances running GitLab 12.6 and higher filters
 out such projects. As Service Ping data is collected from all reporting instances, the
 resulting dataset includes mixed data, which distorts any following business analysis.
diff --git a/doc/development/snowplow/index.md b/doc/development/snowplow/index.md
index a7e41ff1fea..0577df474d9 100644
--- a/doc/development/snowplow/index.md
+++ b/doc/development/snowplow/index.md
@@ -101,7 +101,7 @@ sequenceDiagram
 
 ## Structured event taxonomy
 
-When adding new click events, we should add them in a way that's internally consistent. If we don't, it is very painful to perform analysis across features since each feature captures events differently.
+When adding new click events, we should add them in a way that's internally consistent. If we don't, it is difficult to perform analysis across features because each feature captures events differently.
 
 The current method provides several attributes that are sent on each click event. Please try to follow these guidelines when specifying events to capture:
 
@@ -109,9 +109,9 @@ The current method provides several attributes that are sent on each click event
 | --------- | ------- | -------- | ----------- |
 | category  | text    | true     | The page or backend area of the application. Unless infeasible, please use the Rails page attribute by default in the frontend, and namespace + class name on the backend. |
 | action    | text    | true     | The action the user is taking, or aspect that's being instrumented. The first word should always describe the action or aspect: clicks should be `click`, activations should be `activate`, creations should be `create`, etc. Use underscores to describe what was acted on; for example, activating a form field would be `activate_form_input`. An interface action like clicking on a dropdown would be `click_dropdown`, while a behavior like creating a project record from the backend would be `create_project` |
-| label     | text    | false    | The specific element, or object that's being acted on. This is either the label of the element (e.g. a tab labeled 'Create from template' may be `create_from_template`) or a unique identifier if no text is available (e.g. closing the Groups dropdown in the top navigation bar might be `groups_dropdown_close`), or it could be the name or title attribute of a record being created. |
+| label     | text    | false    | The specific element or object to act on. This can be one of the following: the label of the element (for example, a tab labeled 'Create from template' for `create_from_template`), a unique identifier if no text is available (for example, `groups_dropdown_close` for closing the Groups dropdown in the top bar), or the name or title attribute of a record being created. |
 | property  | text    | false    | Any additional property of the element, or object being acted on. |
-| value     | decimal | false    | Describes a numeric value or something directly related to the event. This could be the value of an input (e.g. `10` when clicking `internal` visibility). |
+| value     | decimal | false    | Describes a numeric value or something directly related to the event. This could be the value of an input. For example, `10` when clicking `internal` visibility. |
 
 ### Examples
 
@@ -156,7 +156,7 @@ LIMIT 20
 
 Snowplow JS adds many [web-specific parameters](https://docs.snowplowanalytics.com/docs/collecting-data/collecting-from-own-applications/snowplow-tracker-protocol/#Web-specific_parameters) to all web events by default.
 
-## Implementing Snowplow JS (Frontend) tracking
+## Implement Snowplow JS (Frontend) tracking
 
 GitLab provides `Tracking`, an interface that wraps the [Snowplow JavaScript Tracker](https://docs.snowplowanalytics.com/docs/collecting-data/collecting-from-own-applications/javascript-trackers/) for tracking custom events. The simplest way to use it is to add `data-` attributes to clickable elements and dropdowns. There is also a Vue mixin (exposing a `track` method), and the static method `Tracking.event`. Each of these requires at minimum a `category` and an `action`. You can provide additional [Structured event taxonomy](#structured-event-taxonomy) properties along with an `extra` object that accepts key-value pairs.
 
@@ -174,7 +174,7 @@ GitLab provides `Tracking`, an interface that wraps the [Snowplow JavaScript Tra
 
 ### Tracking with data attributes
 
-When working within HAML (or Vue templates) we can add `data-track-*` attributes to elements of interest. All elements that have a `data-track-action` attribute automatically have event tracking bound on clicks. You can provide extra data as a valid JSON string using `data-track-extra`.
+When working in HAML (or Vue templates) we can add `data-track-*` attributes to elements of interest. All elements that have a `data-track-action` attribute automatically have event tracking bound on clicks. You can provide extra data as a valid JSON string using `data-track-extra`.
 
 Below is an example of `data-track-*` attributes assigned to a button:
 
@@ -191,7 +191,7 @@ Below is an example of `data-track-*` attributes assigned to a button:
 />
 ```
 
-Event listeners are bound at the document level to handle click events on or within elements with these data attributes. This allows them to be properly handled on re-rendering and changes to the DOM. Note that because of the way these events are bound, click events should not be stopped from propagating up the DOM tree. If for any reason click events are being stopped from propagating, you need to implement your own listeners and follow the instructions in [Tracking within Vue components](#tracking-within-vue-components) or [Tracking in raw JavaScript](#tracking-in-raw-javascript).
+Event listeners are bound at the document level to handle click events on or within elements with these data attributes. This allows them to be properly handled on re-rendering and changes to the DOM. Note that because of the way these events are bound, click events should not be stopped from propagating up the DOM tree. If click events are being stopped from propagating, you must implement your own listeners and follow the instructions in [Tracking within Vue components](#tracking-within-vue-components) or [Tracking in raw JavaScript](#tracking-in-raw-javascript).
 
 Below is a list of supported `data-track-*` attributes:
 
@@ -237,7 +237,7 @@ import Tracking from '~/tracking';
 const trackingMixin = Tracking.mixin({ label: 'right_sidebar' });
 ```
 
-You can provide default options that are passed along whenever an event is tracked from within your component. For instance, if all events within a component should be tracked with a given `label`, you can provide one at this time. Available defaults are `category`, `label`, `property`, and `value`. If no category is specified, `document.body.dataset.page` is used as the default.
+You can provide default options that are passed along whenever an event is tracked from within your component. For example, if all events in a component should be tracked with a given `label`, you can provide one at this time. Available defaults are `category`, `label`, `property`, and `value`. If no category is specified, `document.body.dataset.page` is used as the default.
 
 You can then use the mixin normally in your component with the `mixin` Vue declaration. The mixin also provides the ability to specify tracking options in `data` or `computed`. These override any defaults and allow the values to be dynamic from props, or based on state.
 
@@ -256,7 +256,7 @@ export default {
 };
 ```
 
-The mixin provides a `track` method that can be called within the template,
+The mixin provides a `track` method that can be called from within the template,
 or from component methods. An example of the whole implementation might look like this:
 
 ```javascript
@@ -302,7 +302,7 @@ export default {
 ```
 
 The event data can be provided directly in the `track` function as well.
-This object will merge with any previously provided options.
+This object merges with any previously provided options.
 
 ```javascript
 this.track('click_button', {
@@ -404,7 +404,7 @@ describe('MyTracking', () => {
 
 ### Form tracking
 
-You can enable Snowplow automatic [form tracking](https://docs.snowplowanalytics.com/docs/collecting-data/collecting-from-own-applications/javascript-trackers/javascript-tracker/javascript-tracker-v2/tracking-specific-events/#form-tracking) by calling `Tracking.enableFormTracking` (after the DOM is ready) and providing a `config` object that includes at least one of the following elements:
+Enable Snowplow automatic [form tracking](https://docs.snowplowanalytics.com/docs/collecting-data/collecting-from-own-applications/javascript-trackers/javascript-tracker/javascript-tracker-v2/tracking-specific-events/#form-tracking) by calling `Tracking.enableFormTracking` (after the DOM is ready) and providing a `config` object that includes at least one of the following elements:
 
 - `forms`: determines which forms are tracked, and are identified by the CSS class name.
 - `fields`: determines which fields inside the tracked forms are tracked, and are identified by the field `name`.
@@ -442,7 +442,7 @@ describe('MyFormTracking', () => {
 });
 ```
 
-## Implementing Snowplow Ruby (Backend) tracking
+## Implement Snowplow Ruby (Backend) tracking
 
 GitLab provides `Gitlab::Tracking`, an interface that wraps the [Snowplow Ruby Tracker](https://docs.snowplowanalytics.com/docs/collecting-data/collecting-from-own-applications/ruby-tracker/) for tracking custom events.
 
@@ -485,9 +485,9 @@ https://docs.gitlab.com/ee/development/testing_guide/best_practices.html#test-sn
 
 We use the [AsyncEmitter](https://docs.snowplowanalytics.com/docs/collecting-data/collecting-from-own-applications/ruby-tracker/emitters/#the-asyncemitter-class) when tracking events, which allows for instrumentation calls to be run in a background thread. This is still an active area of development.
 
-## Developing and testing Snowplow
+## Develop and test Snowplow
 
-There are several tools for developing and testing Snowplow Event
+There are several tools for developing and testing a Snowplow event.
 
 | Testing Tool                                 | Frontend Tracking  | Backend Tracking    | Local Development Environment | Production Environment | Production Environment |
 |----------------------------------------------|--------------------|---------------------|-------------------------------|------------------------|------------------------|
@@ -510,7 +510,7 @@ To test frontend events in development:
 
 #### Snowplow Analytics Debugger Chrome Extension
 
-Snowplow Analytics Debugger is a browser extension for testing frontend events. This works on production, staging and local development environments.
+Snowplow Analytics Debugger is a browser extension for testing frontend events. This works on production, staging, and local development environments.
 
 1. Install the [Snowplow Analytics Debugger](https://chrome.google.com/webstore/detail/snowplow-analytics-debugg/jbnlcgeengmijcghameodeaenefieedm) Chrome browser extension.
 1. Open Chrome DevTools to the Snowplow Analytics Debugger tab.
@@ -528,7 +528,7 @@ Snowplow Inspector Chrome Extension is a browser extension for testing frontend
 
 Snowplow Micro is a very small version of a full Snowplow data collection pipeline: small enough that it can be launched by a test suite. Events can be recorded into Snowplow Micro just as they can a full Snowplow pipeline. Micro then exposes an API that can be queried.
 
-Snowplow Micro is a Docker-based solution for testing frontend and backend events in a local development environment. You need to modify GDK using the instructions below to set this up.
+Snowplow Micro is a Docker-based solution for testing frontend and backend events in a local development environment. You must modify GDK using the instructions below to set this up.
 
 - Read [Introducing Snowplow Micro](https://snowplowanalytics.com/blog/2019/07/17/introducing-snowplow-micro/)
 - Look at the [Snowplow Micro repository](https://github.com/snowplow-incubator/snowplow-micro)
@@ -568,14 +568,14 @@ Snowplow Micro is a Docker-based solution for testing frontend and backend event
       formTracking: false,
    ```
 
-1. Update `snowplow_options` in `lib/gitlab/tracking.rb` to add `protocol` and `port`:
+1. Update `options` in `lib/gitlab/tracking.rb` to add `protocol` and `port`:
 
    ```diff
    diff --git a/lib/gitlab/tracking.rb b/lib/gitlab/tracking.rb
    index 618e359211b..e9084623c43 100644
    --- a/lib/gitlab/tracking.rb
    +++ b/lib/gitlab/tracking.rb
-   @@ -41,7 +41,9 @@ def snowplow_options(group)
+   @@ -41,7 +41,9 @@ def options(group)
               cookie_domain: Gitlab::CurrentSettings.snowplow_cookie_domain,
               app_id: Gitlab::CurrentSettings.snowplow_app_id,
               form_tracking: additional_features,
diff --git a/doc/development/snowplow/review_guidelines.md b/doc/development/snowplow/review_guidelines.md
index 285fbc3b44b..8edcbf06a0e 100644
--- a/doc/development/snowplow/review_guidelines.md
+++ b/doc/development/snowplow/review_guidelines.md
@@ -26,7 +26,7 @@ events or touches Snowplow related files.
 #### The merge request **author** should
 
 - For frontend events, when relevant, add a screenshot of the event in
-  the [testing tool](../snowplow/index.md#developing-and-testing-snowplow) used.
+  the [testing tool](../snowplow/index.md#develop-and-test-snowplow) used.
 - For backend events, when relevant, add the output of the
   [Snowplow Micro](index.md#snowplow-mini) good events
   `GET http://localhost:9090/micro/good` (it might be a good idea
@@ -39,5 +39,5 @@ events or touches Snowplow related files.
 - Check the [usage recommendations](../snowplow/index.md#usage-recommendations).
 - Check that the [Event Dictionary](event_dictionary_guide.md) is up-to-date.
 - If needed, check that the events are firing locally using one of the
-[testing tools](../snowplow/index.md#developing-and-testing-snowplow) available.
+[testing tools](../snowplow/index.md#develop-and-test-snowplow) available.
 - Approve the MR, and relabel the MR with `~"product intelligence::approved"`.
diff --git a/doc/development/testing_guide/best_practices.md b/doc/development/testing_guide/best_practices.md
index 937a630f406..cd50849309f 100644
--- a/doc/development/testing_guide/best_practices.md
+++ b/doc/development/testing_guide/best_practices.md
@@ -661,6 +661,12 @@ let_it_be_with_refind(:project) { create(:project) }
 let_it_be(:project, refind: true) { create(:project) }
 ```
 
+Note that `let_it_be` cannot be used with factories that has stubs, such as `allow`.
+The reason is that `let_it_be` happens in a `before(:all)` block, and RSpec does not
+allow stubs in `before(:all)`.
+See this [issue](https://gitlab.com/gitlab-org/gitlab/-/issues/340487) for more details.
+To resolve, use `let`, or change the factory to not use stubs.
+
 ### Time-sensitive tests
 
 [`ActiveSupport::Testing::TimeHelpers`](https://api.rubyonrails.org/v6.0.3.1/classes/ActiveSupport/Testing/TimeHelpers.html)
diff --git a/doc/integration/elasticsearch.md b/doc/integration/elasticsearch.md
index 86bd60f3268..9842881094b 100644
--- a/doc/integration/elasticsearch.md
+++ b/doc/integration/elasticsearch.md
@@ -68,7 +68,7 @@ Keep in mind, these are **minimum requirements** for Elasticsearch.
 Heavily-used Elasticsearch clusters likely require considerably more
 resources.
 
-## Installing Elasticsearch
+## Install Elasticsearch
 
 Elasticsearch is *not* included in the Omnibus packages or when you install from
 source. You must [install it separately](https://www.elastic.co/guide/en/elasticsearch/reference/7.x/install-elasticsearch.html "Elasticsearch 7.x installation documentation").
@@ -81,27 +81,23 @@ it yourself or use a cloud hosted offering like Elastic's [Elasticsearch Service
 service. Running Elasticsearch on the same server as GitLab is not recommended
 and can cause a degradation in GitLab instance performance.
 
-**For a single node Elasticsearch cluster the functional cluster health status
-is yellow** (will never be green) because the primary shard is allocated but
-replicas can not be as there is no other node to which Elasticsearch can assign a
-replica.
+**For a single node Elasticsearch cluster, the functional cluster health status
+is always yellow and never green**. This is due to allocation of the primary shard. Replicas cannot be allocated as there is no other node to which Elasticsearch can assign a replica.
 
 After the data is added to the database or repository and [Elasticsearch is
-enabled in the Admin Area](#enabling-advanced-search) the search index is
+enabled in the Admin Area](#enable-advanced-search), the search index is
 updated automatically.
 
-## Upgrading to a new Elasticsearch major version
+## Upgrade to a new Elasticsearch major version
 
-Since Elasticsearch can read and use indices created in the previous major version, you don't need to change anything in the GitLab configuration when upgrading Elasticsearch.
+Elasticsearch can read and use indices created in the previous major version, so you don't need to change anything in the GitLab configuration when upgrading Elasticsearch.
 
-The only thing worth noting is that if you have created your current index before GitLab 13.0, you might want to reindex from scratch (which implicitly creates an alias) in order to use some features, for example [Zero downtime reindexing](#zero-downtime-reindexing). Once you do that, you are able to perform zero-downtime reindexing and will benefit from any future features that make use of the alias.
+If you created your current index before GitLab 13.0, you might want to reindex from scratch (which implicitly creates an alias) to use some features, for example [Zero downtime reindexing](#zero-downtime-reindexing). After you reindex, you can perform zero-downtime reindexing and benefit from future features that make use of the alias.
 
-If you are unsure when your current index was created,
-you can check whether it was created after GitLab 13.0 by using the
-[Elasticsearch cat aliases API](https://www.elastic.co/guide/en/elasticsearch/reference/7.11/cat-alias.html).
-If the list of aliases returned contains an entry for `gitlab-production` that points to an index
+To check if your current index was created after GitLab 13.0, use the [Elasticsearch cat aliases API](https://www.elastic.co/guide/en/elasticsearch/reference/7.11/cat-alias.html).
+If the returned list of aliases contains an entry for `gitlab-production` that points to an index
 named `gitlab-production-<numerical timestamp>`, your index was created after GitLab 13.0.
-If the `gitlab-production` alias is missing, you need to reindex from scratch to use
+If the `gitlab-production` alias is missing, you must reindex from scratch to use
 features such as Zero-downtime reindexing.
 
 ## Elasticsearch repository indexer
@@ -126,7 +122,7 @@ First, we need to install some dependencies, then we build and install
 the indexer itself.
 
 This project relies on [International Components for Unicode](http://site.icu-project.org/) (ICU) for text encoding,
-therefore we need to ensure the development packages for your platform are
+therefore we must ensure the development packages for your platform are
 installed before running `make`.
 
 #### Debian / Ubuntu
@@ -154,7 +150,7 @@ brew install icu4c
 export PKG_CONFIG_PATH="/usr/local/opt/icu4c/lib/pkgconfig:$PKG_CONFIG_PATH"
 ```
 
-### Building and installing
+### Build and install
 
 To build and install the indexer, run:
 
@@ -166,7 +162,7 @@ sudo -u git -H bundle exec rake gitlab:indexer:install[$indexer_path] RAILS_ENV=
 cd $indexer_path && sudo make install
 ```
 
-The `gitlab-elasticsearch-indexer` will be installed to `/usr/local/bin`.
+The `gitlab-elasticsearch-indexer` is installed to `/usr/local/bin`.
 
 You can change the installation path with the `PREFIX` environment variable.
 Please remember to pass the `-E` flag to `sudo` if you do so.
@@ -177,19 +173,19 @@ Example:
 PREFIX=/usr sudo -E make install
 ```
 
-After installation, be sure to [enable Elasticsearch](#enabling-advanced-search).
+After installation, be sure to [enable Elasticsearch](#enable-advanced-search).
 
 NOTE:
 If you see an error such as `Permission denied - /home/git/gitlab-elasticsearch-indexer/` while indexing, you
 may need to set the `production -> elasticsearch -> indexer_path` setting in your `gitlab.yml` file to
 `/usr/local/bin/gitlab-elasticsearch-indexer`, which is where the binary is installed.
 
-## Enabling Advanced Search
+## Enable Advanced Search
 
 For GitLab instances with more than 50GB repository data you can follow the instructions for [Indexing large
 instances](#indexing-large-instances) below.
 
-To enable Advanced Search, you need to have admin access to GitLab:
+To enable Advanced Search, you must have admin access to GitLab:
 
 1. On the top bar, select **Menu > Admin**.
 1. On the left sidebar, select **Settings > Advanced Search**.
@@ -206,7 +202,7 @@ To enable Advanced Search, you need to have admin access to GitLab:
 1. Select **Index all projects**.
 1. Select **Check progress** in the confirmation message to see the status of
    the background jobs.
-1. Personal snippets need to be indexed using another Rake task:
+1. Personal snippets must be indexed using another Rake task:
 
    ```shell
    # Omnibus installations
@@ -216,7 +212,7 @@ To enable Advanced Search, you need to have admin access to GitLab:
    bundle exec rake gitlab:elastic:index_snippets RAILS_ENV=production
    ```
 
-1. After the indexing has completed, enable **Search with Elasticsearch enabled** and select **Save changes**.
+1. After indexing completes, enable **Search with Elasticsearch enabled** and select **Save changes**.
 
 NOTE:
 When your Elasticsearch cluster is down while Elasticsearch is enabled,
@@ -237,8 +233,8 @@ The following Elasticsearch settings are available:
 | `Username`                                                 | The `username` of your Elasticsearch instance. |
 | `Password`                                                 | The password of your Elasticsearch instance. |
 | `Number of Elasticsearch shards`                      | Elasticsearch indexes are split into multiple shards for performance reasons. In general, you should use at least 5 shards, and indexes with tens of millions of documents need to have more shards ([see below](#guidance-on-choosing-optimal-cluster-configuration)). Changes to this value do not take effect until the index is recreated. You can read more about tradeoffs in the [Elasticsearch documentation](https://www.elastic.co/guide/en/elasticsearch/reference/current/scalability.html). |
-| `Number of Elasticsearch replicas`                    | Each Elasticsearch shard can have a number of replicas. These are a complete copy of the shard, and can provide increased query performance or resilience against hardware failure. Increasing this value will greatly increase total disk space required by the index. |
-| `Limit namespaces and projects that can be indexed`   | Enabling this will allow you to select namespaces and projects to index. All other namespaces and projects will use database search instead. If you enable this option but do not select any namespaces or projects, none will be indexed. [Read more below](#limiting-namespaces-and-projects).
+| `Number of Elasticsearch replicas`                    | Each Elasticsearch shard can have a number of replicas. These are a complete copy of the shard, and can provide increased query performance or resilience against hardware failure. Increasing this value increases total disk space required by the index. |
+| `Limit namespaces and projects that can be indexed`   | Enabling this allows you to select namespaces and projects to index. All other namespaces and projects use database search instead. If you enable this option but do not select any namespaces or projects, none will be indexed. [Read more below](#limit-namespaces-and-projects).
 | `Using AWS hosted Elasticsearch with IAM credentials` | Sign your Elasticsearch requests using [AWS IAM authorization](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html), [AWS EC2 Instance Profile Credentials](https://docs.aws.amazon.com/codedeploy/latest/userguide/getting-started-create-iam-instance-profile.html#getting-started-create-iam-instance-profile-cli), or [AWS ECS Tasks Credentials](https://docs.aws.amazon.com/AmazonECS/latest/userguide/task-iam-roles.html). Please refer to [Identity and Access Management in Amazon Elasticsearch Service](https://docs.aws.amazon.com/elasticsearch-service/latest/developerguide/es-ac.html) for details of AWS hosted Elasticsearch domain access policy configuration. |
 | `AWS Region`                                          | The AWS region in which your Elasticsearch service is located. |
 | `AWS Access Key`                                      | The AWS access key. |
@@ -255,31 +251,31 @@ Sidekiq performance. Return them to their default values if you see increased `s
 in your Sidekiq logs. For more information, see
 [issue 322147](https://gitlab.com/gitlab-org/gitlab/-/issues/322147).
 
-### Limiting namespaces and projects
+### Limit namespaces and projects
 
-If you select `Limit namespaces and projects that can be indexed`, more options will become available.
+If you select `Limit namespaces and projects that can be indexed`, more options become available.
 
 ![limit namespaces and projects options](img/limit_namespaces_projects_options.png)
 
-You can select namespaces and projects to index exclusively. Note that if the namespace is a group it will include
+You can select namespaces and projects to index exclusively. Note that if the namespace is a group, it includes
 any subgroups and projects belonging to those subgroups to be indexed as well.
 
-Advanced Search only provides cross-group code/commit search (global) if all name-spaces are indexed. In this particular scenario where only a subset of namespaces are indexed, a global search will not provide a code or commit scope. This will be possible only in the scope of an indexed namespace. Currently there is no way to code/commit search in multiple indexed namespaces (when only a subset of namespaces has been indexed). For example if two groups are indexed, there is no way to run a single code search on both. You can only run a code search on the first group and then on the second.
+Advanced Search only provides cross-group code/commit search (global) if all name-spaces are indexed. In this particular scenario where only a subset of namespaces are indexed, a global search will not provide a code or commit scope. This is possible only in the scope of an indexed namespace. There is no way to code/commit search in multiple indexed namespaces (when only a subset of namespaces has been indexed). For example if two groups are indexed, there is no way to run a single code search on both. You can only run a code search on the first group and then on the second.
 
 You can filter the selection dropdown by writing part of the namespace or project name you're interested in.
 
 ![limit namespace filter](img/limit_namespace_filter.png)
 
 NOTE:
-If no namespaces or projects are selected, no Advanced Search indexing will take place.
+If no namespaces or projects are selected, no Advanced Search indexing takes place.
 
 WARNING:
-If you have already indexed your instance, you will have to regenerate the index in order to delete all existing data
-for filtering to work correctly. To do this run the Rake tasks `gitlab:elastic:recreate_index` and
-`gitlab:elastic:clear_index_status`. Afterwards, removing a namespace or a project from the list will delete the data
+If you have already indexed your instance, you must regenerate the index to delete all existing data
+for filtering to work correctly. To do this, run the Rake tasks `gitlab:elastic:recreate_index` and
+`gitlab:elastic:clear_index_status`. Afterwards, removing a namespace or a project from the list deletes the data
 from the Elasticsearch index as expected.
 
-## Enabling custom language analyzers
+## Enable custom language analyzers
 
 You can improve the language support for Chinese and Japanese languages by utilizing [`smartcn`](https://www.elastic.co/guide/en/elasticsearch/plugins/current/analysis-smartcn.html) and/or [`kuromoji`](https://www.elastic.co/guide/en/elasticsearch/plugins/current/analysis-kuromoji.html) analysis plugins from Elastic.
 
@@ -303,7 +299,7 @@ For guidance on what to install, see the following Elasticsearch language plugin
 | `Enable Japanese (kuromoji) custom analyzer: Indexing`   | Enables or disables Japanese language support using [`kuromoji`](https://www.elastic.co/guide/en/elasticsearch/plugins/current/analysis-kuromoji.html) custom analyzer for newly created indices.|
 | `Enable Japanese (kuromoji) custom analyzer: Search`  | Enables or disables using [`kuromoji`](https://www.elastic.co/guide/en/elasticsearch/plugins/current/analysis-kuromoji.html) fields for Advanced Search. Please only enable this after [installing the plugin](https://www.elastic.co/guide/en/elasticsearch/plugins/current/analysis-kuromoji.html), enabling custom analyzer indexing and recreating the index.|
 
-## Disabling Advanced Search
+## Disable Advanced Search
 
 To disable the Elasticsearch integration:
 
@@ -327,7 +323,7 @@ The idea behind this reindexing method is to leverage the [Elasticsearch reindex
 and Elasticsearch index alias feature to perform the operation. We set up an index alias which connects to a
 `primary` index which is used by GitLab for reads/writes. When reindexing process starts, we temporarily pause
 the writes to the `primary` index. Then, we create another index and invoke the Reindex API which migrates the
-index data onto the new index. Once the reindexing job is complete, we switch to the new index by connecting the
+index data onto the new index. After the reindexing job is complete, we switch to the new index by connecting the
 index alias to it which becomes the new `primary` index. At the end, we resume the writes and normal operation resumes.
 
 ### Trigger the reindex via the Advanced Search administration
@@ -350,7 +346,7 @@ After this process is completed, the original index is scheduled to be deleted a
 14 days. You can cancel this action by pressing the **Cancel** button on the same
 page you triggered the reindexing process.
 
-While the reindexing is running, you will be able to follow its progress under that same section.
+While the reindexing is running, you can follow its progress under that same section.
 
 #### Elasticsearch zero-downtime reindexing
 
@@ -486,8 +482,8 @@ version](../update/index.md#upgrading-to-a-new-major-version).
 
 Rake tasks are available to:
 
-- [Build and install](#building-and-installing) the indexer.
-- Delete indexes when [disabling Elasticsearch](#disabling-advanced-search).
+- [Build and install](#build-and-install) the indexer.
+- Delete indexes when [disabling Elasticsearch](#disable-advanced-search).
 - Add GitLab data to an index.
 
 The following are some available Rake tasks:
@@ -573,7 +569,7 @@ For basic guidance on choosing a cluster configuration you may refer to [Elastic
 ### Indexing large instances
 
 This section may be helpful in the event that the other
-[basic instructions](#enabling-advanced-search) cause problems
+[basic instructions](#enable-advanced-search) cause problems
 due to large volumes of data being indexed.
 
 WARNING:
@@ -582,7 +578,7 @@ Make sure to prepare for this task by having a [Scalable and Highly Available
 Setup](../administration/reference_architectures/index.md) or creating [extra
 Sidekiq processes](../administration/operations/extra_sidekiq_processes.md).
 
-1. [Configure your Elasticsearch host and port](#enabling-advanced-search).
+1. [Configure your Elasticsearch host and port](#enable-advanced-search).
 1. Create empty indexes:
 
    ```shell
@@ -603,7 +599,7 @@ Sidekiq processes](../administration/operations/extra_sidekiq_processes.md).
    bundle exec rake gitlab:elastic:clear_index_status RAILS_ENV=production
    ```
 
-1. [Enable **Elasticsearch indexing**](#enabling-advanced-search).
+1. [Enable **Elasticsearch indexing**](#enable-advanced-search).
 1. Indexing large Git repositories can take a while. To speed up the process, you can [tune for indexing speed](https://www.elastic.co/guide/en/elasticsearch/reference/current/tune-for-indexing-speed.html#tune-for-indexing-speed):
 
    - You can temporarily disable [`refresh`](https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-refresh.html), the operation responsible for making changes to an index available to search.
@@ -734,7 +730,7 @@ Sidekiq processes](../administration/operations/extra_sidekiq_processes.md).
           } }'
    ```
 
-1. After the indexing has completed, enable [**Search with Elasticsearch enabled**](#enabling-advanced-search).
+1. After the indexing has completed, enable [**Search with Elasticsearch enabled**](#enable-advanced-search).
 
 ### Deleted documents
 
@@ -836,7 +832,7 @@ be necessary for you to [reindex](#zero-downtime-reindexing) after updating GitL
 
 ### I indexed all the repositories but I can't get any hits for my search term in the UI
 
-Make sure you indexed all the database data [as stated above](#enabling-advanced-search).
+Make sure you indexed all the database data [as stated above](#enable-advanced-search).
 
 If there aren't any results (hits) in the UI search, check if you are seeing the same results via the rails console (`sudo gitlab-rails console`):
 
@@ -857,7 +853,7 @@ More [complex Elasticsearch API calls](https://www.elastic.co/guide/en/elasticse
 It is important to understand at which level the problem is manifesting (UI, Rails code, Elasticsearch side) to be able to [troubleshoot further](../administration/troubleshooting/elasticsearch.md#search-results-workflow).
 
 NOTE:
-The above instructions are not to be used for scenarios that only index a [subset of namespaces](#limiting-namespaces-and-projects).
+The above instructions are not to be used for scenarios that only index a [subset of namespaces](#limit-namespaces-and-projects).
 
 See [Elasticsearch Index Scopes](#advanced-search-index-scopes) for more information on searching for specific types of data.
 
@@ -953,7 +949,7 @@ Gitlab::Elastic::Indexer::Error: time="2020-01-23T09:13:00Z" level=fatal msg="he
 ```
 
 You probably have not used either `http://` or `https://` as part of your value in the **"URL"** field of the Elasticsearch Integration Menu. Please make sure you are using either `http://` or `https://` in this field as the [Elasticsearch client for Go](https://github.com/olivere/elastic) that we are using [needs the prefix for the URL to be accepted as valid](https://github.com/olivere/elastic/commit/a80af35aa41856dc2c986204e2b64eab81ccac3a).
-Once you have corrected the formatting of the URL, delete the index (via the [dedicated Rake task](#gitlab-advanced-search-rake-tasks)) and [reindex the content of your instance](#enabling-advanced-search).
+Once you have corrected the formatting of the URL, delete the index (via the [dedicated Rake task](#gitlab-advanced-search-rake-tasks)) and [reindex the content of your instance](#enable-advanced-search).
 
 ### My Elasticsearch cluster has a plugin and the integration is not working
 
diff --git a/doc/update/patch_versions.md b/doc/update/patch_versions.md
index 0a7057ffe97..d09f19d143b 100644
--- a/doc/update/patch_versions.md
+++ b/doc/update/patch_versions.md
@@ -103,7 +103,7 @@ sudo -u git -H make
 
 ### 8. Install/Update `gitlab-elasticsearch-indexer` **(PREMIUM SELF)**
 
-Please follow the [install instruction](../integration/elasticsearch.md#installing-elasticsearch).
+Please follow the [install instruction](../integration/elasticsearch.md#install-elasticsearch).
 
 ### 9. Start application
 
diff --git a/doc/update/upgrading_from_ce_to_ee.md b/doc/update/upgrading_from_ce_to_ee.md
index 93c9432f6d3..d91b3de6df1 100644
--- a/doc/update/upgrading_from_ce_to_ee.md
+++ b/doc/update/upgrading_from_ce_to_ee.md
@@ -88,7 +88,7 @@ sudo -u git -H bundle exec rake cache:clear RAILS_ENV=production
 
 ### 4. Install `gitlab-elasticsearch-indexer` **(PREMIUM SELF)**
 
-Please follow the [install instruction](../integration/elasticsearch.md#installing-elasticsearch).
+Please follow the [install instruction](../integration/elasticsearch.md#install-elasticsearch).
 
 ### 5. Start application
 
diff --git a/doc/user/admin_area/settings/index.md b/doc/user/admin_area/settings/index.md
index 78c1e01c33b..e1c806bed3a 100644
--- a/doc/user/admin_area/settings/index.md
+++ b/doc/user/admin_area/settings/index.md
@@ -37,7 +37,7 @@ To access the default page for Admin Area settings:
 
 | Option | Description |
 | ------ | ----------- |
-| [Elasticsearch](../../../integration/elasticsearch.md#enabling-advanced-search) | Elasticsearch integration. Elasticsearch AWS IAM. |
+| [Elasticsearch](../../../integration/elasticsearch.md#enable-advanced-search) | Elasticsearch integration. Elasticsearch AWS IAM. |
 | [Kroki](../../../administration/integration/kroki.md#enable-kroki-in-gitlab) | Allow rendering of diagrams in AsciiDoc and Markdown documents using [kroki.io](https://kroki.io). |
 | [Mailgun](../../../administration/integration/mailgun.md) | Enable your GitLab instance to receive invite email bounce events from Mailgun, if it is your email provider. |
 | [PlantUML](../../../administration/integration/plantuml.md) | Allow rendering of PlantUML diagrams in documents. |
diff --git a/doc/user/clusters/agent/ci_cd_tunnel.md b/doc/user/clusters/agent/ci_cd_tunnel.md
index 09123fdd472..023affe43d4 100644
--- a/doc/user/clusters/agent/ci_cd_tunnel.md
+++ b/doc/user/clusters/agent/ci_cd_tunnel.md
@@ -4,40 +4,53 @@ 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
 ---
 
-# CI/CD Tunnel
+# CI/CD Tunnel **(PREMIUM)**
 
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/327409) in GitLab 14.1.
-> - Pre-configured `KUBECONFIG` [added](https://gitlab.com/gitlab-org/gitlab/-/issues/324275) in GitLab 14.2.
+> - The pre-configured `KUBECONFIG` was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/324275) in GitLab 14.2.
 
 The CI/CD Tunnel enables users to access Kubernetes clusters from GitLab CI/CD jobs even if there is no network
 connectivity between GitLab Runner and a cluster. GitLab Runner does not have to be running in the same cluster.
 
 Only CI/CD jobs set in the configuration project can access one of the configured agents.
 
-Prerequisites:
+## Prerequisites
 
 - A running [`kas` instance](index.md#set-up-the-kubernetes-agent-server).
 - A [configuration repository](index.md#define-a-configuration-repository) with an Agent config file
   installed (`.gitlab/agents/<agent-name>/config.yaml`).
 - An [Agent record](index.md#create-an-agent-record-in-gitlab).
-- The agent is [installed in the cluster](index.md#install-the-agent-into-the-cluster).
+- The Agent [installed in the cluster](index.md#install-the-agent-into-the-cluster).
 
-If your project has one or more Agent records, a `KUBECONFIG` variable that is compatible with `kubectl` is provided to your CI/CD jobs. A separate context (`kubecontext`) is available for each configured Agent. By default, no context is selected.
+## Use the CI/CD Tunnel to run Kubernetes commands from GitLab CI/CD
+
+If your project has access to one or more Agent records available, its CI/CD
+jobs provide a `KUBECONFIG` variable compatible with `kubectl`.
+
+Also, each Agent has a separate context (`kubecontext`). By default,
+there isn't any context selected.
 
 Contexts are named in the following format: `<agent-configuration-project-path>:<agent-name>`.
 
-To access your cluster from a CI/CD job through the tunnel:
+You can get the list of available contexts by running `kubectl config get-contexts`.
+
+## Example for a `kubectl` command using the CI/CD Tunnel
+
+The following example shows a CI/CD job that runs a `kubectl` command using the CI/CD Tunnel.
+You can run any Kubernetes-specific commands similarly, such as `kubectl`, `helm`,
+`kpt`, and so on. To do so:
 
-1. In your `.gitlab-ci.yml` select the context for the agent you wish to use:
+1. Set your Agent's context in the first command with the format `<agent-configuration-project-path>:<agent-name>`.
+1. Run Kubernetes commands.
 
-   ```yaml
-   deploy:
-     image:
-       name: bitnami/kubectl:latest
-       entrypoint: [""]
-     script:
-     - kubectl config use-context path/to/agent-configuration-project:your-agent-name
-     - kubectl get pods
-   ```
+For example:
 
-1. Execute `kubectl` commands directly against your cluster with this CI/CD job you just created.
+```yaml
+ deploy:
+   image:
+     name: bitnami/kubectl:latest
+     entrypoint: [""]
+   script:
+   - kubectl config use-context path/to/agent-configuration-project:your-agent-name
+   - kubectl get pods
+```