• 지원되는 오브젝트 스토리지 공급자
• 모든 오브젝트 유형에 대해 단일 스토리지 연결 구성하기 (통합 형식)
  • 공통 매개변수 구성
  • 각 객체의 매개변수 구성
    • 특정 기능에 대한 객체 저장소 비활성화
• 각 객체 유형을 구성하여 고유한 저장소 연결 정의 (저장소 전용 형식)
• 연결 설정 구성
  • Amazon S3
    • Amazon 인스턴스 프로필 사용
    • 암호화된 S3 버킷
    • 서버 측 암호화 헤더
  • 오라클 클라우드 S3
  • 구글 클라우드 스토리지 (GCS)
    • GCS 예시
    • GCS 예시와 ADC
  • Azure Blob 스토리지
  • Storj Gateway (SJ)
  • Hitachi Vantara HCP
• Full example using the consolidated form and Amazon S3
• 객체 저장소로 마이그레이션하기
• 통합 형식으로 전환
• 다른 객체 저장소 공급자로 객체 마이그레이션하기
• 파일 시스템 저장소에 대한 대안
• 문제 해결
  • 객체가 GitLab 백업에 포함되지 않음
  • 별도의 버킷 사용
  • S3 API 호환성 문제
  • 항상 download라는 파일 이름으로 다운로드되는 아티팩트
  • 프록시 다운로드
  • ETag 불일치
    • Amazon S3 암호화
    • Google Cloud Storage 암호화
  • 다중 스레드 복사
  • Rails 콘솔을 통한 수동 테스트

오브젝트 스토리지

GitLab은 다양한 유형의 데이터를 저장하기 위해 오브젝트 스토리지 서비스를 사용하는 것을 지원합니다.
NFS보다 권장되며 일반적으로 더 큰 환경에서는 오브젝트 스토리가 훨씬 더 성능이 뛰어나고, 신뢰할 수 있으며, 확장성이 뛰어납니다.

오브젝트 스토리를 구성하려면 두 가지 옵션이 있습니다:

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

• 각 오브젝트 유형별로 자체 스토리지 연결 정의하기:
  각 오브젝트는 자체 오브젝트 스토리지 연결 및 구성을 정의합니다. 이를 스토리지 전용 형식이라고 합니다.

  이미 스토리지 전용 형식을 사용하고 있다면 통합 형식으로 전환하는 방법을 참조하세요.

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

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

GitLab은 Fog 라이브러리와 밀접하게 통합되어 있으므로, GitLab과 함께 사용할 수 있는 공급자를 확인할 수 있습니다.

특히, GitLab은 많은 오브젝트 스토리지 공급자에서 공급업체 및 고객에 의해 테스트되었습니다:

• Amazon S3 (Object Lock 지원되지 않음, 자세한 정보는 issue #335775를 참조하세요)
• Google Cloud Storage
• Digital Ocean Spaces (S3 호환)
• Oracle Cloud Infrastructure
• OpenStack Swift (S3 호환 모드)
• Azure Blob storage
• MinIO (S3 호환)
• 다양한 스토리지 공급업체의 온프레미스 하드웨어 및 장비, 공식적으로 목록이 제공되지 않음.

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

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

통합 형식을 사용하여 오브젝트 스토리를 구성하는 것은 여러 가지 장점이 있습니다:

• 오브젝트 유형 전반에 걸쳐 연결 세부정보가 공유되므로 GitLab 구성을 단순화할 수 있습니다.
• 암호화된 S3 버킷을 사용할 수 있습니다.
• 적절한 Content-MD5 헤더로 S3에 파일을 업로드합니다.

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

• Amazon S3 호환 공급자
• Google Cloud Storage
• Azure Blob storage

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

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

<오브젝트 유형>의 오브젝트 스토리지는 버킷이 지정되어야 합니다.

특정 오브젝트 유형에 대해 로컬 스토리지를 사용하려면,
특정 기능에 대한 오브젝트 스토리지 비활성화하기를 참조하세요.

공통 매개변수 구성

통합된 형식에서 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 차트에서 작업할 때는
차트가 객체 저장소의 통합 형식을 처리하는 방법을 참조하세요.

비통합 형식과 함께 암호화된 S3 버킷의 사용은 지원되지 않습니다.
이를 사용할 경우 ETag 불일치 오류가 발생할 수 있습니다.

참고: 저장소 전용 형식의 경우,
직접 업로드가 기본값이 될 수 있습니다
공유 폴더가 필요하지 않기 때문입니다.

통합 형식으로 지원되지 않는 저장소 유형에 대한 안내는 다음을 참조하세요:

연결 설정 구성

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

Amazon S3

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

Amazon 인스턴스 프로필 사용

객체 저장소 구성에서 AWS 액세스 및 비밀 키를 제공하는 대신에, GitLab이 Amazon Identity Access and Management (IAM) 역할을 사용하여 Amazon 인스턴스 프로필을 설정하도록 구성할 수 있습니다.

이것이 사용될 때마다 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 Workhorse는 SSE-S3 또는 SSE-KMS 암호화가 기본으로 활성화된 S3 버킷에 파일을 올바르게 업로드합니다. AWS KMS 키와 SSE-C 암호화는 각 요청에 암호화 키를 보내야 하므로 지원되지 않습니다.

서버 측 암호화 헤더

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

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

• 연결 설정에서 use_iam_profile가 true입니다.
• 통합 형태가 사용됩니다.

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

오라클 클라우드 S3

오라클 클라우드 S3는 다음 설정을 반드시 사용해야 합니다:

enable_signature_v4_streaming가 true로 설정되면, production.log에서 다음 오류를 볼 수 있습니다:

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

구글 클라우드 스토리지 (GCS)

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

GitLab은 google_json_key_location의 값을 읽은 다음 google_json_key_string을 읽고 마지막으로 google_application_default를 사용합니다. 값이 있는 이러한 설정 중 첫 번째를 사용합니다.

서비스 계정은 버킷에 접근할 수 있는 권한이 있어야 합니다. 더 많은 정보는 Cloud Storage 인증 문서를 참조하세요.

참고: 고객 관리 암호화 키와 함께 버킷 암호화를 사용하려면 통합 형태를 사용하세요.

GCS 예시

리눅스 패키지 설치를 위한 connection 설정의 예시는 다음과 같습니다:

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

GCS 예시와 ADC

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 스토리지

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

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

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

• 리눅스 패키지 설치에 대한 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 자격 증명으로 구성해야 합니다. 리눅스 패키지 설치에서는 이전 설정에서 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 스토리지 도메인을 사용하는 경우, Workhorse 구성에서 azure_storage_domain을 설정할 필요가 없습니다. 이 정보는 GitLab Rails와 Workhorse 간의 API 호출에서 교환됩니다.

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

Hitachi Vantara HCP

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

Full example using the consolidated form and Amazon S3

다음 예제는 AWS S3를 사용하여 모든 지원 서비스에 대해 객체 저장소를 활성화하도록 설정합니다:

객체 저장소로 마이그레이션하기

기존 로컬 데이터를 객체 저장소로 마이그레이션하려면 다음 가이드를 참조하세요:

• 작업 아티팩트 및 아카이브된 작업 로그
• LFS 객체
• 업로드
• 병합 요청 차이
• 패키지 (선택적 기능)
• 의존성 프록시
• Terraform 상태 파일
• 페이지 콘텐츠
• 프로젝트 수준 보안 파일

통합 형식으로 전환

저장소별 구성에서:

• CI/CD 아티팩트, LFS 파일 및 업로드 첨부 파일과 같은 모든 유형의 객체에 대한 객체 저장소 구성은 독립적으로 구성됩니다.
• 비밀번호 및 엔드포인트 URL과 같은 객체 스토어 연결 매개변수는 각 유형마다 복제됩니다.

예를 들어, Linux 패키지 설치는 다음 구성을 가질 수 있습니다:

# 원래 객체 저장소 구성
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이 오랜 시간 실행되어야 할 수 있으므로 절전 모드로 전환될 수 있는 노트북이나 데스크톱 컴퓨터는 피하세요. Rclone을 실행하기 위해 GitLab 서버를 사용할 수 있습니다.

1. 설치 Rclone.

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

   rclone config
   

   구성 프로세스는 대화식입니다. 현재 데이터가 있는 객체 저장소 공급자에 대한 하나(old)와 이동할 공급자에 대한 하나(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 복사를 완료한 후, 유지보수를 예약하고 GitLab 서버를 오프라인 상태로 만드세요. 유지보수 창 동안 두 가지 작업을 수행해야 합니다:

1. 마지막 rclone sync 실행을 수행하여 사용자가 새로운 객체를 추가할 수 없음을 알고 이전 버킷에 남기지 않도록 합니다.
2. uploads에 대한 새로운 공급자를 사용하도록 GitLab 서버의 객체 저장소 구성을 업데이트합니다.

파일 시스템 저장소에 대한 대안

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

항상 download라는 파일 이름으로 다운로드되는 아티팩트

다운로드된 아티팩트 파일 이름은 GetObject 요청에서 response-content-disposition 헤더를 통해 설정됩니다.

S3 제공업체가 이 헤더를 지원하지 않으면 다운로드된 파일은 항상 download로 저장됩니다.

프록시 다운로드

클라이언트는 사전 서명된 시간 제한 URL을 수신하거나 GitLab이 객체 저장소에서 클라이언트로 데이터를 프록시하여 파일을 다운로드할 수 있습니다.

객체 저장소에서 직접 파일을 다운로드하면 GitLab이 처리해야 하는 이그레스 트래픽의 양을 줄이는 데 도움이 됩니다.

파일이 로컬 블록 저장소 또는 NFS에 저장되면 GitLab은 프록시 역할을 해야 합니다.

이는 객체 저장소와 함께하는 기본 동작이 아닙니다.

proxy_download 설정은 이러한 동작을 제어합니다: 기본값은 일반적으로 false입니다.

각 사용 사례에 대한 문서에서 이를 확인하십시오. 파일을 프록시하려면 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 불일치 오류가 발생할 수 있습니다.

Amazon S3 암호화

Amazon Web Services S3에서 이 ETag 불일치 오류가 발생하는 경우, 이는 아마도 버킷의 암호화 설정 때문일 것입니다. 이 문제를 해결하려면 두 가지 옵션이 있습니다:

• 통합 형식 사용.
• Amazon 인스턴스 프로파일 사용.

첫 번째 옵션은 MinIO에 권장됩니다. 그렇지 않은 경우, MinIO의 우회 방법은 서버에서 --compat 매개변수를 사용하는 것입니다.

통합 형식 또는 인스턴스 프로파일이 활성화되지 않으면, GitLab Workhorse는 Content-MD5 HTTP 헤더가 계산되지 않은 사전 서명된 URL을 사용하여 S3에 파일을 업로드합니다. 데이터가 손상되지 않도록 Workhorse는 전송된 데이터의 MD5 해시가 S3 서버에서 반환된 ETag 헤더와 같음을 확인합니다. 암호화가 활성화된 경우, 이 경우와 일치하지 않아 Workhorse가 업로드 중에 ETag 불일치 오류를 보고하게 됩니다.

통합 형식이 사용될 때는:

• S3 호환 객체 저장소 또는 인스턴스 프로파일과 함께 사용될 경우, Workhorse는 내부 S3 클라이언트를 사용하여 보안 자격 증명을 사용하여 Content-MD5 헤더를 계산할 수 있습니다. 이로 인해 S3 서버에서 반환된 ETag 헤더를 비교할 필요가 없어집니다.

• S3 호환 객체 저장소와 함께 사용되지 않을 경우, Workhorse는 사전 서명된 URL을 사용하는 것으로 돌아갑니다.

Google Cloud Storage 암호화

• GitLab 16.11에서 도입됨.

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

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

다중 스레드 복사

GitLab은 파일을 버킷 내에서 복사하는 속도를 높이기 위해 S3 업로드 파트 복사 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에서 설정한 것과 동일한 매개변수를 사용하여 객체 저장소 연결을 설정합니다. 다음 예제 형식을 따릅니다:

   액세스 키를 사용하는 예제 연결:

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