GitLab은 다양한 유형의 데이터를 저장하기 위해 오브젝트 스토리지 서비스 사용을 지원합니다. NFS보다 권장되며, 오브젝트 스토리지는 일반적으로 성능, 안정성, 확장성이 더 뛰어나기 때문에 대규모 설정에서 더 좋습니다.

오브젝트 스토리지를 구성하는 방법에는 두 가지 옵션이 있습니다:

• 권장. 모든 오브젝트 유형에 대한 단일 스토리지 연결 구성: 단일 자격 증명이 지원되는 모든 오브젝트 유형에 공유됩니다. 이를 통합 형식이라고 합니다.

• 각 오브젝트 유형별로 고유한 스토리지 연결 구성: 모든 오브젝트가 자체 오브젝트 스토리지 연결 및 구성을 정의합니다. 이를 스토리지별 형식이라고 합니다.

이미 스토리지별 형식을 사용하고 있는 경우, 통합 형식으로 전환하는 방법을 확인하세요.

데이터를 로컬에 저장하고 있다면, 오브젝트 스토리지로 마이그레이션하는 방법을 확인하세요.

오브젝트 스토리지 공급자 지원#

GitLab은 오브젝트 스토리지에 Fog 라이브러리를 사용하며 다음 세 가지 연결 유형을 지원합니다. 다른 Fog 공급자는 지원되지 않습니다.

오브젝트 스토리지 서비스가 이러한 연결 유형 중 하나와 호환되는 경우, 아래의 해당 연결 설정을 사용하여 구성하세요. 공급자 선택은 사용자에게 달려 있습니다.

활성 테스트 커버리지가 있는 공급자#

GitLab은 다음 공급자를 적극적으로 테스트합니다:

• Amazon S3 - AWS 연결 유형. Object Lock은 지원되지 않습니다. 자세한 내용은 이슈 335775를 참조하세요.

• Google Cloud Storage - Google 연결 유형.

• Azure Blob Storage - AzureRM 연결 유형.

커뮤니티 문서화 공급자#

다음 공급자는 커뮤니티에 의해 문서화되었습니다. GitLab은 이러한 공급자를 테스트하지 않습니다. 구성 예시는 편의를 위해 제공됩니다. 이러한 공급자를 사용하다가 문제가 발생하면, GitLab 지원에서 도움을 드리지 못할 수 있습니다.

• Digital Ocean Spaces. S3 호환, 공급자별 구성 예시를 참조하세요.

• Oracle Cloud Infrastructure. S3 호환, 공급자별 구성 예시를 참조하세요.

• OpenStack Swift (S3 호환 모드).

• Storj Gateway. S3 호환, 공급자별 구성 예시를 참조하세요.

• Ceph RGW. S3 호환, 공급자별 구성 예시를 참조하세요.

• Hitachi Vantara HCP. S3 호환, 공급자별 구성 예시를 참조하세요.

• S3 호환 API를 제공하는 온프레미스 하드웨어 및 어플라이언스.

모든 오브젝트 유형에 대한 단일 스토리지 연결 구성 (통합 형식)#

CI 아티팩트, LFS 파일, 업로드 첨부 파일 등 대부분의 오브젝트 유형은 여러 버킷을 사용하는 오브젝트 스토리지에 단일 자격 증명을 지정하여 오브젝트 스토리지에 저장할 수 있습니다.

GitLab Helm Charts의 경우 통합 형식 구성 방법을 참조하세요.

통합 형식을 사용하여 오브젝트 스토리지를 구성하면 다음과 같은 이점이 있습니다:

• 연결 세부 정보가 오브젝트 유형 간에 공유되므로 GitLab 구성을 단순화할 수 있습니다.

• 암호화된 S3 버킷 사용이 가능합니다.

• 올바른 Content-MD5 헤더로 S3에 파일을 업로드합니다.

통합 형식을 사용하면 직접 업로드가 자동으로 활성화됩니다. 따라서 다음 공급자만 사용할 수 있습니다:

• S3 호환 공급자

• Google Cloud Storage

• Azure Blob storage

통합 형식 구성은 백업 또는 Mattermost에는 사용할 수 없습니다. 백업은 별도로 서버 측 암호화로 구성할 수 있습니다. 지원되는 오브젝트 스토리지 유형의 전체 목록은 표를 참조하세요.

통합 형식을 활성화하면 모든 오브젝트 유형에 대해 오브젝트 스토리지가 활성화됩니다. 모든 버킷이 지정되지 않으면 다음과 같은 오류가 발생할 수 있습니다:

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

특정 오브젝트 유형에 로컬 스토리지를 사용하려면 특정 기능에 대한 오브젝트 스토리지를 비활성화할 수 있습니다.

