• 지원되는 객체 스토리지 제공 업체
• 단일 스토리지 연결 구성 (통합 형식)
  • 공통 매개 변수 구성
  • 각 객체 유형의 매개 변수 구성
    • 특정 기능을위한 객체 스토리지 사용 안 함
• 각 객체 유형을 정의하기 위한 자체 스토리지 연결 구성 (리포지터리별 형식)
• 연결 설정 구성
  • Amazon S3
    • Amazon 인스턴스 프로필 사용
    • 암호화된 S3 버킷
    • 서버 측 암호화 헤더
  • Oracle Cloud S3
  • Google Cloud Storage (GCS)
    • GCS 예시
    • ADC를 사용한 GCS 예시
  • Azure Blob 리포지터리
  • Storj Gateway (SJ)
  • Hitachi Vantara HCP
• Amazon S3를 사용한 통합된 형식 및 전체 예시
• 객체 리포지터리로 이관
• 통합형으로 전환
• 객체의 다른 객체 리포지터리 제공업체로 이관
• 파일 시스템 리포지터리 대체 옵션
• 문제 해결
  • 객체가 GitLab 백업에 포함되지 않음
  • 별도의 버킷 사용
  • S3 API 호환성 문제
  • 프록시 다운로드
  • 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

통합 형태 구성은 백업 또는 Matermost에는 사용할 수 없습니다. 서버 측 암호화로 백업을 구성할 수 있습니다. 지원되는 객체 스토리지 유형의 완전한 디렉터리을 위해 표를 참조하십시오.

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

<object type>의 객체 스토리지에 버킷을 지정해야합니다

특정 객체 유형에 대해 로컬 스토리지를 사용하려면 특정 기능을위한 객체 스토리지를 사용 안 함을 참조하십시오.

공통 매개 변수 구성

통합 형태에서 object_store 섹션은 공통 매개 변수를 정의합니다.

예를 들어 통합 형태 및 Amazon S3 사용를 참조하십시오.

각 객체 유형의 매개 변수 구성

각 객체 유형은 저장될 버킷 이름을 적어도 정의해야합니다.

다음 표는 사용할 수 있는 유효한 objects를 나열합니다.

각 객체 유형 내에서 다음과 같은 세 가지 매개 변수를 정의할 수 있습니다.

예를 들어 통합 형태 및 Amazon S3 사용를 참조하십시오.

특정 기능을위한 객체 스토리지 사용 안 함

위에서 볼 수 있듯이 특정 유형의 객체 리포지터리를 사용 안 함으로 설정하여 enabled 플래그를 false로 설정할 수 있습니다. 예를 들어 CI 아티팩트의 객체 리포지터리를 사용 안 함으로 설정하려면 다음과 같이 설정하십시오.

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

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

gitlab_rails['artifacts_enabled'] = false

각 객체 유형을 정의하기 위한 자체 스토리지 연결 구성 (리포지터리별 형식)

리포지터리별 형태로, 모든 객체는 자체 객체 스토리지 연결 및 구성을 정의합니다. 지원되는 통합 형태가 아닌 리포지터리 형식을 사용하는 것이 좋습니다.

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

통합 형태에서 지원되지 않는 리포지터리 유형의 경우 다음 가이드를 참조하십시오.

연결 설정 구성

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

Amazon S3

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

Amazon 인스턴스 프로필 사용

오브젝트 스토리지 구성에 AWS 액세스 및 비밀 키를 제공하는 대신, GitLab을 구성하여 Amazon Identity Access 및 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 버킷에 기본 암호화를 설정하는 것이 암호화를 활성화하는 가장 쉬운 방법이지만, 암호화된 개체만 업로드되도록 S3 버킷 정책을 설정하려면 storage_options 구성 섹션에서 적절한 암호화 헤더를 보내도록 GitLab을 구성해야 합니다:

기본 암호화와 마찬가지로 Workhorse S3 클라이언트가 활성화되어 있어야 합니다. 다음 중 하나의 조건이 성립되어야 합니다:

• connection 설정에서 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 권한을 갖고 있는지 확인하세요. 일반적으로 이는 서비스 계정에 서비스 계정 토큰 생성자 역할을 부여함으로써 수행됩니다.

• 가상 머신이 Google Cloud API에 액세스하기 위한 올바른 액세스 범위를 갖도록 합니다. 머신에 올바른 범위가 없는 경우, 오류 로그에 다음과 같이 표시될 수 있습니다:

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

Azure Blob 리포지터리

Azure는 BLOB의 모음을 나타내기 위해 container라는 용어를 사용하지만, GitLab은 용어 bucket을 표준화합니다. Azure 컨테이너 이름을 bucket 설정에 구성하는 것을 잊지 마세요.

Azure Blob 리포지터리는 여러 컨테이너에 액세스하는 데 사용되는 단일 세트의 자격 증명을 사용하기 때문에 통합된 형식으로만 사용할 수 있습니다. 각 객체 유형마다 고유한 리포지터리 연결을 정의하려면 (특정 형식 설정) 지원되지 않습니다. 자세한 내용은 통합된 형식으로 전환하는 방법을 참조하십시오.

다음은 Azure에 대한 유효한 연결 매개변수입니다. 자세한 내용은 Azure Blob 리포지터리 문서를 참조하십시오.

