번들 URI

Status: Experiment

History

Introduced in GitLab 17.0 with a flag named gitaly_bundle_uri. Disabled by default.

자체 관리되는 GitLab에서는 기본적으로 이 기능이 활성화되어 있지 않습니다.

관리자는 gitaly_bundle_uri라는 기능 플래그를 활성화하여 이 기능을 사용할 수 있습니다.

GitLab.com 및 GitLab Dedicated에서는 이 기능을 사용할 수 없습니다. 이 기능은 프로덕션 사용을 위한 것이 아닙니다.

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

번들 URI를 사용하면:

GitLab 서버에 대한 네트워크 연결이 좋지 않은 사용자에게 복제 및 가져오기 속도를 높일 수 있습니다. 번들은 CDN에 저장되어 전 세계에서 사용할 수 있게 됩니다.
CI/CD 작업을 실행하는 서버의 부하를 줄일 수 있습니다. CI/CD 작업이 다른 곳에서 번들을 미리 로드할 수 있다면, 누락된 객체와 참조를 점진적으로 가져오기 위해 남은 작업은 서버에 훨씬 적은 부하를 생성합니다.

전제 조건

Git 클라이언트에서 transfer.bundleURI 설정이 활성화되어 있어야 합니다.
GitLab Runner 16.6 이상이 필요합니다.
CI/CD 파이프라인 설정에서 기본 Git 전략이 git clone으로 설정되어 있어야 합니다.

서버 구성

번들이 저장되는 위치를 구성해야 합니다. Gitaly에서 지원하는 저장 서비스는 다음과 같습니다:

Google Cloud Storage
AWS S3 (또는 호환)
Azure Blob Storage
로컬 파일 저장소 (권장하지 않음)

Azure Blob 저장소 구성

Bundle URI에 대한 Azure Blob 저장소 구성 방법은 설치 유형에 따라 다릅니다. 자가 컴파일 설치의 경우, GitLab 외부에서 AZURE_STORAGE_ACCOUNT 및 AZURE_STORAGE_KEY 환경 변수를 설정해야 합니다.

Linux 패키지 (Omnibus)

/etc/gitlab/gitlab.rb를 편집하고 bundle_uri.go_cloud_url을 구성하십시오:

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

소스에서 자가 컴파일

/home/git/gitaly/config.toml을 편집하고 go_cloud_url을 구성하십시오:

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

Google Cloud 저장소 구성

Google Cloud 저장소(GCP)는 애플리케이션 기본 자격 증명을 사용하여 인증합니다. 각 Gitaly 서버에서 다음 방법 중 하나를 사용하여 애플리케이션 기본 자격 증명을 설정하십시오:

gcloud auth application-default login 명령.
GOOGLE_APPLICATION_CREDENTIALS 환경 변수. 자가 컴파일 설치의 경우, GitLab 외부에서 환경 변수를 설정하십시오.

자세한 내용은 Application Default Credentials를 참조하십시오.

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

Linux 패키지 (Omnibus)

/etc/gitlab/gitlab.rb를 편집하고 go_cloud_url을 구성하십시오:

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

소스에서 자가 컴파일

/home/git/gitaly/config.toml을 편집하고 go_cloud_url을 구성하십시오:

[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 옵션을 사용하여 구성됩니다.

리눅스 패키지 (Omnibus)

/etc/gitlab/gitlab.rb를 수정하고 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'
    }
}

직접 컴파일 (소스)

/home/git/gitaly/config.toml을 수정하고 go_cloud_url을 구성하세요:

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

S3 호환 서버 구성하기

MinIO와 같은 S3 호환 서버는 endpoint 매개변수를 추가하여 S3와 유사하게 구성됩니다.

다음 매개변수가 지원됩니다:

region: AWS 리전.
endpoint: 엔드포인트 URL.
disabledSSL: true 값이 SSL을 비활성화합니다.
s3ForcePathStyle: true 값이 경로 스타일 주소 지정을 강제합니다.

리눅스 패키지 (Omnibus)

/etc/gitlab/gitlab.rb을 수정하고 go_cloud_url을 구성하세요:

gitaly['env'] = {
    'AWS_ACCESS_KEY_ID' => 'minio_access_key_id',
    'AWS_SECRET_ACCESS_KEY' => 'minio_secret_access_key'
}
gitaly['configuration'] = {
    bundle_uri: {
        go_cloud_url: 's3://<bucket>?region=minio&endpoint=my.minio.local:8080&disableSSL=true&s3ForcePathStyle=true'
    }
}

직접 컴파일 (소스)

/home/git/gitaly/config.toml을 수정하고 go_cloud_url을 구성하세요:

[bundle_uri]
go_cloud_url = "s3://<bucket>?region=minio&endpoint=my.minio.local:8080&disableSSL=true&s3ForcePathStyle=true"

번들 생성하기

Gitaly가 제대로 구성되면, Gitaly는 번들을 생성할 수 있으며 이는 수동 프로세스입니다. 번들 URI에 대한 번들을 생성하려면, 다음을 실행하세요:

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

이 명령은 번들을 생성하고 구성된 스토리지 서비스에 저장합니다. Gitaly는 생성된 번들을 자동으로 새로 고치지 않습니다. 더 최근 버전의 번들을 생성하려면, 명령을 다시 실행해야 합니다.

이 명령은 cron(8)과 같은 도구를 사용하여 예약할 수 있습니다.

번들 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을 지원하는지 확인하려면 저장소 서비스의 문서를 참조하세요.