Gitlab跨版本升级

以下是我进行升级时的情境说明

  • Gitlab安装方式为Omnibus安装【就是一个rpm或deb包安装的】
  • 节点操作系统是Debian11
  • 安装方式为单节点
  • 当前版本是Gitlab-ce 13.3.1
  • 目标版本是Gitlab-ce 14.8.2

创建升级计划

本文档可作为创建强大计划以升级自我管理 GitLab 实例的指南。

一般注意事项：

  • 如果可能，我们建议您在更新生产实例之前在测试环境中测试升级。理想情况下，您的测试环境应该尽可能地模仿您的生产环境。
  • 如果与支持部门 合作创建您的计划，请分享您的架构的详细信息，包括：
    • GitLab 是如何安装的？【不同的安装方式升级方式不完全相同】
    • 节点的操作系统是什么？（检查不再支持的操作系统版本以确认以后的更新可用）。
    • 是单节点还是多节点设置？如果是多节点，请与我们分享有关每个节点的任何架构细节。
    • 你在使用GitLab Geo吗？如果是这样，请分享有关每个辅助节点的任何架构细节。
    • 您的设置中还有哪些可能对我们理解很重要的独特或有趣的东西？
    • 您当前版本的 GitLab 是否遇到任何已知问题？

升级前和升级后检查

  1. 检查一般配置：gitlab-rake gitlab:check
  2. 确认可以解密加密的数据库值：gitlab-rake gitlab:doctor:secrets
  3. 在Gitlab UI中检查：
    • 用户可以登录。
    • 项目列表可见。
    • 可以访问项目问题和合并请求。
    • 用户可以从 GitLab 克隆存储库。
    • 用户可以将提交推送到 GitLab。
  4. 对于CI/CD检查：
    • Runner是否正常
    • Docker镜像可以正常推送拉取
  5. 如果使用Geo，请在主节点和每个辅助节点上运行相关检查：gitlab-rake gitlab:geo:check
  6. 如果使用 Elasticsearch，请验证搜索是否成功。

我的Debian没有sudo，根据自己的情况选择命令是否需要sudo执行,后续命令依旧如此

我的实际情况只需要对1-4项进行检查

回滚计划

升级过程中可能会出现问题，因此为该场景提供回滚计划至关重要。适当的回滚计划创建了一条清晰的路径，可以将实例恢复到其最后的工作状态。它由一种备份实例的方法和一种恢复它的方法组成。

备份Gitlab

备份Gitlab

GitLab 提供了用于备份和恢复 GitLab 实例的 Rake 任务。

应用程序数据备份会创建一个包含数据库、所有存储库和所有附件的存档文件。

您只能将备份恢复到与 创建它的 GitLab 完全相同的版本和类型 (CE/EE) 。将项目从一台服务器迁移到另一台服务器的最佳方式是通过备份和恢复。

Gitlab提供了一个命令行接口来备份你的整个Gitlab实例，备份内容包括：

  • 数据库
  • 附件
  • Git 存储库数据
  • CI/CD 工作日志
  • CI/CD 工作制品
  • LFS 对象
  • Terrraform状态（14.7新增）
  • Container Registry images
  • GitLab Pages content
  • 包(14.7新增)
  • Snippets
  • Group wikis

不包括：

根据您的 GitLab 版本，如果您使用 Omnibus 包安装了 GitLab，请使用以下命令：

  • Gitlab12.2或更高版本：gitlab-backup create
  • Gitlab12.1或更早版本：gitlab-rake gitlab:backup:create

备份时间戳

备份存档保存在文件config/gitlab.yml中指定的 backup_path中。文件名是[TIMESTAMP]_gitlab_backup.tar，其中TIMESTAMP标识每个备份的创建时间，加上 GitLab 版本。如果您需要恢复 GitLab 并且有多个备份可用，则需要时间戳。

例如，如果备份名称为1493107454_2018_04_25_10.6.4-ce_gitlab_backup.tar，则时间戳为1493107454_2018_04_25_10.6.4-ce。

虽然文档所备份路径配置是在config/gitlab.yml文件中，不过实际上应该是在/etc/gitlab/gitlab.rb中，配置项为gitlab_rails['backup_path'] = "/var/opt/gitlab/backups",默认应该是被注释掉的，不过也没关系，默认就是/var/opt/gitlab/backups

存储配置文件

命令行提供的备份不包括配置文件。主要原因是您的数据库包含的项目包括用于双重身份验证的加密信息和 CI/CD安全变量。将加密信息存储在与其密钥相同的位置首先违背了使用加密的目的。

对于使用包进行安装的实例，备份时应该至少将以下文件备份：

  • /etc/gitlab/gitlab-secrets.json
  • /etc/gitlab/gitlab.rb

