オブジェクトストレージ

GitLabは多くの種類のデータを保持するためにオブジェクトストレージサービスを使うことをサポートしています。一般的に、オブジェクトストレージの方がパフォーマンス、信頼性、スケーラビリティが高いため、大規模なセットアップではNFSよりも推奨されます。

オブジェクトストレージを設定するには、2つのオプションがあります:

データをローカルに保存している場合は、オブジェクトストレージへのマイグレーション方法を参照してください。

サポートしているオブジェクトストレージプロバイダー

GitLabはFogライブラリと密接にインテグレーションされているため、どのプロバイダがGitLabで使用できるかを確認することができます。

具体的には、GitLabはベンダーや顧客によって多くのオブジェクトストレージプロバイダーでテストされています:

すべてのオブジェクトタイプに対して単一のストレージ接続を設定(統合形式)

GitLab 13.2 で導入されました

CIアーティファクト、LFSファイル、アップロード添付ファイルなど、ほとんどの種類のオブジェクトは、複数のバケットを持つオブジェクトストレージに単一のクレデンシャルを指定することでオブジェクトストレージに保存することができます。

統合フォームを使用してオブジェクトストレージを設定すると、多くの利点があります:

連結フォームを使用すると、直接アップロードが自動的に有効になります。そのため、以下のプロバイダのみが使用可能です:

連結フォーム設定はバックアップやMattermostには使用できません。バックアップは、別途サーバーサイド暗号化で設定できます。サポートされているオブジェクトストレージの種類については、表を参照してください。

連結フォームを有効にすると、すべてのオブジェクトタイプのオブジェクトストレージが有効になります。すべてのバケットが指定されていない場合、次のようなエラーが表示されることがあります:

Object storage for <object type> must have a bucket specified

特定のオブジェクトタイプにローカルストレージを使用したい場合は、特定の機能のオブジェクトストレージを無効にすることができます。

共通パラメータの設定

連結フォームでは、object_store セクションで共通のパラメーターセットを定義します。

設定説明
enabledオブジェクトストレージを有効または無効にします。
proxy_download 提供されるすべてのファイルのプロキシを有効にするには、true に設定します。このオプションを使用すると、クライアントがすべてのデータをプロキシする代わりにリモートストレージから直接ダウンロードできるため、イグレストラフィックを削減できます。
connection様々な接続オプションについては後述します。
storage_options サーバー側の暗号化など、新しいオブジェクトを保存する際に使用するオプション。GitLab 13.3 で導入されました。
objects オブジェクト固有の設定

例として、連結フォームとAmazon S3の使い方をご覧ください。

各オブジェクトのパラメータ設定

各オブジェクトの種類は、少なくともそれが保存されるバケツ名を定義しなければなりません。

次の表は、使用可能なobjects の一覧です:

種類説明
artifactsCIアーティファクト
external_diffsマージリクエストの差分
uploadsユーザーのアップロード
lfsGit ラージファイルストレージオブジェクト
packagesプロジェクトパッケージ (PyPI、Maven、NuGet など)
dependency_proxy依存プロキシ
terraform_stateTerraform ステートファイル
pagesPages

各オブジェクトタイプでは、3つのパラメータを定義できます:

設定必須ですか?説明
bucket {チェックサークル}はいオブジェクトタイプのバケット名。enabledfalse に設定されている場合は必須ではありません。
enabled {点線円}いいえ 共通パラメータを上書きします。
proxy_download {点線円}いいえ 共通パラメータを上書きします。

例として、連結フォームとAmazon S3の使い方をご覧ください。

特定の機能のオブジェクトストレージを無効にします。

enabled フラグをfalse に設定することで、特定のタイプのオブジェクトストレージを無効にすることができます。たとえば、CIアーティファクトのオブジェクトストレージを無効にするには、次のようにします:

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

この機能を完全に無効にすれば、バケツは必要ありません。例えば、この設定でCIアーティファクトを無効にした場合、バケットは必要ありません:

