Apply 10 suggestion(s) to 3 file(s)

doc/user/clusters/applications.md

@@ -6,6 +6,10 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 
 # GitLab Managed Apps (DEPRECATED) **(FREE)**
 
+NOTE:
+The new recommended way to manage cluster applications is to use the [cluster management project template](management_project_template.md).
+If you want to migrate your GitLab managed apps management to this template, reference to [migrating from GitLab managed apps to project template](migrating_from_gma_to_project_template.md).
+
 **GitLab Managed Apps** was created to help you configure applications in your
 cluster directly from GitLab. You could use this feature through two different
 methods: "one-click install" and "CI/CD template". Both methods are **deprecated**:
@@ -25,10 +29,6 @@ learn how to proceed to keep your apps up and running:
 - [One-click install method](#install-with-one-click-deprecated)
 - [CI/CD template method](#install-using-gitlab-cicd-deprecated)
 
-NOTE:
-The new recommended way to manage cluster applications is to use the [cluster management project template](management_project_template.md).
-If you want to migrate your GitLab managed apps management to this template, reference to [migrating from GitLab managed apps to project template](migrating_from_gma_to_project_template.md).
-
 ## Install using GitLab CI/CD (DEPRECATED)
 
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20822) in GitLab 12.6.

doc/user/clusters/integrations.md

@@ -14,9 +14,16 @@ To enable cluster integrations, first add a Kubernetes cluster to a GitLab
 [group](../group/clusters/index.md#group-level-kubernetes-clusters) or
 [instance](../instance/clusters/index.md).
 
-You can install your applications by any means. But GitLab provides a 
-[Cluster management project template](management_project_template.md) to support you with
-this task.
+You can install your applications manually as shown in the following sections, or use the
+[Cluster management project template](management_project_template.md) that automates the
+installation.
+
+Although, the [Cluster management project template](management_project_template.md) still
+requires that you manually do the last steps of these sections,
+[Enable Prometheus integration for your cluster](#enable-prometheus-integration-for-your-cluster)
+or [Enable Elastic Stack integration for your cluster](#enable-elastic-stack-integration-for-your-cluster)
+depending on which application you are installing. We plan to also automate this step in the future,
+see the [opened issue](https://gitlab.com/gitlab-org/gitlab/-/issues/326565).
 
 ## Prometheus cluster integration
 

doc/user/clusters/management_project_template.md

@@ -11,62 +11,76 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 
 This [GitLab built-in project template](../project/working_with_projects.md#built-in-templates)
 provides a quicker start for users interested in managing cluster
-applications via [Helm v3](https://helm.sh/) charts. Most specifically, taking advantage of the
-[Helmfile](https://github.com/roboll/helmfile) utility client. The template comprehends of some pre-setup apps that
-we believe to integrate well with GitLab features. Still, you have all the flexibility to remove the ones you do not
+applications via [Helm v3](https://helm.sh/) charts. More specifically, taking advantage of the
+[Helmfile](https://github.com/roboll/helmfile) utility client. The template consists of some pre-configured apps that
+should help you get started quickly using various GitLab features. Still, you have all the flexibility to remove the ones you do not
 need, or even add new ones that are not built-in.
 
 ## How to use this template
 
-1. Create a new project, choosing "GitLab Cluster Management" from our list of [Built-in project templates](../project/working_with_projects.md#built-in-templates). 
-1. Make this project a [Cluster management project](management_project.md).
-1. If you are a user of [GitLab Managed Apps](https://docs.gitlab.com/13.12/ee/user/clusters/applications.html), reference to
-   [Migrating from GitLab Manged Apps](#migrating-from-gitlab-managed-apps).
+1. Create a new project, choosing "GitLab Cluster Management" from the list of [built-in project templates](../project/working_with_projects.md#built-in-templates). 
+1. Make this project a [cluster management project](management_project.md).
+1. If you used the [GitLab Managed Apps](applications.md), refer to
+   [Migrating from GitLab Manged Apps](migrating_from_gma_to_project_template.md).
 
 ### Components
 
-In the repo you will find:
+In the repository of the newly-created project, you will find:
 
-- a predefined [`./.gitlab-ci.yml`](https://gitlab.com/gitlab-org/project-templates/cluster-management/-/blob/master/.gitlab-ci.yml), with a CI pipeline already configured.
-- a main [`./helmfile.yaml`](https://gitlab.com/gitlab-org/project-templates/cluster-management/-/blob/master/helmfile.yaml) to toggle which applications you would like to manage.
-- an `./applications` folder with a `helmfile.yaml` configured for each app we provide.
+- A predefined [`.gitlab-ci.yml`](https://gitlab.com/gitlab-org/project-templates/cluster-management/-/blob/master/.gitlab-ci.yml)
+  file, with a CI pipeline already configured.
+- A main [`helmfile.yaml`](https://gitlab.com/gitlab-org/project-templates/cluster-management/-/blob/master/helmfile.yaml) to toggle which applications you would like to manage.
+- An `applications` directory with a `helmfile.yaml` configured for each application GitLab provides.
 
-#### The [`.gitlab-ci.yml`](https://gitlab.com/gitlab-org/project-templates/cluster-management/-/blob/master/.gitlab-ci.yml)
+#### The `.gitlab-ci.yml` file
 
 The base image used in your pipeline is built by the [cluster-applications](https://gitlab.com/gitlab-org/cluster-integration/cluster-applications)
-project. This image comprehends a set of Bash utility scripts to support [Helm v3 releases](https://helm.sh/docs/intro/using_helm/#three-big-concepts).
-They are:
+project. This image consists of a set of Bash utility scripts to support [Helm v3 releases](https://helm.sh/docs/intro/using_helm/#three-big-concepts):
 
-- `./gl-fail-if-helm2-releases-exist {namespace}`: It tries to detect whether you have apps deployed through Helm v2 
+- `gl-fail-if-helm2-releases-exist {namespace}`: It tries to detect whether you have apps deployed through Helm v2 
   releases for a given namespace. If so, it will fail the pipeline and ask you to manually 
   [migrate your Helm v2 releases to Helm v3](https://helm.sh/docs/topics/v2_v3_migration/).
-- `./gl-ensure-namespace {namespace}`: It creates the given namespace if it does not exist and adds the necessary label 
+- `gl-ensure-namespace {namespace}`: It creates the given namespace if it does not exist and adds the necessary label 
   for the [Cilium](https://github.com/cilium/cilium/) app network policies to work.
-- `./gl-adopt-resource-with-helm-v3 {arguments}`: Used only internally in the [cert-manager](https://cert-manager.io/) app's Helmfile to
-  facilitate GitLab Managed Apps adoption.
-- `./gl-adopt-crds-with-helm-v3 {arguments}`: Also used only internally in the [cert-manager](https://cert-manager.io/) app's Helmfile to
-  facilitate GitLab Managed Apps adoption.
-- `./gl-helmfile {arguments}`: It is a thin wrapper that triggers the [Helmfile](https://github.com/roboll/helmfile) command.
+- `gl-adopt-resource-with-helm-v3 {arguments}`: Used only internally in the [cert-manager's](https://cert-manager.io/) Helmfile to
+  facilitate the GitLab Managed Apps adoption.
+- `gl-adopt-crds-with-helm-v3 {arguments}`: Used only internally in the [cert-manager's](https://cert-manager.io/) Helmfile to
+  facilitate the GitLab Managed Apps adoption.
+- `gl-helmfile {arguments}`: A thin wrapper that triggers the [Helmfile](https://github.com/roboll/helmfile) command.
 
-#### The main [`./helmfile.yml`](https://gitlab.com/gitlab-org/project-templates/cluster-management/-/blob/master/helmfile.yaml)
+#### The main `helmfile.yml` file
 
-This file has a list of paths to other Helmfiles for each app. They're all commented out by default. You must uncomment 
+This file has a list of paths to other Helmfiles for each app. They're all commented out by default, so you must uncomment 
 the paths for the apps that you would like to manage.
 
 By default, each `helmfile.yaml` in these sub-paths will have the attribute `installed: true`, which signifies that everytime
-the pipeline runs, Helmfile will try to either install or update your apps, accordingly to the current state of your
+the pipeline runs, Helmfile will try to either install or update your apps according to the current state of your
 cluster and Helm releases. If you change this attribute to `installed: false`, Helmfile will try to uninstall this app
-from your cluster. Read more about how Helmfile works from their [official repository](https://github.com/roboll/helmfile).
+from your cluster. [Read more](https://github.com/roboll/helmfile) about how Helmfile works.
 
-Also note that, each app in the `./applications/` folder will have a `./applications/{app}/values.yaml` file. This is the 
+Furthermore, each app has an `applications/{app}/values.yaml` file. This is the 
 place where you can define some default values for your app's Helm chart. Some apps will already have defaults
 pre-defined by GitLab.
 
 #### Built-in applications
 
-The list of built-in applications are the same as for the [GitLab Managed Apps CI/CD](https://docs.gitlab.com/13.12/ee/user/clusters/applications.html#install-using-gitlab-cicd-deprecated).
+The built-in applications are intended to provide an easy way to get started with various Kubernetes oriented GitLab features.
 
-### Migrating from GitLab managed apps
+The [built-in supported applications](https://gitlab.com/gitlab-org/project-templates/cluster-management/-/tree/master/applications) are:
 
-If you had GitLab managed apps, either One-Click or CI/CD install, read the docs on how to 
-[migrate from GitLab managed apps to project template](migrating_from_gma_to_project_template.md)
+- Apparmor
+- Cert-manager
+- Cilium
+- Elastic Stack
+- Falco
+- Fluentd
+- GitLab Runner
+- Ingress
+- Prometheus
+- Sentry
+- Vault
+
+### Migrating from GitLab Managed Apps
+
+If you had GitLab Managed Apps, either One-Click or CI/CD install, read the docs on how to 
+[migrate from GitLab Managed Apps to project template](migrating_from_gma_to_project_template.md)

doc/user/clusters/migrating_from_gma_to_project_template.md

@@ -4,35 +4,45 @@ 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
 ---
 
-# Migrating from GitLab managed apps to a [management project tempalte](management_project_template.md)
+# Migrating from GitLab Managed Apps to a management project template
 
-1. Read how the [management project tempalte](management_project_template.md) works.
-1. Create a new project as explained in the [management project tempalte](management_project_template.md).
-1. Detect apps deployed through Helm v2 releases.
+The [GitLab Managed Apps](applications.md) are deprecated in GitLab 14.0. To migrate to the new way of managing them:
 
-   For this, you can use the preconfigured [`.gitlab-ci.yml`](management_project_template.md#the-gitlab-ciyml).
-   In case you had ovewritten the default GitLab managed apps namespace, make sure that the 
-   [`./gl-fail-if-helm2-releases-exist`](management_project_template.md#the-gitlab-ciyml) script is receiving the 
-   correct namespace as an argument. If you kept the default (`gitlab-managed-apps`), then the script is already 
-   setup. So, [run a pipeline manually](../../ci/pipelines/index.md#run-a-pipeline-manually) and read the logs of the
+1. Read how the [management project template](management_project_template.md) works, and
+   create a new project based on the "GitLab Cluster Management" template.
+1. Create a new project as explained in the [management project template](management_project_template.md).
+1. Detect apps deployed through Helm v2 releases by using the pre-configured [`.gitlab-ci.yml`](management_project_template.md#the-gitlab-ciyml-file) file:
+    - In case you had overwritten the default GitLab Managed Apps namespace, edit `.gitlab-ci.yml`,
+      and make sure the script is receiving the correct namespace as an argument:
+
+      ```yaml
+      script:
+        - gl-fail-if-helm2-releases-exist <your_custom_namespace>
+      ```
+
+    - If you kept the default name (`gitlab-managed-apps`), then the script is already
+      set up.
+
+   Either way, [run a pipeline manually](../../ci/pipelines/index.md#run-a-pipeline-manually) and read the logs of the
    `detect-helm2-releases` job to know if you have any Helm v2 releases and which are they.
 
-1. If you have no Helm v2 releases, jump to the next step. Otherwise, follow the official Helm docs on
-   [how to migrate from Helm v2 to Helm v3 and cleanup the
-   Helm v2 releases](https://helm.sh/blog/migrate-from-helm-v2-to-helm-v3/) after you are confident that they have been
-   successfully migrated.
+1. If you have no Helm v2 releases, skip this step. Otherwise, follow the official Helm docs on
+   [how to migrate from Helm v2 to Helm v3](https://helm.sh/blog/migrate-from-helm-v2-to-helm-v3/),
+   and clean up the Helm v2 releases after you are confident that they have been successfully migrated.
+
 1. In this step you should already have only Helm v3 releases.
-   Uncomment from the main [`./helmfile.yaml`](management_project_template.md#the-main-helmfileyml) the paths for the
+   Uncomment from the main [`./helmfile.yaml`](management_project_template.md#the-main-helmfileyml-file) the paths for the
    applications that you would like to manage with this project. Although you could uncomment all the ones you want to
    managed at once, we recommend you repeat the following steps separately for each app, so you do not get lost during
-   the process. So, pick one of your apps and uncomment its `- path: applications/{app}/helmfile.yaml`.
-1. Edit the associated `./applications/{app}/helmfiles.yaml` in this project to match the chart version currently deployed 
+   the process.
+1. Edit the associated `applications/{app}/helmfiles.yaml` to match the chart version currently deployed 
    for your app. Take a GitLab Runner Helm v3 release as an example:
    
    The following command lists the releases and their versions:
 
    ```shell
-   ~> helm ls -n gitlab-managed-apps
+   helm ls -n gitlab-managed-apps
+   
    NAME NAMESPACE REVISION UPDATED STATUS CHART APP VERSION
    runner gitlab-managed-apps 1 2021-06-09 19:36:55.739141644 +0000 UTC deployed gitlab-runner-0.28.0 13.11.0
    ```
@@ -43,38 +53,37 @@ info: To determine the technical writer assigned to the Stage/Group associated w
    Make sure you replace `gitlab-managed-apps` from the above command if you have your apps deployed to a different
    namespace.
 
-1. Edit the `./applications/{app}/values.yaml` associated with your app to match the currently
-   deployed values. E.g. for GitLab Runner:
+1. Edit the `applications/{app}/values.yaml` associated with your app to match the currently
+   deployed values. For example, for GitLab Runner:
+
+    1. Copy the output of the following command (it might be big):
 
-   Copy the output of below the command below, which might be big:
-   
    ```shell
-   ~> helm get values runner -n gitlab-managed-apps -a --output yaml
+   helm get values runner -n gitlab-managed-apps -a --output yaml
    ```
 
-   and overwrite the `./applications/gitlab-runner/values.yaml` with these output of the above command.
+    1. Overwrite `applications/gitlab-runner/values.yaml` with the output of the previous command.
+
    This safe step will guarantee that no unexpected default values overwrite your currently deployed values.
    For instance, your GitLab Runner could have its `gitlabUrl` or `runnerRegistrationToken` overwritten by mistake.
 
-1. Some apps might special conditions
+1. Some apps require special attention:
 
-   Ingress: Because of an existing [chart issue](https://github.com/helm/charts/pull/13646) you might see 
-   `spec.clusterIP: Invalid value` when trying to run the [`./gl-helmfile`](management_project_template.md#the-gitlab-ciyml) 
-   command. To workaround this, after overwriting the release values in your `./applications/ingress/values.yaml`, 
-   you might need to overwrite all the occurrences of `omitClusterIP:false`, setting it to `omitClusterIP: true`. 
-   Another approach, could be to collect these IPs by running the command `kubectl get services -n gitlab-managed-apps`
-   and then overwriting each `ClusterIP` that it complains about with the value you got from that command.
-   
-   Vault: This application introduces a breaking change from the chart we used in Helm v2 to the chart
-   used in Helm v3. So the only way to integrate it with this project is actually to uninstall this app and accept the
-   chart version proposed in `./applications/vault/values.yaml`.
+    - Ingress: Due to an existing [chart issue](https://github.com/helm/charts/pull/13646), you might see
+      `spec.clusterIP: Invalid value` when trying to run the [`./gl-helmfile`](management_project_template.md#the-gitlab-ciyml-file)
+      command. To work around this, after overwriting the release values in `applications/ingress/values.yaml`,
+      you might need to overwrite all the occurrences of `omitClusterIP: false`, setting it to `omitClusterIP: true`.
+      Another approach,could be to collect these IPs by running `kubectl get services -n gitlab-managed-apps`
+      and then overwriting each `ClusterIP` that it complains about with the value you got from that command.
 
-1. Apply the changes
+    - Vault: This application introduces a breaking change from the chart we used in Helm v2 to the chart
+      used in Helm v3. So, the only way to integrate it with this Cluster Management Project is to actually uninstall this app and accept the
+      chart version proposed in `applications/vault/values.yaml`.
 
-   After following all the above steps you could [run a pipeline manually](../../ci/pipelines/index.md#run-a-pipeline-manually)
-   and watch `apply` job logs to see if your applications were successfully detected, installed and if they got any
+1. After following all the previous steps, [run a pipeline manually](../../ci/pipelines/index.md#run-a-pipeline-manually)
+   and watch the `apply` job logs to see if any of your applications were successfully detected, installed, and whether they got any
    unexpected updates.
-
+   
    Some annotation checksums are expected to be updated, as well as this attribute:
 
    ```diff
@@ -83,4 +92,4 @@ info: To determine the technical writer assigned to the Stage/Group associated w
    ```
 
    After getting a successful pipeline, go ahead and repeat these steps for the other apps that you have deployed
-   and would like to manage with this project.
+   and would like to manage with the Cluster Management Project..