• Gitaly 토큰에 대해
• Gitaly를 별도 서버에서 실행하기
  • 네트워크 아키텍처
  • Gitaly 설치
  • Gitaly 서버 구성
    • 인증 구성
    • Gitaly 서버 구성
  • Gitaly 클라이언트 구성
    • 혼합 구성
  • GitLab은 기본 저장소 스토리지가 필요합니다
  • 필요하지 않은 곳에서 Gitaly 비활성화 (선택 사항)
• 제어 그룹
  • 저장소 cgroups 구성 (새로운 방법)
  • 저장소 cgroups 구성 (레거시 방법)
  • 오버 서브스크립션 구성
• 백그라운드 저장소 최적화
• Gitaly 인증 토큰 회전
  • 인증 모니터링 확인
  • “인증 전환” 모드 활성화
  • 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 서버는 Gitaly clients in your cluster보다 먼저 업그레이드 되어야 합니다.

주의: Gitaly 노드의 디스크 요구 사항이 적용됩니다.

자체 서버에서 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 clients에 대해 정확히 해결되도록 지정되어야 합니다.
• Gitaly 클라이언트는 다음과 같습니다.:
  • Puma.
  • Sidekiq.
  • GitLab Workhorse.
  • GitLab Shell.
  • Elasticsearch indexer.
  • Gitaly 자체.
• Gitaly 서버는 /config/gitlab.yml에서 지정된 자신의 (Gitaly 주소, Gitaly 토큰) 쌍을 사용하여 자체에게 RPC 호출을 수행할 수 있어야 합니다.
• 인증은 Gitaly와 GitLab Rails 노드 간에 공유되는 정적 토큰을 통해 수행됩니다.

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

주의: Gitaly 서버는 기본적으로 암호화되지 않은 Gitaly 네트워크 트래픽 때문에 공개 인터넷에 노출되지 않아야 합니다. 방화벽의 사용을 강력히 권장하여 Gitaly 서버로의 접근을 제한해야 합니다. 또 다른 옵션은 TLS를 사용하는 것입니다.

다음 섹션에서는 시크릿 토큰 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 서버를 구성합니다.

경고: GitLab 서버에서 Gitaly로 리포지토리 데이터를 직접 복사하는 경우, 메타데이터 파일인 /var/opt/gitlab/git-data/repositories/.gitaly-metadata가 전송에 포함되지 않도록합니다. 이 파일을 복사하면 GitLab이 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로 원격 서버로 정의할 수 없습니다. 혼합 구성(mixed configuration)을 사용하지 않는 이상입니다.

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

Gitaly 서버의 로그를 추적하면 요청이 들어오는 것을 확인할 수 있어야 합니다. Gitaly 요청을 트리거하는 확실한 방법은 GitLab에서 HTTP 또는 HTTPS를 통해 저장소를 복제하는 것입니다.

경고: 서버 후크(server hooks)가 리포지토리별 또는 전역으로 구성되어 있는 경우, 이러한 것들을 모두 Gitaly 서버로 이동해야 합니다. 여러 Gitaly 서버가 있는 경우 서버 후크를 모든 Gitaly 서버로 복사해야 합니다.

혼합 구성

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

• 다른 Gitaly 서버에서 모든 주소에 연결할 수 있어야 합니다.
• storage1은 gitaly_address에 대해 유효하지 않은 Unix 소켓을 할당 받았습니다.

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 man 페이지를 참조하십시오.
cgroups는 메모리 및 CPU의 과소비로 인한 예기치 못한 리소스 고갈로부터 시스템을 보호하는 데 도움이 될 수 있습니다.

일부 Git 작업은 예상치 못한 높은 트래픽이나 모범 사례를 따르지 않는 대형 저장소에 대한 작업과 같이 과소비로 인해 빈번한 리소스 소비가 발생할 수 있습니다.

강력한 보호를 위해 커널을 구성하여 이러한 작업을 시스템 리소스를 모두 소모하기 전에 중단시킬 수 있는 cgroups를 사용할 수도 있습니다.

Gitaly에는 내장된 cgroups 제어가 있습니다. 설정된 경우 Git 명령이 작동 중인 리포지토리를 기반으로 Gitaly는 Git 프로세스를 리포지토리 cgroups에 할당합니다. 이러한 cgroups를 리포지토리 cgroups라고 합니다. 각 리포지토리 cgroup은 다음을 포함합니다:

• 메모리 및 CPU 제한
• 단일 리포지토리의 Git 프로세스
• 일관된 해시를 사용하여 특정 리포지토리에 대한 Git 프로세스가 항상 동일한 cgroup에 끝나도록 보장합니다.

리포지토리 cgroup이 다음을 도달하면:

• 메모리 제한이 도달되면 커널은 종료할 후보 프로세스를 찾습니다.
• 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 shares입니다.
• cpu_quota_us는 이 할당량 값이 초과될 경우 cgroups의 프로세스를 조절하는 cfs_quota_us입니다. 우리는 cfs_period_us를 100ms로 설정하여 1코어가 100000이 되도록합니다. 0은 제한이 없음을 의미합니다.
• repositories.count는 cgroups 풀에 있는 cgroups의 수입니다. 새 Git 명령이 생성될 때마다 Gitaly는 해당 명령이 대상 리포지토리를 기반으로 이러한 cgroups 중 하나에 할당합니다. 순환 해싱 알고리즘에 따라 Git 명령은 항상 동일한 cgroup에 할당됩니다.
• repositories.memory_bytes는 리포지토리 cgroup에 포함된 모든 Git 프로세스에 적용되는 총 메모리 제한입니다. 0은 제한이 없음을 의미합니다. 이 값은 최상위 레벨 memory_bytes보다 클 수 없습니다.
• repositories.cpu_shares는 리포지토리 cgroup에 포함된 모든 Git 프로세스에 적용되는 CPU 제한입니다. 0은 제한이 없음을 의미합니다. 최대값은 CPU의 100%를 나타내는 1024 shares입니다. 이 값은 최상위 레벨 cpu_shares보다 클 수 없습니다.
• repositories.cpu_quota_us는 리포지토리 cgroup에 포함된 모든 Git 프로세스에 적용되는 cfs_quota_us입니다. Git 프로세스는 지정된 할당량을 초과하여 사용할 수 없습니다. 우리는 cfs_period_us를 100ms로 설정하여 1코어가 100000이 되도록합니다. 0은 제한이 없음을 의미합니다.

예시:

# in /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 제한입니다. 최대값은 CPU의 100%를 나타내는 1024 shares입니다.

예시:

# 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의 제한보다는 작지만 상위 cgroup의 제한의 1/N보다 훨씬 큰 (이 예에서는 20GB) 대폭적 상한선까지 버스트할 수 있습니다. 일반적으로, 모든 1000개의 cgroup은 20GB보다 훨씬 적게 사용할 것입니다.

백그라운드 저장소 최적화

리포지토리에는 비어 있는 디렉토리와 필요 없는 구성 설정이 쌓일 수 있으며 Git 작업을 느리게 할 수 있습니다. Gitaly는 매일 백그라운드 작업을 예약하여 이러한 항목을 정리하고 성능을 향상시킬 수 있습니다.

경고: 백그라운드 저장소 최적화는 실험적인 기능이며 실행 중에 호스트에 상당한 부하를 줄 수 있습니다. 이를 저녁 시간에 예약하고 기간을 짧게 유지(예: 30-60분)해야 합니다.

백그라운드 저장소 최적화는 다음 두 가지 방법 중 하나로 구성할 수 있습니다:

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 인증 토큰을 회전시키는 것은 다음과 같습니다:

• 인증 모니터링 확인.
• “인증 전환” 모드 활성화(#enable-auth-transitioning-mode).
• Gitaly 인증 토큰 업데이트(#update-gitaly-authentication-token).
• 인증 실패가 없는지 확인(#ensure-there-are-no-authentication-failures).
• “인증 전환” 모드 비활성화(#disable-auth-transitioning-mode).
• 인증이 강제되었는지 확인(#verify-authentication-is-enforced).

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

인증 모니터링 확인

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

그럼 나머지 절차를 계속할 수 있습니다.

“인증 전환” 모드 활성화

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: '<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이 아닌 비율로 표시되어야 합니다.

“auth transitioning” 모드 비활성화

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

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

경고: 이 단계를 완료하지 않으면 Gitaly 인증이 없음을 유념하세요.

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

Prometheus 쿼리를 새로고침하세요. 이제 처음과 유사한 결과를 확인해야 합니다. 예를 들어:

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

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

Pack-objects 캐시

Git 저장소에 대한 저장소 역할을 하는 서비스인 Gitaly는 Git fetch 응답의 짧은 롤링 윈도우를 캐시로 구성할 수 있습니다. 이는 서버가 많은 CI fetch 트래픽을 받을 때 서버 부하를 줄일 수 있습니다.

pack-objects 캐시는 git pack-objects를 감싸는데, 이는 Git의 내부적인 부분으로 PostUploadPack 및 SSHUploadPack Gitaly RPC를 통해 간접적으로 호출됩니다. 캐시를 활성화하면, PostUploadPack 또는 SSHUploadPack를 사용하는 모든 것이 이점을 얻을 수 있습니다. 이는 다음과 관계 없이 적용됩니다:

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

이 캐시의 강점은 동시에 발생하는 동일한 페치를 중복으로 처리하는 능력입니다. 이로써 다음과 같은 이점을 얻을 수 있습니다:

• 많은 동시 작업을 실행하는 GitLab 인스턴스의 CI/CD 파이프라인을 사용하는 사용자는 서버 CPU 사용량을 확실히 줄일 수 있습니다.
• 고유한 페치에는 전혀 이점이 없습니다. 예를 들어, 로컬 컴퓨터로 저장소를 복제하여 간단히 확인하는 경우, 이 캐시에서는 이점을 거의 못 볼 것입니다.

pack-objects 캐시는 로컬 캐시이며, 다음과 같습니다:

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

로컬 파일을 사용하면 운영 체제가 pack-objects 캐시 파일의 일부를 자동으로 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에서 소개되었습니다(https://gitlab.com/gitlab-com/gl-infra/scalability/-/issues/2222).

min_occurrences 설정은 새 캐시 항목을 만들기 전에 동일한 요청이 얼마나 자주 발생해야 하는지를 제어합니다. 기본값은 1로, 고유한 요청은 캐시로 기록되지 않습니다.

이 수를 늘리면 캐시 히트 비율이 낮아지고 캐시가 덜 디스크 공간을 사용합니다. 이 수를 줄이면 캐시 히트 비율이 높아지고 캐시가 더 많은 디스크 공간을 사용합니다.

min_occurrences를 1로 설정해야 합니다. GitLab.com에서 0에서 1로 변경함으로써 캐시 디스크 공간을 50% 절약했지만 캐시 히트 비율에 거의 영향을 주지 않았습니다.

캐시 확인

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

캐시를 메트릭을 사용하여 확인하고, 다음에 나오는 로그 정보를 확인할 수 있습니다. 이 로그는 gRPC 로그의 일부이며 호출이 실행될 때 발견될 수 있습니다.

• 캐시 미스의 경우, Gitaly는 pack_objects_cache.generated_bytes 및 pack_objects_cache.served_bytes 메시지를 함께 기록합니다. 또한 팩 객체 생성에 대한 더 자세한 통계를 기록합니다.
• 캐시 히트의 경우, 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는 RPC 호출 전반에 걸쳐 이러한 git cat-file 프로세스를 재사용할 수 있습니다. 이전에 사용된 프로세스는 “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에서 도입.
• gitaly_gpg_signing이라는 플래그와 함께 GitLab 16.3에서 소개됨 (기본값은 비활성화).

플래그: 자체 호스팅 GitLab의 경우, 기본적으로 이 기능을 사용할 수 없습니다. 사용하려면 관리자가 gitaly_gpg_signing이라는 기능 플래그를 활성화할 수 있습니다. GitLab.com 및 전용 GitLab에서는 이 기능을 사용할 수 없습니다.

기본적으로 Gitaly는 GitLab UI를 통해 만든 커밋에 서명하지 않습니다. 예를 들어, 웹 편집기, 웹 IDE, 병합 요청에서 만든 커밋 등입니다.

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

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

GitLab.com에서는 committer_email과 committer_name이 noreply@gitlab.com 및 GitLab으로 설정됩니다. 이와 같은 구성 옵션을 설정하여 Gitaly가 당신의 인스턴스에 의해 커밋되었음을 반영하도록 구성할 수 있습니다.

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 구성에 다시 병합됩니다.

Gitaly는 다음 중 하나라도 발생하는 경우 시작하지 못합니다.

• 구성 명령이 실패하는 경우.
• 명령에 의해 생성된 출력을 유효한 JSON으로 구문 분석할 수 없는 경우.

서버 측 백업 구성

• GitLab 16.3에서 소개됨.
• 최신 백업이 아닌 지정된 백업 복원을 지원하는 서버 측 지원 GitLab 16.6에서 소개됨.
• 증분 백업 생성을 지원하는 서버 측 지원 GitLab 16.6에서 소개됨.

저장소 백업을 구성하여 각 저장소를 호스팅하는 Gitaly 노드가 백업을 생성하고 객체 저장소로 스트리밍하는 방식으로 구성할 수 있습니다. 이를 통해 백업을 생성하고 복원하는 데 필요한 네트워크 리소스를 줄일 수 있습니다.

각 Gitaly 노드는 백업을 위해 객체 저장소에 연결하도록 구성되어야 합니다.

서버 측 백업을 구성한 후, 서버 측 저장소 백업을 만들 수 있습니다.

Azure Blob 저장소 구성

Azure Blob 저장소를 백업으로 구성하는 방법은 설치 유형에 따라 다릅니다. Self-compiled 설치의 경우, 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)는 Application Default Credentials를 사용하여 인증합니다. 각 Gitaly 서버에 Application Default Credentials를 설정하는 방법은 다음 중 하나를 사용하여 설치할 수 있습니다.

• gcloud auth application-default login 명령어를 사용합니다.
• Self-compiled 설치의 경우 GOOGLE_APPLICATION_CREDENTIALS 환경 변수를 설정합니다. GitLab 외부에서 환경 변수를 설정합니다.

자세한 정보는 Application Default Credentials를 참조하십시오.

대상 버킷은 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"