gitlab_rails['artifacts_enabled'] = false

各オブジェクトタイプに独自のストレージ接続を定義する設定(ストレージ固有の形式)

ストレージ専用フォームでは、すべてのオブジェクトが独自のオブジェクトストレージ接続と設定を定義します。GitLab 13.2以降を使用している場合は、統合フォームに移行してください。

非連結フォームでの暗号化されたS3バケットの使用はサポートされていません。使用するとETag mismatchエラーが発生する可能性があります。

note
ストレージ固有形式では、共有フォルダを必要としないため、直接アップロードがデフォルトになる可能性があります。

GitLab 13.1以前のオブジェクトストレージの設定、_または_統合フォームでサポートされていないストレージタイプについては、以下のガイドを参照してください:

オブジェクトストレージの種類連結フォームでサポートされていますか?
セキュリティファイル {点線円}いいえ
バックアップ {点線円}いいえ
コンテナレジストリ(オプション機能) {点線円}いいえ
Mattermost {点線円}いいえ
オートスケールランナーキャッシュ(パフォーマンス向上のためオプション) {点線円}いいえ
アーカイブされたジョブログを含むジョブアーティファクト {チェックサークル}はい
LFSオブジェクト {チェックサークル}はい
アップロード {チェックサークル}はい
マージリクエストの差分 {チェックサークル}はい
パッケージ(オプション機能) {チェックサークル}はい
依存プロキシ(オプション機能) {チェックサークル}はい
Terraform ステートファイル {チェックサークル}はい
ページコンテンツ {チェックサークル}はい

接続設定

連結フォームとストレージ固有フォームの両方で接続を設定する必要があります。以下のセクションでは、connection の設定で使用できるパラメータについて説明します。

Amazon S3

接続設定はFog-awsが提供するものと同じです:

設定説明デフォルト
provider互換性のあるホストに対しては常にAWS です。AWS
aws_access_key_idAWSの認証情報、または互換性のあるもの 
aws_secret_access_keyAWSの認証情報、または互換性のあるもの 
aws_signature_version 2 または4 が有効なオプションです。Digital Ocean Spaces やその他のプロバイダでは、2が必要な場合があります。4
enable_signature_v4_streaming AWS v4 署名で HTTP チャンク転送を有効にするには、true に設定します。Oracle Cloud S3 ではfalseにする必要があります。true
regionAWS リージョン。 
host廃止されました:代わりにendpoint を使用してください。AWSを使用しない場合のS3互換ホスト。例えば、localhost またはstorage.example.com。 HTTPSおよびポート443を想定しています。s3.amazonaws.com
endpoint MinIOなどのS3互換サービスを設定する際に、http://127.0.0.1:9000 のようなURLを入力することで使用できます。これは、hostより優先されます。連結フォームには、常にendpoint を使用してください。(オプション)
path_style bucket_name.host/objectの代わりにhost/bucket_name/object スタイルのパスを使用する場合は、true に設定します。MinIOを使用する場合は、true に設定します。AWS S3 の場合はfalse のままにします。 false.
use_iam_profileアクセスキーの代わりに IAM プロファイルを使用するには、true に設定します。false
aws_credentials_refresh_threshold_secondsIAM で一時的な認証情報を使用する際の自動更新のしきい値を秒単位で設定します。15

Amazonインスタンスプロファイルの使用

オブジェクトストレージの設定でAWSのアクセスキーとシークレットキーを供給する代わりに、Amazon Identity Access and Management(IAM) ロールを使用してAmazonインスタンスプロファイルを設定するようにGitLabを設定することができます。これを使用すると、GitLabはS3バケットにアクセスするたびに一時的な認証情報を取得するので、設定にハードコードされた値は必要ありません。

前提条件:

インスタンスプロファイルを設定するには:

  1. 必要な権限を持つIAMロールを作成します。次の例は、test-bucket という名前のS3バケット用のロールです:

    {
        "Version": "2012-10-17",
        "Statement": [
            {
                "Sid": "VisualEditor0",
                "Effect": "Allow",
                "Action": [
                    "s3:PutObject",
                    "s3:GetObject",
                    "s3:DeleteObject"
                ],
                "Resource": "arn:aws:s3:::test-bucket/*"
            }
        ]
    }
    
  2. このロールをGitLabインスタンスをホストしているEC2インスタンスにアタッチします。
  3. use_iam_profile GitLab設定オプションをtrue に設定します。

暗号化されたS3バケット

インスタンスプロファイルまたは連結フォームで設定した場合、GitLab WorkhorseはSSE-S3またはSSE-KMS暗号化がデフォルトで有効になっているS3バケットに適切にファイルをアップロードします。AWS KMSキーとSSE-C暗号化は、リクエストごとに暗号化キーを送信する必要があるため、サポートされていません。

サーバー側の暗号化ヘッダー

GitLab 13.3 で導入されました

S3バケットにデフォルトの暗号化を設定することは暗号化を有効にする最も簡単な方法ですが、暗号化されたオブジェクトのみがアップロードされるようにバケットポリシーを設定したい場合もあるでしょう。そのためには、storage_options の設定セクションで適切な暗号化ヘッダを送信するように GitLab を設定する必要があります:

設定説明
server_side_encryption暗号化モード (AES256 またはaws:kms)。
server_side_encryption_kms_key_idAmazon リソース名。server_side_encryptionaws:kms を使用する場合にのみ必要です。KMS暗号化の使用については、Amazonのドキュメントを参照してください。

デフォルトの暗号化の場合と同様に、これらのオプションはWorkhorse S3クライアントが有効な場合にのみ機能します。以下の2つの条件のいずれかを満たす必要があります:

  • use_iam_profile が接続設定でtrue
  • 連結フォームを使用しています。

Workhorse S3クライアントを有効にせずにサーバー側の暗号化ヘッダーを使用すると、ETagの不一致エラーが発生します。

Oracle Cloud S3

Oracle Cloud S3は必ず以下の設定を使用してください:

設定
enable_signature_v4_streamingfalse
path_styletrue

enable_signature_v4_streamingtrue に設定されている場合、production.logに以下のエラーが表示されることがあります:

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

Googleクラウドストレージ(GCS)

以下はGCSの有効な接続パラメータです:

設定説明物件例
providerプロバイダー名Google
google_projectGCPプロジェクト名。gcp-project-12345
google_json_key_locationJSONキーのパス。/path/to/gcp-project-12345-abcde.json
google_json_key_stringJSONキー文字列。{ "type": "service_account", "project_id": "example-project-382839", ... }
google_application_default true に設定すると、Google Cloud Application Default Credentialsを使用してサービスアカウントの認証情報を検索します。 

GitLabはgoogle_json_key_location 、次にgoogle_json_key_string 、最後にgoogle_application_default の値を読み込みます。これらの設定のうち、最初に値があるものを使います。

サービスアカウントにはバケットにアクセスする権限が必要です。詳しくはCloud Storage authentication documentation を参照してください。

note
Cloud Key Management Service(KMS)によるバケットの暗号化はサポートされておらず、ETag mismatch エラーが発生します。

GCSの例

Linuxパッケージインストールの場合、connection を連結形式で設定する例です:

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

ADC付きGCSの例

GitLab 13.6で導入されました

Google Cloud Application Default Credentials(ADC) 通常GitLabではデフォルトのサービスアカウントを使用します。これにより、インスタンス用の認証情報を提供する必要がなくなります。例えば、連結形式では

gitlab_rails['object_store']['connection'] = {
  'provider' => 'Google',
  'google_project' => '<GOOGLE PROJECT>',
  'google_application_default' => true
}

ADCを使う場合は、次のことを確認してください:

Azure Blob ストレージ

