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

객체 저장소

GitLab은 다양한 종류의 데이터를 보관하기 위한 객체 저장소 서비스를 지원합니다. 이는 보통 NFS보다 성능, 신뢰성, 확장성이 더 뛰어나기 때문에 일반적으로 대규모 환경에서 더 나은 선택입니다.

객체 저장소를 구성하는 방법은 두 가지가 있습니다.

• 추천 사항. 모든 객체 유형에 대한 단일 저장소 연결 구성: 모든 지원되는 객체 유형에서 공유하는 하나의 자격 증명입니다. 이를 통틀어된 형태라고 합니다.

• 각 객체 유형별로 자체 저장소 연결을 정의: 각 객체가 자체의 객체 저장소 연결과 구성을 정의합니다. 이를 저장소별 형태라고 합니다.

  이미 저장소별 형태를 사용 중인 경우 통합된 형태로 전환하는 방법을 참조하세요.

데이터를 로컬로 저장하는 경우 객체 저장소로 마이그레이션하는 방법을 참조하세요.

지원되는 객체 저장소 제공업체

GitLab은 Fog 라이브러리와 밀접하게 통합되어 있어 GitLab에서 사용할 수 있는 제공업체를 확인할 수 있습니다.

구체적으로, 다음과 같은 여러 객체 저장소 제공업체에서 고객과 공급업체에 의해 GitLab에서 테스트되었습니다.

