gitlab-org--gitlab-foss/doc/user/clusters/applications.md

GitLab Managed Apps

GitLab provides GitLab Managed Apps, a one-click install for various applications which can be added directly to your configured cluster.

These applications are needed for Review Apps and deployments when using Auto DevOps.

You can install them after you create a cluster.

Installing applications

Applications managed by GitLab will be installed onto the gitlab-managed-apps namespace.

This namespace:

• Is different from the namespace used for project deployments.
• Is created once.
• Has a non-configurable name.

To see a list of available applications to install:

1. For a:
   • Project-level cluster, navigate to your project's Operations > Kubernetes.
   • Group-level cluster, navigate to your group's Kubernetes page.

Install Helm first as it's used to install other applications.

NOTE: Note: As of GitLab 11.6, Helm will be upgraded to the latest version supported by GitLab before installing any of the applications.

The following applications can be installed:

• Helm
• Ingress
• Cert-Manager
• Prometheus
• GitLab Runner
• JupyterHub
• Knative

With the exception of Knative, the applications will be installed in a dedicated namespace called gitlab-managed-apps.

NOTE: Note: Some applications are installable only for a project-level cluster. Support for installing these applications in a group-level cluster is planned for future releases. For updates, see the issue tracking progress.

CAUTION: Caution: If you have an existing Kubernetes cluster with Helm already installed, you should be careful as GitLab cannot detect it. In this case, installing Helm via the applications will result in the cluster having it twice, which can lead to confusion during deployments.

Helm

• Available for project-level clusters since GitLab 10.2.
• Available for group-level clusters since GitLab 11.6.

Helm is a package manager for Kubernetes and is required to install all the other applications. It is installed in its own pod inside the cluster which can run the helm CLI in a safe environment.

Cert-Manager

• Available for project-level clusters since GitLab 11.6.
• Available for group-level clusters since GitLab 11.6.

Cert-Manager is a native Kubernetes certificate management controller that helps with issuing certificates. Installing Cert-Manager on your cluster will issue a certificate by Let's Encrypt and ensure that certificates are valid and up-to-date.

NOTE: Note: The jetstack/cert-manager chart is used to install this application with a values.yaml file. Prior to GitLab 12.3, the stable/cert-manager chart was used.

GitLab Runner

• Available for project-level clusters since GitLab 10.6.
• Available for group-level clusters since GitLab 11.10.

GitLab Runner is the open source project that is used to run your jobs and send the results back to GitLab. It is used in conjunction with GitLab CI/CD, the open-source continuous integration service included with GitLab that coordinates the jobs. When installing the GitLab Runner via the applications, it will run in privileged mode by default. Make sure you read the security implications before doing so.

NOTE: Note: The runner/gitlab-runner chart is used to install this application with a values.yaml file.

Ingress

• Available for project-level clusters since GitLab 10.2.
• Available for group-level clusters since GitLab 11.6.

Ingress can provide load balancing, SSL termination, and name-based virtual hosting. It acts as a web proxy for your applications and is useful if you want to use Auto DevOps or deploy your own web apps.

NOTE: Note: The stable/nginx-ingress chart is used to install this application with a values.yaml file.

JupyterHub

• Available for project-level clusters since GitLab 11.0.
• Available for group-level clusters since GitLab 12.3.

JupyterHub is a multi-user service for managing notebooks across a team. Jupyter Notebooks provide a web-based interactive programming environment used for data analysis, visualization, and machine learning.

Authentication will be enabled only for project members for project-level clusters and group members for group-level clusters with Developer or higher access to the associated project or group.

We use a custom Jupyter image that installs additional useful packages on top of the base Jupyter. You will also see ready-to-use DevOps Runbooks built with Nurtch's Rubix library.

More information on creating executable runbooks can be found in our Runbooks documentation. Note that Ingress must be installed and have an IP address assigned before JupyterHub can be installed.

NOTE: Note: The jupyter/jupyterhub chart is used to install this application with a values.yaml file.

Jupyter Git Integration

Introduced in GitLab 12 for project-level clusters.

