使用 Toolbox chart

Toolbox chart 用于在极狐GitLab 应用程序中执行周期性的日常维护任务。这些任务包括备份、数据库重建索引、Sidekiq 维护和 Rake 任务。

配置#

以下配置设置是 Toolbox chart 提供的默认设置：

yaml
1gitlab:
2  ## doc/charts/gitlab/toolbox
3  toolbox:
4    enabled: true
5    replicas: 1
6    backups:
7      cron:
8        enabled: false
9        concurrencyPolicy: Replace
10        failedJobsHistoryLimit: 1
11        schedule: "0 1 * * *"
12        successfulJobsHistoryLimit: 3
13        suspend: false
14        backoffLimit: 6
15        safeToEvict: false
16        restartPolicy: "OnFailure"
17        resources:
18          requests:
19            cpu: 50m
20            memory: 350M
21        persistence:
22          enabled: false
23          accessMode: ReadWriteOnce
24          useGenericEphemeralVolume: false
25          size: 10Gi
26      objectStorage:
27        backend: s3
28        config: {}
29      registry:
30        database: {}
31      openbao:
32        database: {}
33    databaseReindex:
34      cron:
35        enabled: false
36        concurrencyPolicy: Replace
37        failedJobsHistoryLimit: 1
38        schedule: "12 * * * 0,6"
39        successfulJobsHistoryLimit: 3
40        suspend: false
41        backoffLimit: 6
42        safeToEvict: false
43        restartPolicy: "OnFailure"
44        resources:
45          requests:
46            cpu: 200m
47            memory: 400M
48    persistence:
49      enabled: false
50      accessMode: 'ReadWriteOnce'
51      size: '10Gi'
52    resources:
53      requests:
54        cpu: '50m'
55        memory: '350M'
56    securityContext:
57      fsGroup: '1000'
58      runAsUser: '1000'
59      runAsGroup: '1000'
60    containerSecurityContext:
61      runAsUser: '1000'
62    affinity: {}

配置备份#

有关在备份和恢复文档中配置备份的信息。有关如何执行备份的技术实现的更多信息，请参阅备份和恢复架构文档。

镜像仓库元数据数据库凭据#

如果您使用镜像仓库元数据数据库，您可以配置 Toolbox 以接收用于备份和恢复操作的镜像仓库数据库连接详细信息。连接参数（主机、端口、数据库名称、SSL 设置）会自动从镜像仓库 chart 的 ConfigMap中获取。您只需在 Toolbox values 中提供数据库用户名和密码密钥：

yaml
1gitlab:
2  toolbox:
3    backups:
4      registry:
5        database:
6          backupUser: registry_backup
7          restoreUser: registry_restore
8          password:
9            secret: gitlab-toolbox-registry-database-password
10            backupPasswordKey: backupPassword
11            restorePasswordKey: restorePassword

默认密钥名称为 RELEASE-toolbox-registry-database-password，其中 RELEASE 会被替换为 Helm release 名称（通常为 gitlab）。请在部署前创建 Kubernetes 密钥：

shell
kubectl create secret generic <RELEASE>-toolbox-registry-database-password \
  --from-literal=backupPassword=<backup_password> \
  --from-literal=restorePassword=<restore_password>

凭据会挂载到 Toolbox Pod 的 /etc/gitlab/registry-db/ 中，并可在长期运行的 Toolbox 部署和备份 CronJob 中使用。

所需的数据库权限#

备份和恢复用户在镜像仓库元数据数据库上需要不同的权限级别。使用 Linux 软件包（Omnibus）捆绑的 PostgreSQL 时，这些用户和权限会自动创建。对于外部 PostgreSQL，请手动创建用户。

备份用户需要只读访问权限以执行 pg_dump：

