InfoGrab Docs

Gitaly on Kubernetes

요약

Kubernetes에서 Gitaly를 실행하면 가용성 트레이드오프가 있으므로 프로덕션 환경을 계획할 때 이러한 트레이드오프를 고려하고 그에 맞게 기대치를 설정하세요. Gitaly on Kubernetes는 Gitaly 팀에 의해 평가되어 Gitaly를 배포하는 안전한 방법으로 결정되었습니다.

히스토리
  • GitLab 17.3에서 실험적 기능으로 도입되었습니다.
  • GitLab 17.10에서 실험적 기능에서 베타로 변경되었습니다.
  • GitLab 18.2에서 베타에서 제한적 가용성으로 변경되었습니다.
  • GitLab 18.11에서 제한적 가용성에서 일반 가용성으로 변경되었습니다.

Kubernetes에서 Gitaly를 실행하면 가용성 트레이드오프가 있으므로 프로덕션 환경을 계획할 때 이러한 트레이드오프를 고려하고 그에 맞게 기대치를 설정하세요. 이 문서는 기존 제한 사항을 최소화하고 계획하는 방법에 대한 지침을 설명합니다.

Gitaly on Kubernetes는 Gitaly 팀에 의해 평가되어 Gitaly를 배포하는 안전한 방법으로 결정되었습니다. 이 문서의 나머지 부분에서는 이를 위한 모범 사례를 자세히 설명합니다.

타임라인#

Gitaly on Kubernetes는 GitLab 18.11부터 일반 가용성(GA)입니다. GitLab은 클라우드 공급자의 특정 관리형 Kubernetes 오퍼링(예: Amazon EKS, Google GKE, Azure AKS)과의 호환성을 보장하지 않습니다. 프로덕션 환경에 배포하기 전에 특정 환경을 검증해야 합니다.

배경#

설계상 Gitaly(비 클러스터)는 단일 장애 지점(SPoF) 서비스입니다. 데이터는 단일 인스턴스에서 소싱되고 제공됩니다. Kubernetes의 경우 StatefulSet 파드가 교체되면(예: 업그레이드, 노드 유지 관리 또는 퇴출 중) 파드 또는 인스턴스가 제공하는 데이터에 대한 서비스 중단이 발생합니다.

Cloud Native Hybrid 설정(Gitaly VM)에서 Linux 패키지(Omnibus)는 다음을 통해 문제를 마스킹합니다:

  1. 인플레이스 Gitaly 바이너리 업그레이드.
  2. 그레이스풀 리로드 수행.

컨테이너 또는 파드가 완전히 종료되고 새 컨테이너 또는 파드로 시작해야 하는 컨테이너 기반 라이프사이클에는 동일한 접근 방식이 적합하지 않습니다.

Gitaly Cluster(Praefect)는 인스턴스 간 데이터를 복제하여 데이터 및 서비스 고가용성 측면을 해결합니다. 그러나 Gitaly Cluster(Praefect)는 컨테이너 기반 플랫폼에 의해 증폭되는 기존 문제 및 설계 제약 때문에 Kubernetes에서 실행하기에 적합하지 않습니다.

Cloud Native 배포를 지원하기 위해 Gitaly(비 클러스터)만 옵션입니다. 올바른 Kubernetes 및 Gitaly 기능과 구성을 활용하여 서비스 중단을 최소화하고 좋은 사용자 경험을 제공할 수 있습니다.

요구 사항#

이 페이지의 정보는 다음을 가정합니다:

  • Kubernetes 버전 1.29 이상.
  • Kubernetes 노드 runc 버전 1.1.9 이상.
  • Kubernetes 노드 cgroup v2. 네이티브, 하이브리드 v1 모드는 지원되지 않습니다. systemd 스타일 cgroup 구조만 지원됩니다(Kubernetes 기본값).
  • 노드 마운트 포인트 /sys/fs/cgroup에 대한 파드 액세스.
  • containerd 버전 2.1.0 이상.
  • /sys/fs/cgroup에 대한 root 사용자 파일 시스템 권한으로 파드 초기화 컨테이너(init-cgroups) 액세스. Gitaly 컨테이너(사용자 git, UID 1000)에 파드 cgroup을 위임하는 데 사용됩니다.
  • cgroups 파일 시스템이 nsdelegate 플래그로 마운트되지 않아야 합니다. 자세한 내용은 Gitaly 이슈 6480을 참조하세요.

