Add latest changes from gitlab-org/gitlab@13-5-stable-eev13.5.0-rc42

8 files changed, 161 insertions, 128 deletions

diff --git a/doc/user/project/clusters/add_eks_clusters.md b/doc/user/project/clusters/add_eks_clusters.md
index b3b1b51a543..65416d73f06 100644
--- a/doc/user/project/clusters/add_eks_clusters.md
+++ b/doc/user/project/clusters/add_eks_clusters.md
@@ -43,7 +43,7 @@ For example, the following policy document allows assuming a role whose name sta
 
 Generate an access key for the IAM user, and configure GitLab with the credentials:
 
-1. Navigate to **Admin Area > Settings > Integrations** and expand the **Amazon EKS** section.
+1. Navigate to **Admin Area > Settings > General** and expand the **Amazon EKS** section.
 1. Check **Enable Amazon EKS integration**.
 1. Enter the account ID and access key credentials into the respective
    `Account ID`, `Access key ID` and `Secret access key` fields.
@@ -61,22 +61,13 @@ To create and add a new Kubernetes cluster to your project, group, or instance:
    - **Admin Area > Kubernetes**, for an instance-level cluster.
 1. Click **Add Kubernetes cluster**.
 1. Under the **Create new cluster** tab, click **Amazon EKS**. You will be provided with an