sql
1-- Create the backup user
2CREATE ROLE registry_backup WITH LOGIN PASSWORD '<backup_password>'
3  NOINHERIT NOCREATEDB NOSUPERUSER NOREPLICATION;
4
5-- The partitions schema must exist (created by registry migrations)
6-- Grant connect and read-only privileges
7GRANT CONNECT ON DATABASE registry TO registry_backup;
8
9GRANT USAGE ON SCHEMA public TO registry_backup;
10GRANT SELECT ON ALL TABLES IN SCHEMA public TO registry_backup;
11GRANT SELECT ON ALL SEQUENCES IN SCHEMA public TO registry_backup;
12ALTER DEFAULT PRIVILEGES FOR ROLE registry IN SCHEMA public
13  GRANT SELECT ON TABLES TO registry_backup;
14ALTER DEFAULT PRIVILEGES FOR ROLE registry IN SCHEMA public
15  GRANT SELECT ON SEQUENCES TO registry_backup;
16
17GRANT USAGE ON SCHEMA partitions TO registry_backup;
18GRANT SELECT ON ALL TABLES IN SCHEMA partitions TO registry_backup;
19GRANT SELECT ON ALL SEQUENCES IN SCHEMA partitions TO registry_backup;
20ALTER DEFAULT PRIVILEGES FOR ROLE registry IN SCHEMA partitions
21  GRANT SELECT ON TABLES TO registry_backup;
22ALTER DEFAULT PRIVILEGES FOR ROLE registry IN SCHEMA partitions
23  GRANT SELECT ON SEQUENCES TO registry_backup;

ALTER DEFAULT PRIVILEGES 语句确保备份用户自动获得镜像仓库所有者（registry）将来创建的任何表或序列的 SELECT 权限。

恢复用户需要超级用户权限来重新创建 schema、将角色设置为原始对象所有者并创建触发器：

sql
CREATE ROLE registry_restore WITH LOGIN PASSWORD '<restore_password>'
  SUPERUSER;

OpenBao 数据库凭据#

如果您使用 OpenBao chart，请为 Toolbox 配置 OpenBao 数据库凭据以进行备份和恢复。连接参数（主机、端口、数据库名称、SSL 模式）来自 global.openbao.psql。启用 SSL 时，证书来自 global.psql.ssl。

假设已为 OpenBao chart 配置了 global.openbao.psql，您只需在 Toolbox values 中提供数据库用户名和密码密钥：

yaml
1gitlab:
2  toolbox:
3    backups:
4      openbao:
5        database:
6          backupUser: openbao_backup
7          restoreUser: openbao_restore
8          password:
9            secret: gitlab-toolbox-openbao-database-password
10            backupPasswordKey: backupPassword
11            restorePasswordKey: restorePassword

默认密钥名称为 RELEASE-toolbox-openbao-database-password，其中 RELEASE 会被替换为 Helm release 名称（默认为 gitlab）。请创建包含备份和恢复密码的 Kubernetes 密钥。

shell
kubectl create secret generic <RELEASE>-toolbox-openbao-database-password \
  --from-literal=backupPassword=<backup_password> \
  --from-literal=restorePassword=<restore_password>

凭据会挂载到 Toolbox Pod 的 /etc/gitlab/openbao-db/ 中。它们可在长期运行的 Toolbox 部署中使用，当 backups.cron.enabled 为 true 时也可在备份 cron 作业中使用。

如果凭据文件缺失，OpenBao 数据库备份将被跳过并显示警告。如果文件存在但密码文件不可读或为空，备份将失败并显示错误。

所需的数据库权限#

备份和恢复用户在 OpenBao 数据库上需要不同的权限级别。请在运行备份或恢复之前在 PostgreSQL 中创建这些用户。

备份用户需要只读访问权限以执行 pg_dump：

sql
1CREATE ROLE openbao_backup WITH LOGIN PASSWORD '<backup_password>'
2  NOINHERIT NOCREATEDB NOSUPERUSER NOREPLICATION;
3
4GRANT CONNECT ON DATABASE openbao TO openbao_backup;
5
6GRANT USAGE ON SCHEMA public TO openbao_backup;
7GRANT SELECT ON ALL TABLES IN SCHEMA public TO openbao_backup;
8GRANT SELECT ON ALL SEQUENCES IN SCHEMA public TO openbao_backup;
9ALTER DEFAULT PRIVILEGES FOR ROLE openbao IN SCHEMA public
10  GRANT SELECT ON TABLES TO openbao_backup;
11ALTER DEFAULT PRIVILEGES FOR ROLE openbao IN SCHEMA public
12  GRANT SELECT ON SEQUENCES TO openbao_backup;

