使用外部 Gitaly 配置极狐GitLab chart

配置极狐GitLab图表与外部Gitaly

本文档旨在提供有关如何配置此 Helm 图表与外部 Gitaly 服务的文档。

如果您没有配置 Gitaly，用于本地或部署到虚拟机上，请考虑使用我们的Linux 软件包。

外部 Gitaly _服务_ 可以由 Gitaly 节点或 [Praefect](https://gitlab.cn/docs/jh/administration/gitaly/praefect/) 集群提供。

配置图表#

禁用 gitaly 图表及其提供的 Gitaly 服务，并将其他服务指向外部服务。

您需要设置以下属性：

global.gitaly.enabled: 设置为 false 以禁用包含的 Gitaly 图表。
global.gitaly.external: 这是一个外部 Gitaly 服务的数组。
global.gitaly.authToken.secret: 包含用于身份验证的令牌的密钥名称。
global.gitaly.authToken.key: 密钥中的键，包含令牌内容。

外部 Gitaly 服务将使用其自己的极狐GitLab Shell 实例。根据您的实现，您可以使用此图表的密钥进行配置，或者可以使用预定义源的内容配置此图表的密钥。

您可能需要设置以下属性：

global.shell.authToken.secret: 包含极狐GitLab Shell 密钥的密钥名称。
global.shell.authToken.key: 密钥中的键，包含密钥内容。

这是一个完整的示例配置，有两个外部服务（external-gitaly.yml）：

yaml
1global:
2  gitaly:
3    enabled: false
4    external:
5      - name: default                   # required
6        hostname: node1.git.example.com # required
7        port: 8075                      # optional, default shown
8      - name: praefect                  # required
9        hostname: ha.git.example.com    # required
10        port: 2305                      # Praefect uses port 2305
11        tlsEnabled: false               # optional, overrides gitaly.tls.enabled
12    authToken:
13      secret: external-gitaly-token     # required
14      key: token                        # optional, default shown
15    tls:
16      enabled: false                    # optional, default shown

使用上述配置文件结合其他配置通过 gitlab.yml 进行示例安装：

shell
helm upgrade --install gitlab gitlab/gitlab  \
  -f gitlab.yml \
  -f external-gitaly.yml

多个外部 Gitaly#

如果您的实现使用多个外部于这些图表的 Gitaly 节点，您也可以定义多个主机。语法略有不同，以允许所需的复杂性。

提供了一个示例值文件，其中展示了适当的配置集。此值文件的内容不能通过 --set 参数正确解释，因此应使用 -f / --values 标志传递给 Helm。

通过 TLS 连接到外部 Gitaly#

如果您的外部 Gitaly 服务器监听 TLS 端口，您可以让您的极狐GitLab实例通过 TLS 与其通信。为此，您必须：

创建一个包含 Gitaly 服务器证书的 Kubernetes 密钥

shell
kubectl create secret generic gitlab-gitaly-tls-certificate --from-file=gitaly-tls.crt=<path to certificate>

将外部 Gitaly 服务器的证书添加到自定义证书颁发机构列表中。在值文件中，指定以下内容

yaml
global:
  certificates:
    customCAs:
      - secret: gitlab-gitaly-tls-certificate

或使用 --set 将其传递给 helm upgrade 命令

shell
--set global.certificates.customCAs[0].secret=gitlab-gitaly-tls-certificate

要为所有 Gitaly 实例启用 TLS，请设置 global.gitaly.tls.enabled: true。

yaml
global:
  gitaly:
    tls:
      enabled: true

要单独为实例启用，请为该条目设置 tlsEnabled: true。

yaml
1global:
2  gitaly:
3    external:
4      - name: default
5        hostname: node1.git.example.com
6        tlsEnabled: true

您可以为此选择任何有效的密钥名称和键，但请确保键在 `customCAs` 中指定的所有密钥中是唯一的，以避免冲突，因为所有密钥中的键将被挂载。您**不需要**为证书提供密钥，因为这是 _客户端_。

测试极狐GitLab是否能连接到Gitaly#

要检查极狐GitLab是否能连接到外部 Gitaly 服务器：

shell
kubectl exec -it <toolbox-pod> -- gitlab-rake gitlab:gitaly:check

如果您正在使用带有 TLS 的 Gitaly，您还可以检查极狐GitLab图表是否信任 Gitaly 证书：

shell
kubectl exec -it <toolbox-pod> -- echo | /usr/bin/openssl s_client -connect <gitaly-host>:<gitaly-port>

从Gitaly图表迁移到外部Gitaly#

如果您正在使用 Gitaly 图表来提供 Gitaly 服务，并且需要将所有存储库迁移到外部 Gitaly 服务，可以使用以下方法之一完成：

使用存储库存储移动 API 进行迁移（推荐）。
使用备份/恢复方法进行迁移。

使用存储库存储移动 API 进行迁移#

此方法：

使用存储库存储移动 API 将存储库从 Gitaly 图表迁移到外部 Gitaly 服务。
可以在零停机时间下执行。
要求外部 Gitaly 服务驻留在与 Gitaly Pods 相同的 VPC/区域中。
尚未与 Praefect 图表测试，不支持。

第 1 步：设置外部 Gitaly 服务或 Gitaly 集群#

设置一个外部 Gitaly或外部 Gitaly 集群。您必须提供来自图表安装的 Gitaly 令牌和极狐GitLab Shell 密钥作为这些步骤的一部分：

shell
# 获取极狐GitLab Shell 密钥
kubectl get secret <release>-gitlab-shell-secret -ojsonpath='{.data.secret}' | base64 -d

# 获取 Gitaly 令牌
kubectl get secret <release>-gitaly-secret -ojsonpath='{.data.token}' | base64 -d

此处提取的 Gitaly 令牌应用于 AUTH_TOKEN 值。
此处提取的极狐GitLab Shell 密钥应用于 shellsecret 值。

最后，确保外部 Gitaly 服务的防火墙允许来自配置的 Gitaly 端口的流量到您的 Kubernetes Pod IP 范围。

第 2 步：配置实例以使用新的 Gitaly 服务#

配置极狐GitLab以使用外部 Gitaly。如果在您的主 gitlab.yml 配置文件中有任何 Gitaly 引用，请将其删除，并创建一个新的 mixed-gitaly.yml 文件，内容如下。

如果您之前定义了其他 Gitaly 存储，您需要确保在新配置中指定了一个名称相同的匹配 Gitaly 存储，否则恢复操作将失败。

如果您正在配置 TLS，请参阅通过 TLS 连接到外部 Gitaly部分：

yaml
1   global:
2     gitaly:
3       internal:
4         names:
5           - default
6       external:
7         - name: ext-gitaly                # required
8           hostname: node1.git.example.com # required
9           port: 8075                      # optional, default shown
10           tlsEnabled: false               # optional, overrides gitaly.tls.enabled

yaml
1   global:
2     gitaly:
3       internal:
4         names:
5           - default
6       external:
7         - name: ext-gitaly-cluster        # required
8           hostname: ha.git.example.com    # required
9           port: 2305                      # Praefect uses port 2305
10           tlsEnabled: false               # optional, overrides gitaly.tls.enabled

使用 gitlab.yml 和 mixed-gitaly.yml 文件应用新配置：

shell
helm upgrade --install gitlab gitlab/gitlab \
  -f gitlab.yml \
  -f mixed-gitaly.yml

在 Toolbox Pod 上，确认极狐GitLab可以成功连接到外部 Gitaly：

shell
kubectl exec <toolbox pod name> -it -- gitlab-rake gitlab:gitaly:check

确保外部 Gitaly 可以连接回您的图表安装：

确保 Gitaly 服务可以成功回调极狐GitLab API：

shell
sudo /opt/gitlab/embedded/bin/gitaly check /var/opt/gitlab/gitaly/config.toml

在所有 Praefect 节点上，确保 Praefect 服务可以连接到 Gitaly 节点：

shell
# 在 Praefect 节点上运行
sudo /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.toml dial-nodes

在所有 Gitaly 节点上，确保 Gitaly 服务可以成功回调极狐GitLab API：

shell
# 在 Gitaly 节点上运行
sudo /opt/gitlab/embedded/bin/gitaly check /var/opt/gitlab/gitaly/config.toml

第 3 步：获取 Gitaly pod IP 和主机名#

为了使存储库存储移动 API 成功，外部 Gitaly 服务需要能够使用 Pod 服务主机名连接回 Gitaly Pods。为了使 Pod 服务主机名可解析，我们需要将主机名添加到每个运行 Gitaly 进程的外部 Gitaly 服务上的 hosts 文件中。

获取 Gitaly Pods 列表及其各自的内部 IP 地址/主机名：

shell
kubectl get pods -l app=gitaly -o jsonpath='{range .items[*]}{.status.podIP}{"\t"}{.spec.hostname}{"."}{.spec.subdomain}{"."}{.metadata.namespace}{".svc\n"}{end}'

将上一步的输出添加到每个运行 Gitaly 进程的外部 Gitaly 服务上的 /etc/hosts 文件中。
确认可以从每个运行 Gitaly 进程的外部 Gitaly 服务上 ping 到 Gitaly Pod 主机名：
```
shell
ping <gitaly pod hostname>
```

确认连接后，我们可以继续安排存储库存储移动。

第 4 步：安排存储库存储移动#

按照移动存储库中指示的步骤安排移动。

第 5 步：最终配置和验证#

如果您有多个 Gitaly 存储，配置新存储库的存储位置。
考虑为未来生成包含外部 Gitaly 配置的合并 gitlab.yml：
```
shell
helm get values <RELEASE_NAME> -o yaml > gitlab.yml
```
在 gitlab.yml 文件中禁用内部 Gitaly 子图表，并将新的 default 存储库存储指向外部 Gitaly 服务。极狐GitLab需要默认存储库存储：

yaml
1   global:
2     gitaly:
3       enabled: false                      # Disable the internal Gitaly subchart
4       external:
5         - name: ext-gitaly                # required
6           hostname: node1.git.example.com # required
7           port: 8075                      # optional, default shown
8           tlsEnabled: false               # optional, overrides gitaly.tls.enabled
9         - name: default                   # Add the default repository storage, use the same settings as ext-gitaly
10           hostname: node1.git.example.com
11           port: 8075
12           tlsEnabled: false

yaml
1   global:
2     gitaly:
3       enabled: false                      # Disable the internal Gitaly subchart
4       external:
5         - name: ext-gitaly-cluster        # required
6           hostname: ha.git.example.com    # required
7           port: 2305                      # Praefect uses port 2305
8           tlsEnabled: false               # optional, overrides gitaly.tls.enabled
9         - name: default                   # Add the default repository storage, use the same settings as ext-gitaly-cluster
10           hostname: ha.git.example.com
11           port: 2305
12           tlsEnabled: false

应用新配置：

shell
helm upgrade --install gitlab gitlab/gitlab \
  -f gitlab.yml

可选。在按照获取 Gitaly pod IP 和主机名步骤后，删除对每个外部 Gitaly /etc/hosts 文件所做的更改。
确认一切正常后，您可以删除 Gitaly PVC：

WARNING: 在您仔细检查一切正常之前，请勿删除 Gitaly PVC。
```
shell
kubectl delete pvc repo-data-<release>-gitaly-0
```

使用备份/恢复方法进行迁移#

此方法：

从 Gitaly 图表 PersistentVolumeClaim (PVC) 备份您的存储库，然后将它们恢复到外部 Gitaly 服务。
会对所有用户造成停机。
尚未与 Praefect 图表测试，不支持。

第 1 步：获取极狐GitLab图表的当前发布修订版本#

在迁移过程中出现问题的情况下，获取极狐GitLab图表的当前发布修订版本。复制输出并放在一旁，以防需要执行回滚：

shell
helm history <release> --max=1

第 2 步：设置外部 Gitaly 服务或 Gitaly 集群#

设置一个外部 Gitaly或外部 Gitaly 集群。您必须提供来自图表安装的 Gitaly 令牌和极狐GitLab Shell 密钥作为这些步骤的一部分：

shell
# 获取极狐GitLab Shell 密钥
kubectl get secret <release>-gitlab-shell-secret -ojsonpath='{.data.secret}' | base64 -d

# 获取 Gitaly 令牌
kubectl get secret <release>-gitaly-secret -ojsonpath='{.data.token}' | base64 -d

此处提取的 Gitaly 令牌应用于 AUTH_TOKEN 值。
此处提取的极狐GitLab Shell 密钥应用于 shellsecret 值。

第 3 步：验证在迁移过程中无法进行 Git 更改#

为了确保迁移的数据完整性，请防止在以下步骤中对您的 Git 存储库进行任何更改：

1. 启用维护模式

如果您使用的是极狐GitLab 企业版，请通过 UI、API 或 Rails 控制台启用维护模式：

shell
kubectl exec <toolbox pod name> -it -- gitlab-rails runner 'Gitlab::CurrentSettings.update!(maintenance_mode: true)'

2. 缩减 Runner Pods

如果您使用的是极狐GitLab 基础版，您必须缩减集群中运行的任何极狐GitLab Runner Pods。这可以防止 Runner 连接到极狐GitLab以处理 CI/CD 作业。

如果您使用的是极狐GitLab 企业版，此步骤是可选的，因为维护模式会阻止集群中的 Runner 连接到极狐GitLab。

shell
# 记录当前 Runner 副本数，以便稍后可以缩放到此数量
kubectl get deploy -lapp=gitlab-gitlab-runner,release=<release> -o jsonpath='{.items[].spec.replicas}{"\n"}'

# 将 Runner Pods 缩减为零
kubectl scale deploy -lapp=gitlab-gitlab-runner,release=<release> --replicas=0

3. 确认没有 CI 作业正在运行

在管理区域，转到 CI/CD > Jobs。此页面显示所有作业，但请确认没有作业处于 Running 状态。您需要等待作业完成后再继续下一步。

4. 禁用 Sidekiq 定时任务

为防止在迁移期间安排和执行 Sidekiq 作业，请禁用所有 Sidekiq 定时任务：

shell
kubectl exec <toolbox pod name> -it -- gitlab-rails runner 'Sidekiq::Cron::Job.all.map(&:disable!)'

5. 确认没有后台作业正在运行

我们需要等待任何排队或进行中的作业完成后再继续下一步。

在管理区域，转到监控并选择后台作业。
在 Sidekiq 仪表板下，选择 Queues，然后选择 Live Poll。
等待 Busy 和 Enqueued 降至 0。

6. 缩减 Sidekiq 和 Webservice Pods

缩减 Sidekiq 和 Webservice Pods 以确保获取一致的备份。两个服务将在稍后阶段缩放：

Sidekiq Pods 在恢复步骤中缩放回去
Webservice Pods 在切换到外部 Gitaly 服务后缩放回去以测试连接

shell
1# 记录当前 Sidekiq 和 Webservice 副本数，以便稍后可以缩放到此数量
2kubectl get deploy -lapp=sidekiq,release=<release> -o jsonpath='{.items[].spec.replicas}{"\n"}'
3kubectl get deploy -lapp=webservice,release=<release> -o jsonpath='{.items[].spec.replicas}{"\n"}'
4
5# 将 Sidekiq 和 Webservice Pods 缩减为零
6kubectl scale deploy -lapp=sidekiq,release=<release> --replicas=0
7kubectl scale deploy -lapp=webservice,release=<release> --replicas=0

7. 限制对集群的外部连接

为防止用户和外部极狐GitLab Runner 对极狐GitLab进行任何更改，我们需要限制对极狐GitLab的所有不必要的连接。

完成这些步骤后，极狐GitLab在浏览器中完全不可用，直到恢复完成。

为了在迁移期间保持集群对新的外部 Gitaly 服务的可访问性，我们必须将外部 Gitaly 服务的 IP 地址添加到 nginx-ingress 配置中，作为唯一的外部例外。

创建一个 ingress-only-allow-ext-gitaly.yml 文件，内容如下：

yaml
nginx-ingress:
  controller:
    service:
      loadBalancerSourceRanges:
       - "x.x.x.x/32"

x.x.x.x 应为外部 Gitaly 服务的 IP 地址。

使用 gitlab.yml 和 ingress-only-allow-ext-gitaly.yml 文件应用新配置：

shell
helm upgrade <release> gitlab/gitlab \
  -f gitlab.yml \
  -f ingress-only-allow-ext-gitaly.yml

8. 创建存储库校验和列表

在运行备份之前，检查所有极狐GitLab存储库并创建一个存储库校验和列表。将输出重定向到一个文件，以便在迁移后 diff 校验和：

shell
kubectl exec <toolbox pod name> -it -- gitlab-rake gitlab:git:checksum_projects > ~/checksums-before.txt

第 4 步：备份所有存储库#

创建备份，仅包含您的存储库：

shell
kubectl exec <toolbox pod name> -it -- backup-utility --skip artifacts,ci_secure_files,db,external_diffs,lfs,packages,pages,registry,terraform_state,uploads

第 5 步：配置实例以使用新的 Gitaly 服务#

禁用 Gitaly 子图表并配置极狐GitLab以使用外部 Gitaly。如果在您的主 gitlab.yml 配置文件中有任何 Gitaly 引用，请将其删除，并创建一个新的 external-gitaly.yml 文件，内容如下。

如果您之前定义了其他 Gitaly 存储，您需要确保在新配置中指定了一个名称相同的匹配 Gitaly 存储，否则恢复操作将失败。

如果您正在配置 TLS，请参阅通过 TLS 连接到外部 Gitaly部分：

yaml
1   global:
2     gitaly:
3       enabled: false
4       external:
5         - name: default                   # required
6           hostname: node1.git.example.com # required
7           port: 8075                      # optional, default shown
8           tlsEnabled: false               # optional, overrides gitaly.tls.enabled

yaml
1   global:
2     gitaly:
3       enabled: false
4       external:
5         - name: default                   # required
6           hostname: ha.git.example.com    # required
7           port: 2305                      # Praefect uses port 2305
8           tlsEnabled: false               # optional, overrides gitaly.tls.enabled

使用 gitlab.yml、ingress-only-allow-ext-gitaly.yml 和 external-gitaly.yml 文件应用新配置：

shell
helm upgrade --install gitlab gitlab/gitlab \
  -f gitlab.yml \
  -f ingress-only-allow-ext-gitaly.yml \
  -f external-gitaly.yml

如果 Webservice Pods 未运行，请将其缩放到原始副本数。这是必须的，以便我们可以在接下来的步骤中测试极狐GitLab到外部 Gitaly 的连接。
```
shell
kubectl scale deploy -lapp=webservice,release=<release> --replicas=<value>
```