Omnibus GitLab的所有配置都存储在/etc/gitlab. 要备份您的配置，只需运行gitlab-ctl backup-etc（在 GitLab 12.3 中引入）。它会在/etc/gitlab/config_backup/目录下生成一个tar包. 目录和备份文件只有root才能读取。

关于gitlab-secrets.json，我的建议是一定要备份。尤其是在使用了runner或者配置了cicd之类的时候。从实际经验看，会造成runner页面500，管理员设置在保存时500。官方文档中提到过关于丢失secrets-file的解决办法，不过可能由于解决500问题时尝试了错误的方式，导致在我这里官方文档的解决办法并没有用。不过依然有参考价值：
when-the-secrets-file-is-lost：https://docs.gitlab.com/ee/raketasks/backup_restore.html#when-the-secrets-file-is-lost

gitlab.rb是主配置文件
gitlab-secrets.json是一些加密信息，如果丢失的话，使用二次验证登录的用户会无法登录，Gitlab CI中的安全变量也会丢失

对于我来说只需要备份gitlab.rb和gitlab-secrets.json即可

更多的和备份相关的信息可以看:
这里 : https://docs.gitlab.com/omnibus/settings/backups.html
还有
这里 : https://docs.gitlab.com/ee/raketasks/backup_restore.html

恢复Gitlab

GitLab 提供了一个命令行工具来恢复您的整个安装，并且足够灵活以满足您的需求。
您只能将备份恢复到与您创建它的 GitLab完全相同的版本和类型 (CE/EE)（例如 CE 9.1.0）。
如果您的备份与当前安装的版本不同，则需要安装相同版本的Gitlab进行恢复

恢复先决条件

您需要先安装有效的 GitLab，然后才能执行还原。这是因为恢复用的用户(git)通常没有创建或删除SQL数据库的权限来导入必要的数据(gitlabhq_production)

对于包安装的Gitlab，/etc/gitlab/gitlab-secrets.json必须恢复。此文件包含数据库加密密钥、 CI/CD 变量和用于双重身份验证的变量。如果您无法将此加密密钥文件与应用程序数据备份一起还原，则启用了双重身份验证且 GitLab Runner 的用户将失去对 GitLab 服务器的访问权限。

要恢复备份，您必须恢复/etc/gitlab/gitlab-secrets.json （对于 Omnibus 包）或/home/git/gitlab/.secret（对于从源安装）。此文件包含数据库加密密钥、 CI/CD 变量和用于双重身份验证的变量。如果您无法将此加密密钥文件与应用程序数据备份一起还原，则启用了双重身份验证且 GitLab Runner 的用户将失去对 GitLab 服务器的访问权限。

对于包安装的Gitlab，可能还想要恢复/etc/gitlab/gitlab.rb。

从 GitLab 12.9 开始，如果找到未解压缩的备份（如使用 制作的备份 SKIP=tar），并且没有选择使用BACKUP=<timestamp>的备份，则使用未解压缩的备份。

根据您的情况，您可能希望使用以下一个或多个选项运行 restore 命令：

  • BACKUP=timestamp_of_backup：如果存在多个备份，则需要指定恢复哪个备份。
  • force=yes：不询问是否应该重新生成authorized_keys 文件，并假定“是”以警告有关删除数据库表、启用“写入authorized_keys 文件”设置和更新LDAP 提供程序。

如果要还原到作为挂载点的目录，则必须在尝试还原之前确保这些目录为空。否则，GitLab 会在恢复新数据之前尝试移动这些目录，这会导致错误。

恢复包安装的Gitlab

确保满足以下条件：

  • 要恢复的Gitlab版本与备份的版本完全相同
  • 至少运行过一次gitlab-ctl reconfigure
  • Gitlab正在运行。如果没有使用gitlab-ctl start

首先确保您的备份 tar 文件位于 gitlab.rb 配置gitlab_rails['backup_path']中描述的备份目录中。默认值为 /var/opt/gitlab/backups. 且git用户要拥有权限

1
2
cp 11493107454_2018_04_25_10.6.4-ce_gitlab_backup.tar /var/opt/gitlab/backups/
chown git:git /var/opt/gitlab/backups/11493107454_2018_04_25_10.6.4-ce_gitlab_backup.tar

停止连接到数据库的进程。让 GitLab 的其余部分继续运行：

1
2
3
4
gitlab-ctl stop puma
gitlab-ctl stop sidekiq
# 验证
gitlab-ctl status

不过有可能你的连接程序不是puma，可以通过gitlab-ctl status来确认，如果使用的是unicorn,也有可能这两个组件都有,就执行：

