• Gitaly 토큰에 대해
• 별도의 서버에서 Gitaly 실행
  • 네트워크 아키텍처
  • Gitaly 설치
  • Gitaly 서버 구성
    • 인증 구성
    • Gitaly 서버 구성
  • Gitaly 클라이언트 구성
    • 혼합 구성
  • GitLab에는 기본 리포지터리 스토리지가 필요합니다
  • 필요하지 않은 경우 Gitaly 비활성화(옵션)
• 제어 그룹
  • 리포지터리 cgroups 구성(새 방법)
  • 리포지터리 cgroups 구성 (레거시 방법)
  • 오버 서브스크립션 구성
• 배경 리포지터리 최적화
• Gitaly 인증 토큰 회전
  • 인증 모니터링 확인
  • “인증 전환” 모드 활성화
  • Gitaly 인증 토큰 업데이트
  • 인증 실패가 없는지 확인
  • “인증 전환” 모드 비활성화
  • 인증이 강제로 적용되는지 확인
• Pack-objects 캐시
  • 캐시 구성
    • enabled 기본값은 false입니다
    • 캐시 저장 디렉터리 dir
    • 캐시 획득 창 max_age
    • 최소 키 발생 min_occurrences
  • 캐시 관찰
• cat-file 캐시
• GitLab UI 커밋에 대한 커밋 서명 구성
• 외부 명령을 사용하여 구성 생성
• 서버 측 백업 구성
  • Azure Blob 리포지터리 구성
  • Google Cloud 리포지터리 구성
  • S3 리포지터리 구성
    • S3 호환 서버 구성

Gitaly 구성

다음 중 하나의 방법으로 Gitaly를 구성합니다:

다음 구성 옵션도 제공됩니다:

• TLS 지원 활성화.
• RPC 동시성 제한.
• pack-objects 동시성 제한.

Gitaly 토큰에 대해

Gitaly 설명서에서 언급된 토큰은 단순히 관리자가 선택한 임의의 암호일 뿐입니다. 이는 GitLab API나 유사한 다른 웹 API 토큰과는 관련이 없습니다.

별도의 서버에서 Gitaly 실행

기본적으로 Gitaly는 Gitaly 클라이언트와 동일한 서버에서 실행되며 위와 같이 구성됩니다. 단일 서버 설치는 다음에서 사용되는 경우에 가장 효과적입니다:

• Linux 패키지 설치.
• 소스 컴파일 설치.

그러나 Gitaly는 여러 대의 기계에 걸쳐있는 GitLab 설치에 유용한 별도의 서버로 배포될 수 있습니다.

별도의 서버에 Gitaly를 설정하는 절차는 다음과 같습니다:

1. Gitaly 설치.
2. 인증 구성.
3. Gitaly 서버 구성.
4. Gitaly 클라이언트 구성.
5. 필요하지 않은 곳에서 Gitaly 비활성화 (선택 사항).

네트워크 아키텍처

다음 디렉터리은 Gitaly의 네트워크 아키텍처를 설명합니다:

• GitLab Rails는 리포지터리를 리포지터리로 분할합니다.
• /config/gitlab.yml에는 리포지터리 이름에서 (Gitaly 주소, Gitaly 토큰) 쌍으로의 맵이 포함되어 있습니다.
• /config/gitlab.yml에 있는 리포지터리 이름 -> (Gitaly 주소, Gitaly 토큰) 맵은 Gitaly 네트워크 토폴로지의 단일한 진리입니다.
• (Gitaly 주소, Gitaly 토큰)은 Gitaly 서버에 해당합니다.
• Gitaly 서버는 하나 이상의 리포지터리를 호스팅합니다.
• Gitaly 클라이언트는 하나 이상의 Gitaly 서버를 사용할 수 있습니다.
• Gitaly 주소는 모든 Gitaly 클라이언트에서 올바르게 해석되도록 지정되어야 합니다.
• Gitaly 클라이언트는 다음과 같습니다:
  • Puma.
  • Sidekiq.
  • GitLab Workhorse.
  • GitLab Shell.
  • Elasticsearch 색인기.
  • Gitaly 자체.
• Gitaly 서버는 자체 (Gitaly 주소, Gitaly 토큰) 쌍을 사용하여 자체에 대한 RPC 호출을 무조건 수행해야 합니다.
• 인증은 Gitaly 및 GitLab Rails 노드 간에 공유되는 정적 토큰을 통해 수행됩니다.

다음 다이어그램은 Gitaly 서버와 GitLab Rails 간의 통신을 보여주며 HTTP 및 HTTPS 통신의 기본 포트를 보여줍니다.

다음 섹션에서는 비밀 토큰 abc123secret을 사용하여 두 개의 Gitaly 서버를 구성하는 방법에 대해 설명합니다:

• gitaly1.internal.
• gitaly2.internal.

GitLab 설치에 세 개의 리포지터리 스토리지가 있는 것으로 가정합니다:

• default.
• storage1.
• storage2.

원하는 경우 하나의 서버에서 하나의 리포지터리 스토리지를 사용할 수도 있습니다.

Gitaly 설치

다음 중 하나를 사용하여 각 Gitaly 서버에 Gitaly를 설치합니다:

• Linux 패키지 설치. 원하는 Linux 패키지를 다운로드 및 설치하되 EXTERNAL_URL= 값을 제공하지 마십시오.
• 소스 컴파일 설치. Gitaly 설치 단계를 따릅니다.

