正式なドキュメントは英語版であり、この日本語訳はAI支援翻訳により作成された参考用のものです。日本語訳の一部の内容は人間によるレビューがまだ行われていないため、翻訳のタイミングにより英語版との間に差異が生じることがあります。最新かつ正確な情報については、英語版をご参照ください。

オブジェクトストレージ

  • プラン: Free、Premium、Ultimate
  • 提供形態: GitLab Self-Managed

GitLabでは、さまざまな種類のデータをオブジェクトストレージサービスに保存できます。これはNFSより推奨されており、特に大規模なセットアップではオブジェクトストレージの方が一般的に高い性能、信頼性、そしてスケーラビリティを備えているため、より適しています。

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

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

サポート対象のオブジェクトストレージプロバイダー

GitLabはFogライブラリと緊密に統合されているため、GitLabで使用できるプロバイダーを確認できます。

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

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

CIアーティファクト、LFSファイル、アップロード添付ファイルなど、ほとんどのオブジェクトタイプは、複数のバケットを持つオブジェクトストレージに対して単一の認証情報を指定することで保存できます。

GitLab Helmチャートを使用している場合は、統合形式の設定方法を参照してください。

統合形式を使用してオブジェクトストレージを設定すると、次のような利点があります:

統合形式を使用する場合、直接アップロードが自動的に有効になります。そのため、次のプロバイダーのみを使用できます:

統合形式の設定は、バックアップまたはMattermostには使用できません。バックアップについては、サーバー側の暗号化を個別に設定できます。サポート対象のオブジェクトストレージタイプについては、こちらの完全な一覧表を参照してください。

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

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

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

共通パラメータを設定する

統合形式では、object_storeセクションで共通のパラメータセットを定義します。

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

例については、統合形式とAmazon S3の使用方法を参照してください。

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

各オブジェクトタイプについて、少なくとも保存先のバケット名を定義する必要があります。

次の表に、使用できる有効なobjectsを示します:

型説明
artifactsCI/CDジョブアーティファクト
external_diffsマージリクエストの差分
uploadsユーザーアップロード
lfsGit Large File Storageオブジェクト
packagesプロジェクトパッケージ（例: PyPI、Maven、NuGet）
dependency_proxy依存プロキシ
terraform_stateTerraformステートファイル
pagesPages
ci_secure_files安全なファイル

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

設定必須？説明
bucketcheck-circle はい*オブジェクトタイプのバケット名。enabledがfalseに設定されている場合は必須ではありません。
enableddotted-circle いいえ共通パラメータをオーバーライドします。
proxy_downloaddotted-circle いいえ共通パラメータをオーバーライドします。

例については、統合形式とAmazon S3の使用方法を参照してください。

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

前述のとおり、enabledフラグをfalseに設定することで、特定のオブジェクトタイプに対してオブジェクトストレージを無効にできます。たとえば、CIアーティファクトのオブジェクトストレージを無効にするには、次の手順に従います:

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

機能が完全に無効になっている場合、バケットは必要ありません。たとえば、次の設定によりCIアーティファクトを無効にした場合、バケットは不要です:

gitlab_rails['artifacts_enabled'] = false

オブジェクトタイプごとに個別のストレージ接続を設定する（ストレージ固有形式）

ストレージ固有形式では、オブジェクトごとに個別のオブジェクトストレージの接続と設定を定義します。ただし、統合形式でサポートされていないストレージタイプを除き、統合形式を使用することをおすすめします。GitLab Helmチャートを使用する場合は、チャートがオブジェクトストレージの統合形式をどのように扱うのかを参照してください。

統合形式以外では、暗号化されたS3バケットの使用はサポートされていません。使用すると、ETagの不一致エラーが発生する可能性があります。

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

統合形式でサポートされていないストレージタイプについては、次のガイドを参照してください:

