Skip to content

GitLab

Migrating from GitLab Managed Apps to a management project template

The GitLab Managed Apps are deprecated in GitLab 14.0. To migrate to the new way of managing them:

  1. Read how the management project template works, and create a new project based on the "GitLab Cluster Management" template.

  2. Create a new project as explained in the management project template.

  3. Detect apps deployed through Helm v2 releases by using the pre-configured .gitlab-ci.yml file:

    • In case you had overwritten the default GitLab Managed Apps namespace, edit .gitlab-ci.yml, and make sure the script is receiving the correct namespace as an argument:

      script:
  - gl-fail-if-helm2-releases-exist <your_custom_namespace>

    • If you kept the default name (gitlab-managed-apps), then the script is already set up.

    Either way, run a pipeline manually and read the logs of the detect-helm2-releases job to know if you have any Helm v2 releases and which are they.

  4. If you have no Helm v2 releases, skip this step. Otherwise, follow the official Helm docs on how to migrate from Helm v2 to Helm v3, and clean up the Helm v2 releases after you are confident that they have been successfully migrated.

  5. In this step you should already have only Helm v3 releases. Uncomment from the main ./helmfile.yaml the paths for the applications that you would like to manage with this project. Although you could uncomment all the ones you want to managed at once, we recommend you repeat the following steps separately for each app, so you do not get lost during the process.

  6. Edit the associated applications/{app}/helmfiles.yaml to match the chart version currently deployed for your app. Take a GitLab Runner Helm v3 release as an example:

    The following command lists the releases and their versions:

    helm ls -n gitlab-managed-apps

NAME NAMESPACE REVISION UPDATED STATUS CHART APP VERSION
runner gitlab-managed-apps 1 2021-06-09 19:36:55.739141644 +0000 UTC deployed gitlab-runner-0.28.0 13.11.0

    Take the version from the CHART column which is in the format {release}-v{chart_version}, then edit the version: attribute in the ./applications/gitlab-runner/helmfile.yaml, so that it matches the version you have currently deployed. This is a safe step to avoid upgrading versions during this migration. Make sure you replace gitlab-managed-apps from the above command if you have your apps deployed to a different namespace.

  7. Edit the applications/{app}/values.yaml associated with your app to match the currently deployed values. For example, for GitLab Runner:

    1. Copy the output of the following command (it might be big):
    helm get values runner -n gitlab-managed-apps -a --output yaml
    1. Overwrite applications/gitlab-runner/values.yaml with the output of the previous command.

    This safe step will guarantee that no unexpected default values overwrite your currently deployed values. For instance, your GitLab Runner could have its gitlabUrl or runnerRegistrationToken overwritten by mistake.

  8. Some apps require special attention:

    • Ingress: Due to an existing chart issue, you might see spec.clusterIP: Invalid value when trying to run the ./gl-helmfile command. To work around this, after overwriting the release values in applications/ingress/values.yaml, you might need to overwrite all the occurrences of omitClusterIP: false, setting it to omitClusterIP: true. Another approach,could be to collect these IPs by running kubectl get services -n gitlab-managed-apps and then overwriting each ClusterIP that it complains about with the value you got from that command.

    • Vault: This application introduces a breaking change from the chart we used in Helm v2 to the chart used in Helm v3. So, the only way to integrate it with this Cluster Management Project is to actually uninstall this app and accept the chart version proposed in applications/vault/values.yaml.

  9. After following all the previous steps, run a pipeline manually and watch the apply job logs to see if any of your applications were successfully detected, installed, and whether they got any unexpected updates.

    Some annotation checksums are expected to be updated, as well as this attribute:

    --- heritage: Tiller
+++ heritage: Tiller

After getting a successful pipeline, repeat these steps for any other deployed apps you want to manage with the Cluster Management Project.