极狐 GitLab Logo

备份和恢复极狐GitLab 实例

  1. Tier: 基础版, 专业版, 旗舰版
  2. Offering: 私有化部署

极狐GitLab Helm chart 提供了一个来自 Toolbox 子 chart 的实用 pod，作为备份和恢复极狐GitLab 实例的接口。它配备了一个 backup-utility 可执行文件，用于与其他必要的 pod 交互以完成此任务。有关该实用程序如何工作的技术细节，请参阅架构文档。

先决条件#

  1. 此处描述的备份和恢复程序仅在兼容 S3 的 API 上测试过。对其他对象存储服务（如 Google Cloud Storage）的支持将在未来版本中进行测试。

  2. 在恢复过程中，备份 tarball 需要被解压到磁盘。这意味着 Toolbox pod 应该具有必要大小的可用磁盘。

  3. 该 chart 依赖于使用对象存储来存储 产物、uploads、软件包、registry 和 lfs 对象，目前在恢复过程中不会自动迁移这些对象。如果您正在从另一个实例恢复备份，您必须在备份之前将现有实例迁移到使用对象存储。

备份和恢复程序#

  1. 备份极狐GitLab 安装
  2. 恢复极狐GitLab 安装

对象存储#

在使用此 charts 时，我们提供了一个开箱即用的 MinIO 实例，除非指定了外部对象存储。Toolbox 默认连接到包含的 MinIO，除非设置了特定配置。Toolbox 也可以配置为备份到 Amazon S3 或 Google Cloud Storage (GCS)。

备份到 S3#

Toolbox 默认使用 s3cmd 连接到对象存储，除非您指定使用其他 s3 工具。为了配置到外部对象存储的连接性，需要指定 gitlab.toolbox.backups.objectStorage.config.secret，该值指向包含 .s3cfg 文件的 Kubernetes 密钥。如果不同于默认的 config，则需要指定 gitlab.toolbox.backups.objectStorage.config.key。这指向包含 .s3cfg 文件内容的键。

它应该是这样的：

shell
helm install gitlab gitlab/gitlab \
  --set gitlab.toolbox.backups.objectStorage.config.secret=my-s3cfg \
  --set gitlab.toolbox.backups.objectStorage.config.key=config .

此外，需要配置两个存储桶位置，一个用于存储备份，一个临时存储桶用于恢复备份时使用。

shell
--set global.appConfig.backups.bucket=gitlab-backup-storage
--set global.appConfig.backups.tmpBucket=gitlab-tmp-storage

备份到 Google Cloud Storage (GCS)#

要备份到 GCS，您必须首先将 gitlab.toolbox.backups.objectStorage.backend 设置为 gcs。这可确保 Toolbox 在存储和检索对象时使用 gsutil CLI。

此外，需要配置两个存储桶位置，一个用于存储备份，一个临时存储桶用于恢复备份时使用。

shell
--set global.appConfig.backups.bucket=gitlab-backup-storage
--set global.appConfig.backups.tmpBucket=gitlab-tmp-storage

备份实用程序需要访问这些存储桶。有两种方法可以授予访问权限：

  1. 在 Kubernetes 密钥中指定凭据。
  2. 配置 GKE 的工作负载身份联合。

GCS 凭据#

首先，将 gitlab.toolbox.backups.objectStorage.config.gcpProject 设置为包含您的存储桶的 GCP 项目的项目 ID。

您必须使用活动服务帐户 JSON 密钥的内容创建一个 Kubernetes 密钥，其中服务帐户具有您将用于备份的存储桶的 storage.admin 角色。下面是使用 gcloud 和 kubectl 创建密钥的示例。

shell
export PROJECT_ID=$(gcloud config get-value project)
gcloud iam service-accounts create gitlab-gcs --display-name "Gitlab Cloud Storage"
gcloud projects add-iam-policy-binding --role roles/storage.admin ${PROJECT_ID} --member=serviceAccount:gitlab-gcs@${PROJECT_ID}.iam.gserviceaccount.com
gcloud iam service-accounts keys create --iam-account gitlab-gcs@${PROJECT_ID}.iam.gserviceaccount.com storage.config
kubectl create secret generic storage-config --from-file=config=storage.config

配置您的 Helm chart 以使用服务帐户密钥认证到 GCS 进行备份：

shell
helm install gitlab gitlab/gitlab \
  --set gitlab.toolbox.backups.objectStorage.config.secret=storage-config \
  --set gitlab.toolbox.backups.objectStorage.config.key=config \
  --set gitlab.toolbox.backups.objectStorage.config.gcpProject=my-gcp-project-id \
  --set gitlab.toolbox.backups.objectStorage.backend=gcs

配置 GKE 的工作负载身份联合#

请参阅使用极狐GitLab chart 的 GKE 工作负载身份联合文档。

在创建引用 Kubernetes ServiceAccount 的 IAM 允许策略时，授予 roles/storage.objectAdmin 角色。

对于备份，确保通过确保未设置 gitlab.toolbox.backups.objectStorage.config.secret 和 gitlab.toolbox.backups.objectStorage.config.key 来使用 Google 的应用程序默认凭据。

备份到 Azure blob 存储#