가이드#

Kubernetes에서 Gitaly를 실행할 때 다음을 수행해야 합니다:

containerd에서 cgroup_writable 필드 활성화#

Gitaly의 Cgroup 지원에는 권한 없는 컨테이너에 대한 cgroups 쓰기 액세스가 필요합니다. containerd v2.1.0은 cgroup_writable 구성 옵션을 도입했습니다. 활성화하면 이 옵션은 cgroups 파일 시스템이 읽기/쓰기 권한으로 마운트되도록 합니다.

이 필드를 활성화하려면 Gitaly를 배포할 노드에서 다음 단계를 수행하세요. Gitaly가 이미 배포된 경우 구성을 수정한 후 파드를 다시 생성해야 합니다.

  1. /etc/containerd/config.toml에 있는 containerd 구성 파일을 수정하여 cgroup_writable 필드를 포함시킵니다:

    [plugins."io.containerd.grpc.v1.cri".containerd.runtimes.runc]
runtime_type = "io.containerd.runc.v2"
cgroup_writable = true

  2. Kubelet 및 containerd 서비스를 재시작합니다:

    sudo systemctl restart kubelet
sudo systemctl restart containerd

    서비스를 재시작하는 데 오랜 시간이 걸리면 이 명령으로 인해 노드가 NotReady로 표시될 수 있습니다.

파드 중단 처리#

파드는 여러 이유로 교체될 수 있습니다. 서비스 라이프사이클을 이해하고 계획하면 중단을 최소화할 수 있습니다.

예를 들어 Gitaly의 경우, Kubernetes StatefulSet은 spec.template 객체 변경 시 교체되며 이는 Helm Chart 업그레이드(레이블 또는 이미지 태그) 또는 파드 리소스 요청이나 제한 업데이트 중에 발생할 수 있습니다.

이 섹션은 일반적인 파드 중단 사례와 처리 방법에 중점을 둡니다.

유지 관리 창 예약#

서비스가 고가용성이 아니므로 특정 작업이 짧은 서비스 중단을 유발할 수 있습니다. 유지 관리 창을 예약하면 잠재적인 서비스 중단 신호를 보내고 기대치를 설정하는 데 도움이 됩니다. 다음의 경우 유지 관리 창을 사용해야 합니다:

  • GitLab Helm 차트 업그레이드 및 재구성.
  • Gitaly 구성 변경.
  • Kubernetes 노드 유지 관리 창. 예: 업그레이드 및 패치. Gitaly를 전용 노드 풀로 격리하면 도움이 될 수 있습니다.

PriorityClass 사용#

PriorityClass를 사용하여 Gitaly 파드에 다른 파드보다 높은 우선순위를 할당하여 노드 포화 압박, 퇴출 우선순위, 스케줄링 지연에 도움을 줍니다:

  1. 우선순위 클래스를 생성합니다:

    apiVersion: scheduling.k8s.io/v1
kind: PriorityClass
metadata:
  name: gitlab-gitaly
value: 1000000
globalDefault: false
description: "GitLab Gitaly priority class"

  2. 우선순위 클래스를 Gitaly 파드에 할당합니다:

    gitlab:
  gitaly:
    priorityClassName: gitlab-gitaly

퇴출 방지를 위한 노드 자동 스케일링 신호#

노드 자동 스케일링 도구는 파드를 스케줄하고 비용을 최적화하기 위해 필요에 따라 Kubernetes 노드를 추가하고 제거합니다.

축소 이벤트 중에 Gitaly 파드가 리소스 사용을 최적화하기 위해 퇴출될 수 있습니다. 이 동작을 제어하고 워크로드를 제외하기 위한 어노테이션이 일반적으로 제공됩니다. 예를 들어 Cluster Autoscaler 사용 시:

gitlab:
  gitaly:
    annotations:
      cluster-autoscaler.kubernetes.io/safe-to-evict: "false"

리소스 경합 및 포화 처리#

