[分享] 如何从GitLab CE/EE升级到极狐GitLab JH版本

如何从GitLab CE/EE升级到极狐GitLab JH版本

1. 概述

如果您目前使用的是GitLab EE版本,需要先把GitLab EE升级至与GitLab JH相同的版本(如14.1.2),然后从GitLab EE升级到相同版本的GitLab JH版。升级后您原来GitLab EE版本的License将不再有效,需要在升级后导入GitLab JH的License。

如果您目前使用的是GitLab CE版本,需要先升级到与GitLab CE相同版本号的GitLab EE,然后参照GitLab EE的升级步骤进行升级。

因此,您可以参考GitLab官方文档 Upgrading GitLab了解升级的操作步骤及注意事项。本升级指引基于官方文档整理,从GitLab EE升级至GitLab JH版并没有特殊的操作步骤、特殊需要注意的事项。

通常情况下,升级GitLab是一个相对比较简单的过程,但也会因为您现有版本的安装方式、GitLab的版本比较老、是否与外部系统集成(如ElasticSearch)、您是否基于GitLab API进行过定制化开发等原因变得复杂。不过不用担心,您在升级过程中都可以寻求GitLab Inc.或极狐GitLab的技术支持团队的帮助,我们将帮助您顺利完成从GitLab EE版本到GitLab JH版的升级工作。

1.1 本指引适用范围

根据您目前GitLab CE/EE的部署方式,判断本升级指引是否适用。

1.2 升级前须知

请阅读下面的要点,它将帮助您了解升级过程中的注意事项:

  1. 根据您目前GitLab CE/EE的版本,了解正确的升级路径。如果您目前的GitLab CE/EE版本不是14.X,您将需要进行多次升级。请在升级前根据指引选择正确的升级路径,升级路径请参见后续章节。

  2. 根据升级路径,如果您的GitLab CE/EE实例需要进行多次升级,在进行下一次主版本升级之前请确保当前版本的后台迁移已经完成。后续章节的升级指引将对这部分内容进行介绍。

  3. 如果您的GitLab CE/EE实例整合了Elasticsearch,在进行下一次主版本升级之前请确保Elasticsearch的高级搜索迁移已经完成。后续章节的升级指引将对这部分内容进行介绍。

  4. 如果您的GitLab CE/EE实例关联了GitLab Runner,请确保将GitLab Runner升级到与GitLab最接近的版本。

  5. 如果您的应用基于目前GitLab CE/EE版本的API进行了定制化开发或调用,请务必在升级之前在测试环境中先对应用与极狐GitLab JH版进行兼容性测试,避免升级后出现问题。

2. 升级前准备

2.1 确定升级路径

GitLab版本号的命名规则是<主版本号>.<次版本号>.<修正版本号>。根据历史版本的实际情况,GitLab提供了一个版本升级路线图:

8.11.Z8.12.08.17.79.5.1010.8.711.11.812.0.1212.1.1712.10.1413.0.1413.1.1113.8.8latest 13.12.Zlatest 14.0.Z14.1.Zlatest 14.Y.Z

注意:

  • 如果您目前GitLab的版本不在上述路径节点中,请先升级到最临近的一个次版本上,然后按照推荐的升级路径进行升级。
  • 升级路线图中的节点都不能跳过。例外情况: 如果您只有一个Web服务节点(GitLab Rails),可以跳过版本13.1.11
  • 从您目前的版本往升级路径的某个版本升级时,同一个主版本号下的次版本或修正版本间升级是安全的,而且只需要一次升级操作。

