Gitaly는 Git 번들 URI를 지원합니다. 번들 URI는 Git이 원격에서 나머지 객체를 가져오기 전에 객체 데이터베이스를 부트스트랩하기 위해 하나 이상의 번들을 다운로드할 수 있는 위치입니다. 번들 URI는 Git 프로토콜에 내장되어 있습니다.

번들 URI를 사용하면 다음이 가능합니다:

• GitLab 서버와의 네트워크 연결이 좋지 않은 사용자의 클론 및 가져오기 속도를 높입니다. 번들을 CDN에 저장할 수 있어 전 세계에서 사용할 수 있습니다.
• CI/CD 작업을 실행하는 서버의 부하를 줄입니다. CI/CD 작업이 다른 곳에서 번들을 미리 로드할 수 있으면 누락된 객체와 참조를 증분적으로 가져오는 나머지 작업이 서버에 훨씬 적은 부하를 줍니다.

사전 요구사항#

번들 URI 사용을 위한 사전 요구사항은 CI/CD 작업에서 클론하는지 또는 터미널에서 로컬로 클론하는지에 따라 다릅니다.

CI/CD 작업에서 클론#

CI/CD 작업에서 번들 URI를 사용하도록 준비하려면:

1. CI/CD 작업에서 GitLab Runner가 사용하는 GitLab Runner 헬퍼 이미지를 다음을 실행하는 버전으로 선택합니다:

   • Git 버전 2.49.0 이상.
   • GitLab Runner 헬퍼 버전 18.0 이상.

   번들 URI는 git clone 중 Git 서버의 부하를 줄이는 것을 목표로 하는 메커니즘이기 때문에 이 단계가 필요합니다. CI/CD 파이프라인이 실행될 때 git clone 명령을 시작하는 git 클라이언트는 GitLab Runner입니다. git 프로세스는 헬퍼 이미지 내부에서 실행됩니다.

   GitLab 러너에 사용하는 운영 체제 배포판과 아키텍처에 해당하는 이미지를 선택해야 합니다.

   이미지가 요구사항을 충족하는지 다음 명령을 실행하여 확인할 수 있습니다:

   docker run -it <image:tag>
   $ git version
   $ gitlab-runner-helper -v
   

   gitlab-runner-helper 이미지의 Git 버전을 관리하기 위해 운영 체제 배포판의 패키지 관리자를 사용합니다. 따라서 일부 최신 이미지도 여전히 Git 2.49를 실행하지 않을 수 있습니다.

   요구사항을 충족하는 이미지를 찾지 못하면 gitlab-runner-helper를 사용자 지정 이미지의 기본 이미지로 사용합니다. GitLab 컨테이너 레지스트리를 사용하여 사용자 지정 빌드 이미지를 호스팅할 수 있습니다.

2. config.toml 파일을 업데이트하여 선택한 이미지를 사용하도록 GitLab Runner 인스턴스를 구성합니다:

   [[runners]]
     (...)
     executor = "docker"
     [runners.docker]
       (...)
       helper_image = "image:tag" ## <-- put the image name and tag here
   

   자세한 내용은 헬퍼 이미지에 대한 정보를 참조하세요.

3. 새 구성이 적용되도록 러너를 재시작합니다.

4. .gitlab-ci.yml 파일에서 FF_USE_GIT_NATIVE_CLONE GitLab Runner 기능 플래그를 true로 설정하여 활성화합니다:

   variables:
     FF_USE_GIT_NATIVE_CLONE: "true"
   

터미널에서 로컬 클론#

터미널에서 로컬로 클론할 번들 URI를 사용하도록 준비하려면 로컬 Git 구성에서 bundle-uri를 활성화합니다:

git config --global transfer.bundleuri true

서버 구성#

번들이 저장되는 위치를 구성해야 합니다. Gitaly는 다음 스토리지 서비스를 지원합니다:

• Google Cloud Storage
• AWS S3 (또는 호환 가능)
• Azure Blob Storage
• 로컬 파일 스토리지 (권장하지 않음)

Azure Blob 스토리지 구성#

Bundle URI용 Azure Blob 스토리지 구성 방법은 설치 유형에 따라 다릅니다. 소스에서 컴파일한 설치의 경우 GitLab 외부에서 AZURE_STORAGE_ACCOUNT 및 AZURE_STORAGE_KEY 환경 변수를 설정해야 합니다.