Gitaly 서비스 리소스 사용량은 Git 작업의 불확정적인 특성으로 인해 예측할 수 없습니다. 모든 저장소가 같지 않으며 크기는 특히 모노레포의 경우 성능과 리소스 사용량에 크게 영향을 미칩니다.

Kubernetes에서 제어되지 않는 리소스 사용량은 OOM(Out Of Memory) 이벤트를 유발하여 플랫폼이 파드를 종료하고 모든 프로세스를 종료하도록 강제할 수 있습니다. 파드 종료는 두 가지 중요한 문제를 제기합니다:

  • 데이터/저장소 손상
  • 서비스 중단

이 섹션은 영향 범위를 줄이고 전체적으로 서비스를 보호하는 데 중점을 둡니다.

Git 프로세스 리소스 사용량 제한#

Git 프로세스를 격리하면 단일 Git 호출이 모든 서비스 및 파드 리소스를 소비하지 않도록 보장하는 안전성을 제공합니다.

Gitaly는 Linux 컨트롤 그룹(cgroups)을 사용하여 리소스 사용량에 대한 더 작은 저장소별 할당량을 부과할 수 있습니다.

cgroup 할당량을 전체 파드 리소스 할당량 이하로 유지해야 합니다. CPU는 서비스를 느리게 할 뿐이므로 중요하지 않습니다. 그러나 메모리 포화는 파드 종료로 이어질 수 있습니다. 파드 요청과 Git cgroup 할당 사이에 1 GiB 메모리 버퍼는 안전한 시작점입니다. 버퍼 크기는 트래픽 패턴과 저장소 데이터에 따라 다릅니다.

예를 들어, 파드 메모리 요청이 15 GiB인 경우 14 GiB가 Git 호출에 할당됩니다:

gitlab:
  gitaly:
    cgroups:
      enabled: true
      # 모든 저장소 cgroups에 걸친 총 제한, Gitaly 프로세스 제외
      memoryBytes: 15032385536 # 14GiB
      cpuShares: 1024
      cpuQuotaUs: 400000 # 4 cores
      # 저장소당 제한, 50 저장소 cgroups
      repositories:
        count: 50
        memoryBytes: 7516192768 # 7GiB
        cpuShares: 512
        cpuQuotaUs: 200000 # 2 cores

자세한 내용은 Gitaly 구성 문서를 참조하세요.

파드 리소스 적절한 크기 설정#

Gitaly 파드의 크기를 정하는 것은 중요하며 참조 아키텍처는 시작점으로 몇 가지 지침을 제공합니다. 그러나 저장소와 사용 패턴이 다르면 리소스 소비가 다양합니다. 리소스 사용량을 모니터링하고 시간이 지남에 따라 조정해야 합니다.

메모리는 Kubernetes에서 가장 민감한 리소스입니다. 메모리 부족이 파드 종료를 트리거할 수 있기 때문입니다. cgroups로 Git 호출 격리는 저장소 작업에 대한 리소스 사용량을 제한하는 데 도움이 되지만 Gitaly 서비스 자체는 포함하지 않습니다. 이전의 cgroup 할당량 권장 사항에 따라 전체 Git cgroup 메모리 할당과 파드 메모리 요청 사이에 버퍼를 추가하여 안전성을 향상시키세요.

파드 Guaranteed 서비스 품질 클래스가 선호됩니다(리소스 요청이 제한과 일치). 이 설정을 사용하면 파드가 리소스 경합에 덜 취약하고 다른 파드의 소비를 기반으로 퇴출되지 않도록 보장됩니다.

리소스 구성 예시:

gitlab:
  gitaly:
    resources:
      requests:
        cpu: 4000m
        memory: 15Gi
      limits:
        cpu: 4000m
        memory: 15Gi

    init:
      resources:
        requests:
          cpu: 50m
          memory: 32Mi
        limits:
          cpu: 50m
          memory: 32Mi

동시성 제한 구성#

동시성 제한을 사용하여 비정상적인 트래픽 패턴으로부터 서비스를 보호할 수 있습니다. 자세한 내용은 동시성 구성 문서와 제한 모니터링 방법을 참조하세요.

Gitaly 파드 격리#

