summaryrefslogtreecommitdiff
path: root/doc/user/clusters/applications.md
diff options
context:
space:
mode:
Diffstat (limited to 'doc/user/clusters/applications.md')
-rw-r--r--doc/user/clusters/applications.md82
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