gitaly['env'] = {
    'AZURE_STORAGE_ACCOUNT' => 'azure_storage_account',
    'AZURE_STORAGE_KEY' => 'azure_storage_key' # or 'AZURE_STORAGE_SAS_TOKEN'
}
gitaly['configuration'] = {
    bundle_uri: {
        go_cloud_url: 'azblob://<bucket>'
    }
}

[bundle_uri]
go_cloud_url = "azblob://<bucket>"

Google Cloud 스토리지 구성#

Google Cloud 스토리지(GCP)는 애플리케이션 기본 자격 증명을 사용하여 인증합니다. 다음 중 하나를 사용하여 각 Gitaly 서버에서 애플리케이션 기본 자격 증명을 설정합니다:

• gcloud auth application-default login 명령.
• GOOGLE_APPLICATION_CREDENTIALS 환경 변수. 소스에서 컴파일한 설치의 경우 GitLab 외부에서 환경 변수를 설정합니다.

자세한 내용은 애플리케이션 기본 자격 증명을 참조하세요.

대상 버킷은 go_cloud_url 옵션을 사용하여 구성됩니다.

gitaly['env'] = {
    'GOOGLE_APPLICATION_CREDENTIALS' => '/path/to/service.json'
}
gitaly['configuration'] = {
    bundle_uri: {
        go_cloud_url: 'gs://<bucket>'
    }
}

[bundle_uri]
go_cloud_url = "gs://<bucket>"

S3 스토리지 구성#

S3 스토리지 인증을 구성하려면:

• AWS CLI로 인증하는 경우 기본 AWS 세션을 사용할 수 있습니다.
• 그렇지 않으면 AWS_ACCESS_KEY_ID 및 AWS_SECRET_ACCESS_KEY 환경 변수를 사용할 수 있습니다. 소스에서 컴파일한 설치의 경우 GitLab 외부에서 환경 변수를 설정합니다.

자세한 내용은 AWS 세션 문서를 참조하세요.

대상 버킷과 리전은 go_cloud_url 옵션을 사용하여 구성됩니다.

gitaly['env'] = {
    'AWS_ACCESS_KEY_ID' => 'aws_access_key_id',
    'AWS_SECRET_ACCESS_KEY' => 'aws_secret_access_key'
}
gitaly['configuration'] = {
    bundle_uri: {
        go_cloud_url: 's3://<bucket>?region=us-west-1'
    }
}

[bundle_uri]
go_cloud_url = "s3://<bucket>?region=us-west-1"

S3 호환 서버 구성#

S3 호환 서버는 endpoint 파라미터를 추가하여 S3와 유사하게 구성됩니다.

다음 파라미터가 지원됩니다:

• region: AWS 리전.
• endpoint: 엔드포인트 URL.
• disableSSL: SSL을 비활성화하려면 true로 설정합니다. GitLab 17.4.0 이하에서 사용 가능합니다. 17.4.0 이후 GitLab 버전의 경우 disable_https를 사용합니다.
• disable_https: 엔드포인트 옵션에서 HTTPS를 비활성화하려면 true로 설정합니다.
• s3ForcePathStyle: S3 객체에 경로 스타일 URL을 강제 사용하려면 true로 설정합니다. GitLab 버전 17.4.0~17.4.3에서는 사용할 수 없습니다. 해당 버전에서는 use_path_style을 사용합니다.
• use_path_style: 경로 스타일 S3 URL(https://<bucket>.<host> 대신 https://<host>/<bucket>)을 활성화하려면 true로 설정합니다.
• awssdk: 특정 버전의 AWS SDK를 강제합니다. AWS SDK v1을 강제하려면 v1로, AWS SDK v2를 강제하려면 v2로 설정합니다. v1로 설정하면 disable_https 대신 disableSSL을 사용해야 합니다. 설정하지 않으면 기본값은 v2입니다.

use_path_style은 Go Cloud Development Kit 종속성이 v0.38.0에서 v0.39.0으로 업데이트되어 AWS SDK v1에서 v2로 전환될 때 도입되었습니다. 그러나 s3ForcePathStyle 파라미터는 gocloud.dev 유지 관리자가 하위 호환성 지원을 추가한 후 GitLab 17.4.4에서 복원되었습니다. 자세한 내용은 이슈 6489를 참조하세요.

disable_https는 Go Cloud Development Kit v0.40.0(AWS SDK v2)에서 도입되었습니다.

awssdk는 Go Cloud Development Kit v0.24.0에서 도입되었습니다.

gitaly['env'] = {
    'AWS_ACCESS_KEY_ID' => '<your_access_key_id>',
    'AWS_SECRET_ACCESS_KEY' => '<your_secret_access_key>'
}
gitaly['configuration'] = {
    bundle_uri: {
        go_cloud_url: 's3://<bucket>?region=us-east-1&endpoint=s3.example.com:9000&disable_https=true&use_path_style=true'
    }
}

[bundle_uri]
go_cloud_url = "s3://<bucket>?region=us-east-1&endpoint=s3.example.com:9000&disable_https=true&use_path_style=true"

번들 생성#

Gitaly가 구성된 후 Gitaly는 수동 또는 자동으로 번들을 생성할 수 있습니다.

수동 생성#

이 명령은 번들을 생성하고 구성된 스토리지 서비스에 저장합니다.

sudo -u git -- /opt/gitlab/embedded/bin/gitaly bundle-uri \
                                               --config=<config-file> \
                                               --storage=<storage-name> \
                                               --repository=<relative-path>

Gitaly는 생성된 번들을 자동으로 새로 고치지 않습니다. 더 최신 버전의 번들을 생성하려면 명령을 다시 실행해야 합니다.

이 명령을 cron(8)과 같은 도구로 예약할 수 있습니다.

자동 생성#

Gitaly는 동일한 리포지토리에 대해 빈번한 클론을 처리하고 있는지 확인하여 자동으로 번들을 생성할 수 있습니다. 현재 휴리스틱은 각 리포지토리에 대해 git fetch 요청이 발행된 횟수를 추적합니다. 요청 수가 주어진 간격 내에 특정 임계값에 도달하면 Gitaly가 자동으로 번들을 생성합니다.

Gitaly는 또한 리포지토리에 대해 마지막으로 번들을 생성한 시간을 추적합니다. threshold 및 interval을 기반으로 새 번들을 재생성해야 할 때 Gitaly는 주어진 리포지토리에 대해 번들이 마지막으로 생성된 시간을 확인합니다. Gitaly는 기존 번들이 maxBundleAge 구성보다 오래된 경우에만 새 번들을 생성하며, 이 경우 이전 번들을 덮어씁니다. 클라우드 스토리지에는 리포지토리당 하나의 번들만 있을 수 있습니다.

Bundle URI 예시#

다음 예시에서는 Bundle URI 사용 여부에 따라 gitlab.com/gitlab-org/gitlab.git을 클론하는 차이를 보여줍니다.

$ git -c transfer.bundleURI=false clone https://gitlab.com/gitlab-org/gitlab.git
Cloning into 'gitlab'...
remote: Enumerating objects: 5271177, done.
remote: Total 5271177 (delta 0), reused 0 (delta 0), pack-reused 5271177
Receiving objects: 100% (5271177/5271177), 1.93 GiB | 32.93 MiB/s, done.
Resolving deltas: 100% (4140349/4140349), done.
Updating files: 100% (71304/71304), done.

$ git -c transfer.bundleURI=true clone https://gitlab.com/gitlab-org/gitlab.git
Cloning into 'gitlab'...
remote: Enumerating objects: 1322255, done.
remote: Counting objects: 100% (611708/611708), done.
remote: Total 1322255 (delta 611708), reused 611708 (delta 611708), pack-reused 710547
Receiving objects: 100% (1322255/1322255), 539.66 MiB | 22.98 MiB/s, done.
Resolving deltas: 100% (1026890/1026890), completed with 223946 local objects.
Checking objects: 100% (8388608/8388608), done.
Checking connectivity: 1381139, done.
Updating files: 100% (71304/71304), done.

이전 예시에서:

• Bundle URI를 사용하지 않을 경우 GitLab 서버에서 5,271,177개의 객체가 수신되었습니다.
• Bundle URI를 사용할 경우 GitLab 서버에서 1,322,255개의 객체가 수신되었습니다.

이 감소는 클라이언트가 먼저 스토리지 서버에서 번들을 다운로드하기 때문에 GitLab이 더 적은 수의 객체(이전 예시에서는 객체 수의 약 1/4)를 함께 패킹해야 한다는 것을 의미합니다.

번들 보안#

번들은 서명된 URL을 사용하여 클라이언트에 액세스할 수 있도록 만들어집니다. 서명된 URL은 요청을 할 수 있는 제한된 권한과 시간을 제공하는 URL입니다. 스토리지 서비스가 서명된 URL을 지원하는지 확인하려면 스토리지 서비스의 문서를 참조하세요.