Object Storage

原文:https://docs.gitlab.com/ee/administration/object_storage.html

Object Storage

GitLab 支持使用对象存储服务来保存多种类型的数据. 建议在 NFS 上使用它,并且通常在较大的设置中更好,因为对象存储通常具有更高的性能,可靠性和可伸缩性.

Options

GitLab 已在许多对象存储提供程序上进行了测试:

Configuration guides

在 GitLab 中有两种指定对象存储配置的方式:

有关差异以及从一种形式过渡到另一种形式的更多信息,请参见过渡到合并形式 .

Consolidated object storage configuration

GitLab 13.2 中引入.

使用合并对象存储配置具有许多优点:

注意:由于必须使用直接上载模式 ,目前仅支持与 AWS S3 兼容的提供商和 Google. 此模式不支持后台上传. 我们建议直接上传模式,因为它不需要共享文件夹,并且此设置可能成为默认设置 .注意:合并对象存储配置不能用于备份或 Mattermost. 有关完整列表,请参见完整表 .

通过为具有多个存储桶的对象存储指定单个凭证,可以将大多数类型的对象(例如 CI 工件,LFS 文件,上传附件等)保存在对象存储中. 每种类型必须使用不同的存储桶 .

当合并形式为:

  • 通过与 S3 兼容的对象存储一起使用,Workhorse 使用其内部的 S3 客户端上载文件.
  • 不与 S3 兼容的对象存储一起使用,Workhorse 退回到使用预签名的 URL.

有关更多详细信息,请参见” ETag 不匹配错误 “部分.

在所有安装中;

  1. 编辑/etc/gitlab/gitlab.rb并添加以下行,以替换所需的值:

    1. # Consolidated object storage configuration
    2. gitlab_rails['object_store']['enabled'] = true
    3. gitlab_rails['object_store']['proxy_download'] = true
    4. gitlab_rails['object_store']['connection'] = {
    5. 'provider' => 'AWS',
    6. 'region' => '<eu-central-1>',
    7. 'aws_access_key_id' => '<AWS_ACCESS_KEY_ID>',
    8. 'aws_secret_access_key' => '<AWS_SECRET_ACCESS_KEY>'
    9. }
    10. gitlab_rails['object_store']['objects']['artifacts']['bucket'] = '<artifacts>'
    11. gitlab_rails['object_store']['objects']['external_diffs']['bucket'] = '<external-diffs>'
    12. gitlab_rails['object_store']['objects']['lfs']['bucket'] = '<lfs-objects>'
    13. gitlab_rails['object_store']['objects']['uploads']['bucket'] = '<uploads>'
    14. gitlab_rails['object_store']['objects']['packages']['bucket'] = '<packages>'
    15. gitlab_rails['object_store']['objects']['dependency_proxy']['bucket'] = '<dependency-proxy>'
    16. gitlab_rails['object_store']['objects']['terraform_state']['bucket'] = '<terraform-state>'

    对于 GitLab 9.4 或更高版本,如果您使用的是 AWS IAM 配置文件,请确保省略 AWS 访问密钥和秘密访问密钥/值对. 例如:

    1. gitlab_rails['object_store_connection'] = {
    2. 'provider' => 'AWS',
    3. 'region' => '<eu-central-1>',
    4. 'use_iam_profile' => true
    5. }
  2. 保存文件并重新配置 GitLab,以使更改生效.

在源安装中:

  1. 编辑/home/git/gitlab/config/gitlab.yml并添加或修改以下行:

    1. object_store:
    2. enabled: true
    3. proxy_download: true
    4. connection:
    5. provider: AWS
    6. aws_access_key_id: <AWS_ACCESS_KEY_ID>
    7. aws_secret_access_key: <AWS_SECRET_ACCESS_KEY>
    8. region: <eu-central-1>
    9. objects:
    10. artifacts:
    11. bucket: <artifacts>
    12. external_diffs:
    13. bucket: <external-diffs>
    14. lfs:
    15. bucket: <lfs-objects>
    16. uploads:
    17. bucket: <uploads>
    18. packages:
    19. bucket: <packages>
    20. dependency_proxy:
    21. bucket: <dependency_proxy>
    22. terraform_state:
    23. bucket: <terraform>
  2. 编辑/home/git/gitlab-workhorse/config.toml并添加或修改以下行:

    1. [object_storage]
    2. enabled = true
    3. provider = "AWS"
    4. [object_storage.s3]
    5. aws_access_key_id = "<AWS_ACCESS_KEY_ID>"
    6. aws_secret_access_key = "<AWS_SECRET_ACCESS_KEY>"
  3. 保存文件并重新启动 GitLab,以使更改生效.