オブジェクトストレージタイプ統合形式でサポートされているか？
バックアップdotted-circle いいえ
コンテナレジストリ（オプション機能）dotted-circle いいえ
Mattermostdotted-circle いいえ
オートスケールRunnerのキャッシュ（パフォーマンスを向上させるためのオプション）dotted-circle いいえ
安全なファイルcheck-circle はい
ジョブアーティファクト（アーカイブされたジョブログを含む）check-circle はい
LFSオブジェクトcheck-circle はい
アップロードcheck-circle はい
マージリクエストの差分check-circle はい
パッケージ（オプション機能）check-circle はい
依存プロキシ（オプション機能）check-circle はい
Terraformステートファイルcheck-circle はい
Pagesコンテンツcheck-circle はい

接続を設定する

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

Amazon S3

接続設定は、fog-awsによって提供されるものと一致します:

設定説明デフォルト
provider互換性のあるホストの場合、常にAWSになります。AWS
aws_access_key_idAWS認証情報、または互換性のある設定。
aws_secret_access_keyAWS認証情報、または互換性のある設定。
aws_signature_version使用するAWS署名バージョン。2または4が有効なオプションです。Digital Ocean Spacesやその他のプロバイダーでは、2が必要な場合があります。4
enable_signature_v4_streamingAWS v4署名でHTTPチャンク転送を有効にする場合はtrueに設定します。Oracle Cloud S3では、これをfalseにする必要があります。GitLab 17.4で、デフォルトがtrueからfalseに変更されました。false
regionAWSリージョン。
host非推奨: 代わりにendpointを使用してください。AWS以外を使用する場合のS3互換ホスト。例: localhost、storage.example.com。HTTPSおよびポート443が前提となります。s3.amazonaws.com
endpointMinIOなどのS3互換サービスを設定する際に使用できます。http://127.0.0.1:9000などのURLを指定します。これは、hostよりも優先されます。統合形式では必ずendpointを使用してください。（オプション）
path_styletrueに設定すると、bucket_name.host/objectではなく、host/bucket_name/object形式のパスを使用します。MinIOを使用する場合はtrueに設定します。AWS S3の場合はfalseのままにします。false
use_iam_profileアクセスキーの代わりにIAMプロファイルを使用する場合はtrueに設定します。false
aws_credentials_refresh_threshold_secondsIAMで一時的な認証情報を使用する場合、自動更新のしきい値（秒）を設定します。15
disable_imds_v2X-aws-ec2-metadata-tokenを取得するIMDS v2エンドポイントへのアクセスを無効にすることで、IMDS v1を強制的に使用させます。false

Amazonインスタンスプロファイルを使用する

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

前提要件:

インスタンスプロファイルを設定するには、次の手順に従います:

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

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

  2. GitLabインスタンスをホストしているEC2インスタンスに、このロールをアタッチします。

  3. GitLab設定オプションuse_iam_profileをtrueに設定します。

暗号化されたS3バケット

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

サーバーサイド暗号化ヘッダー

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

設定説明
server_side_encryption暗号化モード（AES256またはaws:kms）。
server_side_encryption_kms_key_idAmazonリソース名。これが必要になるのはserver_side_encryptionでaws: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_streamingがtrueに設定されている場合、production.logに次のエラーが記録されることがあります:

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