• 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 패키지 설치에서는 이를 설정을 기존 설정에서 팝럽레이트되므로 필요하지 않습니다.

  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 오류가 발생합니다. 자세한 내용은 issue #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>'

Amazon S3를 사용한 통합된 형식 및 전체 예시

다음 예시는 모든 지원되는 서비스에 대한 오브젝트 스토리지을 가능하게 하는 AWS S3를 사용하는 것입니다:

::Tabs

1. /etc/gitlab/gitlab.rb를 편집하고 원하는 값을 대체하여 다음 라인을 추가하세요:

   # 통합된 오브젝트 스토리지 구성
   gitlab_rails['object_store']['enabled'] = true
   gitlab_rails['object_store']['proxy_download'] = true
   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>'
   }
   # 선택 사항: 서버 측 암호화가 필요한 경우 아래 라인만 필요합니다
   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']['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 Secret로 사용하세요:

   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 Secret를 생성하세요:

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

5. 파일을 저장하고 새 값을 적용하세요:

   helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
   

1. docker-compose.yml을 편집하세요:

   version: "3.6"
   services:
     gitlab:
       environment:
         GITLAB_OMNIBUS_CONFIG: |
           # 통합된 오브젝트 스토리지 구성
           gitlab_rails['object_store']['enabled'] = true
           gitlab_rails['object_store']['proxy_download'] = true
           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>'
           }
           # 선택 사항: 서버 측 암호화가 필요한 경우 아래 라인만 필요합니다
           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을 편집하고 다음 라인을 추가하거나 수정하세요:

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

객체 리포지터리로 이관

기존 로컬 데이터를 객체 리포지터리로 이관하려면 다음 가이드를 참조하세요:

• 작업 아티팩트 및 아카이브된 작업 로그
• LFS 객체
• 업로드
• Merge Request 차이
• 패키지 (선택적 기능)
• 의존성 프록시
• 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이 오랫동안 실행될 수 있으므로 랩톱이나 데스크톱 컴퓨터를 사용하지 않는 것이 좋습니다. GitLab 서버를 사용하여 Rclone을 실행할 수 있습니다.

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. GitLab 서버의 객체 리포지터리 구성을 업데이트하여 uploads에 새 제공업체를 사용하도록 업데이트합니다.

파일 시스템 리포지터리 대체 옵션

GitLab 구현을 확장하거나 장애 허용성 및 중복성을 추가하려면 블록이나 네트워크 파일 시스템에 대한 의존성을 제거할 수 있는 대안들을 고려할 수 있습니다. 다음 추가 가이드를 참조하세요.

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

문제 해결

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

백업 문서에 설명된대로 객체는 GitLab 백업에 포함되지 않습니다. 대신에 객체 리포지터리 제공업체에서 백업을 활성화할 수 있습니다.

별도의 버킷 사용

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

Linux 패키지 및 자체 컴파일 설치에서는 단일 실제 버킷을 여러 가상 버킷으로 분할할 수 있습니다. 객체 리포지터리 버킷 이름이 my-gitlab-objects인 경우 업로드를 my-gitlab-objects/uploads, 아티팩트를 my-gitlab-objects/artifacts 등으로 구성할 수 있습니다. 응용 프로그램은 이들이 별개의 버킷인 것처럼 작동합니다. 버킷 접두사 사용은 Helm 백업과 잘 작동하지 않을 수 있습니다.

Helm 기반 설치는 백업 복원을 위해 별도의 버킷을 핸들링해야 합니다.

S3 API 호환성 문제

모든 S3 제공업체가 GitLab이 사용하는 Fog 라이브러리와 완전히 호환되지 않을 수 있습니다. production.log에서 다음과 같은 오류가 발생할 수 있습니다:

411 Length Required

프록시 다운로드

클라이언트는 사전 서명된 시간 제한 URL을 받거나 GitLab이 객체 리포지터리에서 클라이언트로 데이터를 프록시하는 방식으로 객체 리포지터리에서 파일을 다운로드할 수 있습니다. 객체 리포지터리에서 파일을 직접 다운로드하는 것은 GitLab이 처리해야 하는 탈출 트래픽 양을 줄이는 데 도움이 됩니다.

파일이 로컬 블록 리포지터리나 NFS에 저장되어 있는 경우 GitLab은 프록시 역할을 하게 됩니다. 이것이 객체 리포지터리의 기본 동작이 아닙니다.

proxy_download 설정은 이 동작을 제어합니다. 기본값은 일반적으로 false입니다. 각 사용 사례의 설명서에서 이를 확인하세요. 파일을 프록시로 사용하려면 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를 로드하려고 하면 다음과 같은 오류가 표시될 수 있습니다:

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

또한 일시적으로 사용자는 인증 없이 사전 서명된 시간 제한 객체 리포지터리 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 업로드 파트 복사 API를 사용합니다. 그러나 Ceph S3는 Kraken 11.0.2 이전에서 이를 지원하지 않으며 파일을 복사하는 동안 404 오류를 반환합니다.

이 기능은 :s3_multithreaded_uploads 피처 플래그를 사용하여 비활성화할 수 있습니다. 기능을 비활성화하려면 GitLab 관리자에게 Rails 콘솔 액세스 권한이 있는지 확인한 후 다음 명령을 실행하도록 요청하세요:

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

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