Gitaly 서버 구성

Gitaly 서버를 구성하려면 다음을 수행해야 합니다:

• 인증 구성.
• 리포지터리 경로 구성.
• 네트워크 수신기 활성화.

git 사용자는 구성된 리포지터리 경로에서 읽기, 쓰기 및 권한 설정을 수행할 수 있어야 합니다.

Gitaly 토큰을 회전시키는 동안 다운타임을 방지하기 위해 gitaly['auth_transitioning'] 설정을 사용하여 일시적으로 인증을 비활성화할 수 있습니다. 자세한 내용은 인증 전환 모드 활성화 문서를 참조하십시오.

인증 구성

Gitaly와 GitLab은 인증을 위해 두 개의 공유 비밀을 사용합니다:

• Gitaly 토큰: Gitaly로의 gRPC 요청을 인증하는 데 사용됩니다.
• GitLab Shell 토큰: GitLab Shell에서 GitLab 내부 API로의 인증 콜백에 사용됩니다.

Gitaly 서버 구성

Gitaly 클라이언트 구성

마지막 단계로, Gitaly 클라이언트를 업데이트하여 로컬 Gitaly 서비스 대신 방금 구성한 Gitaly 서버를 사용하도록 전환해야 합니다.

이것은 모든 Gitaly 클라이언트가 Gitaly 서버에 연결하는 것에 장애가 발생하면 모든 Gitaly 요청이 실패하게 될 수 있는 위험한 작업입니다. 예를 들어, 네트워크, 방화벽 또는 이름 해결 문제 등이 발생할 수 있습니다.

Gitaly에서는 다음과 같은 가정을 합니다:

• gitaly1.internal Gitaly 서버가 Gitaly 클라이언트에서 gitaly1.internal:8075에 접근하고, 해당 Gitaly 서버가 /var/opt/gitlab/git-data 및 /mnt/gitlab/git-data에서 읽고 쓰고 권한을 설정할 수 있다.
• gitaly2.internal Gitaly 서버가 Gitaly 클라이언트에서 gitaly2.internal:8075에 접근하고, 해당 Gitaly 서버가 /srv/gitlab/git-data에서 읽고 쓰고 권한을 설정할 수 있다.
• gitaly1.internal 및 gitaly2.internal Gitaly 서버가 서로 통신할 수 있다.

로컬 Gitaly 서버 및 gitaly_address가 없는 원격 서버가 혼합된 구성을 사용하지 않는 한(gitaly_address가 있는 원격 서버와 함께), Gitaly 서버를 정의할 수 없습니다. 혼합 구성을 사용하는 경우에만 가능합니다.

Gitaly 클라이언트를 다음 두 가지 방법 중 하나로 구성할 수 있습니다:

Gitaly 서버에서 Gitaly 로그를 추적하면 요청이 들어오는 것을 확인할 수 있습니다. Gitaly 요청을 확실하게 트리거하는 한 가지 방법은 GitLab에서 HTTP 또는 HTTPS를 통해 리포지터리를 복제하는 것입니다.

혼합 구성

GitLab은 여러 Gitaly 서버 중 하나의 서버에 머물 수 있지만 로컬 및 원격 구성을 혼합하는 설정을 지원하지 않습니다. 다음 설정이 잘못되었습니다.

• 모든 주소는 다른 Gitaly 서버에서 접근 가능해야 합니다.
• storage1은 gitaly_address에 대해 Unix 소켓을 할당받았지만 이는 일부 Gitaly 서버에 대해 유효하지 않습니다.

git_data_dirs({
  'default' => { 'gitaly_address' => 'tcp://gitaly1.internal:8075' },
  'storage1' => { 'path' => '/mnt/gitlab/git-data' },
  'storage2' => { 'gitaly_address' => 'tcp://gitaly2.internal:8075' },
})

로컬 및 원격 Gitaly 서버를 결합하려면 로컬 Gitaly 서버에 대한 외부 주소를 사용하십시오. 예를 들어:

git_data_dirs({
  'default' => { 'gitaly_address' => 'tcp://gitaly1.internal:8075' },
  # Gitaly가 실행 중인 GitLab 서버의 주소
  'storage1' => { 'gitaly_address' => 'tcp://gitlab.internal:8075' },
  'storage2' => { 'gitaly_address' => 'tcp://gitaly2.internal:8075' },
})

gitaly['configuration'] = {
  # ...
  #
  # Gitaly가 모든 네트워크 인터페이스에서 연결을 수락하도록 함
  listen_addr: '0.0.0.0:8075',
  # 또는 TLS의 경우
  tls_listen_addr: '0.0.0.0:9999',
  tls: {
    certificate_path:  '/etc/gitlab/ssl/cert.pem',
    key_path: '/etc/gitlab/ssl/key.pem',
  },
  storage: [
    {
      name: 'storage1',
      path: '/mnt/gitlab/git-data/repositories',
    },
  ],
}

path는 로컬 Gitaly 서버의 리포지터리 샤드에만 포함될 수 있습니다. 제외될 경우, 해당 리포지터리 샤드에는 기본 Git 리포지터리 디렉터리가 사용됩니다.

GitLab에는 기본 리포지터리 스토리지가 필요합니다