• Amazon S3 (Object Lock은 지원되지 않습니다. 자세한 내용은 이슈 #335775를 참조하세요.)
• Google Cloud Storage
• Digital Ocean Spaces (S3 호환)
• Oracle Cloud Infrastructure
• OpenStack Swift (S3 호환 모드)
• Azure Blob 저장소
• MinIO (S3 호환)
• 공식적으로 확립되어 있지 않은 여러 저장소 공급자의 온프레미스 하드웨어 및 기기.

모든 객체 유형을 위한 단일 저장소 연결 구성 (통합된 형태)

CI artifacts, LFS 파일, 그리고 업로드 첨부 파일과 같은 대부분의 객체 유형은 하나의 자격 증명을 지정하여 객체 저장소에 저장될 수 있습니다.

참고: GitLab Helm 차트에서 통합된 형태 구성하는 방법을 확인하세요.

통합된 형태로 객체 저장소를 구성하는 것에는 여러 장점이 있습니다.

• 모든 객체 유형 간에 연결 세부 정보를 공유하기 때문에 GitLab 구성을 단순화할 수 있습니다.
• 암호화된 S3 버킷을 사용할 수 있습니다.
• 적절한 Content-MD5 헤더로 S3에 파일을 업로드합니다.

통합된 형태를 사용하면 직접 업로드가 자동으로 활성화됩니다. 따라서 다음 제공업체만 사용할 수 있습니다.

• Amazon S3 호환 제공업체
• Google Cloud Storage
• Azure Blob 저장소

통합된 형태 구성은 백업이나 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. 이 역할을 EC2 인스턴스에 부여하세요.
3. GitLab 구성 옵션인 use_iam_profile을 true로 설정하세요.

암호화된 S3 버킷

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

서버 측 암호화 헤더

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

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

• 연결 설정에서 use_iam_profile이 true로 설정됨.
• 통합된 형식이 사용 중인 경우.

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

Oracle Cloud S3

Oracle Cloud S3를 사용하려면 다음 설정을 사용해야 합니다:

enable_signature_v4_streaming이 true로 설정된 경우 production.log에 다음과 같은 오류가 표시될 수 있습니다:

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

Google Cloud Storage (GCS)

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

GitLab은 google_json_key_location의 값을 읽은 후 google_json_key_string, 그리고 마지막으로 google_application_default 값을 읽습니다. 이러한 설정 중 가장 먼저 값이 있는 설정을 사용합니다.

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

참고: 고객 관리형 암호화 키로 버킷 암호화를 사용하려면 통합된 형식을 사용해야 합니다.

GCS 예시

Linux 패키지 설치의 경우, 통합 형식의 connection 설정의 예는 다음과 같습니다:

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

ADC가 포함된 GCS 예시

일반적으로 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 Storage

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

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

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 스토리지 도메인을 사용하는 경우 Workhorse 구성에 azure_storage_domain을 설정하지 않아도 됩니다. 이 정보는 GitLab Rails와 Workhorse 간의 API 호출 중에 교환됩니다.

Storj Gateway (SJ)

참고: Storj 게이트웨이는 멀티 스레드 복사(테이블의 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에 대한 연결이 네임스페이스가 아닌 테넌트의 URL로 설정되어 있고 버킷 경로가 <namespace_name>/<bucket_name>로 구성되어야 하는 경우, SignatureDoesNotMatch - The request signature we calculated does not match the signature you provided. Check your HCP Secret Access key and signing method. 오류가 발생할 수 있습니다.

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

Amazon S3와 통합된 형태를 사용한 전체 예시

다음 예시는 모든 지원되는 서비스에 대한 객체 저장소를 활성화하기 위해 AWS S3를 사용합니다:

객체 스토리지로 이관

기존 로컬 데이터를 객체 스토리지로 이관하려면 다음 안내를 참조하세요:

• 작업 아티팩트 작업 아티팩트에는 아카이브된 작업 로그가 포함됨
• LFS 객체 LFS 객체
• 업로드 업로드
• 병합 요청 차이 Merge request diffs
• 패키지 패키지 (옵션 기능)
• 의존성 프록시 Dependency Proxy
• Terraform 상태 파일 Terraform state files
• 페이지 콘텐츠 Pages content
• 프로젝트 수준의 보안 파일 Project-level Secure Files

통합 형태로 전환

저장소별 구성에서:

• 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를 사용하여 수행하는 방법을 안내합니다.

이 단계는 ‘업로드’ 버킷을 이동하는 것으로 가정하지만, 동일한 프로세스가 다른 버킷에 대해서도 동작합니다.

전제 조건:

• Rclone을 실행할 컴퓨터를 선택하세요. 이관할 데이터의 양에 따라 Rclone이 오랜 시간 실행될 수 있으므로 절전 모드로 전환될 수 있는 랩탑이나 데스크탑 컴퓨터는 피해야 합니다. GitLab 서버를 사용하여 Rclone을 실행할 수 있습니다.

1. Rclone 설치

2. 다음을 실행하여 Rclone을 구성하세요:

   rclone config
   

   구성 프로세스는 대화형입니다. 현재 데이터가 있는 객체 저장소 제공업체를 위한 하나(old)와 이동하려는 제공업체를 위한 하나(new) 이상의 “remotes”를 추가합니다.

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. GitLab 서버의 객체 저장소 구성을 ‘uploads’에 대해 새 제공자를 사용하도록 업데이트

파일 시스템 저장소의 대체안

GitLab 구현을 확장하거나 오류 허용성 및 내결함성을 추가하기 위해 블록 또는 네트워크 파일 시스템에 대한 의존성을 제거할 수 있습니다. 다음의 추가적인 안내를 참조하세요:

1. git 사용자 홈 디렉토리가 로컬 디스크에 있는지 확인하세요.
2. SSH 키의 데이터베이스 조회를 구성하여 공유 ‘authorized_keys’ 파일의 필요성을 제거하세요.
3. 작업 로그에 대한 로컬 디스크 사용 방지
4. 페이지 로컬 저장소 비활성화.

문제 해결

GitLab 백업에 객체가 포함되지 않음

백업 문서에 언급된 바와 같이 객체는 GitLab 백업에 포함되지 않습니다. 대신 객체 저장소 제공업체와 함께 백업을 활성화할 수 있습니다.

별도의 버킷 사용

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

리눅스 패키지 및 자체 컴파일 설치를 사용하면 단일 가상 버킷을 여러 가상 버킷으로 분할할 수 있습니다. 객체 저장소 버킷이 ‘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 다운그레이드 오류를 생성하고 리디렉션 처리를 거부할 수 있습니다. 예를 들어, 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를 로드하려고 하면 다음과 같은 오류가 표시될 수 있습니다.

  파일을 로드하는 중 오류가 발생했습니다. 나중에 다시 시도하세요.
  

  자세한 내용은 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 자격 증명을 가진 내부 S3 클라이언트를 사용하여 Content-MD5 헤더를 계산할 수 있습니다. 이는 S3 서버에서 반환된 ETag 헤더를 비교할 필요가 없게 합니다.
• S3 호환형 객체 저장소와 함께 사용되지 않는 경우, Workhorse는 사전 서명된 URL을 사용하기 위해 되감아 사용합니다.

Google Cloud Storage 암호화

• GitLab 16.11에서 도입.

Google Cloud Storage (GCS)에서도 고객 관리형 암호화 키(CMEK)를 사용하면 ETag 불일치 오류가 발생합니다.

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

다중 스레드 복사

GitLab은 버킷 내에서 파일 복사를 가속화하기 위해 S3 Upload Part Copy API를 사용합니다. Ceph S3는 Kraken 11.0.2 이전 버전에서는 이를 지원하지 않고 업로드 프로세스 중에 파일을 복사하면 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: '<여기에 버킷 이름 입력>')
   f = dir.files.create(key: 'test.txt', body: 'test')
   pp f
   pp dir.files.head('test.txt')