Adds Cluster Management Project Template docs

- Explains how to use the Project Template
- Adds doc on how to migrate from GMA

doc/user/clusters/applications.md

@@ -26,7 +26,8 @@ learn how to proceed to keep your apps up and running:
 - [CI/CD template method](#install-using-gitlab-cicd-deprecated)
 
 NOTE:
-Despite being deprecated, the recommended way for installing GitLab integrated applications is by the GitLab CI/CD method presented below. We are working on a [cluster management project template](https://gitlab.com/gitlab-org/gitlab/-/issues/327908) with a simple upgrade path from the CI/CD based method.
+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)
 

doc/user/clusters/integrations.md

@@ -14,6 +14,10 @@ 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.
+
 ## Prometheus cluster integration
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/55244) in GitLab 13.11.

doc/user/clusters/management_project.md

@@ -16,7 +16,7 @@ privileges.
 
 This can be useful for:
 
-- Creating pipelines to install cluster-wide applications into your cluster, see [Install using GitLab CI/CD (beta)](applications.md#install-using-gitlab-cicd-deprecated) for details.
+- Creating pipelines to install cluster-wide applications into your cluster, see [management project template](management_project_template.md) for details.
 - Any jobs that require `cluster-admin` privileges.
 
 ## Permissions

doc/user/clusters/management_project_template.md

+---
+stage: Configure
+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
+---
+
+# Cluster Management Project Template **(FREE)**
+
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/25318) in GitLab 12.10 with Helmfile support via Helm v2.
+> - [Improved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/63577) in GitLab 14.0 with Helmfile support via Helm v3 instead, and a much more flexible usage of Helmfile. This introduces breaking changes that are detailed below.
+
+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
+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).
+
+### Components
+
+In the repo 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.
+
+#### The [`.gitlab-ci.yml`](https://gitlab.com/gitlab-org/project-templates/cluster-management/-/blob/master/.gitlab-ci.yml)
+
+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:
+
+- `./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 
+  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.
+
+#### The main [`./helmfile.yml`](https://gitlab.com/gitlab-org/project-templates/cluster-management/-/blob/master/helmfile.yaml)
+
+This file has a list of paths to other Helmfiles for each app. They're all commented out by default. 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
+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).
+
+Also note that, each app in the `./applications/` folder will have a `./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).
+
+### 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

+---
+stage: Configure
+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)
+
+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.
+
+   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
+   `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. 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
+   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 
+   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
+   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
+   ```
+
+   Take the version from the `CHART` column which is in the format `{release}-v{chart_version}`,
+   then edit the `version:` attribute in the `./applications/gitlab-runner/helmfile.yaml`, so that it matches the version
+   you have currently deployed. This is a safe step to avoid upgrading versions during this migration.
+   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:
+
+   Copy the output of below the command below, which might be big:
+   
+   ```shell
+   ~> 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.
+   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
+
+   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`.
+
+1. Apply the changes
+
+   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
+   unexpected updates.
+
+   Some annotation checksums are expected to be updated, as well as this attribute:
+
+   ```diff
+   --- heritage: Tiller
+   +++ heritage: Tiller
+   ```
+
+   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.