Common parameters

在统一配置中, object_store部分定义了一组公共参数. 在这里,我们使用源安装中的 YAML,因为它更容易看到继承:

  1. object_store:
  2. enabled: true
  3. proxy_download: true
  4. connection:
  5. provider: AWS
  6. aws_access_key_id: <AWS_ACCESS_KEY_ID>
  7. aws_secret_access_key: <AWS_SECRET_ACCESS_KEY>
  8. objects:
  9. ...

Omnibus 配置直接映射到此:

  1. gitlab_rails['object_store']['enabled'] = true
  2. gitlab_rails['object_store']['proxy_download'] = true
  3. gitlab_rails['object_store']['connection'] = {
  4. 'provider' => 'AWS',
  5. 'aws_access_key_id' => '<AWS_ACCESS_KEY_ID',
  6. 'aws_secret_access_key' => '<AWS_SECRET_ACCESS_KEY>'
  7. }
Setting Description
enabled 启用/禁用对象存储
proxy_download 设置为true启用代理服务的所有文件 . Option 可以减少出口流量,因为这允许客户端直接从远程存储下载而不是代理所有数据
connection 下述各种连接选项
objects Object-specific configuration

Connection settings

合并配置表单和特定于存储的配置表单都必须配置连接. 以下各节介绍可在connection设置中使用的参数.

S3-compatible connection settings

连接设置与fog-aws提供的设置匹配:

Setting Description Default
provider 始终适用于兼容主机的AWS AWS
aws_access_key_id AWS 凭证或兼容
aws_secret_access_key AWS 凭证或兼容
aws_signature_version 要使用的 AWS 签名版本. 24是有效选项. 数字海洋空间和其他提供商可能需要2 . 4
enable_signature_v4_streaming 设置为true以启用具有AWS v4 签名的 HTTP 分块传输. Oracle Cloud S3 需要将此设置为false . true
region AWS 区域 us-east-1
host 不使用 AWS 时与 S3 兼容的主机,例如localhoststorage.example.com . 假定使用 HTTPS 和端口 443. s3.amazonaws.com
endpoint 在配置 S3 兼容服务(例如MinIO)时 ,可以通过输入 URL(例如http://127.0.0.1:9000 . 这优先于host . (optional)
path_style 设置为true以使用host/bucket_name/object样式路径而不是bucket_name.host/object . 对于 AWS S3,保留为false . false
use_iam_profile Set to true to use IAM profile instead of access keys false

Oracle Cloud S3 connection settings

请注意,Oracle Cloud S3 必须确保使用以下设置:

Setting Value
enable_signature_v4_streaming false
path_style true

如果将enable_signature_v4_streaming设置为true ,那么您可能会在production.log看到以下错误:

  1. STREAMING-AWS4-HMAC-SHA256-PAYLOAD is not supported

Google Cloud Storage (GCS)

这是 GCS 的有效连接参数:

Setting Description example
provider 提供者名称 Google
google_project GCP 项目名称 gcp-project-12345
google_client_email 服务帐户的电子邮件地址 foo@gcp-project-12345.iam.gserviceaccount.com
google_json_key_location JSON 密钥路径 /path/to/gcp-project-12345-abcde.json

注意:服务帐户必须具有访问存储桶的权限. 看更多

Google example (consolidated form)

对于 Omnibus 安装,这是connection设置的示例:

  1. gitlab_rails['object_store']['connection'] = {
  2. 'provider' => 'Google',
  3. 'google_project' => '<GOOGLE PROJECT>',
  4. 'google_client_email' => '<GOOGLE CLIENT EMAIL>',
  5. 'google_json_key_location' => '<FILENAME>'
  6. }

OpenStack-compatible connection settings

注意这与统一对象存储表单不兼容. 仅特定于存储的表单支持 OpenStack Swift. 如果要使用合并表格,请参阅S3 设置 .

尽管 OpenStack Swift 提供了 S3 兼容性,但某些用户可能希望使用Swift API . 这是以下由swift-openstack提供的 Swift API 的有效连接设置:

Setting Description Default
provider 始终使用OpenStack兼容主机 OpenStack
openstack_username OpenStack 用户名
openstack_api_key OpenStack API key
openstack_temp_url_key 用于生成临时 URL 的 OpenStack 密钥
openstack_auth_url OpenStack 身份验证端点
openstack_region OpenStack 区域
openstack_tenant OpenStack 租户 ID

Rackspace Cloud Files

注意这与统一对象存储表单不兼容. 仅特定于存储的表单支持 Rackspace Cloud.

这是fog-rackspace提供的 Rackspace Cloud 的有效连接参数:

Setting Description example
provider 提供者名称 Rackspace
rackspace_username 可访问容器的 Rackspace 帐户的用户名 joe.smith
rackspace_api_key 可访问容器的 Rackspace 帐户的 API 密钥 ABC123DEF456ABC123DEF456ABC123DE
rackspace_region 要使用的 Rackspace 存储区域,来自服务访问端点列表的三个字母代码 iad
rackspace_temp_url_key 您在 Rackspace API 中为临时 URL 设置的私钥. 在这里阅读更多 ABC123DEF456ABC123DEF456ABC123DE

注意:无论容器启用还是禁用了公共访问,Fog 都会使用 TempURL 方法来授予对 LFS 对象的访问权限. 如果您在引用使用temp-url-key实例化存储的日志中看到错误,请确保已在 Rackspace API 和gitlab.rb正确设置了密钥. 您可以通过将带有令牌标头的 GET 请求发送到服务访问端点 URL 并比较返回的标头的输出,来验证 Rackspace 密钥的设置值.

Object-specific configuration

以下 YAML 显示了object_store部分如何定义特定于对象的配置块,以及如何覆盖enabledproxy_download标志. bucket是每种类型中唯一需要的参数:

  1. object_store:
  2. connection:
  3. ...
  4. objects:
  5. artifacts:
  6. bucket: artifacts
  7. proxy_download: false
  8. external_diffs:
  9. bucket: external-diffs
  10. lfs:
  11. bucket: lfs-objects
  12. uploads:
  13. bucket: uploads
  14. packages:
  15. bucket: packages
  16. dependency_proxy:
  17. enabled: false
  18. bucket: dependency_proxy
  19. terraform_state:
  20. bucket: terraform

这映射到此 Omnibus GitLab 配置:

  1. gitlab_rails['object_store']['objects']['artifacts']['bucket'] = 'artifacts'
  2. gitlab_rails['object_store']['objects']['artifacts']['proxy_download'] = false
  3. gitlab_rails['object_store']['objects']['external_diffs']['bucket'] = 'external-diffs'
  4. gitlab_rails['object_store']['objects']['lfs']['bucket'] = 'lfs-objects'
  5. gitlab_rails['object_store']['objects']['uploads']['bucket'] = 'uploads'
  6. gitlab_rails['object_store']['objects']['packages']['bucket'] = 'packages'
  7. gitlab_rails['object_store']['objects']['dependency_proxy']['enabled'] = false
  8. gitlab_rails['object_store']['objects']['dependency_proxy']['bucket'] = 'dependency-proxy'
  9. gitlab_rails['object_store']['objects']['terraform_state']['bucket'] = 'terraform-state'

这是可以使用的有效objects的列表:

Type Description
artifacts CI artifacts
external_diffs Merge request diffs
uploads User uploads
lfs Git Large File Storage objects
packages Project packages (e.g. PyPI, Maven, NuGet, etc.)
dependency_proxy GitLab Dependency Proxy
terraform_state Terraform state files

在每种对象类型中,可以定义三个参数:

Setting Required? Description
bucket Yes 对象存储的存储桶名称.
enabled No 覆盖通用参数
proxy_download No 覆盖通用参数

Selectively disabling object storage

如上所示,可以通过将enabled标志设置为false来禁用特定类型的对象存储. 例如,要禁用 CI 工件的对象存储:

  1. gitlab_rails['object_store']['objects']['artifacts']['enabled'] = false

如果功能完全禁用,则不需要存储桶. 例如,如果使用此设置禁用了 CI 构件,则不需要存储桶:

  1. gitlab_rails['artifacts_enabled'] = false

Transition to consolidated form

在 GitLab 13.2 之前:

  • 所有类型的对象(例如 CI / CD 工件,LFS 文件,上载附件等)的对象存储配置都必须独立配置.
  • 对于每种类型,必须复制对象存储连接参数,例如密码和端点 URL.

例如,Omnibus GitLab 安装可能具有以下配置:

  1. # Original object storage configuration
  2. gitlab_rails['artifacts_object_store_enabled'] = true
  3. gitlab_rails['artifacts_object_store_direct_upload'] = true
  4. gitlab_rails['artifacts_object_store_proxy_download'] = true
  5. gitlab_rails['artifacts_object_store_remote_directory'] = 'artifacts'
  6. gitlab_rails['artifacts_object_store_connection'] = { 'provider' => 'AWS', 'aws_access_key_id' => 'access_key', 'aws_secret_access_key' => 'secret' }
  7. gitlab_rails['uploads_object_store_enabled'] = true
  8. gitlab_rails['uploads_object_store_direct_upload'] = true
  9. gitlab_rails['uploads_object_store_proxy_download'] = true
  10. gitlab_rails['uploads_object_store_remote_directory'] = 'uploads'
  11. gitlab_rails['uploads_object_store_connection'] = { 'provider' => 'AWS', 'aws_access_key_id' => 'access_key', 'aws_secret_access_key' => 'secret' }

尽管这样做提供了灵活性,但它使得 GitLab 可以跨不同的云提供商存储对象,但同时也带来了额外的复杂性和不必要的冗余. 由于 GitLab Rails 和 Workhorse 组件都需要访问对象存储,因此合并后的表单避免了过多的凭据重复.

注意 当省略原始表单中的所有行时, 使用合并对象存储配置. 要移至合并的表单,请除去原始配置(例如, artifacts_object_store_enableduploads_object_store_connection等).

Storage-specific configuration

有关在 GitLab 13.1 和更早版本中配置对象存储的信息,或对于统一配置表单不支持的存储类型的信息,请参阅以下指南:

对象存储类型 支持统一配置吗?
Backups No
Job artifacts and incremental logging Yes
LFS objects Yes
Uploads Yes
容器注册表 (可选功能) No
Merge request diffs Yes
Mattermost No
软件包 (可选功能) Yes
依赖代理 (可选功能) Yes
假名生成器 (可选功能) No
Autoscale Runner 缓存 (可选以提高性能) No
Terraform state files Yes

Other alternatives to filesystem storage

如果您正在努力扩展 GitLab 实施,或增加容错能力和冗余性,则可能正在考虑消除对块或网络文件系统的依赖. 请参阅以下指南,并注意 Pages 需要磁盘存储

  1. 确保git用户主目录位于本地磁盘上.
  2. 配置SSH 密钥的数据库查找,以消除对共享的authorized_keys文件的需要.

Warnings, limitations, and known issues

Use separate buckets

对于 GitLab,建议为每种数据类型使用单独的存储桶.

我们的配置的局限性是对象存储的每次使用都是单独配置的. 我们有一个需要改进的问题 ,轻松地将一个存储桶与单独的文件夹一起使用可能会带来一个改进.

使用同一个存储桶至少有一个特定的问题:当使用 Helm 图表部署 GitLab 时,除非使用单独的存储桶,否则从备份还原将无法正常工作 .

使用单个存储桶的风险之一是,如果您的组织将来决定将 GitLab 迁移到 Helm 部署. GitLab 可以运行,但是直到组织对备份起作用的关键要求之前,备份的情况可能无法实现.

S3 API compatibility issues

并非所有 S3 提供程序与 GitLab 使用的 Fog 库完全兼容 . 症状包括production.log的错误:

  1. 411 Length Required

GitLab Pages requires NFS

如果您要添加更多的 GitLab 服务器以进行缩放或容错,并且您的要求之一是GitLab 页面,则当前需要 NFS. 有工作正在进行中去除这种依赖性. 将来,GitLab 页面可能会使用对象存储 .

对磁盘存储的依赖性还阻止了使用GitLab Helm 图表部署 Pages.

Incremental logging is required for CI to use object storage

如果将 GitLab 配置为将对象存储用于 CI 日志和工件,则还必须启用增量日志记录 .

Proxy Download

对象存储的许多使用情况都允许将客户端流量重定向到对象存储后端,例如当 Git 客户端通过 LFS 请求大文件时或在下载 CI 工件和日志时.

When the files are stored on local block storage or NFS, GitLab has to act as a proxy. This is not the default behavior with object storage.

proxy_download设置控制此行为:默认设置通常为false . 在每个用例的文档中对此进行验证. 将其设置为true以便 GitLab 代理文件.

当不代理文件时,GitLab 将返回HTTP 302 重定向,该重定向带有预先签名的有时间限制的对象存储 URL . 这可能会导致以下一些问题:

  • 如果 GitLab 使用非安全的 HTTP 访问对象存储,则客户端可能会生成https->http降级错误,并拒绝处理重定向. 解决方案是让 GitLab 使用 HTTPS. 例如,LFS 将产生此错误:

    1. LFS: lfsapi/client: refusing insecure redirect, https->http
  • 客户端将需要信任颁发对象存储证书的证书颁发机构,或者可能返回常见的 TLS 错误,例如:

    1. x509: certificate signed by unknown authority
  • 客户端将需要网络访问对象存储. 如果没有此访问权限,则可能导致的错误包括:

    1. Received status code 403 from server: Forbidden

软件包存储库文档中特别注明了获取” 403 Forbidden响应”,这是某些构建工具的工作方式的副作用.

ETag mismatch

使用默认的 GitLab 设置,某些对象存储后端(例如MinIOAlibaba)可能会生成ETag mismatch错误.

如果您在 Amazon Web Services S3 中看到此 ETag 不匹配错误,则可能是由于存储桶上的加密设置所致. 要解决此问题,您有两种选择:

对于 MinIO,建议使用第一个选项. 否则, MinIO解决方法是在服务器上使用--compat参数.

在未启用统一对象存储配置或实例配置文件的情况下,GitLab Workhorse 将使用没有为它们计算出Content-MD5 HTTP 标头的预签名 URL 将文件上传到 S3. 为了确保数据没有损坏,Workhorse 检查发送的数据的 MD5 哈希值是否等于从 S3 服务器返回的 ETag 标头. 启用加密后,情况并非如此,这将导致 Workhorse 在上传期间报告ETag mismatch错误.

通过整合的对象配置和实例配置文件,Workhorse 具有 S3 凭据,因此可以计算Content-MD5标头. 这样就无需比较从 S3 服务器返回的 ETag 标头.

Using Amazon instance profiles

可以将 GitLab 配置为使用 IAM 角色来设置Amazon 实例配置文件 ,而不是在对象存储配置中提供 AWS 访问和秘密密钥. 使用此功能时,每次访问 S3 存储桶时,GitLab 都会获取临时凭证,因此配置中不需要硬编码的值.

Encrypted S3 buckets

版本历史

使用实例概要文件或统一对象配置进行配置时,GitLab Workhorse 可以将文件正确上载到默认情况下启用 SSE-S3 或 SSE-KMS 加密的 S3 存储桶. 请注意, 尚不支持客户主密钥(CMK)和 SSE-C 加密, 因为这需要向 GitLab 配置提供密钥 .

Disabling the feature

use_iam_profile配置选项设置为true时,默认情况下启用 Workhorse S3 客户端.

可以使用:use_workhorse_s3_client功能标记禁用该功能. 要禁用该功能,请要求具有Rails 控制台访问权限的 GitLab 管理员运行以下命令:

  1. Feature.disable(:use_workhorse_s3_client)

IAM Permissions

设置实例配置文件:

  1. 创建具有必要权限的 Amazon Identity Access and Management(IAM)角色. 以下示例是名为test-bucket的 S3 存储桶的角色:

    1. { "Version": "2012-10-17", "Statement": [ { "Sid": "VisualEditor0", "Effect": "Allow", "Action": [ "s3:PutObject", "s3:GetObject", "s3:AbortMultipartUpload", "s3:DeleteObject" ], "Resource": "arn:aws:s3:::test-bucket/*" } ] }
  2. 将此角色附加到托管您的 GitLab 实例的 EC2 实例.

  3. 通过use_iam_profile配置选项配置 GitLab 以使用它.