환경에 Gitaly 서버를 추가할 때 원래의 default Gitaly 서비스를 대체하고자 할 수 있습니다. 그러나 GitLab은 git_data_dirs에서 default 항목이 필요하기 때문에 GitLab 애플리케이션 서버를 재구성하여 git_data_dirs에서 default 항목을 제거할 수는 없습니다. 더 알아보기

이 제한을 해결하려면:

1. 새로운 Gitaly 서비스에서 추가 저장 위치를 정의하고 추가 저장을 default로 구성합니다.
2. 관리 영역에서 default를 가중치 0으로 설정하여 해당 위치에 리포지터리를 저장하지 못하도록 합니다.

필요하지 않은 경우 Gitaly 비활성화(옵션)

Gitaly를 리모트 서비스로 실행하는 경우 기본적으로 GitLab 서버에서 실행 중인 로컬 Gitaly 서비스를 비활성화하고 필요한 곳에서만 실행하도록 할 수 있습니다.

GitLab 인스턴스에서 Gitaly를 비활성화하는 것은 Gitaly가 GitLab 인스턴스에서 별도의 클러스터 구성에서 실행되는 경우에만 유효합니다. 클러스터의 모든 기계에서 Gitaly를 비활성화하는 것은 유효한 구성이 아닙니다(일부 기계는 Gitaly 서버로 작동해야 합니다).

GitLab 서버에서 Gitaly를 비활성화하는 방법은 다음 중 하나입니다:

제어 그룹

메모리에 대한 cgroups를 활성화할 때 Gitaly 노드에 스왑이 구성되지 않도록해야 합니다. 프로세스가 종료되는 대신 스왑을 사용하게 될 수 있으며 이는 유의미하게 성능이 저하될 수 있습니다.

Linux에서 제어 그룹(cgroups)을 사용하여 Gitaly 프로세스가 사용할 수 있는 메모리와 CPU 양에 제한을 설정할 수 있습니다. 더 많은 정보는 cgroups Linux 매뉴얼 페이지를 참조하십시오. cgroups는 예기치 않은 자원 고갈로부터 시스템을 보호하는 데 도움이 될 수 있으며 메모리 및 CPU의 과도한 소비로 인한 안정성이 떨어질 수 있습니다.

일부 Git 작업은 다음과 같은 상황에서 기억할 만한 리소스를 소비할 수 있습니다:

• 예기치 않게 높은 트래픽.
• Best Practices를 따르지 않는 대규모 리포지터리에 대해 실행되는 작업.

경계를 설정할 경우 이러한 작업이 시스템 자원을 모두 소비해 안정성을 떨어뜨리기 전에 커널이 이러한 작업을 종료할 수 있습니다.

Gitaly에는 내장된 cgroups 제어가 있습니다. 구성된 경우 Gitaly는 Git 명령이 작동하는 리포지터리에 따라 Git 프로세스를 cgroup에 할당합니다. 이러한 cgroups는 리포지터리 cgroups라고하며 각 리포지터리 cgroup은 다음과 같습니다:

• 메모리 및 CPU 제한이 있습니다.
• 단일 리포지터리의 Git 프로세스가 포함됩니다.
• 일관된 해시를 사용하여 주어진 리포지터리의 Git 프로세스가 항상 동일한 cgroup에 종료될 수 있습니다.

리포지터리 cgroup이 다음에서 도달하면:

• 메모리 제한 시 커널은 제거할 후보 프로세스를 검색합니다.
• CPU 제한 시 프로세스가 종료되지 않지만 프로세스는 허용되는 이상의 CPU를 소비하지 못하도록 합니다.

리포지터리 cgroups 구성(새 방법)

• GitLab 15.1에서 이 리포지터리 cgroups 구성 방법이 소개되었습니다.
• cpu_quota_us는 GitLab 15.10에서 소개되었습니다.

Gitaly에서 새 방법으로 리포지터리 cgroups을 구성하려면 /etc/gitlab/gitlab.rb의 gitaly['configuration'][:cgroups]에 대한 새 구성 방법을 사용합니다:

• mountpoint는 부모 cgroup 디렉터리가 마운트된 위치입니다. 기본값은 /sys/fs/cgroup입니다.
• hierarchy_root는 Gitaly이 그룹을 만드는 부모 cgroup이며 사용자 및 Gitaly가 실행되는 그룹으로 소유되어야 합니다. Linux 패키지 설치시 Gitaly가 시작될 때 Gitaly은 mountpoint/<cpu|memory>/hierarchy_root 세트의 디렉터리를 생성합니다.
• memory_bytes는 Gitaly가 생성하는 모든 Git 프로세스에 대해 집합적으로 부과되는 총 메모리 제한입니다. 0은 제한이 없음을 의미합니다.
• cpu_shares는 Gitaly가 생성하는 모든 Git 프로세스에 대해 집합적으로 부과되는 CPU 제한입니다. 0은 제한이 없음을 의미합니다. 최대값은 CPU 전체의 100%를 나타내는 1024입니다.
• cpu_quota_us는 cfs_quota_us이고 이를 기반으로 cgroups의 프로세스를 조절하는 값입니다. cfs_period_us를 100ms로 설정하여 1코어가 100000이 됩니다. 0은 제한이 없음을 의미합니다.
• repositories.count는 cgroups 풀에 속하는 cgroup의 수입니다. 새로운 Git 명령이 스폰될 때마다 Gitaly은 해당 명령을 repository에 기반하여 이러한 cgroups 중 하나에 할당합니다. 순환 해싱 알고리즘은 Git 명령을 이러한 cgroups 중 하나에 할당합니다. 따라서 리포지터리의 Git 명령은 항상 동일한 cgroup에 할당됩니다.
• repositories.memory_bytes는 리포지터리 cgroup에 포함된 모든 Git 프로세스에 부과되는 총 메모리 제한입니다. 0은 제한이 없음을 의미합니다. 이 값은 최상위 memory_bytes의 값을 초과할 수 없습니다.
• repositories.cpu_shares는 리포지터리 cgroup에 포함된 모든 Git 프로세스에 부과되는 CPU 제한입니다. 0은 제한이 없음을 의미합니다. 최대값은 CPU 전체의 100%를 나타내는 1024입니다. 이 값은 최상위 cpu_shares의 값을 초과할 수 없습니다.
• repositories.cpu_quota_us는 리포지터리 cgroup에 포함된 모든 Git 프로세스에 부과되는 cfs_quota_us입니다. Git 프로세스는 주어진 할당량을 초과하여 사용할 수 없습니다. cfs_period_us를 100ms로 설정하여 1코어가 100000이 됩니다. 0은 제한이 없음을 의미합니다.

