diff options
Diffstat (limited to 'doc/user/clusters/applications.md')
| -rw-r--r-- | doc/user/clusters/applications.md | 82 |
1 files changed, 70 insertions, 12 deletions
diff --git a/doc/user/clusters/applications.md b/doc/user/clusters/applications.md index 4e0e2991acb..67a53fa773f 100644 --- a/doc/user/clusters/applications.md +++ b/doc/user/clusters/applications.md @@ -64,21 +64,35 @@ supported by GitLab before installing any of the applications. > - Introduced in GitLab 10.2 for project-level clusters. > - Introduced in GitLab 11.6 for group-level clusters. > - [Uses a local Tiller](https://gitlab.com/gitlab-org/gitlab/-/issues/209736) in GitLab 13.2 and later. +> - [Uses Helm 3](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/46267) for clusters created with GitLab 13.6 and later. [Helm](https://helm.sh/docs/) is a package manager for Kubernetes and is used to install the GitLab-managed apps. GitLab runs each `helm` command in a pod within the `gitlab-managed-apps` namespace inside the cluster. -GitLab's integration uses Helm 2 with a local -[Tiller](https://v2.helm.sh/docs/glossary/#tiller) server for managing -applications. Prior to [GitLab 13.2](https://gitlab.com/gitlab-org/gitlab/-/issues/209736), -GitLab used an in-cluster Tiller server in the `gitlab-managed-apps` -namespace. This server can now be safely removed. +- For clusters created on GitLab 13.6 and newer, GitLab uses Helm 3 to manage + applications. +- For clusters created on versions of GitLab prior to 13.6, GitLab uses + Helm 2 with a local [Tiller](https://v2.helm.sh/docs/glossary/#tiller) server. + Prior to [GitLab 13.2](https://gitlab.com/gitlab-org/gitlab/-/issues/209736), + GitLab used an in-cluster Tiller server in the `gitlab-managed-apps` + namespace. You can safely remove this server after upgrading to GitLab 13.2 + or newer. GitLab's Helm integration does not support installing applications behind a proxy, but a [workaround](../../topics/autodevops/index.md#install-applications-behind-a-proxy) is available. +#### Upgrade a cluster to Helm 3 + +GitLab does not currently offer a way to migrate existing application management +on existing clusters from Helm 2 to Helm 3. To migrate a cluster to Helm 3: + +1. Uninstall all applications on your cluster. +1. [Remove the cluster integration](../project/clusters/add_remove_clusters.md#removing-integration). +1. [Re-add the cluster](../project/clusters/add_remove_clusters.md#existing-kubernetes-cluster) as + an existing cluster. + ### cert-manager > Introduced in GitLab 11.6 for project- and group-level clusters. @@ -93,7 +107,7 @@ The chart used to install this application depends on the version of GitLab used - GitLab 12.3 and newer, the [`jetstack/cert-manager`](https://github.com/jetstack/cert-manager) chart is used with a [`values.yaml`](https://gitlab.com/gitlab-org/gitlab/blob/master/vendor/cert_manager/values.yaml) file. -- GitLab 12.2 and older, the [`stable/cert-manager`](https://gi2wthub.com/helm/charts/tree/master/stable/cert-manager) +- GitLab 12.2 and older, the [`stable/cert-manager`](https://github.com/helm/charts/tree/master/stable/cert-manager) chart was used. If you installed cert-manager prior to GitLab 12.3, Let's Encrypt @@ -625,10 +639,13 @@ To install applications using GitLab CI/CD: - template: Managed-Cluster-Applications.gitlab-ci.yml ``` - The job provided by this template connects to the cluster using tools provided + The job provided by this template connects to the `*` (default) cluster using tools provided in a custom Docker image. It requires that you have a runner registered with the Docker, Kubernetes, or Docker Machine executor. + To install to a specific cluster, read + [Use the template with a custom environment](#use-the-template-with-a-custom-environment). + 1. Add a `.gitlab/managed-apps/config.yaml` file to define which applications you would like to install. Define the `installed` key as `true` to install the application and `false` to uninstall the @@ -647,6 +664,47 @@ applications you have configured. In case of pipeline failure, the output of the [Helm Tiller](https://v2.helm.sh/docs/install/#running-tiller-locally) binary is saved as a [CI job artifact](../../ci/pipelines/job_artifacts.md). +For GitLab versions 13.5 and below, the Ingress, Fluentd, Prometheus, +and Sentry apps are fetched from the central Helm [stable +repository](https://kubernetes-charts.storage.googleapis.com/), which +will be [deleted](https://github.com/helm/charts#deprecation-timeline) +on November 13, 2020. This will cause the installation CI/CD pipeline to +fail. Upgrade to GitLab 13.6, or alternatively, you can +use the following `.gitlab-ci.yml`, which has been tested on GitLab +13.5: + +```yaml +include: + - template: Managed-Cluster-Applications.gitlab-ci.yml + +apply: + image: "registry.gitlab.com/gitlab-org/cluster-integration/cluster-applications:v0.34.1" +``` + +### Use the template with a custom environment + +If you only want apps to be installed on a specific cluster, or if your cluster's +scope does not match `production`, you can override the environment name in your `.gitlab-ci.yml` +file: + +```yaml +include: + - template: Managed-Cluster-Applications.gitlab-ci.yml + +apply: + except: + variables: + - '$CI_JOB_NAME == "apply"' + +.managed-apps: + extends: apply + +example-install: + extends: .managed-apps + environment: + name: example/production +``` + ### Important notes Note the following: @@ -717,7 +775,7 @@ certManager: You can customize the installation of cert-manager by defining a `.gitlab/managed-apps/cert-manager/values.yaml` file in your cluster management project. Refer to the -[chart](https://hub.helm.sh/charts/jetstack/cert-manager) for the +[chart](https://github.com/jetstack/cert-manager) for the available configuration options. Support for installing the Cert Manager managed application is provided by the @@ -797,7 +855,7 @@ least 2 people from the ### Install PostHog using GitLab CI/CD -[PostHog](https://www.posthog.com) 🦔 is a developer-friendly, open-source product analytics platform. +[PostHog](https://posthog.com) 🦔 is a developer-friendly, open-source product analytics platform. To install PostHog into the `gitlab-managed-apps` namespace of your cluster, define the `.gitlab/managed-apps/config.yaml` file with: @@ -954,15 +1012,15 @@ CAUTION: **Caution:** Installation and removal of the Cilium requires a **manual** [restart](https://docs.cilium.io/en/stable/gettingstarted/k8s-install-gke/#restart-unmanaged-pods) of all affected pods in all namespaces to ensure that they are -[managed](https://docs.cilium.io/en/stable/troubleshooting/#ensure-pod-is-managed-by-cilium) +[managed](https://docs.cilium.io/en/v1.8/operations/troubleshooting/#ensure-managed-pod) by the correct networking plugin. NOTE: **Note:** Major upgrades might require additional setup steps. For more information, see -the official [upgrade guide](https://docs.cilium.io/en/stable/install/upgrade/). +the official [upgrade guide](https://docs.cilium.io/en/v1.8/operations/upgrade/). By default, Cilium's -[audit mode](https://docs.cilium.io/en/v1.8/gettingstarted/policy-creation/?highlight=policy-audit#enable-policy-audit-mode) +[audit mode](https://docs.cilium.io/en/v1.8/gettingstarted/policy-creation/#enable-policy-audit-mode) is enabled. In audit mode, Cilium doesn't drop disallowed packets. You can use `policy-verdict` log to observe policy-related decisions. You can disable audit mode by adding the following to |