공통 매개변수 구성#

통합 형식에서 object_store 섹션은 공통 매개변수 집합을 정의합니다.

예시는 통합 형식 및 Amazon S3 사용 방법을 참조하세요.

각 오브젝트의 매개변수 구성#

각 오브젝트 유형은 저장될 버킷 이름을 최소한 정의해야 합니다.

다음 표에는 사용할 수 있는 유효한 objects가 나열되어 있습니다:

각 오브젝트 유형 내에서 세 가지 매개변수를 정의할 수 있습니다:

예시는 통합 형식 및 Amazon S3 사용 방법을 참조하세요.

특정 기능에 대한 오브젝트 스토리지 비활성화#

앞서 설명한 것처럼, enabled 플래그를 false로 설정하여 특정 유형에 대한 오브젝트 스토리지를 비활성화할 수 있습니다. 예를 들어, CI 아티팩트에 대한 오브젝트 스토리지를 비활성화하려면:

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

기능이 완전히 비활성화되면 버킷이 필요하지 않습니다. 예를 들어, 다음 설정으로 CI 아티팩트가 비활성화된 경우 버킷이 필요하지 않습니다:

gitlab_rails['artifacts_enabled'] = false

각 오브젝트 유형별로 고유한 스토리지 연결 구성 (스토리지별 형식)#

스토리지별 형식을 사용하면 모든 오브젝트가 자체 오브젝트 스토리지 연결 및 구성을 정의합니다. 통합 형식에서 지원되지 않는 스토리지 유형을 제외하고는 통합 형식을 사용해야 합니다. GitLab Helm Charts를 사용하는 경우, 차트에서 오브젝트 스토리지에 대한 통합 형식을 처리하는 방법을 참조하세요.

통합 형식을 사용하지 않으면서 암호화된 S3 버킷을 사용하는 것은 지원되지 않습니다. 이를 사용하면 ETag 불일치 오류가 발생할 수 있습니다.

스토리지별 형식의 경우, 공유 폴더가 필요하지 않으므로 직접 업로드가 기본값이 될 수 있습니다.

통합 형식에서 지원되지 않는 스토리지 유형은 다음 가이드를 참조하세요:

연결 설정 구성#

통합 형식과 스토리지별 형식 모두 연결을 구성해야 합니다. 다음 섹션에서는 connection 설정에 사용할 수 있는 매개변수를 설명합니다.

S3 호환 공급자#

이 설정은 AWS 연결 유형을 사용하는 Amazon S3 및 모든 S3 호환 서비스에 적용됩니다. AWS를 직접 사용하지 않는 경우, endpoint를 공급자의 URL로 설정하세요.

S3 호환 서비스는 AWS S3 API를 얼마나 가깝게 구현하는지에 따라 다릅니다. GitLab은 사전 서명 URL, 멀티파트 업로드, 청크 서명 스트리밍 등 특정 S3 동작을 사용하는데, 모든 S3 호환 구현에서 동일하게 지원되지는 않습니다. 공급자가 다른 도구에서는 작동하지만 GitLab에서는 작동하지 않는 경우, 조정이 필요한 설정은 다음과 같습니다:

• aws_signature_version.

• enable_signature_v4_streaming.

연결 설정은 fog-aws에서 제공하는 것과 일치합니다:

S3 호환성 및 알려진 실패 모드#

S3 호환을 주장한다고 해서 공급자가 GitLab과 올바르게 작동한다는 것을 보장하지는 않습니다. S3 호환 공급자에서 오류가 발생하면, 지원 요청을 제기하기 전에 다음 조정을 시도해 보세요:

• 서명 스트리밍: 일부 공급자는 AWS Signature Version 4 스트리밍에 사용되는 청크 전송 인코딩을 거부합니다. enable_signature_v4_streaming: false로 설정하세요.

• 서명 버전: 일부 공급자는 Signature Version 4를 완전히 지원하지 않습니다. aws_signature_version: 2로 설정하세요.

• 경로 스타일 URL: 일부 공급자는 경로 스타일 버킷 주소 지정을 요구합니다. path_style: true로 설정하세요.

• ETag 검증: 일부 공급자는 GitLab이 검증하는 업로드된 오브젝트의 MD5와 일치하지 않는 ETag를 반환합니다. ETag 불일치를 참조하세요.

GitLab 지원은 구성 문제 해결을 도울 수 있지만, 테스트된 세트에 없는 공급자에 특정한 문제에 대해서는 해결을 보장할 수 없습니다.

Amazon 인스턴스 프로파일 사용#