여러 Gitaly 파드를 실행할 때 장애 도메인을 분산시키기 위해 다른 노드에 스케줄해야 합니다. 이는 파드 안티 어피니티를 사용하여 강제할 수 있습니다. 예를 들어:

gitlab:
  gitaly:
    antiAffinity: hard

파드 교체 시간 최적화#

이 섹션은 유지 관리 이벤트 또는 계획되지 않은 인프라 이벤트 중 파드가 트래픽을 제공하기 시작하는 데 걸리는 시간을 줄여 다운타임을 줄이기 위한 최적화 영역을 다룹니다.

영구 볼륨 권한#

데이터 크기가 증가함에 따라(Git 히스토리 및 더 많은 저장소) 파드를 시작하고 준비하는 데 점점 더 많은 시간이 걸립니다.

파드 초기화 중에 영구 볼륨 마운트의 일부로 파일 시스템 권한과 소유권이 컨테이너 uid 및 gid로 명시적으로 설정됩니다. 이 작업은 기본적으로 실행되며, 저장된 Git 데이터에는 많은 작은 파일이 포함되어 있기 때문에 파드 시작 시간을 크게 늦출 수 있습니다.

이 동작은 fsGroupChangePolicy 속성으로 구성할 수 있습니다. 볼륨 루트 uid 또는 gid가 컨테이너 스펙과 일치하지 않는 경우에만 작업을 수행하려면 이 속성을 사용하세요:

gitlab:
  gitaly:
    securityContext:
      fsGroupChangePolicy: OnRootMismatch

헬스 프로브#

Gitaly 파드는 준비 프로브가 성공한 후 트래픽을 제공하기 시작합니다. 기본 프로브 시간은 대부분의 사용 사례를 커버하기 위해 보수적입니다. readinessProbe initialDelaySeconds 속성을 줄이면 프로브가 더 일찍 트리거되어 파드 준비가 가속화됩니다. 예를 들어:

gitlab:
  gitaly:
    statefulset:
      readinessProbe:
        initialDelaySeconds: 2
        periodSeconds: 10
        timeoutSeconds: 3
        successThreshold: 1
        failureThreshold: 3

Gitaly 그레이스풀 종료 타임아웃#

기본적으로 종료 시 Gitaly는 진행 중인 요청을 완료하는 데 1분 타임아웃을 부여합니다. 처음에는 유익해 보이지만 이 타임아웃은:

  • 파드 교체를 느리게 합니다.
  • 종료 프로세스 중에 요청을 거부하여 가용성을 줄입니다.

컨테이너 기반 배포에서 더 좋은 접근 방식은 클라이언트 측 재시도 로직에 의존하는 것입니다. gracefulRestartTimeout 필드를 사용하여 타임아웃을 재구성할 수 있습니다. 예를 들어 1초의 그레이스풀 타임아웃을 부여하려면:

gitlab:
  gitaly:
    gracefulRestartTimeout: 1

디스크 사용량 모니터링#

로그 로테이션이 활성화되지 않은 경우 로그 파일 증가로 인해 스토리지 문제가 발생할 수 있으므로 장기 실행 Gitaly 컨테이너에 대한 디스크 사용량을 정기적으로 모니터링하세요.

Gitaly on Kubernetes로 마이그레이션#

비 Kubernetes Gitaly 노드에서 Gitaly on Kubernetes로 기존 저장소를 마이그레이션하려면:

  • Gitaly on Kubernetes 노드를 배포하고 GitLab Admin 영역에서 새 저장소 스토리지로 추가합니다. 마이그레이션이 진행되는 동안 이전 저장소 스토리지에 새 프로젝트가 생성되지 않도록 모든 새 저장소가 새 저장소 스토리지에 생성되도록 스토리지 가중치를 구성합니다.

  • 저장소 이동 API를 사용하여 기존 저장소를 새 스토리지로 이동합니다. GitLab 저장소는 프로젝트, 그룹, 스니펫에 연결될 수 있으며 각 유형에는 별도의 API가 있습니다. 전체 지침은 GitLab에서 관리하는 저장소 이동을 참조하세요.

이동 기간 동안 각 저장소는 읽기 전용으로 설정되며 이동이 완료될 때까지 쓰기가 불가능합니다.

Gitaly on Kubernetes

