GitLab Managed Apps was a feature of the platform’s Kubernetes integration that provided one-click installation of common cluster apps. This iteration of the feature was deprecated during the GitLab 13 release cycle and removed entirely in June’s 14.0 release. Here’s how to migrate your Managed Apps to a supported deployment model.
Moving Away From Managed Apps
Managed Apps were developed as a way to simplify getting up and running with a new Kubernetes cluster. GitLab provided templates for applications such as NGINX Ingress, Cert Manager and Prometheus.
Two different installation methods were offered: one-click and CI/CD. The one-click method provided a UI within GitLab that listed available apps and let you click to install. Some apps also exposed basic configuration settings. The CI/CD method offered a GitLab CI template to add apps to a cluster as part of a pipeline.
One-click installs are now gone altogether. The CI method remains functional but is deprecated and will be removed in GitLab 15.0. Although Managed Apps drastically simplified installation, they only catered for this stage of the cluster’s lifecycle. Apps were either installed or uninstalled, so you’d quickly need to move to regular Kubernetes management tools to perform maintenance and customization.
Despite the feature’s removal, existing Managed App installs will continue to function in GitLab 14.0. You can safely upgrade GitLab without worrying about downtime in your cluster. Upgrading will remove the Managed Apps UI though, so you’ll be unable to view or uninstall apps from within GitLab.
Gaining Control of Your Apps
Migrating away from Managed Apps doesn’t necessarily require any immediate action on your part. As your apps will remain operational, you can leave them as-is if you’re happy with them staying in the gitlab-managed-apps namespace.
As the apps are simply Helm deployments in your cluster, you can manage them using the kubectl and Helm command-line binaries. They’ll show up as regular Kubernetes resources.
You can list cluster resources which were installed by GitLab using this Kubectl command:
kubectl get all -n gitlab-managed-apps
This lets you check what’s running in your cluster in the absence of GitLab’s old “Applications” page.
You might encounter issues with apps installed by old GitLab versions. These may have been added using Helm v2, which isn’t compatible with modern Helm v3 clients. If you’re not sure whether you’ve got v2 apps installed, use the following command to check:
kubectl get all -n gitlab-managed-apps | grep 'helm.sh/release'
Apps which are shown in this command’s output were installed by Helm v3. Compare the list against the earlier get all command to identify apps added by Helm v2.
If it turns out your apps are using Helm v2, you’ll need to manually walk-through the Helm migration guide to bring them up-to-date. It’s recommended you move to Helm v3 if you’ll be retaining the apps long-term. As an alternative, installing Helm v2 on your machine will let you interact with the apps to apply immediate fixes and maintenance.
Upgrading to GitLab’s New Cluster Apps Model
The overriding objective of Managed Apps – simplifying cluster setup – hasn’t been completely cast aside by GitLab. GitLab 14.0 focuses on cluster “management projects” as a new deployment model for cluster provisioning.
GitLab provides a project template which you can use to install apps into Kubernetes clusters. This addresses the original issues with Managed Apps by ensuring you’ve got full control over the Helm charts which are deployed. You clone the template, connect the project to your cluster, then edit and delete the individual app charts as necessary. Running a CI pipeline will deploy the selected apps to your cluster.
You can migrate existing Managed Apps to the management project format. This lets you continue operating them using a GitLab-endorsed approach. We’ll assume you’ve already got a Kubernetes cluster connected to your GitLab instance, by virtue of your existing deployments.
Begin by creating a new GitLab project using the plus button in the top-right. Click “Create from template”, then scroll down to the “GitLab Cluster Management” template. Click the “Use template” button. On the next screen, give your project a name and press “Create project.”
The template provides a series of Helm charts to deploy apps into your cluster. The individual app charts are stored in the applications directory. Each app gets its own subdirectory.#
Begin by editing helmfile.yaml in the root of your project, either in the GitLab Web IDE or by cloning the repository using Git. This file references the individual application templates. Enable the applications you’re using by uncommenting the relevant lines. In this example, we’ve previously installed Ingress and Cert Manager as GitLab Managed Apps, so we’re enabling them in the cluster management project.
Next you need to work out which chart version is already deployed to your cluster. This step is important so you don’t unintentionally replace your app with a different version.
You can get an app’s version by running helm ls -n gitlab-managed-apps. Look for the app in the output table and note down the version displayed in the CHART column. This will take the format app-name-X.Y.Z; you only need the X.Y.Z part.
Return to your new GitLab project and open the helmfile.yaml associated with the application, such as applications/ingress/helmfile.yaml. Change the version field to match the version you noted down.
Finally, replace the default values.yaml with your existing set of Helm values. Use Helm to load the YAML representation of your app’s values file:
helm get values ingress -n gitlab-managed-apps -a --output yaml
Substitute ingress with the name of your app’s deployment. Copy the entire YAML output and use it to overwrite the applications/ingress/values.yaml file. Make sure to adjust the file path to match your app. Now you’re ready to run the cluster management project deployment.
A deployment pipeline will start automatically when you merge your changes into the default branch (which is usually main for new projects in GitLab 14.0). Use Git to commit your changes and merge them in:
git checkout -b my-branch git add . git commit -m "Migrate existing GitLab Managed Apps" git checkout main git merge my-branch git push -u origin main
The pipeline will run. If the template changes were correct, there should be no impact on your running applications. Some harmless metadata might be modified as the deployment mechanism changes.
You’re now ready to use the cluster management project for the ongoing maintenance of your apps. As an example, you could update to a new version of an app by editing the version field in its helmfile.yaml. Merging the change into main would prompt Helm to apply the changes inside your cluster.
Conclusion
GitLab Managed Apps helped many users to take their first steps with Kubernetes. The feature’s simplicity ultimately proved too limiting though, so it’s now being removed in a multi-step process.
Fortunately, it’s quite straightforward to complete your migration away from Managed Apps. There’s nothing special about them – they’re simply regular Helm deployments which happen to live in your cluster’s gitlab-managed-apps namespace. This means your workloads will remain available even if you upgrade to GitLab 14.0, leaving you free to transition at your own pace.
Moving forwards, cluster management projects are the preferred approach for using GitLab to install popular apps on Kubernetes. While a little more technically demanding, this model gives you much more control and helps you manage your infrastructure as code.