오브젝트 스토리지 구성에서 AWS 액세스 키와 시크릿 키를 제공하는 대신, Amazon Identity Access and Management(IAM) 권한을 사용하여 Amazon 인스턴스 프로파일을 설정하도록 GitLab을 구성할 수 있습니다. 이 방법을 사용하면 S3 버킷에 액세스할 때마다 GitLab이 임시 자격 증명을 가져오므로 구성에 하드코딩된 값이 필요하지 않습니다.

사전 요구 사항:

• GitLab이 인스턴스 메타데이터 엔드포인트에 연결할 수 있어야 합니다.

• GitLab이 인터넷 프록시를 사용하도록 구성된 경우, 엔드포인트 IP 주소를 no_proxy 목록에 추가해야 합니다.

• IMDS v2 액세스의 경우, 홉 제한이 충분한지 확인하세요. GitLab이 컨테이너에서 실행 중인 경우, 제한을 1에서 2로 높여야 할 수 있습니다.

인스턴스 프로파일을 설정하려면:

• 필요한 권한으로 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"
        }
    ]
}

외부 프로세스가 S3 버킷의 오브젝트에 태그를 지정하는 경우(예: AWS GuardDuty Malware Protection), 소스 버킷의 오브젝트 수준 Action 목록에 s3:GetObjectTagging을, 대상 버킷에 s3:PutObjectTagging을 추가하세요. 이러한 권한 없이는 태그가 지정된 오브젝트를 복사할 때 GitLab CopyObject 작업이 AccessDenied로 실패합니다.

• 이 권한을 GitLab 인스턴스를 호스팅하는 EC2 인스턴스에 연결합니다.

• use_iam_profile GitLab 구성 옵션을 true로 설정합니다.

암호화된 S3 버킷#

인스턴스 프로파일 또는 통합 형식으로 구성된 경우, GitLab Workhorse는 기본적으로 SSE-S3 또는 SSE-KMS 암호화가 활성화된 S3 버킷에 파일을 올바르게 업로드합니다. AWS KMS 키와 SSE-C 암호화는 모든 요청에 암호화 키를 전송해야 하므로 지원되지 않습니다.

서버 측 암호화 헤더#

S3 버킷에 기본 암호화를 설정하는 것이 암호화를 활성화하는 가장 쉬운 방법이지만, 버킷 정책을 설정하여 암호화된 오브젝트만 업로드되도록 할 수 있습니다. 이를 위해 storage_options 구성 섹션에서 GitLab이 적절한 암호화 헤더를 전송하도록 구성해야 합니다:

기본 암호화의 경우와 마찬가지로, 이 옵션은 Workhorse S3 클라이언트가 활성화된 경우에만 작동합니다. 다음 두 가지 조건 중 하나를 충족해야 합니다:

• 연결 설정에서 use_iam_profile이 true인 경우.

• 통합 형식을 사용하는 경우.

Workhorse S3 클라이언트를 활성화하지 않고 서버 측 암호화 헤더를 사용하면 ETag 불일치 오류가 발생합니다.

Google Cloud Storage (GCS)#

히스토리

• universe_domain 설정이 GitLab 18.9에서 도입됨.

GCS에 대한 유효한 연결 매개변수는 다음과 같습니다:

GitLab은 google_json_key_location, google_json_key_string, google_application_default 순서로 값을 읽습니다. 값이 있는 첫 번째 설정을 사용합니다.

서비스 계정은 버킷에 액세스할 수 있는 권한을 가져야 합니다. 자세한 내용은 Cloud Storage 인증 문서를 참조하세요.

Google Cloud Application Default Credentials#

Google Cloud Application Default Credentials(ADC)는 일반적으로 GitLab에서 기본 서비스 계정 또는 Workload Identity Federation을 사용하는 데 활용됩니다. 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.)

고객 관리 암호화 키로 버킷 암호화를 사용하려면 통합 형식을 사용하세요.

Linux package (Omnibus)

• /etc/gitlab/gitlab.rb를 편집하고 원하는 값으로 대체하여 다음 줄을 추가합니다:

gitlab_rails['object_store']['connection'] = {
 'provider' => 'Google',
 'google_project' => '',
 'google_json_key_location' => ''
}

ADC를 사용하려면 google_application_default를 대신 사용하세요:

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

비기본 유니버스 도메인을 사용하려면(예: Google Cloud Dedicated):

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

• 파일을 저장하고 GitLab을 재구성합니다:

sudo gitlab-ctl reconfigure

Helm chart (Kubernetes)

• Kubernetes Secret으로 사용하기 위해 object_storage.yaml이라는 파일에 다음 내용을 넣습니다:

provider: Google
google_project: 
google_json_key_location: ''

ADC를 사용하려면 google_application_default를 대신 사용하세요:

provider: Google
google_project: 
google_application_default: true

비기본 유니버스 도메인을 사용하려면(예: Google Cloud Dedicated):

provider: Google
google_project: 
google_application_default: true
universe_domain: 

• Kubernetes Secret을 생성합니다:

kubectl create secret generic -n <namespace> gitlab-object-storage --from-file=connection=object_storage.yaml

• Helm 값을 내보냅니다:

helm get values gitlab > gitlab_values.yaml

• 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

• 파일을 저장하고 새 값을 적용합니다:

helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

Docker

• 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_json_key_location' => ''
        }
        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_application_default' => true
}

비기본 유니버스 도메인을 사용하려면(예: Google Cloud Dedicated):

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

• 파일을 저장하고 GitLab을 재시작합니다:

docker compose up -d

Azure Blob storage#

Azure는 blob 컬렉션을 나타내기 위해 container라는 단어를 사용하지만, GitLab은 bucket이라는 용어를 표준으로 사용합니다. bucket 설정에 Azure 컨테이너 이름을 구성해야 합니다.

Azure Blob storage는 단일 자격 증명 세트를 사용하여 여러 컨테이너에 액세스하기 때문에 통합 형식에서만 사용할 수 있습니다. 스토리지별 형식은 지원되지 않습니다. 자세한 내용은 통합 형식으로 전환하는 방법을 참조하세요.

Azure에 대한 유효한 연결 매개변수는 다음과 같습니다. 자세한 내용은 Azure Blob Storage 문서를 참조하세요.

Linux package (Omnibus)

• /etc/gitlab/gitlab.rb를 편집하고 원하는 값으로 대체하여 다음 줄을 추가합니다:

gitlab_rails['object_store']['connection'] = {
  'provider' => 'AzureRM',
  'azure_storage_account_name' => '',
  'azure_storage_access_key' => '',
  '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_domain' => ''
}

• 파일을 저장하고 GitLab을 재구성합니다:

sudo gitlab-ctl reconfigure

Helm chart (Kubernetes)

• Kubernetes Secret으로 사용하기 위해 object_storage.yaml이라는 파일에 다음 내용을 넣습니다:

provider: AzureRM
azure_storage_account_name: 
azure_storage_access_key: 
azure_storage_domain: blob.core.windows.net

워크로드 또는 관리형 ID를 사용하는 경우, azure_storage_access_key를 생략하세요:

provider: AzureRM
azure_storage_account_name: 
azure_storage_domain: blob.core.windows.net

• Kubernetes Secret을 생성합니다:

kubectl create secret generic -n <namespace> gitlab-object-storage --from-file=connection=object_storage.yaml

• Helm 값을 내보냅니다:

helm get values gitlab > gitlab_values.yaml

• 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

• 파일을 저장하고 새 값을 적용합니다:

helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

Docker

• 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_access_key' => '',
          '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_domain' => ''
}

• 파일을 저장하고 GitLab을 재시작합니다:

docker compose up -d

Self-compiled (source)

자체 컴파일 설치의 경우, Workhorse도 Azure 자격 증명으로 구성해야 합니다. Linux 패키지 설치에서는 Workhorse 설정이 이전 설정에서 채워지기 때문에 이 작업이 필요하지 않습니다.

• /home/git/gitlab/config/gitlab.yml을 편집하고 다음 줄을 추가하거나 수정합니다:

production: &base
  object_store:
    enabled: true
    proxy_download: false
    connection:
      provider: AzureRM
      azure_storage_account_name: ''
      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

• /home/git/gitlab-workhorse/config.toml을 편집하고 다음 줄을 추가하거나 수정합니다:

[object_storage]
  provider = "AzureRM"

[object_storage.azurerm]
  azure_storage_account_name = ""
  azure_storage_access_key = ""

사용자 정의 Azure 스토리지 도메인을 사용하는 경우, azure_storage_domain을 Workhorse 구성에 설정할 필요가 없습니다. 이 정보는 GitLab Rails와 Workhorse 간의 API 호출에서 교환됩니다.

• 파일을 저장하고 GitLab을 재시작합니다:

# systemd를 실행하는 시스템의 경우
sudo systemctl restart gitlab.target

# SysV init을 실행하는 시스템의 경우
sudo service gitlab restart

Azure 워크로드 및 관리형 ID#

히스토리

• GitLab 17.9에서 도입됨

Azure 워크로드 ID 또는 관리형 ID를 사용하려면, 구성에서 azure_storage_access_key를 생략하세요. azure_storage_access_key가 비어 있으면, GitLab은 다음을 시도합니다:

• 워크로드 ID로 임시 자격 증명을 가져옵니다. 환경에 AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_FEDERATED_TOKEN_FILE이 있어야 합니다.

• 워크로드 ID를 사용할 수 없는 경우, Azure Instance Metadata Service에서 자격 증명을 요청합니다.

• 사용자 위임 키를 가져옵니다.

• 해당 키로 SAS 토큰을 생성하여 Storage Account blob에 액세스합니다.

ID에 Storage Blob Data Contributor 권한이 할당되어 있는지 확인하세요.

공급자별 구성 예시#

다음 예시는 비기본 설정이 필요한 특정 S3 호환 공급자에 대한 구성을 보여줍니다. 여기에 나열되지 않은 S3 호환 공급자의 경우, 공급자에 맞는 endpoint를 사용하여 기본 S3 호환 구성을 사용하세요.

Oracle Cloud Infrastructure#

Oracle Cloud Infrastructure S3에는 다음 설정이 필요합니다:

enable_signature_v4_streaming을 true로 설정하면 production.log에서 다음 오류가 발생할 수 있습니다:

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

Storj Gateway (SJ)#

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를 참조하세요.

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.라는 오류가 반환될 수 있습니다. 이러한 경우, endpoint를 네임스페이스 대신 테넌트의 URL로 설정하고, 버킷 경로가 <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
}

# <namespace_name/bucket_name> 형식의 예시
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를 사용하여 지원되는 모든 서비스에 대한 오브젝트 스토리지를 활성화합니다:

Linux package (Omnibus)

• /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_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' => '',
  '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
}

• 파일을 저장하고 GitLab을 재구성합니다:

sudo gitlab-ctl reconfigure

Helm chart (Kubernetes)

• Kubernetes Secret으로 사용하기 위해 object_storage.yaml이라는 파일에 다음 내용을 넣습니다:

provider: AWS
region: us-east-1
aws_access_key_id: 
aws_secret_access_key: 

AWS IAM 프로파일을 사용하는 경우, AWS 액세스 키와 시크릿 액세스 키/값 쌍을 생략하세요. 예를 들어:

provider: AWS
region: us-east-1
use_iam_profile: true

• Kubernetes Secret을 생성합니다:

kubectl create secret generic -n <namespace> gitlab-object-storage --from-file=connection=object_storage.yaml

• Helm 값을 내보냅니다:

helm get values gitlab > gitlab_values.yaml

• 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

• 파일을 저장하고 새 값을 적용합니다:

helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

Docker

• 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_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' => '',
          '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
}

• 파일을 저장하고 GitLab을 재시작합니다:

docker compose up -d

Self-compiled (source)

• /home/git/gitlab/config/gitlab.yml을 편집하고 다음 줄을 추가하거나 수정합니다:

production: &base
  object_store:
    enabled: true
    proxy_download: false
    connection:
      provider: AWS
      aws_access_key_id: 
      aws_secret_access_key: 
      region: eu-central-1
    storage_options:
      server_side_encryption: 
      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

• /home/git/gitlab-workhorse/config.toml을 편집하고 다음 줄을 추가하거나 수정합니다:

[object_storage]
  provider = "AWS"

[object_storage.s3]
  aws_access_key_id = ""
  aws_secret_access_key = ""

AWS IAM 프로파일을 사용하는 경우, AWS 액세스 키와 시크릿 액세스 키/값 쌍을 생략하세요. 예를 들어:

[object_storage.s3]
  use_iam_profile = true

• 파일을 저장하고 GitLab을 재시작합니다:

# systemd를 실행하는 시스템의 경우
sudo systemctl restart gitlab.target

# SysV init을 실행하는 시스템의 경우
sudo service gitlab restart

오브젝트 스토리지로 마이그레이션#

기존 로컬 데이터를 오브젝트 스토리지로 마이그레이션하려면 다음 가이드를 참조하세요:

• 아카이브된 job 로그를 포함한 job 아티팩트

• LFS 오브젝트

• 업로드

• 머지 리퀘스트 diff

• 패키지 (선택 기능)

• Dependency Proxy

• Terraform 상태 파일

• Pages 콘텐츠

• 프로젝트 수준 보안 파일

통합 형식으로 전환#

스토리지별 구성에서:

• 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을 실행할 수 있습니다.

• Rclone을 설치합니다.

• 다음을 실행하여 Rclone을 구성합니다:

rclone config

구성 프로세스는 대화형입니다. 현재 데이터가 있는 오브젝트 스토리지 공급자(old)와 이동할 공급자(new)에 대한 "remote"를 최소 두 개 추가합니다.

