• Gitaly 토큰에 대해
• Gitaly를 독자적인 서버에서 실행
  • 네트워크 아키텍처
  • Gitaly 설치
  • Gitaly 서버 구성
    • 인증 구성
    • Gitaly 서버 구성
  • Gitaly 클라이언트 구성
    • 혼합 구성
  • GitLab은 기본 리포지터리 스토리지를 필요로 합니다
  • 필요하지 않은 경우 Gitaly를 비활성화합니다 (선택 사항)
• 제어 그룹
  • 리포지터리 cgroups 구성 (새로운 방법)
  • 레거시 방식으로 리포지터리 cgroups 구성
  • 초과 등록 구성
• 배경 리포지터리 최적화
• Gitaly 인증 토큰 회전
  • 인증 모니터링 검증
  • “auth transitioning” 모드 활성화
  • Gitaly 인증 토큰 업데이트
  • 인증 실패가 없는지 확인하세요
  • “auth transitioning” 모드 비활성화
  • 인증이 강제로 적용되었는지 확인하세요
• 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 서버는 /config/gitlab.yml에서 지정한 자체 (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'] 설정을 사용하여 일시적으로 인증을 비활성화할 수 있습니다. 자세한 정보는 “auth transitioning mode” 활성화 문서를 참조하세요.

인증 구성

Gitaly 및 GitLab은 인증을 위해 두 개의 공유된 시크릿을 사용합니다:

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

Gitaly 서버 구성

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_address 없이 로컬 Gitaly 서버로서 몇 군데를 정의할 수 없으며, gitaly_address를 사용하는 원격 서버로서 몇 군데를 정의할 수 없습니다. 이 경우 혼합 구성을 사용해야 합니다.

Gitaly 클라이언트를 다음 두 가지 방법 중 하나로 구성하세요.

Gitaly 서버의 로그를 확인하면 요청이 수신되는 것을 확인할 수 있어야 합니다. Gitaly 서버에서 GItLab의 리포지터리를 HTTP 또는 HTTPS를 통해 복제하여 Gitaly 요청을 확실히 유도할 수 있습니다.

혼합 구성

GitLab은 여러 Gitaly 서버 중 하나와 동일한 서버에 상주할 수 있지만 로컬 및 원격 구성을 혼합하는 구성을 지원하지 않습니다. 다음 구성은 잘못된 설정입니다.

• 모든 주소는 다른 Gitaly 서버에서 도달할 수 있어야 합니다.
• storage1은 일부 Gitaly 서버에 대해 유효하지 않은 gitaly_address용 유닉스 소켓을 할당 받았습니다.

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은 default라는 git_data_dirs 항목을 필요로하기 때문입니다. 이 제한에 대해 더 읽어보세요.

이 제한을 해결하려면:

1. 새 Gitaly 서비스에서 추가 저장 위치를 정의하고 추가 저장을 default로 구성합니다.
2. 관리자 영역에서 default를 중요도가 낮은 0으로 설정하여 리포지터리가 거기에 저장되지 않도록 합니다.

필요하지 않은 경우 Gitaly를 비활성화합니다 (선택 사항)

Gitaly를 원격 서비스로 실행하는 경우, 기본적으로 GitLab 서버에서 실행되는 로컬 Gitaly 서비스를 비활성화하고 필요할 때만 실행할 수 있습니다.

GitLab 인스턴스에서 Gitaly를 비활성화하는 것은 GitLab을 사용자 정의 클러스터 구성에서 실행하는 경우에만 의미가 있습니다. 여기서 Gitaly는 GitLab 인스턴스와 별도의 기계에서 실행됩니다. 클러스터의 모든 기계에서 Gitaly를 비활성화하는 것은 유효한 구성이 아닙니다(일부 기계는 Gitaly 서버로 작동해야 함).

GitLab 서버에서 Gitaly를 비활성화하는 방법은 다음과 같습니다:

제어 그룹

메모리에 제한을 두는 경우 Gitaly 노드에 스왑이 구성되지 않았는지 확인해야 합니다. 프로세스가 종료되는 대신 이러한 스왑을 사용하게 될 수 있습니다. 이러한 상황은 상당히 성능에 악영향을 미칠 수 있습니다.

Linux에서 제어 그룹 (cgroups)을 사용하여 Gitaly 프로세스가 소비할 수 있는 메모리와 CPU 양에 제한을 걸 수 있습니다. 자세한 정보는 cgroups Linux 맨 페이지를 참조하세요. cgroups를 사용하면 예상치 못한 자원 고갈로부터 시스템을 보호할 수 있습니다.

일부 Git 작업은 다음과 같은 상황에서 자원을 상당히 많이 소비할 수 있습니다:

• 예상치 못한 고트래픽.
• 모범 사례를 따르지 않는 대형 리포지터리에서 실행되는 작업.

강력한 보호를 위해 커널이 이러한 작업을 시스템 자원을 모두 소모하기 전에 중지시킬 수 있도록 cgroups를 사용할 수 있습니다.

Gitaly는 내장 cgroups 제어 기능을 갖고 있습니다. 구성된 경우 Gitaly는 Git 명령이 작동하는 리포지터리를 기반으로 Git 프로세스를 리포지터리 cgroup에 할당합니다. 각 리포지터리 cgroup은:

• 메모리 및 CPU 제한이 있습니다.
• 단일 리포지터리에 대한 Git 프로세스를 포함합니다.
• 일관된 해시를 사용하여 특정 리포지터리에 대한 Git 프로세스가 항상 동일한 cgroup에 종료되도록합니다.

리포지터리 cgroup에 메모리 제한이 설정되면 커널은 종료할 후보 프로세스를 찾습니다. CPU 제한이 있으면 프로세스는 종료되지 않지만 허용된 CPU 이상의 CPU를 소모하는 것을 방지합니다.

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

• 이 리포지터리 cgroups를 구성하는 방법은 GitLab 15.1에 도입되었습니다.
• 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가 시작될 때 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는 해당 명령이 적용될 리포지터리에 기반하여 이러한 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은 제한이 없음을 의미합니다.

예시:

# /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%를 나타냅니다.

예를 들어:

# /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로 제한됩니다.

이 구성은 “초과 등록(oversubscription)”으로 이어집니다. 풀의 각 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 인증 토큰을 회전하는 것은 다음과 같습니다:

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

이 절차는 서버에서 GitLab를 실행하는 경우에도 작동합니다. 이 경우에 “Gitaly 서버”와 “Gitaly 클라이언트”는 동일한 기계를 가리킵니다.

인증 모니터링 검증

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

그런 다음 절차의 나머지 부분을 진행할 수 있습니다.

“auth transitioning” 모드 활성화

다음과 같이 Gitaly 서버에서 “인증 전환” 모드로 설정하여 잠시 동안 Gitaly 인증을 비활성화하세요:

# /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. 구성 업데이트:

   # /etc/gitlab/gitlab.rb에 추가
   gitaly['configuration'] = {
      # ...
      auth: {
         # ...
         token: '<새 비밀 토큰>',
      },
   }
   

2. Gitaly 재시작:

   gitlab-ctl restart gitaly
   

이 변경 사항을 롤아웃하는 동안 Prometheus 쿼리를 실행하면 enforced="false",status="denied" 카운터에 대한 0이 아닌 값이 반환됩니다.

인증 실패가 없는지 확인하세요

새 토큰을 설정한 후 모든 관련 서비스를 다시 시작하면 일시적으로 인증 모니터링 검증에서 다음과 같은 혼합 결과를 볼 수 있습니다:

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

새 토큰이 모든 Gitaly 클라이언트 및 Gitaly 서버에서 적용된 후 오직 0이 아닌 비율은 enforced="false",status="would be ok"여야 합니다.

“auth transitioning” 모드 비활성화

Gitaly 인증을 다시 활성화하려면 “auth transitioning” 모드를 비활성화하세요. 아래와 같이 Gitaly 서버의 구성을 업데이트하세요:

# /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 트래픽을 받을 때 서버 부하를 줄일 수 있습니다.

팩-오브젝트 캐시는 git pack-objects를 감싸는데, 이는 Git의 내부적인 부분으로 PostUploadPack과 SSHUploadPack Gitaly RPC를 통해 간접적으로 호출됩니다. 캐시가 활성화되면 PostUploadPack이나 SSHUploadPack을 사용하는 모든 것에 이점이 있습니다. 이는 다음과 관련이 있습니다:

• 전송 방법(HTTP 또는 SSH)
• Git 프로토콜 버전(v0 또는 v2)
• 전체 클론, 증분적인 페치, 얕은 클론, 또는 부분 클론과 같은 페치 유형

이 캐시의 강점은 동시에 발생한 동일한 페치를 중복 제거하는 능력입니다. 이는 다음과 같은 곳에서 GitLab 인스턴스에 이점을 줄 수 있습니다:

• 사용자가 많은 동시 작업을 수행하는 CI/CD 파이프라인을 실행하는 GitLab 인스턴스에서 유용할 수 있습니다. 서버 CPU 활용에 명백한 감소가 있어야 합니다.
• 고유한 페치에는 전혀 이점이 없습니다. 예를 들어, 로컬 컴퓨터로 리포지터리를 클론하여 스폿을 확인하는 경우, 이 캐시에서 이점을 보기 어렵습니다. 왜냐하면 당신의 페치는 아마도 고유하기 때문입니다.

팩-오브젝트 캐시는 로컬 캐시입니다. 이는 다음과 같습니다:

• 활성화된 Gitaly 프로세스의 메모리에 메타데이터를 저장합니다.
• 실제 캐시된 Git 데이터를 로컬 저장 장치에 파일로 저장합니다.

로컬 파일을 사용하는 것은 운영 체제가 자동으로 팩-오브젝트 캐시 파일의 일부를 RAM에 유지할 수 있어서 빠릅니다.

팩-오브젝트 캐시는 디스크 쓰기 IO를 상당히 늘릴 수 있으므로 기본적으로 비활성화되어 있습니다. GitLab 15.11 이후, 쓰기 작업량은 약 50% 낮아졌지만 여전히 기본적으로 비활성화되어 있습니다.

캐시 구성

다음은 팩-오브젝트 캐시에 대한 구성 설정입니다. 각 설정은 아래에서 자세히 설명됩니다.

/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 서버의 리포지터리 크기와 형태
• 사용자가 생성하는 트래픽의 종류

관련하여 당신의 캐시 히트 비율이 0%인 것처럼 낙관적 추정으로 gitaly_pack_objects_generated_bytes_total 지표를 사용할 수 있습니다.

필요로 하는 공간의 양은 다음에 따라 다릅니다:

• 사용자가 캐시에서 가져오는 초당 바이트 수
• 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% 절약했으며 거의 영향을 주지 않았습니다.

캐시 관찰

• 팩-오브젝트 캐싱 로그는 GitLab 16.0에서 변경되었습니다.

캐시를 메트릭을 사용하여 확인하고 다음 로그 정보에서 확인할 수 있습니다. 이 로그는 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 RPCs에서 리포지터리에서 Git 객체를 조회해야 합니다. 대부분의 경우 우리는 git cat-file --batch 프로세스를 사용합니다. 성능을 높이기 위해 Gitaly는 이러한 git cat-file 프로세스를 RPC 호출 사이에서 재사용할 수 있습니다. 이전에 사용된 프로세스는 “Git cat-file 캐시”에 유지됩니다. 시스템 자원을 얼마나 많이 사용하는지 제어하기 위해 캐시에 들어갈 수 있는 최대 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 커밋에 대한 검증됨(Verified) 배지 표시는 GitLab 16.3에서 gitaly_gpg_signing이라는 플래그로 도입되었습니다. 기본으로 비활성화됩니다.

플래그: Self-managed GitLab에서는 기본적으로 이 기능을 사용할 수 없습니다. 사용하려면 관리자가 gitaly_gpg_signing이라는 피처 플래그를 활성화해야 합니다. GitLab.com 및 GitLab Dedicated에서는 이 기능을 사용할 수 없습니다.

기본적으로 Gitaly는 GitLab UI를 사용하여 만든 커밋에 서명을 하지 않습니다. 예를 들어, 다음을 사용하여 만든 커밋은 서명되지 않습니다:

• 웹 편집기.
• 웹 IDE.
• Merge Request.

GitLab UI를 통해 만든 커밋에 서명을 Gitaly로 구성할 수 있습니다.

기본적으로 Gitaly는 커밋의 작성자를 커미터로 설정합니다. 이 경우, 커밋의 서명이 작성자나 커미터 양쪽에 모두 속하지 않기 때문에 로컬에서 커밋 검증이 어려울 수 있습니다.

Gitaly를 구성하여 커밋이 당사의 인스턴스에 의해 커밋된 것으로 표시하도록 하려면 committer_email 및 committer_name을 설정할 수 있습니다. 예를 들어, GitLab.com의 경우 이러한 구성 옵션은 noreply@gitlab.com 및 GitLab로 설정됩니다.

GitLab UI를 통해 만든 커밋에 서명을 Gitaly로 구성하는 방법은 다음 중 하나입니다:

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

• GitLab 15.11에서 도입되었습니다.

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

• 각각의 노드에 완전한 구성을 배포하지 않고 각각의 노드를 구성하는 것.
• 노드의 설정을 자동으로 찾아 구성하는 것. 예를 들어, DNS 항목을 사용하는 것.
• 플레인 텍스트로 표시할 필요가 없도록 노드의 시작 시점에 비밀을 설정하는 것.

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

예를 들어, 다음 명령은 AWS 시크릿을 사용하여 GitLab 내부 API에 연결하는 데 사용되는 HTTP 암호를 구성합니다:

#!/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 명령어를 사용합니다.
• 자체 컴파일된 설치의 경우, 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"