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

번들 URI를 사용하면 다음과 같은 효과가 있습니다:

• GitLab 서버와의 네트워크 연결 상태가 좋지 않은 사용자의 클론과 페치 속도를 높입니다. 번들을 CDN에 저장하면 전 세계에서 사용할 수 있습니다.
• CI/CD job을 실행하는 서버의 부하를 줄입니다. CI/CD job이 다른 곳에서 번들을 미리 받아 올 수 있다면, 누락된 객체와 참조를 점진적으로 가져오는 나머지 작업이 서버에 훨씬 적은 부하를 발생시킵니다.

사전 요구 사항#

번들 URI를 사용하기 위한 사전 요구 사항은 CI/CD job에서 클론하는지, 터미널에서 로컬로 클론하는지에 따라 달라집니다.

CI/CD job에서 클론#

CI/CD job에서 번들 URI를 사용할 준비를 하려면:

1. 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 스토리지 구성#

번들 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)는 Application Default Credentials로 인증합니다. 각 Gitaly 서버에서 다음 중 하나로 Application Default Credentials를 설정합니다:

• gcloud auth application-default login 명령.
• GOOGLE_APPLICATION_CREDENTIALS 환경 변수. 자체 컴파일 설치에서는 GitLab 외부에서 이 환경 변수를 설정합니다.

자세한 내용은 Application Default Credentials를 참고합니다.

대상 버킷은 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로 전환될 때 도입되었습니다. 다만 gocloud.dev 유지 관리자가 하위 호환성 지원을 추가한 뒤 GitLab 17.4.4에서 s3ForcePathStyle 파라미터가 복원되었습니다. 자세한 내용은 이슈 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는 해당 리포지터리의 번들이 마지막으로 생성된 시점을 확인합니다. 기존 번들이 maxBundleAge 구성보다 오래된 경우에만 새 번들을 생성하며, 이때 기존 번들을 덮어씁니다. 클라우드 스토리지에는 리포지터리당 번들을 하나만 둘 수 있습니다.

Bundle URI 예시#

다음 예시는 번들 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.

앞의 예시에서:

• 번들 URI를 사용하지 않았을 때는 GitLab 서버에서 객체 5,271,177개를 받았습니다.
• 번들 URI를 사용했을 때는 GitLab 서버에서 객체 1,322,255개를 받았습니다.

이 감소는 클라이언트가 먼저 스토리지 서버에서 번들을 내려받았기 때문에 GitLab이 함께 묶어야 할 객체가 더 적어졌다는 뜻입니다(앞의 예시에서는 객체 수가 약 4분의 1입니다).

번들 보안#

번들은 서명된 URL로 클라이언트에게 제공됩니다. 서명된 URL은 요청을 보낼 수 있는 권한과 시간이 제한된 URL입니다. 사용 중인 스토리지 서비스가 서명된 URL을 지원하는지는 해당 스토리지 서비스의 문서를 참고합니다.