• 이전 데이터를 읽을 수 있는지 확인합니다. 다음 예시는 uploads 버킷을 참조하지만 버킷 이름이 다를 수 있습니다:

rclone ls old:uploads | head

이렇게 하면 uploads 버킷에 현재 저장된 오브젝트의 일부 목록이 출력되어야 합니다. 오류가 발생하거나 목록이 비어 있으면 rclone config를 사용하여 Rclone 구성을 업데이트하세요.

• 초기 복사를 수행합니다. 이 단계에서는 GitLab 서버를 오프라인으로 전환할 필요가 없습니다.

rclone sync -P old:uploads new:uploads

• 첫 번째 동기화가 완료된 후, 새 오브젝트 스토리지 공급자의 웹 UI 또는 명령줄 인터페이스를 사용하여 새 버킷에 오브젝트가 있는지 확인합니다. 오브젝트가 없거나 rclone sync를 실행하는 동안 오류가 발생하면, Rclone 구성을 확인하고 다시 시도하세요.

이전 위치에서 새 위치로 성공적인 Rclone 복사를 최소 한 번 수행한 후, 유지 관리를 예약하고 GitLab 서버를 오프라인으로 전환합니다. 유지 관리 기간 동안 두 가지 작업을 수행해야 합니다:

• 최종 rclone sync를 실행합니다. 사용자가 새 오브젝트를 추가할 수 없으므로 이전 버킷에 남겨두지 않아도 됩니다.

• uploads에 새 공급자를 사용하도록 GitLab 서버의 오브젝트 스토리지 구성을 업데이트합니다.

파일 시스템 스토리지 대안#

GitLab 구현을 확장하거나 내결함성 및 이중화를 추가하려는 경우, 블록 또는 네트워크 파일 시스템에 대한 의존성을 제거하는 방법을 모색하고 있을 것입니다. 다음 추가 가이드를 참조하세요:

• git 사용자 홈 디렉터리가 로컬 디스크에 있는지 확인하세요.

• 공유 authorized_keys 파일이 필요 없도록 SSH 키의 데이터베이스 조회를 구성하세요.

• job 로그에 대한 로컬 디스크 사용을 방지하세요.

• Pages 로컬 스토리지를 비활성화하세요.

문제 해결#

오브젝트가 GitLab 백업에 포함되지 않음#

백업 문서에 명시된 대로, 오브젝트는 GitLab 백업에 포함되지 않습니다. 대신 오브젝트 스토리지 공급자로 백업을 활성화할 수 있습니다.

별도의 버킷 사용#

각 데이터 유형에 대해 별도의 버킷을 사용하는 것이 GitLab에 권장되는 방법입니다. 이렇게 하면 GitLab이 저장하는 다양한 유형의 데이터 간에 충돌이 없습니다. 이슈 292958은 단일 버킷 사용을 가능하게 하는 것을 제안합니다.

Linux 패키지 및 자체 컴파일 설치의 경우, 단일 실제 버킷을 여러 가상 버킷으로 분할할 수 있습니다. 오브젝트 스토리지 버킷이 my-gitlab-objects인 경우 업로드는 my-gitlab-objects/uploads, 아티팩트는 my-gitlab-objects/artifacts 등으로 구성할 수 있습니다. 애플리케이션은 이들을 별도의 버킷인 것처럼 처리합니다. 버킷 접두사 사용은 Helm 백업에서 올바르게 작동하지 않을 수 있습니다.

Helm 기반 설치는 백업 복원을 처리하기 위해 별도의 버킷이 필요합니다.

S3 API 호환성 문제#

S3 호환 공급자에서 오류가 발생하면, 일반적인 원인 및 구성 조정에 대해 S3 호환성 및 알려진 실패 모드를 참조하세요. production.log의 411 Length Required 오류는 일반적으로 서명 스트리밍으로 인해 발생합니다. 이를 해결하려면 enable_signature_v4_streaming: false로 설정하세요.

아티팩트가 항상 파일명 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은 시간이 제한되어 있지만 특정 사용자에게 연결되어 있지 않습니다. 미리 서명된 URL을 획득한 모든 사용자는 URL의 유효 기간 동안 인증 없이 오브젝트에 액세스할 수 있습니다. 직접 다운로드는 오브젝트 스토리지 공급자와 클라이언트 간의 대역폭 요금도 발생시킬 수 있습니다.

ETag 불일치#

기본 GitLab 설정을 사용하면, Alibaba와 같은 일부 S3 호환 오브젝트 스토리지 백엔드에서 ETag mismatch 오류가 발생할 수 있습니다.

Amazon S3 암호화#