GitLab 13.4 で導入されました

Azureはブロブの集合を表すのにcontainer という言葉を使いますが、GitLabはbucket. bucketNETという言葉を標準としています。bucket必ず設定でAzureコンテナ名を設定して bucketください。

Azure Blobストレージは、単一の認証情報セットで複数のコンテナにアクセスするため、連結形式でのみ使用できます。ストレージ固有のフォームはサポートされていません。詳細については、統合フォームへの移行方法を参照してください。

以下は、Azure で有効な接続パラメータです。詳細については、Azure Blob Storage のドキュメントを参照してください。

設定説明物件例
providerプロバイダー名AzureRM
azure_storage_account_nameストレージへのアクセスに使用する Azure Blob Storage アカウントの名前。azuretest
azure_storage_access_keyコンテナへのアクセスに使用するストレージアカウントのアクセスキー。これは通常、base64 でエンコードされた秘密の 512 ビット暗号化キーです。czV2OHkvQj9FKEgrTWJRZVRoV21ZcTN0Nnc5eiRDJkYpSkBOY1JmVWpYbjJy\nNHU3eCFBJUQqRy1LYVBkU2dWaw==\n
azure_storage_domainAzure Blob Storage API への問い合わせに使用するドメイン名(オプション)。デフォルトはblob.core.windows.net です。 Azure China、Azure Germany、Azure US Government、またはその他のカスタム Azure ドメインを使用している場合に設定します。blob.core.windows.net
  • Linux パッケージインストールの場合、これは連結フォームでconnection を設定する例です:

     gitlab_rails['object_store']['connection'] = {
       'provider' => 'AzureRM',
       'azure_storage_account_name' => '<AZURE STORAGE ACCOUNT NAME>',
       'azure_storage_access_key' => '<AZURE STORAGE ACCESS KEY>',
       'azure_storage_domain' => '<AZURE STORAGE DOMAIN>'
     }
    
  • セルフコンパイルインストールの場合、Workhorse も Azure クレデンシャルで設定する必要があります。Linux パッケージのインストールでは、Workhorse の設定は前の設定から入力されるので、これは必要ありません。

    1. /home/git/gitlab-workhorse/config.toml を編集し、以下の行を追加または修正します:

      [object_storage]
        provider = "AzureRM"
            
      [object_storage.azurerm]
        azure_storage_account_name = "<AZURE STORAGE ACCOUNT NAME>"
        azure_storage_access_key = "<AZURE STORAGE ACCESS KEY>"
      

    カスタムAzureストレージドメインを使用している場合、azure_storage_domain 、Workhorseの設定で設定する必要はありません。この情報はGitLab RailsとWorkhorse間のAPIコールで交換されます。

Storjゲートウェイ(SJ)

note
Storj Gatewayはマルチスレッドコピーをサポートしていません(表のUploadPartCopy )。実装が計画されている間は、完了するまでマルチスレッドコピーを無効にする必要があります。

Storj Networkは S3 互換の API ゲートウェイを提供します。以下の設定例を使用してください:

gitlab_rails['object_store']['connection'] = {
  'provider' => 'AWS',
  'endpoint' => 'https://gateway.storjshare.io',
  'path_style' => true,
  'region' => 'eu1',
  'aws_access_key_id' => 'ACCESS_KEY',
  'aws_secret_access_key' => 'SECRET_KEY',
  'aws_signature_version' => 2,
  'enable_signature_v4_streaming' => false
}

署名のバージョンは2 でなければなりません。v4 を使用すると、HTTP 411 Length Required エラーが発生します。詳細はイシュー#4419を参照してください。

統合フォームとAmazon S3を使用した完全な例

次の例では、AWS S3 を使用して、サポートされているすべてのサービスのオブジェクトストレージを有効にします:

Linux package (Omnibus)
  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>'
    }
    # OPTIONAL: The following lines are only needed if server side encryption is required
    gitlab_rails['object_store']['storage_options'] = {
      'server_side_encryption' => '<AES256 or aws:kms>',
      'server_side_encryption_kms_key_id' => '<arn:aws:kms:xxx>'
    }
    gitlab_rails['object_store']['objects']['artifacts']['bucket'] = 'gitlab-artifacts'
    gitlab_rails['object_store']['objects']['external_diffs']['bucket'] = 'gitlab-mr-diffs'
    gitlab_rails['object_store']['objects']['lfs']['bucket'] = 'gitlab-lfs'
    gitlab_rails['object_store']['objects']['uploads']['bucket'] = 'gitlab-uploads'
    gitlab_rails['object_store']['objects']['packages']['bucket'] = 'gitlab-packages'
    gitlab_rails['object_store']['objects']['dependency_proxy']['bucket'] = 'gitlab-dependency-proxy'
    gitlab_rails['object_store']['objects']['terraform_state']['bucket'] = 'gitlab-terraform-state'
    gitlab_rails['object_store']['objects']['pages']['bucket'] = 'gitlab-pages'
    

    AWS IAM プロファイルを使用している場合は、AWS アクセスキーとシークレットアクセスキー/値のペアを省略します。例えば

    gitlab_rails['object_store']['connection'] = {
      'provider' => 'AWS',
      'region' => 'eu-central-1',
      'use_iam_profile' => true
    }
    
  2. ファイルを保存して GitLab を再設定してください:

    sudo gitlab-ctl reconfigure
    
Helm chart (Kubernetes)
  1. Kubernetes Secretとして使用するため、object_storage.yaml という名前のファイルに以下の内容を記述します:

    provider: AWS
    region: us-east-1
    aws_access_key_id: <AWS_ACCESS_KEY_ID>
    aws_secret_access_key: <AWS_SECRET_ACCESS_KEY>
    

    AWS IAM プロファイルを使用している場合は、AWS アクセスキーとシークレットアクセスキー/値のペアを省略します。例えば

    provider: AWS
    region: us-east-1
    use_iam_profile: true
    
  2. Kubernetesシークレットを作成します:

    kubectl create secret generic -n <namespace> gitlab-object-storage --from-file=connection=object_storage.yaml
    
  3. Helm の値をエクスポートします:

    helm get values gitlab > gitlab_values.yaml
    
  4. gitlab_values.yaml を編集します:

    global:
      appConfig:
        object_store:
          enabled: false
          proxy_download: true
          storage_options: {}
            # server_side_encryption:
            # server_side_encryption_kms_key_id
          connection:
            secret: gitlab-object-storage
        lfs:
          enabled: true
          proxy_download: true
          bucket: gitlab-lfs
          connection: {}
            # secret:
            # key:
        artifacts:
          enabled: true
          proxy_download: true
          bucket: gitlab-artifacts
          connection: {}
            # secret:
            # key:
        uploads:
          enabled: true
          proxy_download: true
          bucket: gitlab-uploads
          connection: {}
            # secret:
            # key:
        packages:
          enabled: true
          proxy_download: true
          bucket: gitlab-packages
          connection: {}
        externalDiffs:
          enabled: true
          when:
          proxy_download: true
          bucket: gitlab-mr-diffs
          connection: {}
        terraformState:
          enabled: true
          bucket: gitlab-terraform-state
          connection: {}
        ciSecureFiles:
          enabled: true
          bucket: gitlab-ci-secure-files
          connection: {}
        dependencyProxy:
          enabled: true
          proxy_download: true
          bucket: gitlab-dependency-proxy
          connection: {}
    
  5. ファイルを保存して、新しい値を適用します:

    helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
    
Docker
  1. docker-compose.yml を編集します:

    version: "3.6"
    services:
      gitlab:
        environment:
          GITLAB_OMNIBUS_CONFIG: |
            # 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>'
            }
            # OPTIONAL: The following lines are only needed if server side encryption is required
            gitlab_rails['object_store']['storage_options'] = {
              'server_side_encryption' => '<AES256 or aws:kms>',
              'server_side_encryption_kms_key_id' => '<arn:aws:kms:xxx>'
            }
            gitlab_rails['object_store']['objects']['artifacts']['bucket'] = 'gitlab-artifacts'
            gitlab_rails['object_store']['objects']['external_diffs']['bucket'] = 'gitlab-mr-diffs'
            gitlab_rails['object_store']['objects']['lfs']['bucket'] = 'gitlab-lfs'
            gitlab_rails['object_store']['objects']['uploads']['bucket'] = 'gitlab-uploads'
            gitlab_rails['object_store']['objects']['packages']['bucket'] = 'gitlab-packages'
            gitlab_rails['object_store']['objects']['dependency_proxy']['bucket'] = 'gitlab-dependency-proxy'
            gitlab_rails['object_store']['objects']['terraform_state']['bucket'] = 'gitlab-terraform-state'
            gitlab_rails['object_store']['objects']['ci_secure_files']['bucket'] = 'gitlab-ci-secure-files'
            gitlab_rails['object_store']['objects']['pages']['bucket'] = 'gitlab-pages'
    

    AWS IAM プロファイルを使用している場合は、AWS アクセスキーとシークレットアクセスキー/値のペアを省略します。例えば

    gitlab_rails['object_store']['connection'] = {
      'provider' => 'AWS',
      'region' => 'eu-central-1',
      'use_iam_profile' => true
    }
    
  2. ファイルを保存して GitLab を再起動します:

    docker compose up -d
    
Self-compiled (source)
  1. /home/git/gitlab/config/gitlab.yml を編集し、以下の行を追加または修正します:

    production: &base
      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
        storage_options:
          server_side_encryption: <AES256 or aws:kms>
          server_side_encryption_key_kms_id: <arn:aws:kms:xxx>
        objects:
          artifacts:
            bucket: gitlab-artifacts
          external_diffs:
            bucket: gitlab-mr-diffs
          lfs:
            bucket: gitlab-lfs
          uploads:
            bucket: gitlab-uploads
          packages:
            bucket: gitlab-packages
          dependency_proxy:
            bucket: gitlab-dependency-proxy
          terraform_state:
            bucket: gitlab-terraform-state
          ci_secure_files:
            bucket: gitlab-ci-secure-files
          pages:
            bucket: gitlab-pages
    

    AWS IAM プロファイルを使用している場合は、AWS アクセスキーとシークレットアクセスキー/値のペアを省略します。例えば

    connection:
      provider: AWS
      region: eu-central-1
      use_iam_profile: true
    
  2. /home/git/gitlab-workhorse/config.toml を編集し、以下の行を追加または修正します:

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

    AWS IAM プロファイルを使用している場合は、AWS アクセスキーとシークレットアクセスキー/値のペアを省略します。例えば

    [object_storage.s3]
      use_iam_profile = true
    
  3. ファイルを保存して GitLab を再起動します:

    # For systems running systemd
    sudo systemctl restart gitlab.target
       
    # For systems running SysV init
    sudo service gitlab restart
    

オブジェクトストレージへのマイグレーション

既存のローカルデータをオブジェクトストレージにマイグレーションするには、以下のガイドを参照してください:

統合フォームへの移行

GitLab 13.2以前:

  • CI/CD アーティファクト、LFS ファイル、アップロードされた添付ファイルなど、すべてのタイプのオブジェクトストレージの設定は、個別に行う必要がありました。
  • パスワードやエンドポイント URL などのオブジェクト ストア接続パラメータは、タイプごとに複製する必要がありました。

たとえば、Linuxパッケージのインストールでは、次のような設定が考えられます:

# 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)。

オブジェクトを別のオブジェクト・ストレージ・プロバイダにマイグレーションします。