-   `Account ID` and `External ID` to use in the next step.
-1. In the [IAM Management Console](https://console.aws.amazon.com/iam/home), create an EKS management IAM role.
-   To do so, follow the [Amazon EKS cluster IAM role](https://docs.aws.amazon.com/eks/latest/userguide/service_IAM_role.html) instructions
-   to create a IAM role suitable for managing the AWS EKS cluster's resources on your behalf.
-   In addition to the policies that guide suggests, you must also include the `AmazonEKSClusterPolicy`
-   policy for this role in order for GitLab to manage the EKS cluster correctly.
-1. In the [IAM Management Console](https://console.aws.amazon.com/iam/home), create an IAM role:
-   1. From the left panel, select **Roles**.
-   1. Click **Create role**.
-   1. Under `Select type of trusted entity`, select **Another AWS account**.
-   1. Enter the Account ID from GitLab into the `Account ID` field.
-   1. Check **Require external ID**.
-   1. Enter the External ID from GitLab into the `External ID` field.
-   1. Click **Next: Permissions**.
-   1. Click **Create Policy**, which will open a new window.
-   1. Select the **JSON** tab, and paste in the following snippet in place of the existing content:
+   `Account ID` and `External ID` needed for later steps.
+1. In the [IAM Management Console](https://console.aws.amazon.com/iam/home), create an IAM policy:
+   1. From the left panel, select **Policies**.
+   1. Click **Create Policy**, which opens a new window.
+   1. Select the **JSON** tab, and paste the following snippet in place of the
+      existing content. These permissions give GitLab the ability to create
+      resources, but not delete them:
 
       ```json
       {
@@ -123,15 +114,26 @@ To create and add a new Kubernetes cluster to your project, group, or instance:
       }
       ```
 
-      NOTE: **Note:**
-      These permissions give GitLab the ability to create resources, but not delete them.
-      This means that if an error is encountered during the creation process, changes will
+      If an error is encountered during the creation process, changes will
       not be rolled back and you must remove resources manually. You can do this by deleting
       the relevant [CloudFormation stack](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/cfn-console-delete-stack.html)
 
    1. Click **Review policy**.
    1. Enter a suitable name for this policy, and click **Create Policy**. You can now close this window.
-   1. Switch back to the "Create role" window, and select the policy you just created.
+
+1. In the [IAM Management Console](https://console.aws.amazon.com/iam/home), create an EKS management IAM role.
+   To do so, follow the [Amazon EKS cluster IAM role](https://docs.aws.amazon.com/eks/latest/userguide/service_IAM_role.html) instructions
+   to create a IAM role suitable for managing the AWS EKS cluster's resources on your behalf.
+   In addition to the policies that guide suggests, you must also include the `AmazonEKSClusterPolicy`
+   policy for this role in order for GitLab to manage the EKS cluster correctly.
+1. In the [IAM Management Console](https://console.aws.amazon.com/iam/home), create an IAM role:
+   1. From the left panel, select **Roles**.
+   1. Click **Create role**.
+   1. Under `Select type of trusted entity`, select **Another AWS account**.
+   1. Enter the Account ID from GitLab into the `Account ID` field.
+   1. Check **Require external ID**.
+   1. Enter the External ID from GitLab into the `External ID` field.
+   1. Click **Next: Permissions**, and select the policy you just created.
    1. Click **Next: Tags**, and optionally enter any tags you wish to associate with this role.
    1. Click **Next: Review**.
    1. Enter a role name and optional description into the fields provided.
diff --git a/doc/user/project/clusters/add_remove_clusters.md b/doc/user/project/clusters/add_remove_clusters.md
index 18d9fa67ee1..094f4bcf6ba 100644
--- a/doc/user/project/clusters/add_remove_clusters.md
+++ b/doc/user/project/clusters/add_remove_clusters.md
@@ -19,9 +19,12 @@ and learn how to spin up a Kubernetes cluster managed by Google Cloud Platform (
 in a few clicks.
 
 TIP: **Tip:**
-Every new Google Cloud Platform (GCP) account receives [$300 in credit upon sign up](https://console.cloud.google.com/freetrial),
-and in partnership with Google, GitLab is able to offer an additional $200 for new GCP accounts to get started with GitLab's
-Google Kubernetes Engine Integration. All you have to do is [follow this link](https://cloud.google.com/partners/partnercredit/?pcn_code=0014M00001h35gDQAQ#contact-form) and apply for credit.
+Every new Google Cloud Platform (GCP) account receives
+[$300 in credit upon sign up](https://console.cloud.google.com/freetrial).
+In partnership with Google, GitLab is able to offer an additional $200 for new GCP
+accounts to get started with GitLab's Google Kubernetes Engine Integration.
+[Follow this link](https://cloud.google.com/partners/partnercredit/?pcn_code=0014M00001h35gDQAQ#contact-form)
+to apply for credit.
 
 ## Before you begin
 
@@ -30,7 +33,7 @@ Before [adding a Kubernetes cluster](#create-new-cluster) using GitLab, you need
 - GitLab itself. Either:
   - A [GitLab.com account](https://about.gitlab.com/pricing/#gitlab-com).
   - A [self-managed installation](https://about.gitlab.com/pricing/#self-managed) with GitLab version
-    12.5 or later. This will ensure the GitLab UI can be used for cluster creation.
+    12.5 or later. This ensures the GitLab UI can be used for cluster creation.
 - The following GitLab access:
   - [Maintainer access to a project](../../permissions.md#project-members-permissions) for a
     project-level cluster.
@@ -41,28 +44,25 @@ Before [adding a Kubernetes cluster](#create-new-cluster) using GitLab, you need
 
 ## Access controls
 
-When creating a cluster in GitLab, you will be asked if you would like to create either:
+> - Restricted service account for deployment was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/51716) in GitLab 11.5.
 
-- A [Role-based access control (RBAC)](https://kubernetes.io/docs/reference/access-authn-authz/rbac/) cluster.
-- An [Attribute-based access control (ABAC)](https://kubernetes.io/docs/reference/access-authn-authz/abac/) cluster.
+When creating a cluster in GitLab, you are asked if you would like to create either:
 
-NOTE: **Note:**
-[RBAC](#rbac-cluster-resources) is recommended and the GitLab default.
+- A [Role-based access control (RBAC)](https://kubernetes.io/docs/reference/access-authn-authz/rbac/)
+  cluster, which is the GitLab default and recommended option.
+- An [Attribute-based access control (ABAC)](https://kubernetes.io/docs/reference/access-authn-authz/abac/) cluster.
 
 GitLab creates the necessary service accounts and privileges to install and run
 [GitLab managed applications](index.md#installing-applications). When GitLab creates the cluster,
 a `gitlab` service account with `cluster-admin` privileges is created in the `default` namespace
 to manage the newly created cluster.
 
-NOTE: **Note:**
-Restricted service account for deployment was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/51716) in GitLab 11.5.
-
 The first time you install an application into your cluster, the `tiller` service
 account is created with `cluster-admin` privileges in the
-`gitlab-managed-apps` namespace. This service account will be used by Helm to
+`gitlab-managed-apps` namespace. This service account is used by Helm to
 install and run [GitLab managed applications](index.md#installing-applications).
 
-Helm will also create additional service accounts and other resources for each
+Helm also creates additional service accounts and other resources for each
 installed application. Consult the documentation of the Helm charts for each application
 for details.
 
@@ -77,7 +77,7 @@ Note the following about access controls:
 
 - Environment-specific resources are only created if your cluster is
   [managed by GitLab](index.md#gitlab-managed-clusters).
-- If your cluster was created before GitLab 12.2, it will use a single namespace for all project
+- If your cluster was created before GitLab 12.2, it uses a single namespace for all project
   environments.
 
 ### RBAC cluster resources
@@ -151,11 +151,12 @@ Amazon Elastic Kubernetes Service (EKS) at the project, group, or instance level
 
 ## Add existing cluster
 
-If you have an existing Kubernetes cluster, you can add it to a project, group, or instance.
+If you have an existing Kubernetes cluster, you can add it to a project, group,
+or instance.
 
-NOTE: **Note:**
-Kubernetes integration is not supported for arm64 clusters. See the issue
-[Helm Tiller fails to install on arm64 cluster](https://gitlab.com/gitlab-org/gitlab/-/issues/29838) for details.
+Kubernetes integration isn't supported for arm64 clusters. See the issue
+[Helm Tiller fails to install on arm64 cluster](https://gitlab.com/gitlab-org/gitlab/-/issues/29838)
+for details.
 
 ### Existing Kubernetes cluster
 
@@ -181,7 +182,7 @@ To add a Kubernetes cluster to your project, group, or instance:
       kubectl cluster-info | grep 'Kubernetes master' | awk '/http/ {print $NF}'
       ```
 
-   1. **CA certificate** (required) - A valid Kubernetes certificate is needed to authenticate to the cluster. We will use the certificate created by default.
+   1. **CA certificate** (required) - A valid Kubernetes certificate is needed to authenticate to the cluster. We use the certificate created by default.
       1. List the secrets with `kubectl get secrets`, and one should be named similar to
          `default-token-xxxxx`. Copy that token name for use below.
       1. Get the certificate by running this command:
@@ -190,9 +191,20 @@ To add a Kubernetes cluster to your project, group, or instance:
          kubectl get secret <secret name> -o jsonpath="{['data']['ca\.crt']}" | base64 --decode
          ```
 
-         NOTE: **Note:**
-         If the command returns the entire certificate chain, you need copy the *root ca*
-         certificate at the bottom of the chain.
+         If the command returns the entire certificate chain, you must copy the Root CA
+         certificate and any intermediate certificates at the bottom of the chain.
+         A chain file has following structure:
+
+         ```plaintext
+            -----BEGIN MY CERTIFICATE-----
+            -----END MY CERTIFICATE-----
+            -----BEGIN INTERMEDIATE CERTIFICATE-----
+            -----END INTERMEDIATE CERTIFICATE-----
+            -----BEGIN INTERMEDIATE CERTIFICATE-----
+            -----END INTERMEDIATE CERTIFICATE-----
+            -----BEGIN ROOT CERTIFICATE-----
+            -----END ROOT CERTIFICATE-----
+         ```
 
    1. **Token** -
       GitLab authenticates against Kubernetes using service tokens, which are
@@ -229,10 +241,10 @@ To add a Kubernetes cluster to your project, group, or instance:
          kubectl apply -f gitlab-admin-service-account.yaml
          ```
 
-         You will need the `container.clusterRoleBindings.create` permission
+         You need the `container.clusterRoleBindings.create` permission
          to create cluster-level roles. If you do not have this permission,
          you can alternatively enable Basic Authentication and then run the
-         `kubectl apply` command as an admin:
+         `kubectl apply` command as an administrator:
 
          ```shell
          kubectl apply -f gitlab-admin-service-account.yaml --username=admin --password=<password>
@@ -257,7 +269,7 @@ To add a Kubernetes cluster to your project, group, or instance:
 
          Copy the `<authentication_token>` value from the output:
 
-         ```yaml
+         ```plaintext
          Name:         gitlab-token-b5zv4
          Namespace:    kube-system
          Labels:       <none>
@@ -274,7 +286,7 @@ To add a Kubernetes cluster to your project, group, or instance:
          ```
 
       NOTE: **Note:**
-      For GKE clusters, you will need the
+      For GKE clusters, you need the
       `container.clusterRoleBindings.create` permission to create a cluster
       role binding. You can follow the [Google Cloud
       documentation](https://cloud.google.com/iam/docs/granting-changing-revoking-access)
@@ -283,7 +295,7 @@ To add a Kubernetes cluster to your project, group, or instance:
    1. **GitLab-managed cluster** - Leave this checked if you want GitLab to manage namespaces and service accounts for this cluster.
       See the [Managed clusters section](index.md#gitlab-managed-clusters) for more information.
    1. **Project namespace** (optional) - You don't have to fill it in; by leaving
-      it blank, GitLab will create one for you. Also:
+      it blank, GitLab creates one for you. Also:
       - Each project should have a unique namespace.
       - The project namespace is not necessarily the namespace of the secret, if
         you're using a secret with broader permissions, like the secret from `default`.
@@ -294,21 +306,21 @@ To add a Kubernetes cluster to your project, group, or instance:
 
 1. Finally, click the **Create Kubernetes cluster** button.
 
-After a couple of minutes, your cluster will be ready to go. You can now proceed
+After a couple of minutes, your cluster is ready. You can now proceed
 to install some [pre-defined applications](index.md#installing-applications).
 
 #### Disable Role-Based Access Control (RBAC) (optional)
 
 When connecting a cluster via GitLab integration, you may specify whether the
-cluster is RBAC-enabled or not. This will affect how GitLab interacts with the
+cluster is RBAC-enabled or not. This affects how GitLab interacts with the
 cluster for certain operations. If you did *not* check the **RBAC-enabled cluster**
-checkbox at creation time, GitLab will assume RBAC is disabled for your cluster
+checkbox at creation time, GitLab assumes RBAC is disabled for your cluster
 when interacting with it. If so, you must disable RBAC on your cluster for the
 integration to work properly.
 
-![rbac](img/rbac_v13_1.png)
+![RBAC](img/rbac_v13_1.png)
 
-NOTE: **Note:**
+CAUTION: **Caution:**
 Disabling RBAC means that any application running in the cluster,
 or user who can authenticate to the cluster, has full API access. This is a
 [security concern](index.md#security-implications), and may not be desirable.
@@ -356,3 +368,12 @@ When removing the cluster integration, note:
 
 To learn more on automatically deploying your applications,
 read about [Auto DevOps](../../../topics/autodevops/index.md).
+
+## Troubleshooting
+
+### There was a problem authenticating with your cluster. Please ensure your CA Certificate and Token are valid
+
+If you encounter this error while adding a Kubernetes cluster, ensure you're
+properly pasting the service token. Some shells may add a line break to the
+service token, making it invalid. Ensure that there are no line breaks by
+pasting your token into an editor and removing any additional spaces.
diff --git a/doc/user/project/clusters/index.md b/doc/user/project/clusters/index.md
index 8d188f00ceb..459ba144186 100644
--- a/doc/user/project/clusters/index.md
+++ b/doc/user/project/clusters/index.md
@@ -1,6 +1,6 @@
 ---
 stage: Monitor
-group: APM
+group: Health
 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
 ---
 
@@ -12,8 +12,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/39840) in
 >   GitLab 11.11 for [instances](../../instance/clusters/index.md).
 
-## Overview
-
 Using the GitLab project Kubernetes integration, you can:
 
 - Use [Review Apps](../../../ci/review_apps/index.md).
@@ -31,6 +29,11 @@ Besides integration at the project level, Kubernetes clusters can also be
 integrated at the [group level](../../group/clusters/index.md) or
 [GitLab instance level](../../instance/clusters/index.md).
 
+To view your project level Kubernetes clusters, navigate to **Operations > Kubernetes**
+from your project. On this page, you can [add a new cluster](#adding-and-removing-clusters)
+and view information about your existing clusters, such as nodes count and rough estimates
+of memory and CPU usage.
+
 ## Setting up
 
 ### Supported cluster versions
@@ -49,10 +52,9 @@ Currently, GitLab supports the following Kubernetes versions:
 - 1.17
 - 1.16
 - 1.15
-- 1.14
+- 1.14 (deprecated, support ends on December 22, 2020)
 - 1.13 (deprecated, support ends on November 22, 2020)
 
-NOTE: **Note:**
 Some GitLab features may support versions outside the range provided here.
 
 ### Adding and removing clusters
@@ -192,7 +194,6 @@ To clear the cache:
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/24580) in GitLab 11.8.
 
-NOTE: **Note:**
 You do not need to specify a base domain on cluster settings when using GitLab Serverless. The domain in that case
 will be specified as part of the Knative installation. See [Installing Applications](#installing-applications).
 
@@ -220,13 +221,11 @@ Auto DevOps automatically detects, builds, tests, deploys, and monitors your
 applications.
 
 To make full use of Auto DevOps (Auto Deploy, Auto Review Apps, and
-Auto Monitoring) you will need the Kubernetes project integration enabled.
+Auto Monitoring) you will need the Kubernetes project integration enabled, but
+Kubernetes clusters can be used without Auto DevOps.
 
 [Read more about Auto DevOps](../../../topics/autodevops/index.md)
 
-NOTE: **Note:**
-Kubernetes clusters can be used without Auto DevOps.
-
 ## Deploying to a Kubernetes cluster
 
 A Kubernetes cluster can be the destination for a deployment job. If
@@ -249,36 +248,51 @@ GitLab CI/CD build environment.
 | Variable | Description |
 | -------- | ----------- |
 | `KUBE_URL` | Equal to the API URL. |
-| `KUBE_TOKEN` | The Kubernetes token of the [environment service account](add_remove_clusters.md#access-controls). |
-| `KUBE_NAMESPACE` | The namespace associated with the project's deployment service account. In the format `<project_name>-<project_id>-<environment>`. For GitLab-managed clusters, a matching namespace is automatically created by GitLab in the cluster. |
+| `KUBE_TOKEN` | The Kubernetes token of the [environment service account](add_remove_clusters.md#access-controls). Prior to GitLab 11.5, `KUBE_TOKEN` was the Kubernetes token of the main service account of the cluster integration. |
+| `KUBE_NAMESPACE` | The namespace associated with the project's deployment service account. In the format `<project_name>-<project_id>-<environment>`. For GitLab-managed clusters, a matching namespace is automatically created by GitLab in the cluster. If your cluster was created before GitLab 12.2, the default `KUBE_NAMESPACE` is set to `<project_name>-<project_id>`. |
 | `KUBE_CA_PEM_FILE` | Path to a file containing PEM data. Only present if a custom CA bundle was specified. |
 | `KUBE_CA_PEM` | (**deprecated**) Raw PEM data. Only if a custom CA bundle was specified. |
-| `KUBECONFIG` | Path to a file containing `kubeconfig` for this deployment. CA bundle would be embedded if specified. This config also embeds the same token defined in `KUBE_TOKEN` so you likely will only need this variable. This variable name is also automatically picked up by `kubectl` so you won't actually need to reference it explicitly if using `kubectl`. |
+| `KUBECONFIG` | Path to a file containing `kubeconfig` for this deployment. CA bundle would be embedded if specified. This configuration also embeds the same token defined in `KUBE_TOKEN` so you likely will only need this variable. This variable name is also automatically picked up by `kubectl` so you won't actually need to reference it explicitly if using `kubectl`. |
 | `KUBE_INGRESS_BASE_DOMAIN` | From GitLab 11.8, this variable can be used to set a domain per cluster. See [cluster domains](#base-domain) for more information. |
 
-NOTE: **Note:**
-Prior to GitLab 11.5, `KUBE_TOKEN` was the Kubernetes token of the main
-service account of the cluster integration.
-
-NOTE: **Note:**
-If your cluster was created before GitLab 12.2, default `KUBE_NAMESPACE` will be set to `<project_name>-<project_id>`.
-
 ### Custom namespace
 
-> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27630) in GitLab 12.6.
-
-The Kubernetes integration defaults to project-environment-specific namespaces
-of the form `<project_name>-<project_id>-<environment>` (see [Deployment
-variables](#deployment-variables)).
-
-For **non**-GitLab-managed clusters, the namespace can be customized using
-[`environment:kubernetes:namespace`](../../../ci/environments/index.md#configuring-kubernetes-deployments)
-in `.gitlab-ci.yml`.
-
-NOTE: **Note:**
-When using a [GitLab-managed cluster](#gitlab-managed-clusters), the
-namespaces are created automatically prior to deployment and [can not be
-customized](https://gitlab.com/gitlab-org/gitlab/-/issues/38054).
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27630) in GitLab 12.6.
+> - An option to use project-wide namespaces [was added](https://gitlab.com/gitlab-org/gitlab/-/issues/38054) in GitLab 13.5.
+
+The Kubernetes integration provides a `KUBECONFIG` with an auto-generated namespace
+to deployment jobs. It defaults to using project-environment specific namespaces
+of the form `<prefix>-<environment>`, where `<prefix>` is of the form
+`<project_name>-<project_id>`. To learn more, read [Deployment variables](#deployment-variables).
+
+You can customize the deployment namespace in a few ways:
+
+- You can choose between a **namespace per [environment](../../../ci/environments/index.md)**
+  or a **namespace per project**. A namespace per environment is the default and recommended
+  setting, as it prevents the mixing of resources between production and non-production environments.
+- When using a project-level cluster, you can additionally customize the namespace prefix.
+  When using namespace-per-environment, the deployment namespace is `<prefix>-<environment>`,
+  but otherwise just `<prefix>`.
+- For **non-managed** clusters, the auto-generated namespace is set in the `KUBECONFIG`,
+  but the user is responsible for ensuring its existence. You can fully customize
+  this value using
+  [`environment:kubernetes:namespace`](../../../ci/environments/index.md#configuring-kubernetes-deployments)
+  in `.gitlab-ci.yml`.
+
+When you customize the namespace, existing environments remain linked to their current
+namespaces until you [clear the cluster cache](#clearing-the-cluster-cache).
+
+CAUTION: **Warning:**
+By default, anyone who can create a deployment job can access any CI variable within
+an environment's deployment job. This includes `KUBECONFIG`, which gives access to
+any secret available to the associated service account in your cluster.
+To keep your production credentials safe, consider using
+[Protected Environments](../../../ci/environments/protected_environments.md),
+combined with either
+
+- a GitLab-managed cluster and namespace per environment,
+- *or*, an environment-scoped cluster per protected environment. The same cluster
+  can be added multiple times with multiple restricted service accounts.
 
 ### Integrations
 
diff --git a/doc/user/project/clusters/kubernetes_pod_logs.md b/doc/user/project/clusters/kubernetes_pod_logs.md
index afb6d016f45..2e224208eb8 100644
--- a/doc/user/project/clusters/kubernetes_pod_logs.md
+++ b/doc/user/project/clusters/kubernetes_pod_logs.md
@@ -1,6 +1,6 @@
 ---
 stage: Monitor
-group: APM
+group: Health
 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
 ---
 
@@ -28,7 +28,6 @@ above the log file data, depending on your configuration:
 <i class="fa fa-youtube-play youtube" aria-hidden="true"></i>
 To learn more about the Log Explorer, see [APM - Log Explorer](https://www.youtube.com/watch?v=hWclZHA7Dgw).
 
-NOTE: **Note:**
 [Learn more about Kubernetes + GitLab](https://about.gitlab.com/solutions/kubernetes/).
 Everything you need to build, test, deploy, and run your application at scale.
 
diff --git a/doc/user/project/clusters/runbooks/index.md b/doc/user/project/clusters/runbooks/index.md
index 360b02efb69..c1e4e821efd 100644
--- a/doc/user/project/clusters/runbooks/index.md
+++ b/doc/user/project/clusters/runbooks/index.md
@@ -115,9 +115,7 @@ the components outlined above and the pre-loaded demo runbook.
       VARIABLE_VALUE = project.variables.get('PRIVATE_TOKEN').value
       ```
 
-1. To configure the operation of a runbook, create and configure variables:
-
-   NOTE: **Note:**
+1. To configure the operation of a runbook, create and configure variables.
    For this example, we are using the **Run SQL queries in Notebook** section in the
    sample runbook to query a PostgreSQL database. The first four lines of the following
    code block define the variables that are required for this query to function:
diff --git a/doc/user/project/clusters/securing.md b/doc/user/project/clusters/securing.md
index a15660051f7..bed01ff4d58 100644
--- a/doc/user/project/clusters/securing.md
+++ b/doc/user/project/clusters/securing.md
@@ -85,7 +85,7 @@ Host Security (Falco) are deployed with this model.
 
 To deploy GitLab Managed Apps to your cluster, you must first
 [add your cluster](add_remove_clusters.md)
-to GitLab. Then [install](../../clusters/applications.md#installing-applications)
+to GitLab. Then [install](../../clusters/applications.md#install-with-one-click)
 the Web Application Firewall from the project or group Kubernetes page.
 
 Note that your project doesn't have to be hosted or deployed through GitLab. You can manage a
diff --git a/doc/user/project/clusters/serverless/aws.md b/doc/user/project/clusters/serverless/aws.md
index 543ffdbce8f..db91f78fc20 100644
--- a/doc/user/project/clusters/serverless/aws.md
+++ b/doc/user/project/clusters/serverless/aws.md
@@ -136,8 +136,8 @@ This example code does the following:
 In order to interact with your AWS account, the GitLab CI/CD pipelines require both `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` to be defined in your GitLab settings under **Settings > CI/CD > Variables**.
 For more information please see [Create a custom variable in the UI](../../../../ci/variables/README.md#create-a-custom-variable-in-the-ui).
 
-NOTE: **Note:**
-   The AWS credentials you provide must include IAM policies that provision correct access control to AWS Lambda, API Gateway, CloudFormation, and IAM resources.
+ The AWS credentials you provide must include IAM policies that provision correct
+ access control to AWS Lambda, API Gateway, CloudFormation, and IAM resources.
 
 #### Deploying your function
 
@@ -154,9 +154,7 @@ endpoints:
 #### Manually testing your function
 
 Running the following `curl` command should trigger your function.
-
-NOTE: **Note:**
-Your URL should be the one retrieved from the GitLab deploy stage log.
+Your URL should be the one retrieved from the GitLab deploy stage log:
 
 ```shell
 curl https://u768nzby1j.execute-api.us-east-1.amazonaws.com/production/hello
@@ -222,7 +220,8 @@ the environment of the deployed function:
 
 ```yaml
 provider:
-  ...
+  # Other configuration omitted
+  # ...
   environment:
     A_VARIABLE: ${env:A_VARIABLE}
 ```
@@ -245,10 +244,10 @@ functions:
   hello:
     handler: src/handler.hello
     events:
-      - http: # Rewrite this part to enable CORS
+      - http:  # Rewrite this part to enable CORS
           path: hello
           method: get
-          cors: true # <-- CORS here
+          cors: true  # <-- CORS here
 ```
 
 You also need to return CORS specific headers in your function response:
@@ -378,7 +377,6 @@ To set these:
    `AWS_SECRET_ACCESS_KEY`.
 1. Mask the credentials so they do not show in logs using the **Masked** toggle.
 
-NOTE: **Note:**
 The AWS credentials you provide must include IAM policies that provision correct access
 control to AWS Lambda, API Gateway, CloudFormation, and IAM resources.
 
diff --git a/doc/user/project/clusters/serverless/index.md b/doc/user/project/clusters/serverless/index.md
index 1157c2c5632..603c4bd73b1 100644
--- a/doc/user/project/clusters/serverless/index.md
+++ b/doc/user/project/clusters/serverless/index.md
@@ -75,8 +75,8 @@ To run Knative on GitLab, you will need:
 
 ## Installing Knative via GitLab's Kubernetes integration
 
-NOTE: **Note:**
-The minimum recommended cluster size to run Knative is 3-nodes, 6 vCPUs, and 22.50 GB memory. **RBAC must be enabled.**
+The minimum recommended cluster size to run Knative is 3-nodes, 6 vCPUs, and 22.50 GB
+memory. **RBAC must be enabled.**
 
 1. [Add a Kubernetes cluster](../add_remove_clusters.md).
 1. Select the **Applications** tab and scroll down to the Knative app section. Enter the domain to be used with
@@ -99,22 +99,19 @@ The minimum recommended cluster size to run Knative is 3-nodes, 6 vCPUs, and 22.
 
    ![DNS entry](img/dns-entry.png)
 
-NOTE: **Note:**
 You can deploy either [functions](#deploying-functions) or [serverless applications](#deploying-serverless-applications)
-on a given project but not both. The current implementation makes use of a `serverless.yml` file to signal a FaaS project.
+on a given project, but not both. The current implementation makes use of a
+`serverless.yml` file to signal a FaaS project.
 
 ## Using an existing installation of Knative
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/58941) in GitLab 12.0.
 
-NOTE: **Note:**
-The "invocations" monitoring feature of GitLab serverless will not work when
+The _invocations_ monitoring feature of GitLab serverless won't work when
 adding an existing installation of Knative.
 
-It is also possible to use GitLab Serverless with an existing Kubernetes
-cluster which already has Knative installed.
-
-You must do the following:
+It's also possible to use GitLab Serverless with an existing Kubernetes cluster
+which already has Knative installed. You must do the following:
 
 1. Follow the steps to
    [add an existing Kubernetes
@@ -453,16 +450,16 @@ To run a function locally:
 
 > Introduced in GitLab 11.5.
 
+12345678901234567890123456789012345678901234567890123456789012345678901234567890
 Serverless applications are an alternative to [serverless functions](#deploying-functions).
-They are useful in scenarios where an existing runtime does not meet the needs of an application,
-such as one written in a language that has no runtime available. Note though that serverless
-applications should be stateless!
-
-NOTE: **Note:**
-You can reference and import the sample [Knative Ruby App](https://gitlab.com/knative-examples/knative-ruby-app) to get started.
+They're useful in scenarios where an existing runtime does not meet the needs of
+an application, such as one written in a language that has no runtime available.
+Note though that serverless applications should be stateless.
 
-Add the following `.gitlab-ci.yml` to the root of your repository
-(you may skip this step if you've previously cloned the sample [Knative Ruby App](https://gitlab.com/knative-examples/knative-ruby-app) mentioned above):
+You can reference and import the sample [Knative Ruby App](https://gitlab.com/knative-examples/knative-ruby-app)
+to get started. Add the following `.gitlab-ci.yml` to the root of your repository
+(you may skip this step if you've previously cloned the previously mentioned,
+sample [Knative Ruby App](https://gitlab.com/knative-examples/knative-ruby-app)):
 
 ```yaml
 include:
@@ -561,14 +558,18 @@ Or:
 
 ## Enabling TLS for Knative services
 
-By default, a GitLab serverless deployment will be served over `http`. In order to serve over `https` you
-must manually obtain and install TLS certificates.
+By default, a GitLab serverless deployment will be served over `http`. To serve
+over `https`, you must manually obtain and install TLS certificates.
 
-The simplest way to accomplish this is to
-use [Certbot to manually obtain Let's Encrypt certificates](https://knative.dev/docs/serving/using-a-tls-cert/#using-certbot-to-manually-obtain-let-s-encrypt-certificates). Certbot is a free, open source software tool for automatically using Let’s Encrypt certificates on manually-administrated websites to enable HTTPS.
+12345678901234567890123456789012345678901234567890123456789012345678901234567890
+The simplest way to accomplish this is to use Certbot to
+[manually obtain Let's Encrypt certificates](https://knative.dev/docs/serving/using-a-tls-cert/#using-certbot-to-manually-obtain-let-s-encrypt-certificates).
+Certbot is a free, open source software tool for automatically using Let’s Encrypt
+certificates on manually-administered websites to enable HTTPS.
 
-NOTE: **Note:**
-The instructions below relate to installing and running Certbot on a Linux server that has Python 3 installed and may not work on other operating systems or with other versions of Python.
+The following instructions relate to installing and running Certbot on a Linux
+server that has Python 3 installed, and may not work on other operating systems
+or with other versions of Python.
 
 1. Install Certbot by running the
    [`certbot-auto` wrapper script](https://certbot.eff.org/docs/install.html#certbot-auto).
@@ -788,7 +789,7 @@ The instructions below relate to installing and running Certbot on a Linux serve
    kubectl edit gateway knative-ingress-gateway --namespace knative-serving
    ```
 
-   Update the gateway to include the following tls: section and configuration:
+   Update the gateway to include the following `tls:` section and configuration:
 
    ```shell
    tls: