From a5f4bba440d7f9ea47046a0a561d49adf0a1e6d4 Mon Sep 17 00:00:00 2001 From: GitLab Bot Date: Wed, 16 Jun 2021 18:25:58 +0000 Subject: Add latest changes from gitlab-org/gitlab@14-0-stable-ee --- doc/user/clusters/management_project_template.md | 86 ++++++++++++++++++++++++ 1 file changed, 86 insertions(+) create mode 100644 doc/user/clusters/management_project_template.md (limited to 'doc/user/clusters/management_project_template.md') diff --git a/doc/user/clusters/management_project_template.md b/doc/user/clusters/management_project_template.md new file mode 100644 index 00000000000..52390cb18b0 --- /dev/null +++ b/doc/user/clusters/management_project_template.md @@ -0,0 +1,86 @@ +--- +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. 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 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 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) + 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` 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 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 + 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'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` file + +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 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](https://github.com/roboll/helmfile) about how Helmfile works. + +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 built-in applications are intended to provide an easy way to get started with various Kubernetes oriented GitLab features. + +The [built-in supported applications](https://gitlab.com/gitlab-org/project-templates/cluster-management/-/tree/master/applications) are: + +- 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) -- cgit v1.2.1