• サポートしているオブジェクトストレージプロバイダー
• すべてのオブジェクトタイプに対して単一のストレージ接続を設定（統合形式）
  • 共通パラメータの設定
  • 各オブジェクトのパラメータ設定
    • 特定の機能のオブジェクトストレージを無効にします。
• 各オブジェクトタイプに独自のストレージ接続を定義する設定（ストレージ固有の形式）
• 接続設定
  • Amazon S3
    • Amazonインスタンスプロファイルの使用
    • 暗号化されたS3バケット
    • サーバー側の暗号化ヘッダー
  • Oracle Cloud S3
  • Googleクラウドストレージ(GCS)
    • GCSの例
    • ADC付きGCSの例
  • Azure Blob ストレージ
  • Storjゲートウェイ(SJ)
• 統合フォームとAmazon S3を使用した完全な例
• オブジェクトストレージへのマイグレーション
• 統合フォームへの移行
• オブジェクトを別のオブジェクト・ストレージ・プロバイダにマイグレーションします。
• ファイルシステムストレージの代替
• トラブルシューティング
  • GitLabバックアップにオブジェクトが含まれません。
  • 別々のバケットを使う
  • S3 API互換性のイシュー
  • プロキシのダウンロード
  • ETagの不一致
  • マルチスレッドコピー

オブジェクトストレージ

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

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

• 推奨すべてのオブジェクト・タイプに対して単一のストレージ接続を設定します：単一のクレデンシャルを、サポートされるすべてのオブジェクト・タイプで共有します。これは連結形式と呼ばれます。

• 各オブジェクト・タイプが独自のストレージ接続を定義するように設定します：各オブジェクトは独自のオブジェクトストレージ接続と設定を定義します。これをストレージ固有形式と呼びます。

  すでにストレージ固有フォームを使用している場合は、統合フォームへの移行方法を参照してください。

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

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

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

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

• Amazon S3(Object Lockはサポートされていません。詳しくはイシュー#335775をご覧ください)
• Googleクラウドストレージ
• Digital Ocean Spaces(S3互換)
• オラクルクラウドインフラ
• OpenStack Swift（S3互換モード）
• Azure Blobストレージ
• MinIO(S3互換)
• 様々なストレージベンダーのオンプレミスハードウェアとアプライアンス。

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

GitLab 13.2 で導入されました。

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

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

• 接続の詳細がオブジェクトタイプ間で共有されるため、GitLabの設定を簡素化できます。
• 暗号化されたS3バケットを使用することができます。
• 適切なContent-MD5 ヘッダ を付けて S3 にファイルをアップロードします。

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

• Amazon S3互換プロバイダ
• Googleクラウドストレージ
• Azure Blobストレージ

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

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

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

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

共通パラメータの設定

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

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

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

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

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

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

例として、連結フォームと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エラーが発生する可能性があります。

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

接続設定

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

Amazon S3

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

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

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

前提条件：

• GitLabがインスタンスメタデータのエンドポイントに接続できること。
• GitLabがインターネットプロキシを使用するように設定されている場合、エンドポイントIPアドレスをno_proxy リストに追加する必要があります。

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

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 13.1でインスタンスプロファイルとS3のデフォルト暗号化のみに導入されました。
• GitLab 13.2で、連結フォームと S3デフォルトの暗号化が使用されている場合に、静的な認証情報のために導入されました。

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

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

GitLab 13.3 で導入されました。

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

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

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

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

Oracle Cloud S3

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

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

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

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

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

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

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

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を使う場合は、次のことを確認してください：

• 使用するサービスアカウントがiam.serviceAccounts.signBlob 権限を持っていること。通常、これはサービス・アカウントにService Account Token Creator ロールを付与することで行われます。

• 仮想マシンがGoogle Cloud API にアクセスするための正しいアクセス スコープを持っています。マシンに正しいスコープがない場合、エラーログに表示されることがあります：

   Google::Apis::ClientError (insufficientPermissions: Request had insufficient authentication scopes.)
  

Azure Blob ストレージ

GitLab 13.4 で導入されました。

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

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

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

• 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)

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 を使用して、サポートされているすべてのサービスのオブジェクトストレージを有効にします：

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

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

• アーカイブされたジョブログを含むジョブアーティファクト
• LFSオブジェクト
• アップロード
• マージリクエストの差分
• パッケージ（オプション機能）
• 依存プロキシ
• Terraform ステートファイル
• ページコンテンツ
• プロジェクトレベルのセキュアファイル

統合フォームへの移行

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つの方法があります：

• 統合フォームを使用します。
• Amazonインスタンスプロファイルを使用します。

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)