通过将 gitlab.toolbox.backups.objectStorage.backend 设置为 azure 可以使用 Azure blob 存储来存储备份。这使得 Toolbox 可以使用包含的 azcopy 复制来传输和检索备份文件到 Azure blob 存储。

要使用 Azure blob 存储，需要在现有资源组中创建一个存储帐户。使用存储帐户的名称、访问密钥和 blob 主机创建一个配置密钥。

创建包含参数的配置文件：

yaml
# azure-backup-conf.yaml
azure_storage_account_name: <storage account>
azure_storage_access_key: <access key value>
azure_storage_domain: blob.core.windows.net # optional

可以使用以下 kubectl 命令创建 Kubernetes 密钥：

shell
kubectl create secret generic backup-azure-creds \
  --from-file=config=azure-backup-conf.yaml

一旦创建了密钥，极狐GitLab Helm chart 可以通过将备份设置添加到已部署的值中或者通过在 Helm 命令行中提供设置来进行配置。例如：

shell
helm install gitlab gitlab/gitlab \
  --set gitlab.toolbox.backups.objectStorage.config.secret=backup-azure-creds \
  --set gitlab.toolbox.backups.objectStorage.config.key=config \
  --set gitlab.toolbox.backups.objectStorage.backend=azure

从密钥中提取的访问密钥用于生成和刷新短期共享访问签名 (SAS) 令牌以访问存储帐户。

此外，需要事先创建两个存储桶/容器，一个用于存储备份，一个临时存储桶用于恢复备份时使用。将存储桶名称添加到您的值或设置中。例如：

shell
--set global.appConfig.backups.bucket=gitlab-backup-storage
--set global.appConfig.backups.tmpBucket=gitlab-tmp-storage

故障排除#

Pod 驱逐问题#

由于备份是在对象存储目标之外本地组装的，因此需要临时磁盘空间。所需空间可能会超过实际备份存档的大小。默认配置将使用 Toolbox pod 的文件系统来存储临时数据。如果您发现 pod 因资源不足而被驱逐，您应该为 pod 附加一个持久卷以保存临时数据。在 GKE 上，将以下设置添加到您的 Helm 命令中：

shell
--set gitlab.toolbox.persistence.enabled=true

如果您的备份是作为包含的备份 cron 作业的一部分运行的，那么您也需要为 cron 作业启用持久性：

shell
--set gitlab.toolbox.backups.cron.persistence.enabled=true

对于其他提供商，您可能需要创建一个持久卷。请参阅我们的存储文档，了解如何执行此操作的可能示例。

“未找到存储桶”错误#

如果在备份期间看到 Bucket not found 错误，请检查存储桶的凭据是否已配置。

该命令取决于云服务提供商：

  • 对于 AWS S3，凭据存储在 toolbox pod 的 ~/.s3cfg 中。运行：

    shell
    s3cmd ls

  • 对于 GCP GCS，运行：

    shell
    gsutil ls

您应该会看到可用存储桶的列表。

GCP 中的“AccessDeniedException: 403”错误#

错误如 [Error] AccessDeniedException: 403 <GCP Account> does not have storage.objects.list access to the Google Cloud Storage bucket. 通常发生在极狐GitLab 实例的备份或恢复过程中，因为缺少权限。

备份和恢复操作使用环境中的所有存储桶，因此确认环境中的所有存储桶都已创建，并且 GCP 帐户可以访问（列出、读取和写入）所有存储桶：

  1. 查找您的 toolbox pod：

    shell
    kubectl get pods -lrelease=RELEASE_NAME,app=toolbox

  2. 获取 pod 环境中的所有存储桶。将 <toolbox-pod-name> 替换为您实际的 toolbox pod 名称，但保留 "BUCKET_NAME" 不变：

    shell
    kubectl describe pod <toolbox-pod-name> | grep "BUCKET_NAME"

  3. 确认您对环境中的每个存储桶都有访问权限：

    shell
    1# 列出
2gsutil ls gs://<bucket-to-validate>/
3
4# 读取
5gsutil cp gs://<bucket-to-validate>/<object-to-get> <save-to-location>
6
7# 写入
8gsutil cp -n <local-file> gs://<bucket-to-validate>/

使用 --backend s3 运行 backup-utility 时的“ERROR: /home/git/.s3cfg: None”错误#

当未通过 gitlab.toolbox.backups.objectStorage.config.secret 值指定包含 .s3cfg 文件的 Kubernetes 密钥时，会发生此错误。

要解决此问题，请按照备份到 S3中的说明进行操作。

使用 S3 时的“PermissionError: 文件不可写”错误#

如果 toolbox 用户没有权限写入与存储桶项目存储权限匹配的文件，则会发生类似 [Error] WARNING: <file> not writable: Operation not permitted 的错误。

为了防止这种情况，请通过在 .s3cfg 文件中添加以下标志来配置 s3cmd，该文件通过 gitlab.toolbox.backups.objectStorage.config.secret 引用。

toml
preserve_attrs = False

恢复时跳过的代码库#

从极狐GitLab 16.6/Chart 7.6 开始，如果备份存档已重命名，恢复时可能会跳过代码库。为了避免这种情况，请不要重命名备份存档，并将备份重命名为其原始名称（{backup_id}_gitlab_backup.tar）。

原始备份 ID 可以从代码库备份目录结构中提取：repositories/@hashed/*/*/*/{backup_id}/LATEST