예: ruby # /etc/gitlab/gitlab.rb에 추가 gitaly['configuration'] = { # ... cgroups: { mountpoint: '/sys/fs/cgroup', hierarchy_root: 'gitaly', memory_bytes: 64424509440, # 60gb cpu_shares: 1024, cpu_quota_us: 400000 # 4 cores repositories: { count: 1000, memory_bytes: 32212254720, # 20gb cpu_shares: 512, cpu_quota_us: 200000 # 2 cores }, }, }

리포지터리 cgroups 구성 (레거시 방법)

레거시 방법을 사용하여 Gitaly에서 리포지터리 cgroups를 구성하려면 /etc/gitlab/gitlab.rb에서 다음 설정을 사용하십시오:

• cgroups_count는 생성된 cgroups의 수입니다. 새 명령이 실행될 때마다 Gitaly는 해당 명령의 명령 줄 인수에 따라 이러한 cgroups 중 하나에 할당합니다. 원형 해싱 알고리즘이 이러한 cgroups에 명령을 할당합니다.
• cgroups_mountpoint는 부모 cgroup 디렉터리가 마운트된 위치입니다. 기본값은 /sys/fs/cgroup입니다.
• cgroups_hierarchy_root는 Gitaly가 그룹을 생성하는 부모 cgroup이며 사용자 및 Gitaly가 실행되는 그룹에 속해야 합니다. Linux 패키지 설치시 Gitaly가 시작될 때 디렉터리 세트 mountpoint/<cpu|memory>/hierarchy_root가 생성됩니다.
• cgroups_memory_enabled는 cgroups의 메모리 제한을 활성화하거나 비활성화합니다.
• cgroups_memory_bytes는 각 cgroup이 추가된 프로세스에 적용하는 총 메모리 한도입니다.
• cgroups_cpu_enabled는 cgroups의 CPU 제한을 활성화하거나 비활성화합니다.
• cgroups_cpu_shares는 각 cgroup이 추가된 프로세스에 적용하는 CPU 제한입니다. 최대값은 1024 shares로 CPU의 100%를 나타냅니다.

예시:

# in /etc/gitlab/gitlab.rb
gitaly['cgroups_count'] = 1000
gitaly['cgroups_mountpoint'] = "/sys/fs/cgroup"
gitaly['cgroups_hierarchy_root'] = "gitaly"
gitaly['cgroups_memory_limit'] = 32212254720
gitaly['cgroups_memory_enabled'] = true
gitaly['cgroups_cpu_shares'] = 1024
gitaly['cgroups_cpu_enabled'] = true

오버 서브스크립션 구성

이전 예시에서 새 구성 방법을 사용하여:

• 최상위 메모리 제한은 60GB로 제한됩니다.
• 리포지터리 풀의 1000개 cgroup 중 각각은 20GB로 제한됩니다.

이 구성은 “오버 서브스크립션”으로 이어집니다. 풀의 각 cgroup은 최상위 메모리 제한의 1/1000보다 훨씬 큰 용량을 갖습니다.

이 전략에는 두 가지 주요 이점이 있습니다:

• 최상위 cgroup의 메모리 제한을 호스트의 용량보다 작은 임계값으로 설정할 수 있기 때문에 호스트가 전반적인 메모리 기아(OOM)로부터 보호됩니다. 그 cgroup 외부의 프로세스는 OOM의 위험에 노출되지 않습니다.
• 이 예시에서 각 리포지터리 풀의 각 개별 cgroup이 부모 cgroup의 제한보다 작지만 부모의 제한의 1/N보다 상당히 큰 (이 예에서는 20GB) 관대한 상한선까지 버스트할 수 있도록 해줍니다. 일반적으로 모든 1000개 cgroup은 20GB보다 훨씬 적은 용량을 사용할 것입니다.

배경 리포지터리 최적화

리포지터리에서 빈 디렉터리 및 불필요한 구성 설정이 축적되어 Git 작업을 느리게 만들 수 있습니다. Gitaly는 이러한 항목을 정리하고 성능을 향상시키기 위해 매일 백그라운드 작업을 예약할 수 있습니다.