Amazon Web Services S3에서 ETag 불일치 오류가 발생하는 경우, 버킷의 암호화 설정으로 인한 것일 가능성이 높습니다. 이 문제를 해결하는 방법에는 두 가지가 있습니다:

• 통합 형식을 사용합니다.

• Amazon 인스턴스 프로파일을 사용합니다.

통합 형식은 S3 호환 서비스에 권장됩니다. 일부 서비스는 ETag 불일치 오류를 해결하기 위해 호환성 모드를 활성화하는 등 추가적인 서버 측 구성이 필요할 수 있습니다.

통합 형식 또는 인스턴스 프로파일을 활성화하지 않으면, 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 암호화#

히스토리

• GitLab 16.11에서 도입됨.

ETag 불일치 오류는 고객 관리 암호화 키(CMEK)로 데이터 암호화를 활성화할 때도 Google Cloud Storage(GCS)에서 발생합니다.

CMEK를 사용하려면 통합 형식을 사용하세요.

멀티스레드 복사#

GitLab은 S3 Upload Part Copy API를 사용하여 버킷 내에서 파일 복사를 가속화합니다. 이 기능은 일부 S3 호환 공급자에서 지원되지 않으며, 업로드 중 404 오류를 반환합니다.

멀티스레드 복사를 비활성화하려면, Rails 콘솔 액세스가 있는 GitLab 관리자에게 다음 명령을 실행하도록 요청하세요:

Feature.disable(:s3_multithreaded_uploads)

Rails Console을 통한 수동 테스트#

구성 오류가 의심될 때 오브젝트 스토리지 연결을 확인하려면 이 방법을 사용하세요. 다음 예시는 연결을 테스트하고, 테스트 오브젝트를 쓰고, 다시 읽는 방법을 보여줍니다.

• Rails 콘솔을 시작합니다.

• /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_secret_access_key: ''
  }
)

AWS IAM 프로파일을 사용하는 연결 예시:

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

• 테스트할 버킷 이름을 지정하고, 테스트 파일을 쓰고, 마지막으로 읽습니다.

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

추가 디버깅 활성화#

히스토리

• AWS_DEBUG 환경 변수 지원이 GitLab 18.3에서 도입됨.

HTTP 요청을 확인하기 위해 추가 디버깅을 활성화할 수도 있습니다. 로그 파일에 자격 증명이 유출되는 것을 방지하기 위해 Rails Console에서 이 작업을 수행해야 합니다. 다음은 다양한 공급자에 대해 요청 디버깅을 활성화하는 방법을 보여줍니다:

Amazon S3

EXCON_DEBUG 환경 변수를 설정합니다:

ENV['EXCON_DEBUG'] = "1"

AWS_DEBUG 환경 변수를 1로 설정하여 GitLab Workhorse 로그에서 S3 HTTP 요청 및 응답 헤더 로깅을 활성화할 수도 있습니다. Linux 패키지(Omnibus)의 경우:

• /etc/gitlab/gitlab.rb를 편집하고 다음 줄을 추가합니다:

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

• 파일을 저장하고 GitLab을 재구성합니다:

sudo gitlab-ctl reconfigure

S3 호환 스토리지 요청 및 응답 헤더는 /var/log/gitlab/gitlab-workhorse/current에 기록됩니다.

Google Cloud Storage

로거를 STDOUT에 출력하도록 구성합니다:

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

Azure Blob Storage

DEBUG 환경 변수를 설정합니다:

ENV['DEBUG'] = "1"

Geo 추적 데이터베이스를 초기화하여 오브젝트 일관성 확보#

다음 Geo 시나리오를 가정합니다:

• 환경에 Geo 기본 및 보조 노드가 있습니다.

• 기본에서 오브젝트 스토리지로 마이그레이션했습니다.

보조는 별도의 오브젝트 스토리지 버킷을 사용합니다.

• "Allow this secondary site to replicate content on Object Storage" 옵션이 활성화되어 있습니다.

이러한 마이그레이션은 오브젝트가 추적 데이터베이스에서 동기화된 것으로 표시되지만 오브젝트 스토리지에서 실제로 누락될 수 있습니다. 이 경우, 마이그레이션 후 오브젝트 상태가 일관되게 유지되도록 Geo 보조 사이트 복제를 초기화하세요.

오브젝트 스토리지로 마이그레이션 후 불일치#

로컬에서 오브젝트 스토리지로 마이그레이션할 때 데이터 불일치가 발생할 수 있습니다. 특히 마이그레이션 전에 파일이 수동으로 삭제된 경우, Geo와 함께 사용할 때 더욱 그렇습니다.