1
2
3
4
5
gitlab-ctl stop unicorn
gitlab-ctl stop puma
gitlab-ctl stop sidekiq

gitlab-ctl status

接下来，恢复备份，指定要恢复的备份的时间戳：

1
sudo gitlab-backup restore BACKUP=11493107454_2018_04_25_10.6.4-ce

GitLab 12.1 及更早版本的用户应改用该命令gitlab-rake gitlab:backup:restore。可能会出现一些已知的错误。

如果您的备份 tar 文件与已安装的 GitLab 版本之间存在 GitLab 版本不匹配，则恢复命令将中止并显示错误消息。

接下来，如果有必要的话，恢复/etc/gitlab/gitlab-secrets.json和/etc/gitlab/gitlab.rb

重新配置、重启、检查Gitlab：

1
2
3
gitlab-ctl reconfigure
gitlab-ctl restart
gitlab-rake gitlab:check SANITIZE=true

在 GitLab 13.1 及更高版本中，检查数据库值可以被正确解密，特别是对/etc/gitlab/gitlab-secrets.json进行了恢复

1
gitlab-rake gitlab:doctor:secrets

为了增加保证，您可以对上传的文件执行完整性检查：

1
2
3
gitlab-rake gitlab:artifacts:check
gitlab-rake gitlab:lfs:check
gitlab-rake gitlab:uploads:check

确定升级路径

必须停机才可以一次升级多个Gitlab版本。

在下面的升级路径中找到您的版本所在的位置，并相应地升级 GitLab，同时咨询 特定于版本的升级说明：

8.11.Z -> 8.12.0 -> 8.17.7 -> 9.5.10 -> 10.8.7 -> 11.11.8 -> 12.0.12 -> 12.1.17 -> 12.10.14 -> 13.0.14 -> 13.1.11 -> 13.8.8 -> 13.12.15 -> 14.0.12 -> 14.9.0 -> 14.10.Z -> 15.0.Z -> latest 15.Y.Z

下表虽然并不详尽，但显示了一些受支持升级路径的示例。上述版本之间的附加步骤是可能的。我们仅列出最低限度的必要步骤。

目标版本 你的版本 支持的升级路径 笔记
14.6.2 13.10.2 13.10.2-> 13.12.15-> 14.0.12->14.6.2 需要两个中间版本：13.12和14.0，然后14.6.2。
14.1.8 13.9.2 13.9.2-> 13.12.15-> 14.0.12->14.1.8 需要两个中间版本：13.12和14.0，然后14.1.8。
13.12.15 12.9.2 12.9.2-> 12.10.14-> 13.0.14-> 13.1.11-> 13.8.8->13.12.15 需要四个中间版本：12.10、和13.0、然后。 13.1``13.8.8``13.12.15
13.2.10 11.5.0 11.5.0-> 11.11.8-> 12.0.12-> 12.1.17-> 12.10.14-> 13.0.14-> 13.1.11->13.2.10 需要六个中间版本：11.11, 12.0, 12.1, 12.10,13.0和13.1, then 13.2.10。
12.10.14 11.3.4 11.3.4-> 11.11.8-> 12.0.12-> 12.1.17->12.10.14 需要三个中间版本：11.11、12.0和12.1、 然后12.10.14。
12.9.5 10.4.5 10.4.5-> 10.8.7-> 11.11.8-> 12.0.12-> 12.1.17->12.9.5 需要四个中间版本：10.8、和11.11、然后。 12.0``12.1``12.9.5
12.2.5 9.2.6 9.2.6-> 9.5.10-> 10.8.7-> 11.11.8-> 12.0.12-> 12.1.17->12.2.5 需要五个中间版本：9.5, 10.8, 11.11, 12.0, 和12.1, then 12.2.5。
11.3.4 8.13.4 8.13.4-> 8.17.7-> 9.5.10-> 10.8.7->11.3.4 8.17.7是版本 89.5.10中的最后一个版本，是版本 910.8.7中的最后一个版本，是版本 10 中的最后一个版本。

这个表看起来有点头皮发麻，其实有个简单的看法，就是别管下边的的表格。只看上边的路径即可,把当前版本号往路径里放，然后按照所在位置后边的路径升级即可。比如我现在版本是13.3.1那么我后边最近的版本就是 13.8.8 ，那么下一个版本就升级到13.8.8然后13.12.15然后14.0.12最后是最新的14.8.2。如果你的版本不尽相同，可以参考这条路线，然后在测试环境测试之后确定升级路径。

准备安装程序

所有版本的安装包可以在这里进行下载，官方提供了rpm和deb格式的安装包。注意架构，别像我一样安装时才发现下载了一堆arm的.

下载路径在详情页右上角，有个小的Download的按钮，右下方wget位置也有直链。