두 가지 방법 중 하나로 백그라운드 리포지터리 최적화를 구성하세요:

gitaly['configuration'] = {
  # ...
  daily_maintenance: {
    # ...
    start_hour: 4,
    start_minute: 30,
    duration: '30m',
    storages: ['default'],
  },
}

[daily_maintenance]
start_hour = 4
start_minute = 30
duration = '30m'
storages = ["default"]

Gitaly 인증 토큰 회전

프로덕션 환경에서 자격 증명을 회전하는 것은 종종 다운타임을 필요로 하거나 중단을 발생시킵니다.

그러나 Gitaly 인증 토큰을 서비스 중단 없이 회전할 수 있습니다. Gitaly 인증 토큰을 회전하는 것에는 다음이 포함됩니다:

• 인증 모니터링 확인
• “인증 전환” 모드 활성화
• Gitaly 인증 토큰 업데이트
• 인증 실패가 없는지 확인
• “인증 전환” 모드 비활성화
• 인증이 강제로 적용되는지 확인

이 절차는 서버에서 GitLab을 실행 중이면 작동합니다. 해당 경우에 “Gitaly 서버” 및 “Gitaly 클라이언트”는 동일한 기계를 참조합니다.

인증 모니터링 확인

Gitaly 인증 토큰을 회전하기 전에 Prometheus를 사용하여 GitLab 설치의 인증 동작을 확인할 수 있는지 확인하세요.

그런 다음 절차의 나머지를 진행하세요.

“인증 전환” 모드 활성화

다음과 같이 Gitaly 서버에서 일시적으로 “인증 전환” 모드를 사용하여 Gitaly 인증을 비활성화하세요:

# in /etc/gitlab/gitlab.rb
gitaly['configuration'] = {
  # ...
  auth: {
    # ...
    transitioning: true,
  },
}

이 변경 후 Prometheus 쿼리에서 다음과 유사한 결과가 나와야 합니다:

{enforced="false",status="would be ok"}  4424.985419441742

enforced="false"이므로 새 토큰을 롤아웃하는 것이 안전합니다.

Gitaly 인증 토큰 업데이트

새 Gitaly 인증 토큰으로 업데이트하려면 각 Gitaly 클라이언트 및 Gitaly 서버에서 다음을 수행하세요:

1. 구성을 업데이트하세요:

   # in /etc/gitlab/gitlab.rb
   gitaly['configuration'] = {
      # ...
      auth: {
         # ...
         token: '<new secret token>',
      },
   }
   

2. Gitaly를 다시 시작하세요:

   gitlab-ctl restart gitaly
   

이 변경이 롤아웃되는 동안 Prometheus 쿼리를 실행하면 enforced="false",status="denied" 카운터에 0이 아닌 값이 표시됩니다.

인증 실패가 없는지 확인

새 토큰이 설정되고 관련된 모든 서비스가 다시 시작된 후 인증 모니터링을 확인하면 다음의 혼합된 결과를 임시로 볼 수 있습니다:

• status="would be ok".
• status="denied".

새 토큰이 모든 Gitaly 클라이언트 및 Gitaly 서버에서 선택되면 enforced="false",status="would be ok"의 카운터만 0이 아닌 값이 됩니다.

“인증 전환” 모드 비활성화

Gitaly 인증을 다시 활성화하려면 Gitaly 서버의 구성을 다음과 같이 업데이트하세요:

# in /etc/gitlab/gitlab.rb
gitaly['configuration'] = {
  # ...
  auth: {
    # ...
    transitioning: false,
  },
}

인증이 강제로 적용되는지 확인

Prometheus 쿼리를 새로고침하세요. 이제 시작할 때와 유사한 결과를 볼 수 있어야 합니다. 예를 들어:

{enforced="true",status="ok"}  4424.985419441742

enforced="true"는 인증이 적용되고 있음을 의미합니다.

Pack-objects 캐시

Gitaly는 Git 리포지터리에 대한 리포지터리를 제공하는 서비스로, Git fetch 응답의 짧은 롤링 윈도우를 캐시로 구성할 수 있습니다. 이를 통해 서버에 대량의 CI fetch 트래픽이 들어왔을 때 서버 부하를 줄일 수 있습니다.

pack-objects 캐시는 git pack-objects를 감싸는데, 이는 Git의 내부 부분으로 PostUploadPack 및 SSHUploadPack Gitaly RPC를 통해 간접적으로 호출됩니다. Gitaly는 사용자가 HTTP를 통해 Git fetch를 수행할 때 PostUploadPack를 실행하거나, 사용자가 SSH를 통해 Git fetch를 할 때 SSHUploadPack를 실행합니다.

캐시가 활성화되면 PostUploadPack 또는 SSHUploadPack을 사용하는 모든 항목에서 혜택을 받을 수 있습니다. 이는 다음과 관계가 없습니다:

• 전송 방식(HTTP 또는 SSH)
• Git 프로토콜 버전(v0 또는 v2)
• 전체 복제, 증분 획득, 얕은 복제, 또는 부분 복제와 같은 획득 유형

이 캐시의 강점은 중복되는 동시 fetch를 중복 처리할 수 있는 능력입니다. 이에 대한 설명은:

• 많은 동시 작업을 수행하는 GitLab 인스턴스에서 혜택을 볼 수 있습니다. 서버 CPU 사용량이 뚜렷하게 감소해야 합니다.
• 전혀 고유한 fetch에서는 혜택을 받지 못합니다. 예를 들어, 로컬 컴퓨터로 리포지터리를 복제하여 약간의 점검을 할 경우 캐시가 혜택을 보일 가능성이 적습니다.

pack-objects 캐시는 로컬 캐시로, 다음과 같은 특징을 가집니다:

• 활성화된 Gitaly 프로세스의 메모리에 메타데이터를 저장합니다.
• 실제 캐시를 사용하여 캐싱하고 있는 Git 데이터를 로컬 리포지터리의 파일에 저장합니다.

로컬 파일을 사용하는 것은 운영 체제가 캐시 파일의 일부를 RAM에 자동으로 유지할 수 있어 더 빠를 수 있습니다.

pack-objects 캐시는 디스크 쓰기 IO의 증가로 이어질 수 있기 때문에 기본적으로 비활성화되어 있습니다. GitLab 15.11 이후의 버전에서는 쓰기 작업 부하가 약 50% 감소하지만, 캐시는 여전히 기본적으로 비활성화된 상태입니다.

캐시 구성

다음은 pack-objects 캐시에 대한 구성 설정입니다. 각 설정은 아래에서 자세히 설명하겠습니다.

/etc/gitlab/gitlab.rb에서 다음을 설정합니다:

gitaly['configuration'] = {
  # ...
  pack_objects_cache: {
    # ...
    enabled: true,
    # dir: '/var/opt/gitlab/git-data/repositories/+gitaly/PackObjectsCache',
    # max_age: '5m',
    # min_occurrences: 1,
  },
}

enabled 기본값은 false입니다

캐시는 기본적으로 비활성화되어 있습니다. 이는 경우에 따라 디스크로의 바이트 쓰기량이 급격히 증가할 수 있기 때문입니다. GitLab.com에서는 추가 작업 부하를 리포지터리 디스크가 처리할 수 있다는 것을 검증했지만, 어디에서나 이것이 사실임을 가정할 수 없다고 판단했습니다.

캐시 저장 디렉터리 dir

캐시에는 파일을 저장할 디렉터리가 필요합니다. 이 디렉터리는 다음과 같아야 합니다:

• 충분한 공간이 있는 파일 시스템에 있어야 합니다. 캐시 파일 시스템에 공간이 부족하면 모든 획득 작업이 실패합니다.
• 충분한 IO 대역폭이 있는 디스크에 있어야 합니다. 캐시 디스크의 IO 대역폭이 부족하면 모든 획득 및 아마도 전체 서버가 느려집니다.

기본적으로 캐시 저장 디렉터리는 구성 파일에서 정의된 첫 번째 Gitaly 리포지터리의 하위 디렉터리로 설정됩니다.

여러 Gitaly 프로세스는 캐시 저장용 동일한 디렉터리를 사용할 수 있습니다. 각 Gitaly 프로세스는 생성하는 캐시 파일의 일부분으로 고유한 무작위 문자열을 사용합니다. 이는 다음과 같은 것을 의미합니다:

• 충돌하지 않습니다.
• 다른 프로세스의 파일을 재사용하지 않습니다.

기본 디렉터리는 리포지터리 데이터가 있는 파일 시스템에 캐시 파일을 위치시키지만, 이는 필수 요소가 아닙니다. 인프라에 더 적합하다면 캐시 파일을 다른 파일 시스템에 위치시킬 수 있습니다.

디스크에서 필요로 하는 IO 대역폭은 다음에 따라 달라집니다:

• Gitaly 서버의 리포지터리의 크기 및 형태.
• 사용자가 생성하는 트래픽의 종류.

gitaly_pack_objects_generated_bytes_total 메트릭을 사용하여 캐시 히트 비율이 0%라고 가정한 비관적인 추정을 할 수 있습니다.

필요한 공간은 다음에 따라 달라집니다:

• 사용자가 캐시에서 가져오는 초당 바이트 수.
• max_age 캐시 획득 창 크기.

사용자가 100MB/s를 가져오고 5분 창을 사용하는 경우, 평균적으로는 5*60*100MB = 30GB의 데이터가 캐시 디렉터리에 있습니다. 이 평균은 기대 예상 평균이며, 보장되는 것이 아닙니다. 최대 크기는 이 평균을 초과할 수 있습니다.

캐시 획득 창 max_age

max_age 구성 설정을 통해 캐시 히트 발생 확률과 캐시 파일의 평균 크기를 제어할 수 있습니다. max_age보다 오래된 항목은 디스크에서 삭제됩니다.

캐시 획득은 진행 중인 요청에 방해가 되지 않습니다. 느린 연결로 인해 max_age보다 삭제하는 데 소요되는 시간보다 짧아도 괜찮습니다. 이는 Unix 파일 시스템에서 삭제된 파일을 실제로 삭제하지 않기 때문입니다.

최소 키 발생 min_occurrences

• GitLab 15.11에서 도입.

min_occurrences 설정을 통해 동일한 요청이 얼마나 자주 발생해야 새로운 캐시 항목을 작성할지를 제어할 수 있습니다. 기본 값은 1로, 고유한 요청은 캐시에 기록되지 않습니다.

• 이 숫자를 높이면 캐시 히트 비율이 낮아지고 캐시 파일 사용량이 줄어듭니다.
• 이 숫자를 낮추면 캐시 히트 비율이 높아지고 캐시 파일 사용량이 늘어납니다.