オブジェクトストレージ内のGitLabデータを別のオブジェクトストレージプロバイダにマイグレーションする必要があるかもしれません。次の手順では、Rcloneを使った方法を紹介します。

この手順ではuploads バケットを移行することを想定していますが、他のバケットでも同じ手順が使えます。

前提条件:

  • Rcloneを実行するコンピュータを選択します。マイグレーションするデータの量によっては、Rcloneを長時間実行する必要があるので、省電力にできるラップトップやデスクトップ・コンピュータを使うのは避けるべきです。GitLabサーバーを使ってRcloneを実行することができます。
  1. Rcloneをインストールします。
  2. 以下を実行してRcloneを設定します:

    rclone config
    

    設定プロセスは対話式です。少なくとも 2 つの “リモート” を追加します。1 つは現在データがあるオブジェクトストレージプロバイダー用 (old)、もう 1 つは移行先のプロバイダー用 (new)です。

  3. 古いデータを読めることを確認します。以下の例では、uploads バケットを参照していますが、あなたのバケットには別の名前があるかもしれません:

    rclone ls old:uploads | head
    

    これで、現在uploads バケツに格納されているオブジェクトの一部のリストが表示されるはずです。エラーが表示されたり、リストが空だったりした場合は、rclone config を使って Rclone の設定を更新してください。

  4. 初期コピーを行います。このステップでは、GitLabサーバーをオフラインにする必要はありません。

    rclone sync -P old:uploads new:uploads
    
  5. 最初の同期が完了したら、新しいオブジェクトストレージプロバイダのウェブUIかコマンドラインインターフェイスを使って、新しいバケットにオブジェクトがあることを確認します。もし何もなかったり、rclone sync の実行中にエラーが発生した場合は、Rclone の設定を確認してもう一度試してください。

古い場所から新しい場所へのRcloneコピーが少なくとも1回成功したら、メンテナンスをスケジュールしてGitLabサーバーをオフラインにします。メンテナンス・ウィンドウの間に、2つのことを行う必要があります:

  1. ユーザーが新しいオブジェクトを追加できないことを承知で、古いバケツにオブジェクトを残さないように、最後にrclone sync を実行します。
  2. GitLabサーバーのオブジェクトストレージ設定を更新して、uploads の新しいプロバイダーを使用するようにします。

ファイルシステムストレージの代替

GitLabの実装をスケールアウトしたり、フォールトトレランスや冗長性を追加したりする場合、ブロックファイルシステムやネットワークファイルシステムへの依存を取り除くことを検討しているかもしれません。以下の追加ガイドをご覧ください:

  1. git ユーザーのホームディレクトリ が内部ディスクにあることを確認してください。
  2. SSH キーのデータベース検索を設定し、共有authorized_keys ファイルが不要になるようにします。
  3. ジョブログのローカルディスク使用を防止します。
  4. Pages ローカルストレージを無効にします。

トラブルシューティング

GitLabバックアップにオブジェクトが含まれません。

バックアップのドキュメントにあるように、オブジェクトはGitLabのバックアップには含まれません。代わりにオブジェクトストレージプロバイダーでバックアップを有効にすることができます。

別々のバケットを使う

GitLabでは、データ型ごとに別々のバケットを使うことが推奨されています。こうすることで、GitLabが保存する様々な種類のデータが衝突することがなくなります。イシュー292958では、単一のバケットを使用できるようにすることを提案しています。

Linuxパッケージやセルフコンパイルによるインストールでは、単一の実バケットを複数の仮想バケットに分割することが可能です。オブジェクトストレージのバケットがmy-gitlab-objects と呼ばれる場合、アップロードはmy-gitlab-objects/uploads に、アーティファクトはmy-gitlab-objects/artifacts に、といった設定が可能です。アプリケーションは、これらが別々のバケットであるかのように動作します。バケット接頭辞の使用は、Helmバックアップでは正しく動作しない可能性があります。

Helm ベースのインストールでは、バックアップのリストアを処理するために別のバケットが必要です。