Google Cloud Storage (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_defaultGoogle Cloudのアプリケーションのデフォルト認証情報を使用してサービスアカウントの認証情報を特定する場合は、trueに設定します。

GitLabは、まずgoogle_json_key_location、次にgoogle_json_key_string、最後にgoogle_application_defaultの順に値を読み取ります。これらのうち、値を持つ最初の設定を使用します。

サービスアカウントには、バケットにアクセスするための権限が必要です。詳細については、Cloud Storageの認証に関するドキュメントを参照してください。

Google Cloudのアプリケーションのデフォルト認証情報

Google Cloudのアプリケーションのデフォルト認証情報（ADC）を使用するのは、通常、GitLabでデフォルトのサービスアカウントまたはWorkload Identity連携を使用する場合です。google_application_defaultをtrueに設定し、google_json_key_locationとgoogle_json_key_stringを省略します。

ADCを使用する場合は、次の点を確認してください:

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

  • Google Compute仮想マシンを使用している場合は、Google Cloud APIにアクセスするための適切なアクセススコープが設定されていること。マシンに適切なスコープが設定されていない場合、エラーログに次のように記録されることがあります:

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

顧客管理の暗号化キーでバケットの暗号化を使用するには、統合形式を使用します。

  1. /etc/gitlab/gitlab.rbを編集し、必要な値に置き換えて次の行を追加します:

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

    ADCを使用する場合は、代わりにgoogle_application_defaultを使用します:

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

  2. ファイルを保存して、GitLabを再設定します:

    sudo gitlab-ctl reconfigure

  1. 次の内容をobject_storage.yamlファイルに記述し、Kubernetesシークレットとして使用します:

    provider: Google
google_project: <GOOGLE PROJECT>
google_json_key_location: '<FILENAME>'

    ADCを使用する場合は、代わりにgoogle_application_defaultを使用します:

    provider: Google
google_project: <GOOGLE PROJECT>
google_application_default: 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:
     artifacts:
       bucket: gitlab-artifacts
     ciSecureFiles:
       bucket: gitlab-ci-secure-files
       enabled: true
     dependencyProxy:
       bucket: gitlab-dependency-proxy
       enabled: true
     externalDiffs:
       bucket: gitlab-mr-diffs
       enabled: true
     lfs:
       bucket: gitlab-lfs
     object_store:
       connection:
         secret: gitlab-object-storage
       enabled: true
       proxy_download: false
     packages:
       bucket: gitlab-packages
     terraformState:
       bucket: gitlab-terraform-state
       enabled: true
     uploads:
       bucket: gitlab-uploads

  5. ファイルを保存して、新しい値を適用します:

    helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

  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'] = false
        gitlab_rails['object_store']['connection'] = {
          'provider' => 'Google',
          'google_project' => '<GOOGLE PROJECT>',
          'google_json_key_location' => '<FILENAME>'
        }
        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'

    ADCを使用する場合は、代わりにgoogle_application_defaultを使用します:

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

  2. ファイルを保存して、GitLabを再起動します:

    docker compose up -d

Azure Blob Storage

Azureではblobのコレクションを表す用語としてcontainerを使用していますが、GitLabではこの用語をbucketに統一しています。必ず、bucket設定でAzureコンテナ名を指定してください。

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

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

設定説明例
providerプロバイダー名。AzureRM
azure_storage_account_nameストレージへのアクセスに使用するAzure Blob Storageアカウントの名前。azuretest
azure_storage_access_keyコンテナへのアクセスに使用するストレージアカウントのアクセスキー。これは通常、base64でエンコードされた512ビットの暗号化キーであり、シークレットとして扱われます。これは、AzureワークロードIDまたはマネージドIDを使用する場合は省略可能です。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

  1. /etc/gitlab/gitlab.rbを編集し、必要な値に置き換えて次の行を追加します:

    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>'
}
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'

    ワークロードIDを使用している場合は、azure_storage_access_keyを省略します:

    gitlab_rails['object_store']['connection'] = {
  'provider' => 'AzureRM',
  'azure_storage_account_name' => '<AZURE STORAGE ACCOUNT NAME>',
  'azure_storage_domain' => '<AZURE STORAGE DOMAIN>'
}

  2. ファイルを保存して、GitLabを再設定します:

    sudo gitlab-ctl reconfigure

  1. 次の内容をobject_storage.yamlファイルに記述し、Kubernetesシークレットとして使用します:

    provider: AzureRM