请参见下面的例子:

  • 如果当前GitLab版本是14.0.1,升级路径为: 14.0.1 → 14.0.9 → 14.1.2 → GitLab JH 14.1.2
  • 如果当前GitLab版本是13.2.8,升级路径为: 13.2.8 → 13.8.8 → 13.12.11 → 14.0.9 → 14.1.2 → GitLab JH 14.1.2
  • 如果当前GitLab版本是12.9.2,升级路径为:`12.9.2 → 12.10.14 → 13.0.14 → 13.1.11 → 13.8.8 → 13.12.11 → 14.0.9 → 14.1.2 → GitLab JH 14.1.2
  • 如果当前GitLab版本是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.8.8 → 13.12.11 → 14.0.9 → 14.1.2 → GitLab JH 14.1.2

您也可以通过官方文档了解更多相关内容:

2.2 了解特定版本的注意事项及发行说明

在确定您的GitLab升级路径后,请了解升级过程中特定版本的注意事项及发行说明,相关链接如下:

2.3 何时从GitLab EE升级到GitLab JH

当您按照上述升级路径将GitLab EE升级到14.1.0或以上版本时,即可以进行GitLab EE到JH的版本切换操作。

注意:切换EE版本到JH版本时,原有的GitLab EE License会自动移除,需要您使用GitLab JH的License重新激活。添加License的菜单位于Admin Area → Subscription → Upload New License.

2.4 如何从GitLab CE升级到GitLab JH

您可以先从GitLab CE升级到相同版本的GitLab EE,然后按升级路径升级GitLab EE,最后切换到目标GitLab JH版本。

3. 升级操作步骤

3.1 资料备份

在进行升级操作前建议对GitLab进行备份,详细的备份说明请参见Back up and restore GitLab
以下小节是关于备份操作的说明。

3.1.1 数据备份

进入https://<your_gitlab_domain>/admin,查看当前Gitlab版本。

  • 如果是GitLab 12.2 或更新版本:

    sudo gitlab-backup create STRATEGY=copy
    
  • 如果是GitLab 12.1 或更旧版本:

    gitlab-rake gitlab:backup:create STRATEGY=copy
    

注意: 上述命令采用Copy策略进行数据备份,请确保您的磁盘空间至少要大于/opt/gitlab/目录空间的一倍,以免由于空间不足造成备份失败。备份选项包括:

更多的备份选项参见备份选项

3.1.2 配置备份

在Omnibus GitLab 中所有的配置保存在/etc/gitlab。

  • 如果是GitLab 12.3 或更高版本,请执行:

    sudo gitlab-ctl backup-etc <DIRECTORY>
    

    若不指定DIRECTORY,GitLab会自动创建/etc/gitlab/config_backup/ 保存配置的备份文件。

  • 如果是GitLab 12.2 或更低版本,请手工备份/etc/gitlab目录下文件

    tar -cvf gitlab-config.tar /etc/gitlab/
    

注意:请不要将配置的备份与数据的备份保存在一起,以免数据泄露。

3.1.3 SSH秘钥备份

机器的SSH主机密钥保存在/etc/ssh/中。如果需要执行整个机器的还原,请备份这些密钥

3.2 后台迁移任务

为了确保升级的顺利进行,您必须确认后台迁移任务均为0时,才可以开始升级。根据您当前版本的不同,参见以下两种不同的操作方式来查看后台迁移任务数:

  1. 如果您的GitLab EE版本为12.9或更新版本,执行如下命令:
sudo gitlab-rails runner -e production 'puts Gitlab::BackgroundMigration.remaining'
  1. 如果您的GitLab EE版本为12.8或更旧版本

先进入Rails console:

sudo gitlab-rails c

然后,在Rails console中执行如下命令:

puts Sidekiq::Queue.new("background_migration").size
Sidekiq::ScheduledSet.new.select { |r| r.klass == 'BackgroundMigrationWorker' }.size

如果后台迁移卡住未能完成,可以通过以下命令重新执行后台迁移命令:

# Start the rails console
sudo gitlab-rails c

# Execute the following in the rails console
scheduled_queue = Sidekiq::ScheduledSet.new
pending_job_classes = scheduled_queue.select { |job| job["class"] == "BackgroundMigrationWorker" }.map { |job| job["args"].first }.uniq
pending_job_classes.each { |job_class| Gitlab::BackgroundMigration.steal(job_class) }

3.3 ElasticSearch迁移任务(可选)

如果您已经启用了Elasticsearch整合,某些主版本需要确保ES迁移已完成,才能开始升级。通过执行以下命令可以找到是否有未完成的迁移任务:

sudo gitlab-rake gitlab:elastic:list_pending_migrations

如果Elasticsearch迁移被卡住一直未能完成,请参见 Retry a halted migration

3.4 Omnibus GitLab升级

根据您使用的linux系统发行版的不同,升级命令稍有不同。请根据您使用的Linux发行版参见对应的操作步骤:

3.4.1 在Debian/Ubuntu上升级Omnibus GitLab

1. 升级方式一(手工下载安装包)
1) 下载升级包

您可以从官方网站下载对应发行版的安装包:

2) 跳过备份(可选)

升级时会自动对GitLab进行数据备份,如果您已经对GitLab进行备份,则在每个版本时可以跳过自动备份。跳过备份可直接创建/etc/gitlab/skip-auto-backup空文件,如:

sudo touch /etc/gitlab/skip-auto-backup
3) 执行Omnibus GitLab安装包
  • 检查当前安装版本:
sudo apt-cache policy gitlab-ee | grep Installed
Installed: 13.8.0-ee.0
  • 手动升级
# Debian/Ubuntu
dpkg -i gitlab-ee-<version>.deb
2. 升级方式二(在线升级)
1)跳过备份(可选)

升级时会自动对GitLab进行数据备份,如果您已经对GitLab进行备份,则在每个版本时可以跳过自动备份。跳过备份可直接创建/etc/gitlab/skip-auto-backup空文件,如:

sudo touch /etc/gitlab/skip-auto-backup
2)在包管理器中找到您的GitLab版本
sudo apt-cache madison gitlab-ee
3)指定版本在线升级

以gitlab-ee-12.0.12-ee.0为例:

sudo apt install gitlab-ee=12.0.12-ee.0

注意:

  • 如果之前不是通过包管理器安装的,需要先设置仓库

    curl https://packages.gitlab.com/install/repositories/gitlab/gitlab-ee/script.deb.sh | sudo bash
    
  • 最后升级到极狐GitLab JH版本时,请使用手工下载安装包方式。

3.4.2 在CentOS 7中升级Omnibus GitLab

1. 升级方式一(手工下载安装包)
1) 下载升级包

您可以从官方网站下载对应发行版的安装包:

2) 跳过备份(可选)

升级时会自动对GitLab进行数据备份,如果您已经对GitLab进行备份,则在每个版本时可以跳过自动备份。跳过备份可直接创建/etc/gitlab/skip-auto-backup空文件,如:

sudo touch /etc/gitlab/skip-auto-backup
3) 执行Omnibus GitLab安装包
  • 检查当前安装版本:
sudo rpm -q gitlab-ee
  • 手动升级
# CentOS/RHEL
rpm -Uvh gitlab-ee-<version>.rpm
2. 升级方式二(在线升级)
1)跳过备份(可选)

升级时会自动对GitLab进行数据备份,如果您已经对GitLab进行备份,则在每个版本时可以跳过自动备份。跳过备份可直接创建/etc/gitlab/skip-auto-backup空文件,如:

sudo touch /etc/gitlab/skip-auto-backup
2)在包管理器中找到您的GitLab版本
yum --showduplicates list gitlab-ee
3)指定版本在线升级

以gitlab-ee-12.0.12-ee.0为例:

yum install gitlab-ee-12.0.12-ee.0.el7

注意:

  • 最后升级到极狐GitLab JH版本时,请使用手工下载安装包方式。

3.4.3 在CentOS 8中升级Omnibus GitLab

1. 升级方式一(手工下载安装包)
1) 下载升级包

您可以从官方网站下载对应发行版的安装包:

2) 跳过备份(可选)

升级时会自动对GitLab进行数据备份,如果您已经对GitLab进行备份,则在每个版本时可以跳过自动备份。跳过备份可直接创建/etc/gitlab/skip-auto-backup空文件,如:

sudo touch /etc/gitlab/skip-auto-backup
3) 执行Omnibus GitLab安装包
  • 检查当前安装版本:
sudo rpm -q gitlab-ee
  • 手动升级
# CentOS/RHEL
rpm -Uvh gitlab-ee-<version>.rpm
2. 升级方式二(在线升级)
1)跳过备份(可选)

升级时会自动对GitLab进行数据备份,如果您已经对GitLab进行备份,则在每个版本时可以跳过自动备份。跳过备份可直接创建/etc/gitlab/skip-auto-backup空文件,如:

sudo touch /etc/gitlab/skip-auto-backup
2)在包管理器中找到您的GitLab版本
dnf search gitlab-ee*
3)指定版本在线升级

以gitlab-ee-12.0.12-ee.0为例:

dnf install gitlab-ee-12.0.12-ee.0.el8

注意:

  • 最后升级到极狐GitLab JH版本时,请使用手工下载安装包方式。

3.5 GitLab Runner升级

如果您的GitLab关联了GitLab Runner,那么在升级GitLab之后,也需要将GitLab Runner的版本升级到与GitLab最接近的版本。根据您安装GitLab Runner方式的不同,参见对应的升级操作步骤:

3.5.1 在Debian/Ubuntu上升级GitLab Runner

1. 添加官方的Gitlab仓库
curl -L "https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh" | sudo bash
2. 在包管理器中找到您的GitLab Runner版本
apt-cache madison gitlab-runner

请您选择与GitLab版本最接近的GitLab Runner版本。

3. 指定版本在线升级
export GITLAB_RUNNER_DISABLE_SKEL=true; sudo -E apt-get install gitlab-runner=xx.y.z

3.5.2 在CentOS 7上升级GitLab Runner

1. 添加官方的Gitlab仓库
curl -L "https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.rpm.sh" | sudo bash
2. 在包管理器中找到您的GitLab Runner版本
yum list gitlab-runner --showduplicates | sort -r

请您选择与GitLab版本最接近的GitLab Runner版本。

3. 指定版本在线升级
export GITLAB_RUNNER_DISABLE_SKEL=true; sudo -E yum install gitlab-runner-xx.y.z-1

3.5.3 在GitLab中集成的Kubernetes上升级GitLab Runner

在GitLab中集成的Kubernetes上可以一键升级Gitlab Runner。
操作步骤:
进入Admin area → Kubernetes → 点击kubernetes实例名 → 点击Applications标签页 → 在GitLab Runner组件上点击update即可。

3.5.4 GitLab Runner升级注意事项

升级runner后,/home/gitlab-runner/如果存在.bash_logout,会造成pipeline报错:No such file or directory,请删除.bash_logout文件,即可。

4. 注意事项

4.1 CentOS系统升级Gitlab的注意事项

  1. CentOS7官方镜像自带的yum仓库源不包括新版本的Ruby和Git,需要手动添加:

    • 通过asdf安装ruby,使用asdf安装ruby需要在当前目录中创建版本文件echo 'ruby 2.7.2' > .tool-versions;您也可以通过其他方式自行安装Ruby 2.7或者更新版本。

    • 参考CentOS 7 升级Git的升级Git至最新,您也可以通过其他方式自行更新Git至2.4或者更新版本。

  2. 由于Legacy Storage将在未来被Gitlab淘汰,如果您从低版本升级至Gitlab 13.Y.Z,建议您执行gitlab-rake gitlab:storage:migrate_to_hashed,将项目存储从Legacy Storage转移到hashed storage。

  3. 使用Omnibus安装Gitlab时,Gitlab 11.X.Y以及之前的版本没有提供CentOS 8的安装包。

  4. 在CentOS上通过Docker安装Gitlab Runner时需要注意SELinux对资源的限制,详情参考:use SELinux by default

4.2 关于14.x版本升级的故障排查

14.0.x->14.4.x(或类似跨度的版本)升级期间如果出现类似下面的报错:

Expected batched background migration for the given configuration to be marked as 'finished', but it is 'active':

Finalize it manualy by running

         sudo gitlab-rake gitlab:background_migrations:finalize[CopyColumnUsingBackgroundMigrationJob,ci_builds,id,'[["id"\, "stage_id"]\, ["id_convert_to_bigint"\, "stage_id_convert_to_bigint"]]']
...

请手工执行报错提示中的命令(可能是多个,都需要运行一遍),比如上述提示中的sudo gitlab-rake xxxx命令, 然后运行’sudo gitlab-rake db:migrate’,直到数据库迁移成功。
最后再重新reconfigure。

参考:Database migrations failing because of batched background migration not finished