S3 API互換性のイシュー

すべてのS3プロバイダがGitLabが使用しているFogライブラリと完全に互換性があるわけではありません。症状としては、production.log でエラーが発生します:

411 Length Required

プロキシのダウンロード

クライアントは、事前に署名された期限付きのURLを受け取るか、GitLabがオブジェクトストレージからクライアントにデータをプロキシすることで、オブジェクトストレージ内のファイルをダウンロードすることができます。オブジェクトストレージから直接ファイルをダウンロードすることで、GitLabが処理する必要のあるイグレストラフィックの量を減らすことができます。

ファイルがローカルのブロックストレージやNFSに保存されている場合、GitLabはプロキシとして動作しなければなりません。これはオブジェクトストレージのデフォルトの動作ではありません。

proxy_download 設定はこの動作をコントロールします:デフォルトは一般的にfalse です。各使用例のドキュメントで確認してください。GitLabにファイルをプロキシさせたい場合は、true に設定してください。

ファイルをプロキシしない場合、GitLabは事前に署名された時間制限のあるオブジェクトストレージURLでHTTP 302リダイレクトを返します。その結果、以下のような問題が発生する可能性があります:

  • 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
    
  • オブジェクトストレージのバケットは、GitLabインスタンスのURLからCross-Origin Resource Sharing(CORS) アクセスを許可する必要があります。リポジトリページで PDF を読み込もうとすると、以下のエラーが表示されることがあります:

     An error occurred while loading the file. Please try again later.
    

    詳しくはLFS ドキュメントをご覧ください。

さらに、短期間であれば、ユーザーは事前に署名された期間限定のオブジェクトストレージURLを、認証なしで他のユーザーと共有することができます。また、オブジェクトストレージのプロバイダとクライアントの間で帯域幅の料金が発生する場合があります。

ETagの不一致

デフォルトのGitLab設定を使用すると、MinIOや Alibabaなどのオブジェクトストレージバックエンドによっては、ETag mismatch エラーが発生する場合があります。

Amazon Web Services S3 でこの ETag mismatch エラーが発生する場合、バケットの暗号化設定が原因である可能性があります。このイシューを解決するには、2つの方法があります:

MinIOの場合は、最初のオプションを推奨します。それ以外のMinIOの回避策は、サーバーで--compat パラメータを使用することです。

連結フォームやインスタンスプロファイルを有効にしていない場合、GitLab WorkhorseはContent-MD5 HTTPヘッダが計算されていない署名済みのURLを使ってファイルをS3にアップロードします。データが破損していないことを確認するために、Workhorseは送信されたデータのMD5ハッシュがS3サーバーから返されたETagヘッダーと等しいことをチェックします。暗号化が有効な場合、これは当てはまらず、Workhorseはアップロード中にETag mismatch エラーを報告します。

連結形式が

  • S3互換のオブジェクトストレージまたはインスタンスプロファイルで使用される場合、WorkhorseはContent-MD5 ヘッダを計算できるように、S3の認証情報を持つ内部S3クライアントを使用します。これにより、S3サーバーから返されるETagヘッダーを比較する必要がなくなります。
  • S3互換のオブジェクトストレージで使用しない場合、Workhorseは署名済みURLの使用に戻ります。

GCSCloud Key Management Service(KMS)によるバケットの暗号化はサポートされておらず、ETag mismatch エラーが発生します。

マルチスレッドコピー

GitLabは、バケット内のファイルのコピーを高速化するためにS3 Upload Part Copy APIを使用しています。Kraken 11.0.2より前のCeph S3はこれをサポートしておらず、アップロード処理中にファイルがコピーされると404エラーが返されます。

この機能は、:s3_multithreaded_uploads 機能フラグを使用して無効にできます。この機能を無効にするには、RailsコンソールにアクセスできるGitLab管理者に以下のコマンドを実行してもらいます:

Feature.disable(:s3_multithreaded_uploads)