From ca760ee24beb9e4add6a937424b17dba5a16f39c Mon Sep 17 00:00:00 2001 From: Clemens Beck Date: Wed, 10 Dec 2025 17:28:16 +0100 Subject: [PATCH 1/6] Docs: Document how to migrate from bundled stateful services * Document how to migrate bundled MinIO to Garage. * Document how to migrate bundled Redis to Valkey. * Document how to migrate bundled PostgreSQL to CloudNativePG. The migration process can be desribed in three phases: 1. Backup the instance. 1. Provision external services and configure GitLab for them. 1. Restore backup into new services. The migration was tested on GKE 1.33 but should be provider agnostic. Closes https://gitlab.com/gitlab-org/charts/gitlab/-/issues/6230 --- doc/advanced/external-db/_index.md | 2 + doc/advanced/external-redis/_index.md | 9 + doc/charts/minio/_index.md | 9 + doc/installation/bundled_chart_migration.md | 220 ++++++++++++++++++++ 4 files changed, 240 insertions(+) create mode 100644 doc/installation/bundled_chart_migration.md diff --git a/doc/advanced/external-db/_index.md b/doc/advanced/external-db/_index.md index a949548211..890f18bba5 100644 --- a/doc/advanced/external-db/_index.md +++ b/doc/advanced/external-db/_index.md @@ -10,6 +10,8 @@ title: Configure the GitLab chart with an external database The bundled bitnami PostgreSQL chart is not production ready. For a production-ready GitLab chart deployment, use an external database. +To migrate from the bundled PostgreSQL chart, check [the migration documentation](../../installation/bundled_chart_migration.md). + {{< /alert >}} Prerequisites: diff --git a/doc/advanced/external-redis/_index.md b/doc/advanced/external-redis/_index.md index 98b90f7312..1d6dc389f1 100644 --- a/doc/advanced/external-redis/_index.md +++ b/doc/advanced/external-redis/_index.md @@ -5,6 +5,15 @@ info: To determine the technical writer assigned to the Stage/Group associated w title: Configure the GitLab chart with an external Redis --- +{{< alert type="warning" >}} + +The bundled bitnami Redis chart is not production ready. For a production-ready GitLab chart deployment, use an +external Valkey or Redis. + +To migrate from the bundled Redis chart, check [the migration documentation](../../installation/bundled_chart_migration.md). + +{{< /alert >}} + This document intends to provide documentation on how to configure this Helm chart with an external Redis service. If you don't have Redis configured, for on-premise or deployment to VM, diff --git a/doc/charts/minio/_index.md b/doc/charts/minio/_index.md index 4170166439..4bd49225d4 100644 --- a/doc/charts/minio/_index.md +++ b/doc/charts/minio/_index.md @@ -12,6 +12,15 @@ title: Using MinIO for Object storage {{< /details >}} +{{< alert type="note" >}} + +The bundled MinIO chart is not production ready. For a production-ready GitLab chart deployment, use an +external object storage solution. + +To migrate from the bundled MinIO chart, check [the migration documentation](../../installation/bundled_chart_migration.md). + +{{< /alert >}} + This chart is based on [`stable/minio`](https://github.com/helm/charts/tree/master/stable/minio) version [`0.4.3`](https://github.com/helm/charts/tree/aaaf98b5d25c26cc2d483925f7256f2ce06be080/stable/minio), and inherits most settings from there. diff --git a/doc/installation/bundled_chart_migration.md b/doc/installation/bundled_chart_migration.md new file mode 100644 index 0000000000..be1eda56e3 --- /dev/null +++ b/doc/installation/bundled_chart_migration.md @@ -0,0 +1,220 @@ +--- +stage: GitLab Delivery +group: Operate +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments +title: Migrate from the bundled Redis, PostgreSQL and MinIO +--- + +{{< details >}} + +- Tier: Free, Premium, Ultimate +- Offering: GitLab Self-Managed + +{{< /details >}} + +This guide explains the basic process of migrating the bundled MinIO, Redis and PostgreSQL to self-managed +alternatives, namely Valkey, CloudNativePG, and Garage. + +_Important:_ Depending on your requirements other solutions might be more appropriate, like a Omnibus-managed +PostgreSQL/Redis or cloud-managed alternatives. Check the [reference architecture](https://docs.gitlab.com/administration/reference_architectures/) +for more information on alternatives. + +GitLab can only provide best-effort support for the components used in this guide. + +1. [Backup](../backup-restore/_index.md) all of the current data and note the backup ID. + +1. Download the backup from the backup bucket to your local machine. + +1. Provision your external Valkey/Redis service. For example using the official [valkey Helm chart](https://github.com/valkey-io/valkey-helm): + + ```shell + helm repo add valkey https://valkey.io/valkey-helm/ + helm install valkey valkey/valkey \ + --set dataStorage.enabled=true \ + --set dataStorage.size=2Gi \ + --set auth.enabled=true \ + --set auth.aclUsers.default.permissions="~* &* +@all" \ + --set auth.aclUsers.default.password=default-password + ``` + +1. Provision your external PostgreSQL service. For example using [CloudNativePG](https://cloudnative-pg.io/documentation/current/installation_upgrade/): + + 1. Install the CloudNativePG Operator: + + ```shell + kubectl apply --server-side -f https://raw.githubusercontent.com/cloudnative-pg/cloudnative-pg/release-1.28/releases/cnpg-1.28.0.yaml + ``` + + 1. Provision a PostgreSQL cluster for GitLab: + + ```yaml + apiVersion: postgresql.cnpg.io/v1 + kind: Cluster + metadata: + name: gitlab-rails-db + namespace: gitlab + spec: + instances: 1 + imageName: ghcr.io/cloudnative-pg/postgresql:17 + storage: + size: 5Gi + bootstrap: + initdb: + database: gitlabhq_production + owner: gitlab + postInitSQL: + - CREATE EXTENSION IF NOT EXISTS pg_trgm; + - CREATE EXTENSION IF NOT EXISTS btree_gist; + - CREATE EXTENSION IF NOT EXISTS plpgsql; + - CREATE EXTENSION IF NOT EXISTS amcheck; + ``` + +1. Provision your external object storage solution, for example [Garage](https://garagehq.deuxfleurs.fr/): + + 1. Install the Garage Helm chart. + + ```shell + helm plugin install https://github.com/aslafy-z/helm-git + helm repo add garage git+https://git.deuxfleurs.fr/Deuxfleurs/garage.git@script/helm?ref=main-v1 + helm install garage garage/garage --set persistence.data.size=5Gi --set persistence.meta.size=250Mi + ``` + + 1. Initialize the cluster layout: + + ```shell + Check node IDs + kubectl exec garage-0 -- /garage status + Assign nodes to gitlab zone + kubectl exec garage-0 -- /garage layout assign -z gitlab -c 5G + ``` + + 1. Create the GitLab buckets + + ```shell + kubectl exec garage-0 -- /garage bucket create git-lfs + kubectl exec garage-0 -- /garage bucket create gitlab-artifacts + kubectl exec garage-0 -- /garage bucket create gitlab-backups + kubectl exec garage-0 -- /garage bucket create gitlab-ci-secure-files + kubectl exec garage-0 -- /garage bucket create gitlab-dependency-proxy + kubectl exec garage-0 -- /garage bucket create gitlab-mr-diffs + kubectl exec garage-0 -- /garage bucket create gitlab-packages + kubectl exec garage-0 -- /garage bucket create gitlab-pages + kubectl exec garage-0 -- /garage bucket create gitlab-terraform-state + kubectl exec garage-0 -- /garage bucket create gitlab-uploads + kubectl exec garage-0 -- /garage bucket create registry + kubectl exec garage-0 -- /garage bucket create runner-cache + kubectl exec garage-0 -- /garage bucket create tmp + ``` + + 1. Create a API key and grant access to the created buckets: + + ```shell + kubectl exec garage-0 -- /garage key create gitlab-app-key + kubectl exec garage-0 -- /garage bucket allow --read --write --key gitlab-app-key git-lfs + kubectl exec garage-0 -- /garage bucket allow --read --write --key gitlab-app-key gitlab-artifacts + kubectl exec garage-0 -- /garage bucket allow --read --write --key gitlab-app-key gitlab-backups + kubectl exec garage-0 -- /garage bucket allow --read --write --key gitlab-app-key gitlab-ci-secure-files + kubectl exec garage-0 -- /garage bucket allow --read --write --key gitlab-app-key gitlab-dependency-proxy + kubectl exec garage-0 -- /garage bucket allow --read --write --key gitlab-app-key gitlab-mr-diffs + kubectl exec garage-0 -- /garage bucket allow --read --write --key gitlab-app-key gitlab-packages + kubectl exec garage-0 -- /garage bucket allow --read --write --key gitlab-app-key gitlab-pages + kubectl exec garage-0 -- /garage bucket allow --read --write --key gitlab-app-key gitlab-terraform-state + kubectl exec garage-0 -- /garage bucket allow --read --write --key gitlab-app-key gitlab-uploads + kubectl exec garage-0 -- /garage bucket allow --read --write --key gitlab-app-key registry + kubectl exec garage-0 -- /garage bucket allow --read --write --key gitlab-app-key runner-cache + kubectl exec garage-0 -- /garage bucket allow --read --write --key gitlab-app-key tmp + ``` + + 1. Create a Secret configuring the object storage access: + + ```shell + cat < Date: Thu, 11 Dec 2025 10:10:28 +0100 Subject: [PATCH 2/6] Add keep annotation to MinIO PVC to avoid accidential data loss Annotation can be toggled with `minio.persistence.keep=true|false`. Defaults to true. --- charts/minio/templates/_helpers.tpl | 11 +- charts/minio/values.yaml | 2 + doc/installation/_index.md | 14 +- doc/installation/bundled_chart_migration.md | 186 +++++++++++--------- 4 files changed, 121 insertions(+), 92 deletions(-) diff --git a/charts/minio/templates/_helpers.tpl b/charts/minio/templates/_helpers.tpl index e66c4581ae..0be6c93c67 100755 --- a/charts/minio/templates/_helpers.tpl +++ b/charts/minio/templates/_helpers.tpl @@ -53,9 +53,14 @@ if there is a shared tls secret for all ingresses. Return the formatted annotations for the PersistentVolumeClaim. */}} {{- define "minio.persistence.annotations" -}} -{{- if .Values.persistence.annotations -}} -{{- toYaml .Values.persistence.annotations -}} -{{- end -}} +{{- $annotations := dict -}} +{{- if .Values.persistence.keep -}} +{{- $_ := set $annotations "helm.sh/resource-policy" "keep" }} +{{- end -}} +{{- with .Values.persistence.annotations -}} +{{- $annotations := merge $annotations . -}} +{{- end -}} +{{- toYaml $annotations -}} {{- end -}} {{/* diff --git a/charts/minio/values.yaml b/charts/minio/values.yaml index 2213836222..0eab22cfa3 100755 --- a/charts/minio/values.yaml +++ b/charts/minio/values.yaml @@ -85,6 +85,8 @@ replicas: 4 ## persistence: enabled: true + # Keep the PVC even after uninstalling in chart. + keep: true ## minio data Persistent Volume Storage Class ## If defined, storageClassName: diff --git a/doc/installation/_index.md b/doc/installation/_index.md index f9742e7f88..e00d0ee516 100644 --- a/doc/installation/_index.md +++ b/doc/installation/_index.md @@ -74,14 +74,16 @@ to use appropriate up-to-date, patched images commensurate with their security r ## Configure the Helm chart to use external stateful data -You can configure the GitLab Helm chart to point to external stateful storage -for items like PostgreSQL, Redis, all non-Git repository storage, and Git repository storage (Gitaly). +For production-gradede deployments, the chart should be configured to point +externalized object storage, Valkey/Redis, PostgreSQL, and Gitaly services that +match with your selected [reference architecture](https://docs.gitlab.com/administration/reference_architectures/). -The following Infrastructure as Code (IaC) options use this approach. +While GitLab chart bundles a MinIO, PostgreSQL, and Redis charts for proof-of-concept +and testing scenarios, these components and charts have experiences several project and +licencing changes upstream impacting our ability to maintain these components. -For production-grade implementation, the appropriate chart parameters should be used to -point to prebuilt, externalized state stores that align with the chosen -[reference architecture](https://docs.gitlab.com/administration/reference_architectures/). +If you are running a production system with one of these bundled charts, please +[migrate](bundled_chart_migration.md) to externalized solutions. ### Use the reference architectures diff --git a/doc/installation/bundled_chart_migration.md b/doc/installation/bundled_chart_migration.md index be1eda56e3..bf5e16b3ed 100644 --- a/doc/installation/bundled_chart_migration.md +++ b/doc/installation/bundled_chart_migration.md @@ -21,21 +21,34 @@ for more information on alternatives. GitLab can only provide best-effort support for the components used in this guide. -1. [Backup](../backup-restore/_index.md) all of the current data and note the backup ID. +## Backup GitLab -1. Download the backup from the backup bucket to your local machine. +First [backup](../backup-restore/_index.md) all of the current data and note the backup ID. +If you are migration of MinIO, you will need to download the backup archive to a local +machine. -1. Provision your external Valkey/Redis service. For example using the official [valkey Helm chart](https://github.com/valkey-io/valkey-helm): +## Provision external services - ```shell - helm repo add valkey https://valkey.io/valkey-helm/ - helm install valkey valkey/valkey \ - --set dataStorage.enabled=true \ - --set dataStorage.size=2Gi \ - --set auth.enabled=true \ - --set auth.aclUsers.default.permissions="~* &* +@all" \ - --set auth.aclUsers.default.password=default-password - ``` +To replace the bundled MinIO, Redis and Valkey charts provision externally managed replacements. +For an overview on the available options check the [recommended providers and services](https://docs.gitlab.com/administration/reference_architectures/#recommended-cloud-providers-and-services) +and make sure they meet the [current minimum requirements](https://docs.gitlab.com/install/requirements/) +are met. + +### Provision external Valkey/Redis + +Provision your external Valkey/Redis service. For example using the official [valkey Helm chart](https://github.com/valkey-io/valkey-helm): + +```shell +helm repo add valkey https://valkey.io/valkey-helm/ +helm install valkey valkey/valkey \ + --set dataStorage.enabled=true \ + --set dataStorage.size=2Gi \ + --set auth.enabled=true \ + --set auth.aclUsers.default.permissions="~* &* +@all" \ + --set auth.aclUsers.default.password=default-password +``` + +### Provision external PostgreSQL 1. Provision your external PostgreSQL service. For example using [CloudNativePG](https://cloudnative-pg.io/documentation/current/installation_upgrade/): @@ -69,89 +82,96 @@ GitLab can only provide best-effort support for the components used in this guid - CREATE EXTENSION IF NOT EXISTS amcheck; ``` -1. Provision your external object storage solution, for example [Garage](https://garagehq.deuxfleurs.fr/): +### Provision external object storage - 1. Install the Garage Helm chart. +Provision your external object storage solution, for example [Garage](https://garagehq.deuxfleurs.fr/): - ```shell - helm plugin install https://github.com/aslafy-z/helm-git - helm repo add garage git+https://git.deuxfleurs.fr/Deuxfleurs/garage.git@script/helm?ref=main-v1 - helm install garage garage/garage --set persistence.data.size=5Gi --set persistence.meta.size=250Mi - ``` +1. Install the Garage Helm chart. - 1. Initialize the cluster layout: + ```shell + helm plugin install https://github.com/aslafy-z/helm-git + helm repo add garage git+https://git.deuxfleurs.fr/Deuxfleurs/garage.git@script/helm?ref=main-v1 + helm install garage garage/garage --set persistence.data.size=5Gi --set persistence.meta.size=250Mi + ``` - ```shell - Check node IDs - kubectl exec garage-0 -- /garage status - Assign nodes to gitlab zone - kubectl exec garage-0 -- /garage layout assign -z gitlab -c 5G - ``` +1. Initialize the cluster layout: - 1. Create the GitLab buckets + ```shell + Check node IDs + kubectl exec garage-0 -- /garage status + Assign nodes to gitlab zone + kubectl exec garage-0 -- /garage layout assign -z gitlab -c 5G + ``` - ```shell - kubectl exec garage-0 -- /garage bucket create git-lfs - kubectl exec garage-0 -- /garage bucket create gitlab-artifacts - kubectl exec garage-0 -- /garage bucket create gitlab-backups - kubectl exec garage-0 -- /garage bucket create gitlab-ci-secure-files - kubectl exec garage-0 -- /garage bucket create gitlab-dependency-proxy - kubectl exec garage-0 -- /garage bucket create gitlab-mr-diffs - kubectl exec garage-0 -- /garage bucket create gitlab-packages - kubectl exec garage-0 -- /garage bucket create gitlab-pages - kubectl exec garage-0 -- /garage bucket create gitlab-terraform-state - kubectl exec garage-0 -- /garage bucket create gitlab-uploads - kubectl exec garage-0 -- /garage bucket create registry - kubectl exec garage-0 -- /garage bucket create runner-cache - kubectl exec garage-0 -- /garage bucket create tmp - ``` +1. Create the GitLab buckets - 1. Create a API key and grant access to the created buckets: + ```shell + kubectl exec garage-0 -- /garage bucket create git-lfs + kubectl exec garage-0 -- /garage bucket create gitlab-artifacts + kubectl exec garage-0 -- /garage bucket create gitlab-backups + kubectl exec garage-0 -- /garage bucket create gitlab-ci-secure-files + kubectl exec garage-0 -- /garage bucket create gitlab-dependency-proxy + kubectl exec garage-0 -- /garage bucket create gitlab-mr-diffs + kubectl exec garage-0 -- /garage bucket create gitlab-packages + kubectl exec garage-0 -- /garage bucket create gitlab-pages + kubectl exec garage-0 -- /garage bucket create gitlab-terraform-state + kubectl exec garage-0 -- /garage bucket create gitlab-uploads + kubectl exec garage-0 -- /garage bucket create registry + kubectl exec garage-0 -- /garage bucket create runner-cache + kubectl exec garage-0 -- /garage bucket create tmp + ``` - ```shell - kubectl exec garage-0 -- /garage key create gitlab-app-key - kubectl exec garage-0 -- /garage bucket allow --read --write --key gitlab-app-key git-lfs - kubectl exec garage-0 -- /garage bucket allow --read --write --key gitlab-app-key gitlab-artifacts - kubectl exec garage-0 -- /garage bucket allow --read --write --key gitlab-app-key gitlab-backups - kubectl exec garage-0 -- /garage bucket allow --read --write --key gitlab-app-key gitlab-ci-secure-files - kubectl exec garage-0 -- /garage bucket allow --read --write --key gitlab-app-key gitlab-dependency-proxy - kubectl exec garage-0 -- /garage bucket allow --read --write --key gitlab-app-key gitlab-mr-diffs - kubectl exec garage-0 -- /garage bucket allow --read --write --key gitlab-app-key gitlab-packages - kubectl exec garage-0 -- /garage bucket allow --read --write --key gitlab-app-key gitlab-pages - kubectl exec garage-0 -- /garage bucket allow --read --write --key gitlab-app-key gitlab-terraform-state - kubectl exec garage-0 -- /garage bucket allow --read --write --key gitlab-app-key gitlab-uploads - kubectl exec garage-0 -- /garage bucket allow --read --write --key gitlab-app-key registry - kubectl exec garage-0 -- /garage bucket allow --read --write --key gitlab-app-key runner-cache - kubectl exec garage-0 -- /garage bucket allow --read --write --key gitlab-app-key tmp - ``` +1. Create a API key and grant access to the created buckets: + + ```shell + kubectl exec garage-0 -- /garage key create gitlab-app-key + kubectl exec garage-0 -- /garage bucket allow --read --write --key gitlab-app-key git-lfs + kubectl exec garage-0 -- /garage bucket allow --read --write --key gitlab-app-key gitlab-artifacts + kubectl exec garage-0 -- /garage bucket allow --read --write --key gitlab-app-key gitlab-backups + kubectl exec garage-0 -- /garage bucket allow --read --write --key gitlab-app-key gitlab-ci-secure-files + kubectl exec garage-0 -- /garage bucket allow --read --write --key gitlab-app-key gitlab-dependency-proxy + kubectl exec garage-0 -- /garage bucket allow --read --write --key gitlab-app-key gitlab-mr-diffs + kubectl exec garage-0 -- /garage bucket allow --read --write --key gitlab-app-key gitlab-packages + kubectl exec garage-0 -- /garage bucket allow --read --write --key gitlab-app-key gitlab-pages + kubectl exec garage-0 -- /garage bucket allow --read --write --key gitlab-app-key gitlab-terraform-state + kubectl exec garage-0 -- /garage bucket allow --read --write --key gitlab-app-key gitlab-uploads + kubectl exec garage-0 -- /garage bucket allow --read --write --key gitlab-app-key registry + kubectl exec garage-0 -- /garage bucket allow --read --write --key gitlab-app-key runner-cache + kubectl exec garage-0 -- /garage bucket allow --read --write --key gitlab-app-key tmp + ``` - 1. Create a Secret configuring the object storage access: +1. Create a Secret configuring the object storage access: - ```shell - cat < Date: Fri, 12 Dec 2025 09:45:23 +0100 Subject: [PATCH 3/6] Document PVC and Secret cleanup --- doc/installation/bundled_chart_migration.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/doc/installation/bundled_chart_migration.md b/doc/installation/bundled_chart_migration.md index bf5e16b3ed..06fc91b5e5 100644 --- a/doc/installation/bundled_chart_migration.md +++ b/doc/installation/bundled_chart_migration.md @@ -238,3 +238,14 @@ PostgreSQL. ```shell helm upgrade gitlab gitlab/gitlab -f your-values.yaml ``` + +1. Confirm GitLab is operational. + +1. Confirm [backups](../backup-restore/backup.md) work as intended by doing a fresh backup. + +1. Delete Secrets and PersistentVolumeClaims related to the bundled PostgreSQL, MinIO, and Redis. + + ```shell + kubectl delete pvc gitlab-minio redis-data-gitlab-redis-master-0 data-gitlab-postgresql-0 + kubectl delete secret gitlab-postgresql-password gitlab-redis-secret gitlab-minio-secret gitlab-minio-tls + ``` -- GitLab From a8e53cf95f94010c5af513464f6de8e1b7844ce9 Mon Sep 17 00:00:00 2001 From: Clemens Beck Date: Fri, 12 Dec 2025 12:17:01 +0100 Subject: [PATCH 4/6] Rephrase scope of this guide --- doc/installation/bundled_chart_migration.md | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) diff --git a/doc/installation/bundled_chart_migration.md b/doc/installation/bundled_chart_migration.md index 06fc91b5e5..51613fffb8 100644 --- a/doc/installation/bundled_chart_migration.md +++ b/doc/installation/bundled_chart_migration.md @@ -12,14 +12,20 @@ title: Migrate from the bundled Redis, PostgreSQL and MinIO {{< /details >}} -This guide explains the basic process of migrating the bundled MinIO, Redis and PostgreSQL to self-managed -alternatives, namely Valkey, CloudNativePG, and Garage. +This guide explains how to migrate from the bundled MinIO, Redis, and PostgreSQL to externally +managed alternatives such as Valkey, CloudNativePG, and Garage. -_Important:_ Depending on your requirements other solutions might be more appropriate, like a Omnibus-managed -PostgreSQL/Redis or cloud-managed alternatives. Check the [reference architecture](https://docs.gitlab.com/administration/reference_architectures/) -for more information on alternatives. +{{< alert type="warning" >}} -GitLab can only provide best-effort support for the components used in this guide. +Depending on your requirements, existing infrastructure, and personal preferences, solutions +other than the self-managed components described in this guide may be more suitable. + +Please evaluate cloud provider services or Omnibus-managed PostgreSQL and Redis as alternatives. +For more information, see the [reference architecture documentation](https://docs.gitlab.com/administration/reference_architectures/). + +Note that GitLab can only offer best-effort support for the components covered in this guide. + +{{< /alert >}} ## Backup GitLab -- GitLab From aa954bd6b29000047aa05c04ce3bf732cbfca848 Mon Sep 17 00:00:00 2001 From: Clemens Beck Date: Fri, 12 Dec 2025 13:33:09 +0100 Subject: [PATCH 5/6] Document conditional steps --- doc/installation/bundled_chart_migration.md | 21 +++++++++++++++------ 1 file changed, 15 insertions(+), 6 deletions(-) diff --git a/doc/installation/bundled_chart_migration.md b/doc/installation/bundled_chart_migration.md index 51613fffb8..357ef977cb 100644 --- a/doc/installation/bundled_chart_migration.md +++ b/doc/installation/bundled_chart_migration.md @@ -30,8 +30,13 @@ Note that GitLab can only offer best-effort support for the components covered i ## Backup GitLab First [backup](../backup-restore/_index.md) all of the current data and note the backup ID. -If you are migration of MinIO, you will need to download the backup archive to a local -machine. + +Please note that: + +- If you are migration of MinIO, you will need to download the backup archive to a local machine. +- If you are only migrating Redis, you can skip the backup and restore steps. +- If you are only migrating PostgreSQL, you can [skip](../backup-restore/backup.md#skipping-components) backing + up all components but the `db`. ## Provision external services @@ -219,27 +224,31 @@ PostgreSQL. install: false ``` -1. Upgrade your GitLab instance with migrations disabled. + Check the related [Redis](../advanced/external-redis/_index.md), [PostgreSQL](../advanced/external-db/_index.md), + and [object storage](../advanced/external-object-storage/_index.md) documentation for more + information. + +1. If you are upgrading PostgreSQL, upgrade your GitLab instance with migrations disabled. ```shell helm upgrade gitlab gitlab/gitlab -f your-values.yaml --set gitlab.migrations.enabled=false ``` -1. Copy your backup to the toolbox and upload it to your new Object Storage. +1. If you are migrating MinIO, copy your backup to the toolbox and upload it to your new object storage. ```shell kubectl cp LOCAL_BACKUP_ARCHIVE.tar TOOLBOX_POD:/tmp s3cmd put /tmp/LOCAL_BACKUP_ARCHIVE.tar s3://gitlab-backups/ ``` -1. [Restore the backup](../backup-restore/restore.md): +1. If you are migrarting PostgreSQL or MinIO, [restore the backup](../backup-restore/restore.md): ```shell kubectl exec -ti TOOLBOX_POD -- bash backup-utility --restore -t BACKUP_ID ``` -1. Upgrade your GitLab instance with migrations enabled. +1. Upgrade your GitLab instance. ```shell helm upgrade gitlab gitlab/gitlab -f your-values.yaml -- GitLab From f583831d570967f3573be97ff3b184e9914bf526 Mon Sep 17 00:00:00 2001 From: Clemens Beck Date: Fri, 12 Dec 2025 13:56:31 +0100 Subject: [PATCH 6/6] Add warning for metadata DB --- doc/installation/bundled_chart_migration.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/doc/installation/bundled_chart_migration.md b/doc/installation/bundled_chart_migration.md index 357ef977cb..f8fb5aba29 100644 --- a/doc/installation/bundled_chart_migration.md +++ b/doc/installation/bundled_chart_migration.md @@ -37,6 +37,8 @@ Please note that: - If you are only migrating Redis, you can skip the backup and restore steps. - If you are only migrating PostgreSQL, you can [skip](../backup-restore/backup.md#skipping-components) backing up all components but the `db`. +- If you enabled the [Registry Metadata Database](https://docs.gitlab.com/administration/packages/container_registry_metadata_database/) + the metadata data will not be covered by the default backup/restore process. ## Provision external services -- GitLab