예를 들어, 인스턴스 관리자가 로컬 파일 시스템에서 여러 아티팩트를 수동으로 삭제합니다. 이러한 변경 사항은 데이터베이스에 올바르게 전파되지 않아 불일치가 발생합니다. 오브젝트 스토리지로 마이그레이션한 후에도 이러한 불일치가 남아 문제를 일으킬 수 있습니다. Geo 보조는 데이터베이스에는 여전히 참조되지만 더 이상 존재하지 않는 파일을 계속 복제하려고 할 수 있습니다.

Geo를 사용할 때 불일치 식별#

다음 Geo 시나리오를 가정합니다:

• 환경에 Geo 기본 및 보조 노드가 있습니다.

• 두 시스템 모두 오브젝트 스토리지로 마이그레이션되었습니다.

보조는 기본과 동일한 오브젝트 스토리지를 사용합니다.

• Allow this secondary site to replicate content on Object Storage 옵션이 비활성화되어 있습니다.

• 오브젝트 스토리지 마이그레이션 전에 여러 업로드가 수동으로 삭제되었습니다.

이 예시에서는 이슈에 업로드된 두 이미지가 있습니다.

이러한 시나리오에서 보조는 기본과 동일한 오브젝트 스토리지를 사용하므로 더 이상 데이터를 복제할 필요가 없습니다. 불일치로 인해 관리자는 보조가 여전히 데이터를 복제하려고 시도하는 것을 볼 수 있습니다:

기본 사이트에서:

• 오른쪽 상단에서 Admin을 선택합니다.

• 왼쪽 사이드바에서 Geo > Sites를 선택합니다.

• primary site를 보고 확인 정보를 확인합니다. 모든 업로드가 확인되었습니다:

[

](/19.2/administration/img/geo_primary_uploads_verification_v17_11.png)

• secondary site를 보고 확인 정보를 확인합니다. 보조가 동일한 오브젝트 스토리지를 사용해야 함에도 불구하고 두 업로드가 여전히 동기화되고 있음을 주목하세요. 즉, 업로드를 동기화할 필요가 없어야 합니다:

[

](/19.2/administration/img/geo_secondary_uploads_inconsistencies_v17_11.png)

불일치 정리#

삭제 명령을 실행하기 전에 최근의 작동하는 백업이 있는지 확인하세요.

이전 시나리오를 기반으로, 여러 업로드가 불일치를 일으키고 있으며 아래 예시로 사용됩니다.

잠재적인 잔재물을 올바르게 삭제하려면 다음 절차를 따르세요:

• 식별된 불일치를 해당 모델 이름에 매핑합니다. 모델 이름은 다음 단계에서 필요합니다.

• Rails 콘솔을 시작합니다.

• 이전 단계의 모델 이름을 기반으로 여전히 로컬에 저장된(오브젝트 스토리지 대신) 모든 "파일"을 쿼리합니다. 이 경우 업로드가 영향을 받으므로 모델 이름 Upload를 사용합니다. openbao.png가 여전히 로컬에 저장되어 있는 것을 확인하세요:

Upload.with_files_stored_locally

#]

• 식별된 리소스의 id를 사용하여 올바르게 삭제합니다. 먼저 find를 사용하여 올바른 리소스인지 확인하고 destroy를 실행합니다:

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

• 선택적으로, find를 다시 실행하여 리소스가 올바르게 삭제되었는지 확인합니다. 더 이상 찾을 수 없어야 합니다:

Upload.find(108)

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

영향을 받는 모든 오브젝트 스토리지 유형에 대해 이 단계를 반복합니다.

다중 노드 GitLab 인스턴스에서 job 로그가 누락됨#

둘 이상의 Rails 노드(웹 서비스 또는 Sidekiq를 실행하는 서버)가 있는 GitLab 인스턴스에서는 Runner에서 전송된 후 모든 노드에서 job 로그를 사용할 수 있도록 하는 메커니즘이 필요합니다. job 로그는 로컬 디스크 또는 오브젝트 스토리지에 저장할 수 있습니다.

NFS를 사용하지 않고, 증분 로깅 기능이 활성화되지 않은 경우 job 로그가 손실될 수 있습니다:

• 러너에서 로그를 수신하는 노드가 로컬 디스크에 로그를 씁니다.

• GitLab이 로그를 아카이브하려고 할 때, 종종 해당 로그에 액세스할 수 없는 다른 서버에서 job이 실행됩니다.

• 오브젝트 스토리지에 업로드가 실패합니다.

다음 오류가 /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 아티팩트가 오브젝트 스토리지에 기록되는 경우, 증분 로깅 기능을 활성화해야 합니다.