azure_storage_account_name: <YOUR_AZURE_STORAGE_ACCOUNT_NAME>
azure_storage_access_key: <YOUR_AZURE_STORAGE_ACCOUNT_KEY>
azure_storage_domain: blob.core.windows.net

    ワークロードIDまたはマネージドIDを使用している場合は、azure_storage_access_keyを省略します:

    provider: AzureRM
azure_storage_account_name: <YOUR_AZURE_STORAGE_ACCOUNT_NAME>
azure_storage_domain: blob.core.windows.net

  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:
     artifacts:
       bucket: gitlab-artifacts
     ciSecureFiles:
       bucket: gitlab-ci-secure-files
       enabled: true
     dependencyProxy:
       bucket: gitlab-dependency-proxy
       enabled: true
     externalDiffs:
       bucket: gitlab-mr-diffs
       enabled: true
     lfs:
       bucket: gitlab-lfs
     object_store:
       connection:
         secret: gitlab-object-storage
       enabled: true
       proxy_download: false
     packages:
       bucket: gitlab-packages
     terraformState:
       bucket: gitlab-terraform-state
       enabled: true
     uploads:
       bucket: gitlab-uploads

  5. ファイルを保存して、新しい値を適用します:

    helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

  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'] = false
        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>'
        }
        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'

    マネージドIDを使用している場合は、azure_storage_access_keyを省略します。

    gitlab_rails['object_store']['connection'] = {
  'provider' => 'AzureRM',
  'azure_storage_account_name' => '<AZURE STORAGE ACCOUNT NAME>',
  'azure_storage_domain' => '<AZURE STORAGE DOMAIN>'
}

  2. ファイルを保存して、GitLabを再起動します:

    docker compose up -d

自己コンパイルによるインストールの場合、WorkhorseにもAzure認証情報を設定する必要があります。Linuxパッケージインストールの場合、Workhorseの設定は以前の設定が引き継がれるため、この作業は不要です。

  1. /home/git/gitlab/config/gitlab.ymlを編集し、次の行を追加または修正します:

    production: &base
  object_store:
    enabled: true
    proxy_download: false
    connection:
      provider: AzureRM
      azure_storage_account_name: '<AZURE STORAGE ACCOUNT NAME>'
      azure_storage_access_key: '<AZURE STORAGE ACCESS KEY>'
    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

  2. /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ストレージドメインを使用している場合、Workhorseの設定でazure_storage_domainを設定する必要はnot（ありません）。この情報は、GitLab RailsとWorkhorse間のAPIコールでやり取りされます。

  3. ファイルを保存して、GitLabを再起動します:

    # For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

AzureワークロードIDマネージドID

AzureワークロードIDまたはマネージドIDを使用する場合は、設定からazure_storage_access_keyを省略します。azure_storage_access_keyが空の場合、GitLabは次の処理を試みます:

  1. ワークロードIDを使用して一時的な認証情報を取得します。AZURE_TENANT_ID、AZURE_CLIENT_ID、AZURE_FEDERATED_TOKEN_FILEを環境変数に設定しておく必要があります。
  2. ワークロードIDが利用できない場合は、Azureインスタンスメタデータサービスに対して認証情報をリクエストします。
  3. ユーザー委任キーを取得します。
  4. そのキーを使用して、ストレージアカウントのblobにアクセスするためのSASトークンを生成します。

対象のIDにStorage Blob Data Contributorロールが割り当てられていることを確認します。

Storj Gateway（SJ）

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

Storjネットワークは、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を参照してください。

Hitachi Vantara HCP

HCPへの接続時に、次のエラーが返される場合があります。SignatureDoesNotMatch - The request signature we calculated does not match the signature you provided. Check your HCP Secret Access key and signing method.このような場合、ネームスペースではなくテナントのURLにendpointを設定し、バケットパスを<namespace_name>/<bucket_name>の形式で設定していることを確認してください。

HCPは、S3互換のAPIを提供しています。次の設定例を使用してください:

gitlab_rails['object_store']['connection'] = {
  'provider' => 'AWS',
  'endpoint' => 'https://<tenant_endpoint>',
  'path_style' => true,
  'region' => 'eu1',
  'aws_access_key_id' => 'ACCESS_KEY',
  'aws_secret_access_key' => 'SECRET_KEY',
  'aws_signature_version' => 4,
  'enable_signature_v4_streaming' => false
}

# Example of <namespace_name/bucket_name> formatting
gitlab_rails['object_store']['objects']['artifacts']['bucket'] = '<namespace_name>/<bucket_name>'

Ceph RGW

Ceph RGWは、Ceph用のS3互換APIです。次の設定例を使用してください:

gitlab_rails['object_store']['connection'] = {
  'provider' => 'AWS',
  'endpoint' => 'https://rgw-ceph.example.com',
  'region' => 'us-west-1',
  'aws_access_key_id' => 'ACCESS_KEY',
  'aws_secret_access_key' => 'SECRET_KEY',
  'path_style': true
}

Ceph RGWでサーバー側の暗号化を有効にするには、HTTPSを使用して接続する必要があります。Cephは、安全でない接続を介した暗号化リクエストを拒否します。

統合形式とAmazon S3を使用した完全な設定例

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

  1. /etc/gitlab/gitlab.rbを編集し、必要な値に置き換えて次の行を追加します:

    # Consolidated object storage configuration
gitlab_rails['object_store']['enabled'] = true
gitlab_rails['object_store']['proxy_download'] = false
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を再設定します:

    sudo gitlab-ctl reconfigure

  1. 次の内容をobject_storage.yamlファイルに記述し、Kubernetesシークレットとして使用します:

    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:
     artifacts:
       bucket: gitlab-artifacts
     ciSecureFiles:
       bucket: gitlab-ci-secure-files
       enabled: true
     dependencyProxy:
       bucket: gitlab-dependency-proxy
       enabled: true
     externalDiffs:
       bucket: gitlab-mr-diffs
       enabled: true
     lfs:
       bucket: gitlab-lfs
     object_store:
       connection:
         secret: gitlab-object-storage
       enabled: true
       proxy_download: false
     packages:
       bucket: gitlab-packages
     terraformState:
       bucket: gitlab-terraform-state
       enabled: true
     uploads:
       bucket: gitlab-uploads

  5. ファイルを保存して、新しい値を適用します:

    helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

  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'] = false
        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

  1. /home/git/gitlab/config/gitlab.ymlを編集し、次の行を追加または修正します:

    production: &base
  object_store:
    enabled: true
    proxy_download: false
    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

オブジェクトストレージに移行する

既存のローカルデータをオブジェクトストレージに移行するには、次のガイドを参照してください:

統合形式に移行する

ストレージ固有設定の場合:

  • 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'] = false
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'] = false
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. 最初の同期が完了したら、新しいオブジェクトストレージプロバイダーのWeb UIまたはコマンドラインインターフェースを使用して、新しいバケットにオブジェクトが存在することを確認します。オブジェクトが存在しない場合、またはrclone syncの実行中にエラーが発生した場合は、Rcloneの設定を確認し、再試行してください。

以前の場所から新しい場所へのRcloneコピーが少なくとも1回成功したら、メンテナンスのスケジュールを計画し、GitLabサーバーをオフラインにします。メンテナンス期間中は、次の2つの作業を行う必要があります:

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

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

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

  1. gitユーザーのホームディレクトリがローカルディスク上にあることを確認します。
  2. 共有のauthorized_keysファイルの必要性をなくすため、SSHキーのデータベース検索を設定します。
  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

アーティファクトが常にdownloadというファイル名でダウンロードされる

ダウンロードされるアーティファクトのファイル名は、GetObjectリクエスト内のresponse-content-dispositionヘッダーで設定されます。S3プロバイダーがこのヘッダーをサポートしていない場合、ダウンロードされたファイルは常にdownloadという名前で保存されます。

