Object Storage

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

• Options

• Configuration guides

  • Consolidated object storage configuration

    • Common parameters

  • Connection settings

    • S3-compatible connection settings
    • Oracle Cloud S3 connection settings

    • Google Cloud Storage (GCS)

      • Google example (consolidated form)

    • OpenStack-compatible connection settings

    • Rackspace Cloud Files

  • Object-specific configuration

    • Selectively disabling object storage

  • Transition to consolidated form

• Storage-specific configuration

  • Other alternatives to filesystem storage

• Warnings, limitations, and known issues

  • Use separate buckets
  • S3 API compatibility issues
  • GitLab Pages requires NFS
  • Incremental logging is required for CI to use object storage
  • Proxy Download
  • ETag mismatch

  • Using Amazon instance profiles

    • Encrypted S3 buckets

      • Disabling the feature

    • IAM Permissions

Object Storage

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

Options

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

• Amazon S3
• Google Cloud Storage
• Digital Ocean Spaces
• Oracle Cloud Infrastructure
• Openstack Swift
• 来自各种存储供应商的本地硬件和设备.
• MinIO. 我们在 Helm Chart 文档中提供了有关部署此配置的指南 .

Configuration guides

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

• 合并形式 ：所有支持的对象类型都共享一个凭证.
• Storage-specific form: Every object defines its own object storage connection and configuration.

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

Consolidated object storage configuration

在GitLab 13.2 中引入.

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

• 由于连接详细信息在对象类型之间共享，因此可以简化您的 GitLab 配置.
• 它允许使用加密的 S3 存储桶 .
• It uploads files to S3 with proper Content-MD5 headers.

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

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

当合并形式为：

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

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

在所有安装中；

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

   # Consolidated object storage configuration
   gitlab_rails['object_store']['enabled'] = true
   gitlab_rails['object_store']['proxy_download'] = true
   gitlab_rails['object_store']['connection'] = {
     'provider' => 'AWS',
     'region' => '<eu-central-1>',
     'aws_access_key_id' => '<AWS_ACCESS_KEY_ID>',
     'aws_secret_access_key' => '<AWS_SECRET_ACCESS_KEY>'
   }
   gitlab_rails['object_store']['objects']['artifacts']['bucket'] = '<artifacts>'
   gitlab_rails['object_store']['objects']['external_diffs']['bucket'] = '<external-diffs>'
   gitlab_rails['object_store']['objects']['lfs']['bucket'] = '<lfs-objects>'
   gitlab_rails['object_store']['objects']['uploads']['bucket'] = '<uploads>'
   gitlab_rails['object_store']['objects']['packages']['bucket'] = '<packages>'
   gitlab_rails['object_store']['objects']['dependency_proxy']['bucket'] = '<dependency-proxy>'
   gitlab_rails['object_store']['objects']['terraform_state']['bucket'] = '<terraform-state>' 

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

   gitlab_rails['object_store_connection'] = {
    'provider' => 'AWS',
    'region' => '<eu-central-1>',
    'use_iam_profile' => true
   } 

   1. 保存文件并重新配置 GitLab，以使更改生效.

在源安装中：

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

   object_store:
    enabled: true
    proxy_download: true
    connection:
      provider: AWS
      aws_access_key_id: <AWS_ACCESS_KEY_ID>
      aws_secret_access_key: <AWS_SECRET_ACCESS_KEY>
      region: <eu-central-1>
    objects:
      artifacts:
        bucket: <artifacts>
      external_diffs:
        bucket: <external-diffs>
      lfs:
        bucket: <lfs-objects>
      uploads:
        bucket: <uploads>
      packages:
        bucket: <packages>
      dependency_proxy:
        bucket: <dependency_proxy>
      terraform_state:
        bucket: <terraform> 

   1. 编辑/home/git/gitlab-workhorse/config.toml并添加或修改以下行：

   [object_storage]
    enabled = true
    provider = "AWS"
   
   [object_storage.s3]
    aws_access_key_id = "<AWS_ACCESS_KEY_ID>"
    aws_secret_access_key = "<AWS_SECRET_ACCESS_KEY>" 

   1. 保存文件并重新启动 GitLab，以使更改生效.

Common parameters

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

 object_store:
      enabled: true
      proxy_download: true
      connection:
        provider: AWS
        aws_access_key_id: <AWS_ACCESS_KEY_ID>
        aws_secret_access_key: <AWS_SECRET_ACCESS_KEY>
      objects:
        ... 

Omnibus 配置直接映射到此：

gitlab_rails['object_store']['enabled'] = true
gitlab_rails['object_store']['proxy_download'] = true
gitlab_rails['object_store']['connection'] = {
  'provider' => 'AWS',
  'aws_access_key_id' => '<AWS_ACCESS_KEY_ID',
  'aws_secret_access_key' => '<AWS_SECRET_ACCESS_KEY>'
} 

Connection settings

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

S3-compatible connection settings

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

Oracle Cloud S3 connection settings

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

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

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

Google Cloud Storage (GCS)

这是 GCS 的有效连接参数：

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

Google example (consolidated form)

对于 Omnibus 安装，这是connection设置的示例：

gitlab_rails['object_store']['connection'] = {
  'provider' => 'Google',
  'google_project' => '<GOOGLE PROJECT>',
  'google_client_email' => '<GOOGLE CLIENT EMAIL>',
  'google_json_key_location' => '<FILENAME>'
} 

OpenStack-compatible connection settings

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

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

Rackspace Cloud Files

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

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

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

Object-specific configuration

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

 object_store:
      connection:
        ...
      objects:
        artifacts:
          bucket: artifacts
          proxy_download: false
        external_diffs:
          bucket: external-diffs
        lfs:
          bucket: lfs-objects
        uploads:
          bucket: uploads
        packages:
          bucket: packages
        dependency_proxy:
          enabled: false
          bucket: dependency_proxy
        terraform_state:
          bucket: terraform 

这映射到此 Omnibus GitLab 配置：

gitlab_rails['object_store']['objects']['artifacts']['bucket'] = 'artifacts'
gitlab_rails['object_store']['objects']['artifacts']['proxy_download'] = false
gitlab_rails['object_store']['objects']['external_diffs']['bucket'] = 'external-diffs'
gitlab_rails['object_store']['objects']['lfs']['bucket'] = 'lfs-objects'
gitlab_rails['object_store']['objects']['uploads']['bucket'] = 'uploads'
gitlab_rails['object_store']['objects']['packages']['bucket'] = 'packages'
gitlab_rails['object_store']['objects']['dependency_proxy']['enabled'] = false
gitlab_rails['object_store']['objects']['dependency_proxy']['bucket'] = 'dependency-proxy'
gitlab_rails['object_store']['objects']['terraform_state']['bucket'] = 'terraform-state' 

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

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

Selectively disabling object storage

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

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

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

gitlab_rails['artifacts_enabled'] = false 

Transition to consolidated form

在 GitLab 13.2 之前：

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

例如，Omnibus GitLab 安装可能具有以下配置：

# Original object storage configuration
gitlab_rails['artifacts_object_store_enabled'] = true
gitlab_rails['artifacts_object_store_direct_upload'] = true
gitlab_rails['artifacts_object_store_proxy_download'] = true
gitlab_rails['artifacts_object_store_remote_directory'] = 'artifacts'
gitlab_rails['artifacts_object_store_connection'] = { 'provider' => 'AWS', 'aws_access_key_id' => 'access_key', 'aws_secret_access_key' => 'secret' }
gitlab_rails['uploads_object_store_enabled'] = true
gitlab_rails['uploads_object_store_direct_upload'] = true
gitlab_rails['uploads_object_store_proxy_download'] = true
gitlab_rails['uploads_object_store_remote_directory'] = 'uploads'
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_enabled ， uploads_object_store_connection等）.

Storage-specific configuration

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

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的错误：

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 将产生此错误：

   LFS: lfsapi/client: refusing insecure redirect, https->http 

  • 客户端将需要信任颁发对象存储证书的证书颁发机构，或者可能返回常见的 TLS 错误，例如：

   x509: certificate signed by unknown authority 

  • 客户端将需要网络访问对象存储. 如果没有此访问权限，则可能导致的错误包括：

   Received status code 403 from server: Forbidden 

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

ETag mismatch

使用默认的 GitLab 设置，某些对象存储后端（例如MinIO和Alibaba）可能会生成ETag mismatch错误.

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

• Use the consolidated object configuration.
• Use Amazon instance profiles.

对于 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 13.1中仅针对实例配置文件引入.
• 使用整合对象存储配置时，在GitLab 13.2 中引入了用于静态证书的功能.

使用实例概要文件或统一对象配置进行配置时，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 管理员运行以下命令：

Feature.disable(:use_workhorse_s3_client) 

IAM Permissions

设置实例配置文件：

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

   {  "Version":  "2012-10-17",  "Statement":  [  {  "Sid":  "VisualEditor0",  "Effect":  "Allow",  "Action":  [  "s3:PutObject",  "s3:GetObject",  "s3:AbortMultipartUpload",  "s3:DeleteObject"  ],  "Resource":  "arn:aws:s3:::test-bucket/*"  }  ]  } 

   1. 将此角色附加到托管您的 GitLab 实例的 EC2 实例.

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