Tier: Free, Premium, Ultimate
Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
원문 보기
요약

Kubernetes에서 Gitaly를 실행하면 가용성 트레이드오프가 있으므로 프로덕션 환경을 계획할 때 이러한 트레이드오프를 고려하고 그에 맞게 기대치를 설정하세요. Gitaly on Kubernetes는 Gitaly 팀에 의해 평가되어 Gitaly를 배포하는 안전한 방법으로 결정되었습니다.

히스토리
  • GitLab 17.3에서 실험적 기능으로 도입되었습니다.
  • GitLab 17.10에서 실험적 기능에서 베타로 변경되었습니다.
  • GitLab 18.2에서 베타에서 제한적 가용성으로 변경되었습니다.
  • GitLab 18.11에서 제한적 가용성에서 일반 가용성으로 변경되었습니다.

Kubernetes에서 Gitaly를 실행하면 가용성 트레이드오프가 있으므로 프로덕션 환경을 계획할 때 이러한 트레이드오프를 고려하고 그에 맞게 기대치를 설정하세요. 이 문서는 기존 제한 사항을 최소화하고 계획하는 방법에 대한 지침을 설명합니다.

Gitaly on Kubernetes는 Gitaly 팀에 의해 평가되어 Gitaly를 배포하는 안전한 방법으로 결정되었습니다. 이 문서의 나머지 부분에서는 이를 위한 모범 사례를 자세히 설명합니다.

타임라인#

Gitaly on Kubernetes는 GitLab 18.11부터 일반 가용성(GA)입니다. GitLab은 클라우드 공급자의 특정 관리형 Kubernetes 오퍼링(예: Amazon EKS, Google GKE, Azure AKS)과의 호환성을 보장하지 않습니다. 프로덕션 환경에 배포하기 전에 특정 환경을 검증해야 합니다.

배경#

설계상 Gitaly(비 클러스터)는 단일 장애 지점(SPoF) 서비스입니다. 데이터는 단일 인스턴스에서 소싱되고 제공됩니다. Kubernetes의 경우 StatefulSet 파드가 교체되면(예: 업그레이드, 노드 유지 관리 또는 퇴출 중) 파드 또는 인스턴스가 제공하는 데이터에 대한 서비스 중단이 발생합니다.

Cloud Native Hybrid 설정(Gitaly VM)에서 Linux 패키지(Omnibus)는 다음을 통해 문제를 마스킹합니다:

  1. 인플레이스 Gitaly 바이너리 업그레이드.
  2. 그레이스풀 리로드 수행.

컨테이너 또는 파드가 완전히 종료되고 새 컨테이너 또는 파드로 시작해야 하는 컨테이너 기반 라이프사이클에는 동일한 접근 방식이 적합하지 않습니다.

Gitaly Cluster(Praefect)는 인스턴스 간 데이터를 복제하여 데이터 및 서비스 고가용성 측면을 해결합니다. 그러나 Gitaly Cluster(Praefect)는 컨테이너 기반 플랫폼에 의해 증폭되는 기존 문제 및 설계 제약 때문에 Kubernetes에서 실행하기에 적합하지 않습니다.

Cloud Native 배포를 지원하기 위해 Gitaly(비 클러스터)만 옵션입니다. 올바른 Kubernetes 및 Gitaly 기능과 구성을 활용하여 서비스 중단을 최소화하고 좋은 사용자 경험을 제공할 수 있습니다.

요구 사항#

이 페이지의 정보는 다음을 가정합니다:

  • Kubernetes 버전 1.29 이상.
  • Kubernetes 노드 runc 버전 1.1.9 이상.
  • Kubernetes 노드 cgroup v2. 네이티브, 하이브리드 v1 모드는 지원되지 않습니다. systemd 스타일 cgroup 구조만 지원됩니다(Kubernetes 기본값).
  • 노드 마운트 포인트 /sys/fs/cgroup에 대한 파드 액세스.
  • containerd 버전 2.1.0 이상.
  • /sys/fs/cgroup에 대한 root 사용자 파일 시스템 권한으로 파드 초기화 컨테이너(init-cgroups) 액세스. Gitaly 컨테이너(사용자 git, UID 1000)에 파드 cgroup을 위임하는 데 사용됩니다.
  • cgroups 파일 시스템이 nsdelegate 플래그로 마운트되지 않아야 합니다. 자세한 내용은 Gitaly 이슈 6480을 참조하세요.