プロキシダウンロード

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

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

proxy_download設定によってこの動作を制御します。デフォルトはfalseです。各ユースケースのドキュメントでこの設定を確認してください。

GitLabにファイルをプロキシ処理させる場合は、proxy_downloadをtrueに設定します。proxy_downloadをtrueに設定すると、GitLabサーバーで大きなパフォーマンスの低下が発生する可能性があります。GitLabサーバーのデプロイでは、proxy_downloadはfalseに設定されています。

proxy_downloadをfalseにすると、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からのクロスオリジンリソース共有（CORS）アクセスを許可している必要があります。リポジトリページでPDFを読み込もうとすると、次のエラーが表示される場合があります:

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

    詳細については、LFSのドキュメントを参照してください。

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

ETagの不一致

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

Amazon S3の暗号化

Amazon Web Services S3でこのETag不一致エラーが発生している場合は、バケットの暗号化設定が原因である可能性があります。この問題を解決するには、次の2つのオプションがあります:

MinIOを使用している場合は、最初のオプションをおすすめします。それ以外のMinIO向けの回避策としては、サーバーで--compatパラメータを使用する方法があります。

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

統合形式では、次のようになります:

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

Google Cloud Storageの暗号化

Google Cloud Storage（GCS）でも、顧客管理の暗号化キー（CMEK）によるデータ暗号化を有効にすると、ETag不一致エラーが発生します。

CMEKを使用する場合は、統合形式を使用してください。

マルチスレッドコピー

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

この機能は、:s3_multithreaded_uploads機能フラグを使用して無効にできます。この機能を無効にするには、Railsコンソールアクセス権を持つGitLab管理者に、次のコマンドを実行するよう依頼してください:

Feature.disable(:s3_multithreaded_uploads)

Railsコンソールを使用して手動でテストする

状況によっては、Railsコンソールを使用してオブジェクトストレージの設定をテストすると役立つ場合があります。次の例では、指定された一連の接続設定をテストし、テスト用オブジェクトの書き込みを試み、最後にそれを読み取ります。

  1. Railsコンソールを起動します。

  2. 次の例の形式で、/etc/gitlab/gitlab.rbで設定したのと同じパラメータを使用して、オブジェクトストレージ接続を設定します:

    既存のアップロード設定を使用した接続の例:

    settings = Gitlab.config.uploads.object_store.connection.deep_symbolize_keys
connection = Fog::Storage.new(settings)

    アクセスキーを使用した接続の例:

    connection = Fog::Storage.new(
  {
    provider: 'AWS',
    region: 'eu-central-1',
    aws_access_key_id: '<AWS_ACCESS_KEY_ID>',
    aws_secret_access_key: '<AWS_SECRET_ACCESS_KEY>'
  }
)

    AWS IAMプロファイルを使用した接続の例:

    connection = Fog::Storage.new(
  {
    provider: 'AWS',
    use_iam_profile: true,
    region: 'us-east-1'
  }
)

  3. テスト対象のバケット名を指定し、テスト用ファイルに書き込み、最後に読み取ります。

    dir = connection.directories.new(key: '<bucket-name-here>')
f = dir.files.create(key: 'test.txt', body: 'test')
pp f
pp dir.files.head('test.txt')

追加のデバッグを有効にする

HTTPリクエストを確認するために、追加のデバッグを有効にすることもできます。ログファイルで認証情報が漏洩しないように、この操作はRailsコンソールで行う必要があります。次に、リクエストのデバッグを有効にする方法をプロバイダー別に示します:

EXCON_DEBUG環境変数を設定します:

ENV['EXCON_DEBUG'] = "1"

