Merge branch 'selhorn-environs-6' into 'master'

More vale and other edits

See merge request gitlab-org/gitlab!58609

doc/ci/environments/index.md

@@ -125,25 +125,24 @@ For more information about the `environment` keywords, see
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/300741) in GitLab 13.10.
 
-There are cases where you might want to use a code name as an environment name instead of using
-an [industry standard](https://en.wikipedia.org/wiki/Deployment_environment). For example, your environment might be called `customer-portal` instead of `production`.
-This is perfectly fine, however, it loses information that the specific
-environment is used as production.
-
-To keep information that a specific environment is for production or
-some other use, you can set one of the following tiers to each environment:
-
-| Environment tier           | Environment names examples                                |
-| ----           | --------                                |
-| `production`   | Production, Live                        |
-| `staging`      | Staging, Model, Pre, Demo               |
-| `testing`      | Test, QC                                |
-| `development`  | Dev, [Review apps](../review_apps/index.md), Trunk |
-| `other`        |                                         |
-
-By default, an approximate tier is automatically guessed and set from [the environment name](../yaml/README.md#environmentname).
-Alternatively, you can specify a specific tier with `deployment_tier` keyword,
-see the [`.gitlab-ci.yml` syntax reference](../yaml/README.md#environmentdeployment_tier) for more details.
+Sometimes, instead of using an [industry standard](https://en.wikipedia.org/wiki/Deployment_environment)
+environment name, like `production`, you might want to use a code name, like `customer-portal`.
+While there is no technical reason not to use a name like `customer-portal`, the name
+no longer indicates that the environment is used for production.
+
+To indicate that a specific environment is for a specific use,
+you can use tiers:
+
+| Environment tier | Environment name examples                          |
+|------------------|----------------------------------------------------|
+| `production`     | Production, Live                                   |
+| `staging`        | Staging, Model, Pre, Demo                          |
+| `testing`        | Test, QC                                           |
+| `development`    | Dev, [Review apps](../review_apps/index.md), Trunk |
+| `other`          |                                                    |
+
+By default, GitLab assumes a tier based on [the environment name](../yaml/README.md#environmentname).
+Instead, you can use the [`deployment_tier` keyword](../yaml/README.md#environmentdeployment_tier) to specify a tier.
 
 ## Configure manual deployments
 
@@ -206,8 +205,8 @@ deploy:
 ```
 
 When you use the GitLab Kubernetes integration to deploy to a Kubernetes cluster,
-cluster and namespace information is displayed above the job
-trace on the deployment job page:
+you can view cluster and namespace information. On the deployment
+job page, it's displayed above the job trace:
 
 ![Deployment cluster information](../img/environments_deployment_cluster_v12_8.png)
 
@@ -259,7 +258,7 @@ For an overview, see [Set dynamic URLs after a job finished](https://youtu.be/70
 ### Example of setting dynamic environment URLs
 
 The following example shows a Review App that creates a new environment
-per merge request. The `review` job is triggered by every push, and
+for each merge request. The `review` job is triggered by every push, and
 creates or updates an environment named `review/your-branch-name`.
 The environment URL is set to `$DYNAMIC_ENVIRONMENT_URL`:
 
@@ -347,7 +346,7 @@ places in GitLab:
 
 You can see this information in a merge request if:
 
-- The merge request is eventually merged to the default branch (usually `master`).
+- The merge request is eventually merged to the default branch (usually `main`).
 - That branch also deploys to an environment (for example, `staging` or `production`).
 
 For example:
@@ -430,7 +429,7 @@ Due to resource limitations, a background worker for stopping environments only
 every hour. This means that environments aren't stopped at the exact timestamp specified, but are
 instead stopped when the hourly cron worker detects expired environments.
 
-In the following example, each merge request creates a new Review App environment.
+In the following example, each merge request creates a Review App environment.
 Each push triggers the `review_app` job and an environment named `review/your-branch-name`
 is created or updated. The environment runs until `stop_review_app` is executed:
 
@@ -477,7 +476,7 @@ You can manually override a deployment's expiration date.
 
 1. Go to the project's **Operations > Environments** page.
 1. Select the deployment name.
-1. In the top right, select the thumbtack (**{thumbtack}**).
+1. On the top right, select the thumbtack (**{thumbtack}**).
 
 ![Environment auto stop](img/environment_auto_stop_v13_10.png)
 
@@ -501,7 +500,7 @@ To delete a stopped environment in the GitLab UI:
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/208655) in GitLab 13.2.
 
-By default, whenever GitLab CI/CD runs a job for a specific environment, it
+By default, when GitLab CI/CD runs a job for a specific environment, it
 triggers a deployment and [(optionally) cancels outdated
 deployments](deployment_safety.md#ensure-only-one-deployment-job-runs-at-a-time).
 
@@ -525,8 +524,6 @@ and can be used to [protect builds from unauthorized access](protected_environme
 
 ### Group similar environments
 
-> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/7015) in GitLab 8.14.
-
 You can group environments into collapsible sections in the UI.
 
 For example, if all of your environments start with the name `review`,
@@ -548,10 +545,9 @@ deploy_review:
 
 ### Environment incident management
 
-You have successfully setup a Continuous Delivery/Deployment workflow in your project.
 Production environments can go down unexpectedly, including for reasons outside
-of your own control. For example, issues with external dependencies, infrastructure,
-or human error can cause major issues with an environment. This could include:
+of your control. For example, issues with external dependencies, infrastructure,
+or human error can cause major issues with an environment. Things like:
 
 - A dependent cloud service goes down.
 - A 3rd party library is updated and it's not compatible with your application.
@@ -573,7 +569,7 @@ severity is shown, so you can identify which environments need immediate attenti
 ![Environment alert](img/alert_for_environment.png)
 
 When the issue that triggered the alert is resolved, it is removed and is no
-longer visible on the environment page.
+longer visible on the environments page.
 
 If the alert requires a [rollback](#retry-or-roll-back-a-deployment), you can select the
 deployment tab from the environment page and select which deployment to roll back to.
@@ -585,7 +581,7 @@ deployment tab from the environment page and select which deployment to roll bac
 In a typical Continuous Deployment workflow, the CI pipeline tests every commit before deploying to
 production. However, problematic code can still make it to production. For example, inefficient code
 that is logically correct can pass tests even though it causes severe performance degradation.
-Operators and SREs monitor the system to catch such problems as soon as possible. If they find a
+Operators and SREs monitor the system to catch these problems as soon as possible. If they find a
 problematic deployment, they can roll back to a previous stable version.
 
 GitLab Auto Rollback eases this workflow by automatically triggering a rollback when a
@@ -600,54 +596,49 @@ Limitations of GitLab Auto Rollback:
 
 GitLab Auto Rollback is turned off by default. To turn it on:
 
-1. Visit **Project > Settings > CI/CD > Automatic deployment rollbacks**.
+1. Go to **Project > Settings > CI/CD > Automatic deployment rollbacks**.
 1. Select the checkbox for **Enable automatic rollbacks**.
-1. Click **Save changes**.
+1. Select **Save changes**.
 
 ### Monitoring environments
 
-If you have enabled [Prometheus for monitoring system and response metrics](../../user/project/integrations/prometheus.md),
-you can monitor the behavior of your app running in each environment. For the monitoring
-dashboard to appear, you need to Configure Prometheus to collect at least one
+To monitor the behavior of your app as it runs in each environment,
+enable [Prometheus for monitoring system and response metrics](../../user/project/integrations/prometheus.md).
+For the monitoring dashboard to appear, configure Prometheus to collect at least one
 [supported metric](../../user/project/integrations/prometheus_library/index.md).
 
-In GitLab 9.2 and later, all deployments to an environment are shown directly on the monitoring dashboard.
+All deployments to an environment are shown on the monitoring dashboard.
+You can view changes in performance for each version of your application.
 
-Once configured, GitLab attempts to retrieve [supported performance metrics](../../user/project/integrations/prometheus_library/index.md)
+GitLab attempts to retrieve [supported performance metrics](../../user/project/integrations/prometheus_library/index.md)
 for any environment that has had a successful deployment. If monitoring data was
 successfully retrieved, a **Monitoring** button appears for each environment.
 
-Clicking the **Monitoring** button displays a new page showing up to the last
-8 hours of performance data. It may take a minute or two for data to appear
-after initial deployment.
-
-All deployments to an environment are shown directly on the monitoring dashboard,
-which allows easy correlation between any changes in performance and new
-versions of the app, all without leaving GitLab.
+To view the last eight hours of performance data, select the **Monitoring** button.
+It may take a minute or two for data to appear after initial deployment.
 
 ![Monitoring dashboard](../img/environments_monitoring.png)
 
 #### Embedding metrics in GitLab Flavored Markdown
 
-Metric charts can be embedded within GitLab Flavored Markdown. See [Embedding Metrics within GitLab Flavored Markdown](../../operations/metrics/embed.md) for more details.
+Metric charts can be embedded in GitLab Flavored Markdown. See [Embedding Metrics in GitLab Flavored Markdown](../../operations/metrics/embed.md) for more details.
 
 ### Web terminals
 
-> Web terminals were added in GitLab 8.15 and are only available to project Maintainers and Owners.
-
 If you deploy to your environments with the help of a deployment service (for example,
 the [Kubernetes integration](../../user/project/clusters/index.md)), GitLab can open
-a terminal session to your environment.
+a terminal session to your environment. You can then debug issues without leaving your web browser.
+
+The Web terminal is a container-based deployment, which often lack basic tools (like an editor),
+and can be stopped or restarted at any time. If this happens, you lose all your
+changes. Treat the Web terminal as a debugging tool, not a comprehensive online IDE.
 
-This is a powerful feature that allows you to debug issues without leaving the comfort
-of your web browser. To enable it, follow the instructions given in the service integration
-documentation.
+Web terminals:
 
-Note that container-based deployments often lack basic tools (like an editor), and may
-be stopped or restarted at any time. If this happens, you lose all your
-changes. Treat this as a debugging tool, not a comprehensive online IDE.
+- Are available to project Maintainers and Owners only.
+- Must [be enabled](../../administration/integration/terminal.md).
 
-Once enabled, your environments display a **Terminal** button:
+In the UI, you can view the Web terminal by selecting a **Terminal** button:
 
 ![Terminal button on environment index](img/environments_terminal_button_on_index_v13_10.png)
 
@@ -655,8 +646,7 @@ You can also access the terminal button from the page for a specific environment
 
 ![Terminal button for an environment](img/environments_terminal_button_on_show_v13_10.png)
 
-Wherever you find it, clicking the button takes you to a separate page to
-establish the terminal session:
+Select the button to establish the terminal session:
 
 ![Terminal page](../img/environments_terminal_page.png)
 
@@ -665,14 +655,14 @@ by your deployment so you can:
 
 - Run shell commands and get responses in real time.
 - Check the logs.
-- Try out configuration or code tweaks etc.
+- Try out configuration or code tweaks.
 
-You can open multiple terminals to the same environment, they each get their own shell
+You can open multiple terminals to the same environment. They each get their own shell
 session and even a multiplexer like `screen` or `tmux`.
 
 ### Check out deployments locally
 
-In GitLab 8.13 and later, a reference in the Git repository is saved for each deployment, so
+A reference in the Git repository is saved for each deployment, so
 knowing the state of your current environments is only a `git fetch` away.
 
 In your Git configuration, append the `[remote "<your-remote>"]` block with an extra
@@ -689,24 +679,23 @@ fetch = +refs/environments/*:refs/remotes/origin/environments/*
 
 You can limit the environment scope of a CI/CD variable by
 defining which environments it can be available for.
+For example, if the environment scope is `production`, then only the jobs
+with the environment `production` defined would have this specific variable.
 
-Wildcards can be used and the default environment scope is `*`. This means that
-any jobs can have this variable regardless of whether an environment is defined.
+The default environment scope is a wildcard (`*`), which means that
+any job can have this variable, regardless of whether an environment is defined.
 
-For example, if the environment scope is `production`, then only the jobs
-having the environment `production` defined would have this specific variable.
-Wildcards (`*`) can be used along with the environment name, therefore if the
-environment scope is `review/*` then any jobs with environment names starting
-with `review/` would have that particular variable.
+If the environment scope is `review/*`, then jobs with environment names starting
+with `review/` would have that variable available.
 
 Some GitLab features can behave differently for each environment.
 For example, you can
 [create a secret variable to be injected only into a production environment](../variables/README.md#limit-the-environment-scopes-of-cicd-variables).
 
 In most cases, these features use the _environment specs_ mechanism, which offers
-an efficient way to implement scoping within each environment group.
+an efficient way to implement scoping in each environment group.
 
-Let's say there are four environments:
+For example, if there are four environments:
 
 - `production`
 - `staging`
@@ -723,11 +712,11 @@ Each environment can be matched with the following environment spec:
 | review/*         |              |           | Matched            | Matched            |
 | review/feature-1 |              |           | Matched            |                    |
 
-As you can see, you can use specific matching for selecting a particular environment,
-and also use wildcard matching (`*`) for selecting a particular environment group,
-such as [Review Apps](../review_apps/index.md) (`review/*`).
+You can use specific matching to select a particular environment.
+You can also use wildcard matching (`*`) to select a particular environment group,
+like [Review Apps](../review_apps/index.md) (`review/*`).
 
-Note that the most _specific_ spec takes precedence over the other wildcard matching. In this case,
+The most specific spec takes precedence over the other wildcard matching. In this case,
 the `review/feature-1` spec takes precedence over `review/*` and `*` specs.
 
 ## Related topics