When installing JupyterHub onto your Kubernetes cluster, JupyterLab's Git extension is automatically provisioned and configured using the authenticated user's:

• Name.
• Email.
• Newly created access token.

JupyterLab's Git extension enables full version control of your notebooks as well as issuance of Git commands within Jupyter. Git commands can be issued via the Git tab on the left panel or via Jupyter's command line prompt.

NOTE: Note: JupyterLab's Git extension stores the user token in the JupyterHub DB in encrypted format and in the single user Jupyter instance as plain text. This is because Git requires storing credentials as plain text. Potentially, if a nefarious user finds a way to read from the file system in the single user Jupyter instance they could retrieve the token.

You can clone repositories from the files tab in Jupyter:

Knative

• Available for project-level clusters since GitLab 11.5.
• Available for group-level and instance-level clusters since GitLab 12.3.

Knative provides a platform to create, deploy, and manage serverless workloads from a Kubernetes cluster. It is used in conjunction with, and includes Istio to provide an external IP address for all programs hosted by Knative.

You will be prompted to enter a wildcard domain where your applications will be exposed. Configure your DNS server to use the external IP address for that domain. For any application created and installed, they will be accessible as <program_name>.<kubernetes_namespace>.<domain_name>. This will require your kubernetes cluster to have RBAC enabled.

NOTE: Note: The knative/knative chart is used to install this application.

Prometheus

• Available for project-level clusters since GitLab 10.4.
• Available for group-level clusters since GitLab 11.11.

Prometheus is an open-source monitoring and alerting system useful to supervise your deployed applications.

NOTE: Note: The stable/prometheus chart is used to install this application with a values.yaml file.

Upgrading applications

Introduced in GitLab 11.8.

The applications below can be upgraded.

Application	GitLab version
Runner	11.8+

To upgrade an application:

1. For a:
   • Project-level cluster, navigate to your project's Operations > Kubernetes.
   • Group-level cluster, navigate to your group's Kubernetes page.
2. Select your cluster.
3. If an upgrade is available, the Upgrade button is displayed. Click the button to upgrade.

NOTE: Note: Upgrades will reset values back to the values built into the runner chart plus the values set by values.yaml

Uninstalling applications

Introduced in GitLab 11.11.

The applications below can be uninstalled.

Application	GitLab version	Notes
Cert-Manager	12.2+	The associated private key will be deleted and cannot be restored. Deployed applications will continue to use HTTPS, but certificates will not be renewed. Before uninstalling, you may wish to back up your configuration or revoke your certificates
GitLab Runner	12.2+	Any running pipelines will be canceled.
Helm	12.2+	The associated Tiller pod will be deleted and cannot be restored.
Ingress	12.1+	The associated load balancer and IP will be deleted and cannot be restored. Furthermore, it can only be uninstalled if JupyterHub is not installed.
JupyterHub	12.1+	All data not committed to GitLab will be deleted and cannot be restored.
Knative	12.1+	The associated IP will be deleted and cannot be restored.
Prometheus	11.11+	All data will be deleted and cannot be restored.

To uninstall an application:

1. For a:
   • Project-level cluster, navigate to your project's Operations > Kubernetes.
   • Group-level cluster, navigate to your group's Kubernetes page.
2. Select your cluster.
3. Click the Uninstall button for the application.

Support for uninstalling all applications is planned for progressive rollout. To follow progress, see the relevant epic.

Troubleshooting applications

Applications can fail with the following error:

Error: remote error: tls: bad certificate

To avoid installation errors:

• Before starting the installation of applications, make sure that time is synchronized between your GitLab server and your Kubernetes cluster.

• Ensure certificates are not out of sync. When installing applications, GitLab expects a new cluster with no previous installation of Helm.

  You can confirm that the certificates match via kubectl:

  kubectl get configmaps/values-content-configuration-ingress -n gitlab-managed-apps -o \
  "jsonpath={.data['cert\.pem']}" | base64 -d > a.pem
  kubectl get secrets/tiller-secret -n gitlab-managed-apps -o "jsonpath={.data['ca\.crt']}" | base64 -d > b.pem
  diff a.pem b.pem