また、AWS_DEBUG環境変数を1に設定することで、GitLab WorkhorseログでS3 HTTPリクエストとレスポンスヘッダーのログの生成を有効にすることもできます。Linuxパッケージ（Omnibus）の場合は、以下の手順に従います:

  1. /etc/gitlab/gitlab.rbを編集し、次の行を追加します:

    gitlab_workhorse['env'] = {
  'AWS_DEBUG' => '1'
}

  2. ファイルを保存して、GitLabを再設定します:

    sudo gitlab-ctl reconfigure

    S3互換ストレージのリクエストとレスポンスのヘッダーは、/var/log/gitlab/gitlab-workhorse/currentにログされます。

STDOUTにログを記録するようにロガーを設定します:

Google::Apis.logger = Logger::new(STDOUT)

DEBUG環境変数を設定します:

ENV['DEBUG'] = "1"

完全なオブジェクトの一貫性を確保するためにGeo追跡データベースをリセットする

次のGeoのシナリオを考えてみましょう:

  • 環境は、Geoプライマリノードとセカンダリノードで構成されています。
  • プライマリでオブジェクトストレージに移行しました。
    • セカンダリは、個別のオブジェクトストレージバケットを使用します。
    • オプション「このセカンダリサイトにオブジェクトストレージ上のコンテンツのレプリケーションを許可する」が有効になっています。

このような移行により、オブジェクトは、オブジェクトストレージから物理的に欠落しているにもかかわらず、追跡データベースで同期済みとしてマークされる可能性があります。その場合は、オブジェクトの状態が移行後に一貫性を保つように、Geoセカンダリサイトのレプリケーションをリセットしてください。

オブジェクトストレージへの移行後の不整合

ローカルからオブジェクトストレージに移行すると、データの不整合が発生することがあります。とりわけ、移行前にファイルを手動で削除している時に、Geoと組み合わせて使用した場合に発生する可能性があります。

たとえば、インスタンス管理者がローカルファイルシステムの複数のアーティファクトを手動で削除したとします。このような変更はデータベースに適切に伝播されず、不整合が発生します。オブジェクトストレージへの移行後にこのような不整合が残り、これによってフリクションが生じる可能性があります。これらのファイルはデータベースでまだ参照されているために、Geoセカンダリは引き続きこれらのファイルのレプリケートを試行する可能性がありますが、ファイルは存在していません。

Geoを使用する際に不整合を特定する

次のGeoのシナリオを考えてみましょう:

  • 環境は、Geoプライマリノードとセカンダリノードで構成されている
  • 両方のシステムがオブジェクトストレージに移行されている
    • セカンダリはプライマリと同じオブジェクトストレージを使用する
    • オプションAllow this secondary site to replicate content on Object Storageが無効になっている
  • オブジェクトストレージの移行前に、複数のアップロードが手動で削除された
    • この例では、イシューにアップロードされた2つのイメージ

このようなシナリオでは、セカンダリはプライマリと同じオブジェクトストレージを利用するため、データをレプリケートする必要がなくなります。ただし、一部の不整合により、セカンダリが依然としてデータのレプリケートを試みている様子が管理者に観察されることがあります:

プライマリサイトで次の手順に従います:

  1. 左側のサイドバーの下部で、管理者を選択します。新しいナビゲーションをオンにしている場合は、右上隅でアバターを選択し、管理者を選択します。
  2. Geo > サイトを選択します。
  3. primary site（プライマリサイト）を見て、検証情報を確認します。すべてのアップロードが検証済みです: プライマリの検証が成功していることを示すGeoサイトダッシュボード。
  4. secondary site（セカンダリサイト）を見て、検証情報を確認します。セカンダリサイトは同じオブジェクトストレージを使用しているはずですが、2つのアップロードがまだ同期中であることに注意してください。つまり、アップロードを同期する必要はありません: セカンダリの不整合を示すGeoサイトダッシュボード。

不整合をクリーンアップする

削除コマンドを実行する前に、適切に機能する最近のバックアップを用意しておいてください。