가이드#

Kubernetes에서 Gitaly를 실행할 때 다음을 수행해야 합니다:

containerd에서 cgroup_writable 필드 활성화#

Gitaly의 Cgroup 지원에는 권한 없는 컨테이너에 대한 cgroups 쓰기 액세스가 필요합니다. containerd v2.1.0은 cgroup_writable 구성 옵션을 도입했습니다. 활성화하면 이 옵션은 cgroups 파일 시스템이 읽기/쓰기 권한으로 마운트되도록 합니다.

이 필드를 활성화하려면 Gitaly를 배포할 노드에서 다음 단계를 수행하세요. Gitaly가 이미 배포된 경우 구성을 수정한 후 파드를 다시 생성해야 합니다.

  1. /etc/containerd/config.toml에 있는 containerd 구성 파일을 수정하여 cgroup_writable 필드를 포함시킵니다:

    [plugins."io.containerd.grpc.v1.cri".containerd.runtimes.runc]
runtime_type = "io.containerd.runc.v2"
cgroup_writable = true

  2. Kubelet 및 containerd 서비스를 재시작합니다:

    sudo systemctl restart kubelet
sudo systemctl restart containerd

    서비스를 재시작하는 데 오랜 시간이 걸리면 이 명령으로 인해 노드가 NotReady로 표시될 수 있습니다.

파드 중단 처리#

파드는 여러 이유로 교체될 수 있습니다. 서비스 라이프사이클을 이해하고 계획하면 중단을 최소화할 수 있습니다.

예를 들어 Gitaly의 경우, Kubernetes StatefulSet은 spec.template 객체 변경 시 교체되며 이는 Helm Chart 업그레이드(레이블 또는 이미지 태그) 또는 파드 리소스 요청이나 제한 업데이트 중에 발생할 수 있습니다.

이 섹션은 일반적인 파드 중단 사례와 처리 방법에 중점을 둡니다.

유지 관리 창 예약#

서비스가 고가용성이 아니므로 특정 작업이 짧은 서비스 중단을 유발할 수 있습니다. 유지 관리 창을 예약하면 잠재적인 서비스 중단 신호를 보내고 기대치를 설정하는 데 도움이 됩니다. 다음의 경우 유지 관리 창을 사용해야 합니다:

  • GitLab Helm 차트 업그레이드 및 재구성.
  • Gitaly 구성 변경.
  • Kubernetes 노드 유지 관리 창. 예: 업그레이드 및 패치. Gitaly를 전용 노드 풀로 격리하면 도움이 될 수 있습니다.

PriorityClass 사용#

PriorityClass를 사용하여 Gitaly 파드에 다른 파드보다 높은 우선순위를 할당하여 노드 포화 압박, 퇴출 우선순위, 스케줄링 지연에 도움을 줍니다:

  1. 우선순위 클래스를 생성합니다:

    apiVersion: scheduling.k8s.io/v1
kind: PriorityClass
metadata:
  name: gitlab-gitaly
value: 1000000
globalDefault: false
description: "GitLab Gitaly priority class"

  2. 우선순위 클래스를 Gitaly 파드에 할당합니다:

    gitlab:
  gitaly:
    priorityClassName: gitlab-gitaly

퇴출 방지를 위한 노드 자동 스케일링 신호#

노드 자동 스케일링 도구는 파드를 스케줄하고 비용을 최적화하기 위해 필요에 따라 Kubernetes 노드를 추가하고 제거합니다.

축소 이벤트 중에 Gitaly 파드가 리소스 사용을 최적화하기 위해 퇴출될 수 있습니다. 이 동작을 제어하고 워크로드를 제외하기 위한 어노테이션이 일반적으로 제공됩니다. 예를 들어 Cluster Autoscaler 사용 시:

gitlab:
  gitaly:
    annotations:
      cluster-autoscaler.kubernetes.io/safe-to-evict: "false"

리소스 경합 및 포화 처리#

