1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
|
---
stage: Configure
group: Configure
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
---
# Migrate from GitLab Managed Apps to Cluster Management Projects **(FREE)**
The [GitLab Managed Apps](applications.md) were deprecated in GitLab 14.0
in favor of [Cluster Management Projects](management_project.md).
Managing your cluster applications through a project enables you a
lot more flexibility to manage your cluster than through the late GitLab Managed Apps.
To migrate to the cluster management project you need
[GitLab Runners](../../ci/runners/index.md)
available and be familiar with [Helm](https://helm.sh/).
## Migrate to a Cluster Management Project
To migrate from GitLab Managed Apps to a Cluster Management Project,
follow the steps below.
See also [video walk-throughs](#video-walk-throughs) with examples.
1. Create a new project based on the [Cluster Management Project template](management_project_template.md#create-a-new-project-based-on-the-cluster-management-template).
1. [Associate your new Cluster Management Project with your cluster](management_project.md#associate-the-cluster-management-project-with-the-cluster).
1. Detect apps deployed through Helm v2 releases by using the pre-configured [`.gitlab-ci.yml`](management_project_template.md#the-gitlab-ciyml-file) 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:
```yaml
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](../../ci/pipelines/index.md#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.
1. 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](https://helm.sh/blog/migrate-from-helm-v2-to-helm-v3/),
and clean up the Helm v2 releases after you are confident that they have been successfully migrated.
1. In this step you should already have only Helm v3 releases.
Uncomment from the main [`./helmfile.yaml`](management_project_template.md#the-main-helmfileyml-file) 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.
1. 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:
```shell
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.
1. 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):
```shell
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.
1. Some apps require special attention:
- Ingress: Due to an existing [chart issue](https://github.com/helm/charts/pull/13646), you might see
`spec.clusterIP: Invalid value` when trying to run the [`./gl-helmfile`](management_project_template.md#the-gitlab-ciyml-file)
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`.
- Cert-manager:
- For users on Kubernetes version 1.20 or above, the deprecated cert-manager v0.10 is no longer valid and
and the upgrade includes a breaking change. So we suggest that you [backup and uninstall cert-manager v0.10](#backup-and-uninstall-cert-manager-v010)
, and install cert-manager v1.4 instead. To install this version, uncomment the `applications/cert-manager-1-4/helmfile.yaml`
from the [`./helmfile.yaml`](management_project_template.md#the-main-helmfileyml-file).
This triggers a pipeline to install the new version.
- For users on Kubernetes versions lower than 1.20, you can stick to v0.10 by uncommenting
`applications/cert-manager/helmfile.yaml`
in your project's main Helmfile ([`./helmfile.yaml`](management_project_template.md#the-main-helmfileyml-file)).
1. After following all the previous steps, [run a pipeline manually](../../ci/pipelines/index.md#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:
```diff
--- 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.
## Backup and uninstall cert-manager v0.10
1. Follow the [official docs](https://docs.cert-manager.io/en/release-0.10/tasks/backup-restore-crds.html) on how to
backup your cert-manager v0.10 data.
1. Uninstall cert-manager by editing the setting all the occurrences of `installed: true` to `installed: false` in the
`applications/cert-manager/helmfile.yaml` file.
1. Search for any left-over resources by executing the following command `kubectl get Issuers,ClusterIssuers,Certificates,CertificateRequests,Orders,Challenges,Secrets,ConfigMaps -n gitlab-managed-apps | grep certmanager`.
1. For each of the resources found in the previous step, delete them with `kubectl delete -n gitlab-managed-apps {ResourceType} {ResourceName}`.
For example, if you found a resource of type `ConfigMap` named `cert-manager-controller`, delete it by executing:
`kubectl delete configmap -n gitlab-managed-apps cert-manager-controller`.
## Video walk-throughs
You can watch these videos with examples on how to migrate from GMA to a Cluster Management project:
- [Migrating from scratch using a brand new cluster management project](https://youtu.be/jCUFGWT0jS0). Also covers Helm v2 apps migration.
- [Migrating from an existing GitLab managed apps CI/CD project](https://youtu.be/U2lbBGZjZmc).
|