ALTER DEFAULT PRIVILEGES 语句确保备份用户自动获得 OpenBao 所有者将来创建的任何表或序列的 SELECT 权限。请将示例中的所有者角色 openbao 替换为您设置的 global.openbao.psql.username。

恢复用户需要 SUPERUSER，因为 pg_dump 生成的转储包含 ALTER TABLE ... OWNER TO <owner> 语句（pg_dump 运行时未使用 --no-owner）。应用这些语句需要原始所有者角色或 SUPERUSER，但对于恢复用户来说 SUPERUSER 是最简单的选择。

sql
CREATE ROLE openbao_restore WITH LOGIN PASSWORD '<restore_password>'
  SUPERUSER;

配置周期性数据库重建索引#

数据库重建索引可以定期执行，以：

• 异步创建和删除索引。
• 在后台运行 PostgreSQL 约束验证。
• 重建 PostgreSQL 索引以减少索引膨胀。

重建索引由 gitlab:db:reindex Rake 任务执行。Toolbox chart 提供了一个 CronJob 来定期运行该 Rake 任务。

通过将 databaseReindex.cron.enabled的值设置为 true 来启用此 CronJob。该作业将自动：

1. 选择两个索引膨胀最严重的索引。
2. 在后台重建这些索引。

使用 databaseReindex.cron.schedule 值设置 CronJob 的调度。您应在流量较低的时段运行重建索引。例如，GitLab.com 的数据库重建索引在周六和周日运行。

持久化配置#

备份和恢复的持久化存储是分别配置的。在为备份和恢复操作配置极狐GitLab 时，请查看以下注意事项。

备份使用 backups.cron.persistence.* 属性，恢复使用 persistence.* 属性。有关持久化存储配置的进一步描述将仅使用最终属性键（例如 .enabled 或 .size），需要添加相应的前缀。

持久化存储默认处于禁用状态，因此对于任何有相当规模的备份或恢复，都需要将 .enabled 设置为 true。此外，需要指定 .storageClass 以便 Kubernetes 创建 PersistentVolume，或者手动创建 PersistentVolume。如果 .storageClass 指定为 -，则将使用 Kubernetes 集群中指定的默认 StorageClass 创建 PersistentVolume。

如果手动创建 PersistentVolume，则可以使用 .volumeName 属性或使用选择器 .matchLables / .matchExpressions 属性来指定卷。

在大多数情况下，.accessMode的默认值将为仅 Toolbox 访问 PersistentVolume 提供足够的控制。请查阅 Kubernetes 集群中安装的 CSI 驱动程序的文档，以确保该设置正确。

备份注意事项#

备份操作需要一定量的磁盘空间，以便在写入备份对象存储之前保存正在备份的各个组件。磁盘空间量取决于以下因素：

• 项目数量以及每个项目下存储的数据量
• PostgresSQL 数据库的大小（议题、合并请求等）
• 每个对象存储后端的大小

确定大致大小后，可以设置 backups.cron.persistence.size 属性，以便开始备份。

恢复注意事项#

在恢复备份期间，需要先将备份解压到磁盘，然后再替换正在运行的实例上的文件。此恢复磁盘空间的大小由 persistence.size 属性控制。请注意，随着极狐GitLab 安装规模的增长，恢复磁盘空间的大小也需要相应增长。在大多数情况下，恢复磁盘空间的大小应与备份磁盘空间的大小相同。

Toolbox 包含的工具#

Toolbox 容器包含有用的极狐GitLab 工具，例如 Rails 控制台、Rake 任务等。这些命令允许您检查数据库迁移的状态、执行管理任务的 Rake 任务、与 Rails 控制台交互：

shell
1# locate the Toolbox pod
2kubectl get pods -lapp=toolbox
3
4# Launch a shell inside the pod
5kubectl exec -it <Toolbox pod name> -- bash
6
7# open Rails console
8gitlab-rails console -e production
9
10# execute a Rake task
11gitlab-rake gitlab:env:info

affinity#

有关更多信息，请参阅 affinity。