安装

安装就简单了，根据自己的平台，使用rpm -i或者dpkg -i按照升级路径逐个进行安装即可。不过在跨大版本号的时候先看下下面的内容。

强烈建议，每成功升级一个版本之后，都基于升级后的版本进行一次备份。升级路径越长该操作越有必要。至于为什么我就不解释了吧。

必须要注意的事情

unicorn切换到puma

从 GitLab 13.0 开始，Puma 是默认的 Web 服务器，并且 Unicorn 已被禁用。
在 GitLab 14.0 中，Unicorn 已从 Linux 包中删除，不再受支持。
注意这两句话是不一样的：
第一句的意思是在13这个版本中，Unicorn虽然已经被禁用，但还能用。在配置中开启即可。
第二句的意思是在14这个版本中，已经不存在Unicorn这个东西了。

这个带来的影响是，如果你打算升级到14，那么在升级路径上13版本这个阶段，必须将Unicorn完全切换到Puma，注意不是禁用，是所有和Unicorn相关的配置都必须删除。下面是官方文档的切换指南：

从 Unicorn 切换到 Puma：

  1. 确定合适的 Puma worker 和 thread 设置。

  2. 将任何自定义 Unicorn 设置转换为 Puma。

    下表总结了在使用 Linux 包时，哪些 Unicorn 配置键与 Puma 中的配置键对应，哪些没有对应的配置键。

    独角兽 彪马
    unicorn['enable'] puma['enable']
    unicorn['worker_timeout'] puma['worker_timeout']
    unicorn['worker_processes'] puma['worker_processes']
    不适用 puma['ha']
    不适用 puma['min_threads']
    不适用 puma['max_threads']
    unicorn['listen'] puma['listen']
    unicorn['port'] puma['port']
    unicorn['socket'] puma['socket']
    unicorn['pidfile'] puma['pidfile']
    unicorn['tcp_nopush'] 不适用
    unicorn['backlog_socket'] 不适用
    unicorn['somaxconn'] puma['somaxconn']
    不适用 puma['state_path']
    unicorn['log_directory'] puma['log_directory']
    unicorn['worker_memory_limit_min'] 不适用
    unicorn['worker_memory_limit_max'] puma['per_worker_max_memory_mb']
    unicorn['exporter_enabled'] puma['exporter_enabled']
    unicorn['exporter_address'] puma['exporter_address']
    unicorn['exporter_port'] puma['exporter_port']

  3. 重新配置 GitLab：

    1
    gitlab-ctl reconfigure

  4. 可选的。对于多节点部署，将负载均衡器配置为使用 就绪检查。

数据库迁移

在成功升级到14之后的第一个版本之后，不要着急进行下一步，因为有任务可能没有完成。如果你已经升级并且碰到了下面这个问题，回滚重来吧。

1
2
3
4
StandardError: An error has occurred, all later migrations canceled:

Expected batched background migration for the given configuration to be marked as 'finished', but it is 'active':
  {:job_class_name=>"CopyColumnUsingBackgroundMigrationJob", :table_name=>"push_event_payloads", :column_name=>"event_id", :job_arguments=>[["event_id"], ["event_id_convert_to_bigint"]]}

为了避免上述问题，参照下面的步骤：

  1. 检查数据库中批处理后台迁移的状态，并使用适当的参数手动运行它们，直到状态查询不返回任何行。

  2. 当所有这些状态都标记为完成时，重新运行您的安装迁移。

  3. 从 GitLab 升级 完成数据库迁移：

    1
    gitlab-rake db:migrate

  4. 运行重新配置：

    1
    gitlab-ctl reconfigure

  5. 完成安装的升级。

上边是官方文档中的步骤，简单说明下就是：

  1. 在升级到14之后的第一个版本执行gitlab-rake db:migrate:status检查后台数据是否迁移完成。其中完成的状态为up，未完成的为down。
  2. 如果没有完成，则执行gitlab-rake db:migrate这个命令手动完成迁移。
  3. 执行gitlab-ctl reconfigure
  4. 继续升级过程

提醒：如果你有数据迁移没有完成，那么在执行 gitlab-rake db:migrate 之后可以从Gitlab UI的 管理员 –> 监控 –> 后台迁移页面看到相关队列。地址的话就是：http://GITLAB_HOST/admin/background_migrations

最后：祝你好运

  1. Plan your upgrade ↩
  2. backup_restore ↩
  3. backup ↩
  4. update ↩
  5. puma ↩
  6. maintenance ↩
  7. background_migrations ↩
Cloud
Linux 容器 Gitlab

本博客所有文章除特别声明外，均采用 CC BY-SA 4.0 协议 ，转载请注明出处！