Gitaly 서비스 리소스 사용량은 Git 작업의 불확정적인 특성으로 인해 예측할 수 없습니다. 모든 저장소가 같지 않으며 크기는 특히 모노레포의 경우 성능과 리소스 사용량에 크게 영향을 미칩니다.

Kubernetes에서 제어되지 않는 리소스 사용량은 OOM(Out Of Memory) 이벤트를 유발하여 플랫폼이 파드를 종료하고 모든 프로세스를 종료하도록 강제할 수 있습니다. 파드 종료는 두 가지 중요한 문제를 제기합니다:

  • 데이터/저장소 손상
  • 서비스 중단

이 섹션은 영향 범위를 줄이고 전체적으로 서비스를 보호하는 데 중점을 둡니다.

Git 프로세스 리소스 사용량 제한#

Git 프로세스를 격리하면 단일 Git 호출이 모든 서비스 및 파드 리소스를 소비하지 않도록 보장하는 안전성을 제공합니다.

Gitaly는 Linux 컨트롤 그룹(cgroups)을 사용하여 리소스 사용량에 대한 더 작은 저장소별 할당량을 부과할 수 있습니다.

cgroup 할당량을 전체 파드 리소스 할당량 이하로 유지해야 합니다. CPU는 서비스를 느리게 할 뿐이므로 중요하지 않습니다. 그러나 메모리 포화는 파드 종료로 이어질 수 있습니다. 파드 요청과 Git cgroup 할당 사이에 1 GiB 메모리 버퍼는 안전한 시작점입니다. 버퍼 크기는 트래픽 패턴과 저장소 데이터에 따라 다릅니다.

예를 들어, 파드 메모리 요청이 15 GiB인 경우 14 GiB가 Git 호출에 할당됩니다:

gitlab:
  gitaly:
    cgroups:
      enabled: true
      # 모든 저장소 cgroups에 걸친 총 제한, Gitaly 프로세스 제외
      memoryBytes: 15032385536 # 14GiB
      cpuShares: 1024
      cpuQuotaUs: 400000 # 4 cores
      # 저장소당 제한, 50 저장소 cgroups
      repositories:
        count: 50
        memoryBytes: 7516192768 # 7GiB
        cpuShares: 512
        cpuQuotaUs: 200000 # 2 cores

자세한 내용은 Gitaly 구성 문서를 참조하세요.

파드 리소스 적절한 크기 설정#

Gitaly 파드의 크기를 정하는 것은 중요하며 참조 아키텍처는 시작점으로 몇 가지 지침을 제공합니다. 그러나 저장소와 사용 패턴이 다르면 리소스 소비가 다양합니다. 리소스 사용량을 모니터링하고 시간이 지남에 따라 조정해야 합니다.

메모리는 Kubernetes에서 가장 민감한 리소스입니다. 메모리 부족이 파드 종료를 트리거할 수 있기 때문입니다. cgroups로 Git 호출 격리는 저장소 작업에 대한 리소스 사용량을 제한하는 데 도움이 되지만 Gitaly 서비스 자체는 포함하지 않습니다. 이전의 cgroup 할당량 권장 사항에 따라 전체 Git cgroup 메모리 할당과 파드 메모리 요청 사이에 버퍼를 추가하여 안전성을 향상시키세요.

파드 Guaranteed 서비스 품질 클래스가 선호됩니다(리소스 요청이 제한과 일치). 이 설정을 사용하면 파드가 리소스 경합에 덜 취약하고 다른 파드의 소비를 기반으로 퇴출되지 않도록 보장됩니다.

리소스 구성 예시:

gitlab:
  gitaly:
    resources:
      requests:
        cpu: 4000m
        memory: 15Gi
      limits:
        cpu: 4000m
        memory: 15Gi

    init:
      resources:
        requests:
          cpu: 50m
          memory: 32Mi
        limits:
          cpu: 50m
          memory: 32Mi

동시성 제한 구성#

동시성 제한을 사용하여 비정상적인 트래픽 패턴으로부터 서비스를 보호할 수 있습니다. 자세한 내용은 동시성 구성 문서와 제한 모니터링 방법을 참조하세요.

Gitaly 파드 격리#