前のシナリオに基づいて、複数のアップロードが原因で不整合が発生しています（これらの不整合は以下で例として使用されます）。

残っている可能性がある不整合を適切に削除するため、次の手順に従います:

  1. 特定された不整合をそれぞれのモデル名にマップします。以降の手順ではモデル名が必要です。

    オブジェクトストレージタイプモデル名
    バックアップ該当なし
    コンテナレジストリ該当なし
    Mattermost該当なし
    オートスケールRunnerキャッシュ該当なし
    安全なファイルCi::SecureFile
    ジョブアーティファクトCi::JobArtifactおよびCi::PipelineArtifact
    LFSオブジェクトLfsObject
    アップロードUpload
    マージリクエストの差分MergeRequestDiff
    パッケージPackages::PackageFile
    依存プロキシDependencyProxy::BlobおよびDependencyProxy::Manifest
    TerraformステートファイルTerraform::StateVersion
    PagesコンテンツPagesDeployment

  2. Railsコンソールを起動します。

  3. 前の手順のモデル名に基づいて、（オブジェクトストレージではなく）ローカルにまだ保存されているすべての「ファイル」をクエリします。この場合アップロードが影響を受けるため、モデル名Uploadが使用されます。openbao.pngがまだローカルに保存されていることを確認します:

    Upload.with_files_stored_locally
    #<Upload:0x00007d35b69def68
  id: 108,
  size: 13346,
  path: "c95c1c9bf91a34f7d97346fd3fa6a7be/openbao.png",
  checksum: "db29d233de49b25d2085dcd8610bac787070e721baa8dcedba528a292b6e816b",
  model_id: 2,
  model_type: "Project",
  uploader: "FileUploader",
  created_at: Wed, 02 Apr 2025 05:56:47.941319000 UTC +00:00,
  store: 1,
  mount_point: nil,
  secret: "[FILTERED]",
  version: 2,
  uploaded_by_user_id: 1,
  organization_id: nil,
  namespace_id: nil,
  project_id: 2,
  verification_checksum: nil>]

  4. 特定されたリソースのidを使用して、それらを適切に削除します。まず、findを使用して正しいリソースであることを確認し、次にdestroyを実行します:

    Upload.find(108)
Upload.find(108).destroy

  5. 必要に応じてfindを再度実行して、リソースが正しく削除されたことを確認します。結果として、リソースは見つからないはずです:

    Upload.find(108)
    ActiveRecord::RecordNotFound: Couldn't find Upload with 'id'=108

影響を受けるすべてのオブジェクトストレージの種類に対して、同じ手順を繰り返します。

マルチノードのGitLabインスタンスでジョブログが欠落している

複数のRailsノード（WebサービスまたはSidekiqを実行しているサーバー）を持つGitLabインスタンスでは、Runnerから送信された後、すべてのノードでジョブログを利用できるようにするメカニズムが必要です。ジョブログは、ローカルディスクまたはオブジェクトストレージに保存できます。

NFSが使用されておらず、インクリメンタルログの生成機能が有効になっていない場合、ジョブログが失われる可能性があります:

  1. Runnerからログを受信するノードは、ログをローカルディスクに書き込みます。
  2. GitLabがログをアーカイブしようとすると、多くの場合、ジョブはログにアクセスできない別のサーバーで実行されます。
  3. オブジェクトストレージへのアップロードが失敗します。

次のエラーも/var/log/gitlab/gitlab-rails/exceptions_json.logにログされる可能性があります:

{
  "severity": "ERROR",
  "exception.class": "Ci::AppendBuildTraceService::TraceRangeError",
  "extra.build_id": 425187,
  "extra.body_end": 12955,
  "extra.stream_size": 720,
  "extra.stream_class": {},
  "extra.stream_range": "0-12954"
}

CIアーティファクトがマルチノード環境のオブジェクトストレージに書き込まれる場合、インクリメンタルログの生成機能を有効にする必要があります。