min_occurrences를 1로 설정해야 합니다. GitLab.com에서 0에서 1로 변경하면 캐시 디스크 사용량이 50% 줄어들면서 캐시 히트 비율에 거의 영향을 미치지 않았습니다.

캐시 관찰

• pack-objects 캐싱에 대한 로그는 GitLab 16.0에서 변경되었습니다.

pack-objects 캐시는 메트릭을 사용하거나 다음에 기록된 정보를 통해 관찰할 수 있습니다. 이러한 로그는 gRPC 로그의 일부이며 호출이 실행될 때 발견할 수 있습니다.

• 캐시 미스의 경우, Gitaly는 pack_objects_cache.generated_bytes와 pack_objects_cache.served_bytes 메시지를 모두 기록합니다. Gitaly는 또한 팩 오브젝트 생성에 관한 몇 가지 자세한 통계를 기록합니다.
• 캐시 히트의 경우, Gitaly는 pack_objects_cache.served_bytes 메시지만 기록합니다.

예시:

{
  "bytes":26186490,
  "correlation_id":"01F1MY8JXC3FZN14JBG1H42G9F",
  "grpc.meta.deadline_type":"none",
  "grpc.method":"PackObjectsHook",
  "grpc.request.fullMethod":"/gitaly.HookService/PackObjectsHook",
  "grpc.request.glProjectPath":"root/gitlab-workhorse",
  "grpc.request.glRepository":"project-2",
  "grpc.request.repoPath":"@hashed/d4/73/d4735e3a265e16eee03f59718b9b5d03019c07d8b6c51f90da3a666eec13ab35.git",
  "grpc.request.repoStorage":"default",
  "grpc.request.topLevelGroup":"@hashed",
  "grpc.service":"gitaly.HookService",
  "grpc.start_time":"2021-03-25T14:57:52.747Z",
  "level":"info",
  "msg":"finished unary call with code OK",
  "peer.address":"@",
  "pid":20961,
  "span.kind":"server",
  "system":"grpc",
  "time":"2021-03-25T14:57:53.543Z",
  "pack_objects.compression_statistics": "Total 145991 (delta 68), reused 6 (delta 2), pack-reused 145911",
  "pack_objects.enumerate_objects_ms": 170,
  "pack_objects.prepare_pack_ms": 7,
  "pack_objects.write_pack_file_ms": 786,
  "pack_objects.written_object_count": 145991,
  "pack_objects_cache.generated_bytes": 49533030,
  "pack_objects_cache.hit": "false",
  "pack_objects_cache.key": "123456789",
  "pack_objects_cache.served_bytes": 49533030,
  "peer.address": "127.0.0.1",
  "pid": 8813,
}

cat-file 캐시

많은 Gitaly RPC에서는 리포지터리에서 Git 객체를 조회해야 합니다. 대부분 우리는 그 작업을 위해 git cat-file --batch 프로세스를 사용합니다. 성능을 향상시키기 위해, Gitaly는 이러한 git cat-file 프로세스를 RPC 호출 전후로 재사용할 수 있습니다. 이전에 사용된 프로세스는 “Git cat-file cache”에 유지됩니다. 이게 얼마나 많은 시스템 리소스를 사용하는지 제어하기 위해, cat-file 프로세스의 최대 수를 설정할 수 있습니다.

기본 제한은 100개의 cat-file이며, 이는 git cat-file --batch 및 git cat-file --batch-check 프로세스의 쌍을 구성합니다. “파일 개수가 너무 많음”에 관한 오류나 새로운 프로세스를 만들 수 없는 경우와 같은 문제가 발생한다면, 이 제한을 낮출 수 있습니다.

이상적으로, 이 숫자는 표준 트래픽을 처리하는 데 충분히 많아야 합니다. 제한을 높이면 캐시 히트 비율을 메트릭해야 합니다. 히트 비율이 개선되지 않는다면, 더 높은 제한은 의미 있는 차이를 만들고 있지 않을 가능성이 높습니다. 다음은 히트 비율을 확인하는 예제 Prometheus 쿼리입니다:

sum(rate(gitaly_catfile_cache_total{type="hit"}[5m])) / sum(rate(gitaly_catfile_cache_total{type=~"(hit)|(miss)"}[5m]))

cat-file 캐시를 Gitaly 구성 파일에서 설정하세요.

GitLab UI 커밋에 대한 커밋 서명 구성

• GitLab 15.4에서 도입됨.
• 서명된 GitLab UI 커밋에 대한 검증됨 뱃지 표시가 [GitLab 16.3에서 도입됨]되었으며, 기본적으로 비활성화되어 있습니다.
• GitLab 16.3에서 rotated_signing_keys 옵션을 통해 여러 키를 사용하여 서명을 확인하는 기능이 도입되었습니다.
• GitLab 17.0에서는 Self-Managed 및 GitLab Dedicated에서 기본적으로 활성화됨.

FLAG: 기본적으로 이 기능은 Self-Managed GitLab에서 사용할 수 있습니다. 이 기능을 숨기려면 관리자가 gitaly_gpg_signing이름의 피처 플래그를 비활성화할 수 있습니다. GitLab.com에서는 이 기능을 사용할 수 없으며, GitLab Dedicated에서는 사용할 수 있습니다.