여러 Gitaly 파드를 실행할 때 장애 도메인을 분산시키기 위해 다른 노드에 스케줄해야 합니다. 이는 파드 안티 어피니티를 사용하여 강제할 수 있습니다. 예를 들어:

gitlab:
  gitaly:
    antiAffinity: hard

파드 교체 시간 최적화#

이 섹션은 유지 관리 이벤트 또는 계획되지 않은 인프라 이벤트 중 파드가 트래픽을 제공하기 시작하는 데 걸리는 시간을 줄여 다운타임을 줄이기 위한 최적화 영역을 다룹니다.

영구 볼륨 권한#

데이터 크기가 증가함에 따라(Git 히스토리 및 더 많은 저장소) 파드를 시작하고 준비하는 데 점점 더 많은 시간이 걸립니다.

파드 초기화 중에 영구 볼륨 마운트의 일부로 파일 시스템 권한과 소유권이 컨테이너 uid 및 gid로 명시적으로 설정됩니다. 이 작업은 기본적으로 실행되며, 저장된 Git 데이터에는 많은 작은 파일이 포함되어 있기 때문에 파드 시작 시간을 크게 늦출 수 있습니다.

이 동작은 fsGroupChangePolicy 속성으로 구성할 수 있습니다. 볼륨 루트 uid 또는 gid가 컨테이너 스펙과 일치하지 않는 경우에만 작업을 수행하려면 이 속성을 사용하세요:

gitlab:
  gitaly:
    securityContext:
      fsGroupChangePolicy: OnRootMismatch

헬스 프로브#

Gitaly 파드는 준비 프로브가 성공한 후 트래픽을 제공하기 시작합니다. 기본 프로브 시간은 대부분의 사용 사례를 커버하기 위해 보수적입니다. readinessProbe initialDelaySeconds 속성을 줄이면 프로브가 더 일찍 트리거되어 파드 준비가 가속화됩니다. 예를 들어:

gitlab:
  gitaly:
    statefulset:
      readinessProbe:
        initialDelaySeconds: 2
        periodSeconds: 10
        timeoutSeconds: 3
        successThreshold: 1
        failureThreshold: 3

Gitaly 그레이스풀 종료 타임아웃#

기본적으로 종료 시 Gitaly는 진행 중인 요청을 완료하는 데 1분 타임아웃을 부여합니다. 처음에는 유익해 보이지만 이 타임아웃은:

  • 파드 교체를 느리게 합니다.
  • 종료 프로세스 중에 요청을 거부하여 가용성을 줄입니다.

컨테이너 기반 배포에서 더 좋은 접근 방식은 클라이언트 측 재시도 로직에 의존하는 것입니다. gracefulRestartTimeout 필드를 사용하여 타임아웃을 재구성할 수 있습니다. 예를 들어 1초의 그레이스풀 타임아웃을 부여하려면:

gitlab:
  gitaly:
    gracefulRestartTimeout: 1

디스크 사용량 모니터링#

로그 로테이션이 활성화되지 않은 경우 로그 파일 증가로 인해 스토리지 문제가 발생할 수 있으므로 장기 실행 Gitaly 컨테이너에 대한 디스크 사용량을 정기적으로 모니터링하세요.

Gitaly on Kubernetes로 마이그레이션#

비 Kubernetes Gitaly 노드에서 Gitaly on Kubernetes로 기존 저장소를 마이그레이션하려면:

  • Gitaly on Kubernetes 노드를 배포하고 GitLab Admin 영역에서 새 저장소 스토리지로 추가합니다. 마이그레이션이 진행되는 동안 이전 저장소 스토리지에 새 프로젝트가 생성되지 않도록 모든 새 저장소가 새 저장소 스토리지에 생성되도록 스토리지 가중치를 구성합니다.

  • 저장소 이동 API를 사용하여 기존 저장소를 새 스토리지로 이동합니다. GitLab 저장소는 프로젝트, 그룹, 스니펫에 연결될 수 있으며 각 유형에는 별도의 API가 있습니다. 전체 지침은 GitLab에서 관리하는 저장소 이동을 참조하세요.

이동 기간 동안 각 저장소는 읽기 전용으로 설정되며 이동이 완료될 때까지 쓰기가 불가능합니다.