기본적으로 Gitaly는 GitLab UI를 통해 만든 커밋에 서명하지 않습니다. 예를 들어, 웹 에디터, 웹 IDE, Merge Request을 통해 만든 커밋은 서명되지 않습니다.

GitLab UI를 통해 만든 커밋에 서명을 설정할 수 있습니다.

기본적으로 Gitaly는 커밋의 저자를 커미터로 설정합니다. 이 경우에는 커밋의 서명이 커밋의 저자나 커미터 둘 다에 속하지 않아서 로컬에서 커밋 확인이 어려울 수 있습니다.

GitLab.com의 경우, committer_email과 committer_name이 noreply@gitlab.com 및 GitLab로 설정되어 있습니다.

rotated_signing_keys는 검증을 위해서만 사용할 키 디렉터리입니다. Gitaly는 구성된 signing_key를 사용하여 웹 커밋을 확인하려고 시도하고, 성공할 때까지 순서대로 로테이션된 키를 사용합니다. 다음 중 하나인 경우 rotated_signing_keys 옵션을 설정하세요:

• 서명 키가 로테이션되는 경우.
• 다른 인스턴스에서 프로젝트를 이전하거나 그들의 웹 커밋을 검증됨으로 표시하려는 경우에 여러 키를 지정하려는 경우.

GitLab UI를 통해 만든 커밋에 서명을 설정하는 방법은 두 가지 중 하나로 설정할 수 있습니다:

외부 명령을 사용하여 구성 생성

• GitLab 15.11에서 도입됨.

외부 명령을 사용하여 Gitaly 구성의 일부를 생성할 수 있습니다. 다음과 같은 이유로 이렇게 할 수 있습니다:

• 각각의 노드에 전체 구성을 배포하지 않고 노드를 구성하기 위해서.
• 노드 설정의 자동 검색을 사용하여 구성하기 위해서. 예를 들어, DNS 항목을 사용하기 위해서.
• 노드의 시작 시점에서 시크릿을 구성하여 평문으로 표시될 필요가 없게 하기 위해서.

외부 명령을 사용하여 구성을 생성하기 위해, Gitaly 노드의 원하는 구성을 JSON 형식으로 표준 출력으로 덤프하는 스크립트를 제공해야 합니다.

예를 들어, 다음 명령은 GitLab 내부 API에 연결하는 데 사용되는 HTTP 비밀번호를 AWS 비밀로 설정합니다:

#!/usr/bin/env ruby
require 'json'
JSON.generate({"gitlab": {"http_settings": {"password": `aws get-secret-value --secret-id ...`}})

그런 다음 Gitaly에게 스크립트 경로를 알려줘야 합니다:

gitaly['configuration'] = {
    config_command: '/path/to/config_command',
}

config_command = "/path/to/config_command"

구성을 완료한 후, Gitaly는 시작 시에 해당 명령을 실행하고 그 결과를 JSON으로 파싱합니다. 그 결과로 나온 구성은 나머지 Gitaly 구성에 다시 Merge됩니다.

구성 명령이 실패하거나 명령에 의해 생성된 출력이 유효한 JSON으로 구문 분석할 수 없는 경우에는 Gitaly가 시작하지 못할 것입니다.

서버 측 백업 구성

• GitLab 16.3에서 소개됨.
• 최신 백업 대신 특정 백업을 복원하는 서버 측 지원은 GitLab 16.6에서 소개됨.
• 증분 백업을 만드는 서버 측 지원은 GitLab 16.6에서 소개됨.

원격 리포지터리 백업은 각 리포지터리를 호스트하는 Gitaly 노드가 해당 백업을 생성하고 스트리밍하는 방식으로 구성할 수 있습니다. 이는 백업을 만들고 복원하는 데 필요한 네트워크 리소스를 줄이는 데 도움이 됩니다.

각 Gitaly 노드는 백업을 위해 객체 리포지터리에 연결되도록 구성되어야 합니다.

서버 측 백업을 구성한 후 서버 측 리포지터리 백업을 만들 수 있습니다.

Azure Blob 리포지터리 구성

백업을 위해 Azure Blob 리포지터리를 구성하는 방법은 설치 유형에 따라 다릅니다. 자체 컴파일한 설치의 경우 GitLab 외부에서 AZURE_STORAGE_ACCOUNT 및 AZURE_STORAGE_KEY 환경 변수를 설정해야 합니다.

gitaly['env'] = {
    'AZURE_STORAGE_ACCOUNT' => 'azure_storage_account',
    'AZURE_STORAGE_KEY' => 'azure_storage_key' # 또는 'AZURE_STORAGE_SAS_TOKEN'
}
gitaly['configuration'] = {
    backup: {
        go_cloud_url: 'azblob://gitaly-backups'
    }
}

[backup]
go_cloud_url = "azblob://gitaly-backups"

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'] = {
    backup: {
        go_cloud_url: 'gs://gitaly-backups'
    }
}

[backup]
go_cloud_url = "gs://gitaly-backups"

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'] = {
    backup: {
        go_cloud_url: 's3://gitaly-backups?region=us-west-1'
    }
}

[backup]
go_cloud_url = "s3://gitaly-backups?region=us-west-1"

S3 호환 서버 구성

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

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

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

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

[backup]
go_cloud_url = "s3://gitaly-backups?region=minio&endpoint=my.minio.local:8080&disableSSL=true&s3ForcePathStyle=true"