보조 사이트의 컨테이너 레지스트리

Tier: Premium, Ultimate

Offering: Self-managed

당신은 기본 Geo 사이트의 컨테이너 레지스트리를 미러링하는 보조 Geo 사이트에서 컨테이너 레지스트리를 설정할 수 있습니다.

note
컨테이너 레지스트리 복제는 재해 복구 목적으로만 사용됩니다. 우리는 보조 사이트에서 컨테이너 레지스트리 데이터를 가져오는 것을 권장하지 않습니다. 향후 이를 구현하기 위한 기능 제안에 대한 자세한 내용은 Geo: 보조 사이트에서 읽기 요청을 제공하여 컨테이너 이미지를 가속화하기를 참조하세요. 귀하 또는 귀하의 GitLab 담당자가 이 기능에 대한 관심을 등록하기 위해 찬성 투표를 하시는 것이 좋습니다.

지원되는 컨테이너 레지스트리

Geo는 다음 유형의 컨테이너 레지스트리를 지원합니다:

지원되는 이미지 형식

Geo에서 지원하는 컨테이너 이미지 형식은 다음과 같습니다:

또한, Geo는 BuildKit 캐시 이미지도 지원합니다.

지원되는 스토리지

Docker

지원되는 레지스트리 스토리지 드라이버에 대한 자세한 정보는 Docker 레지스트리 스토리지 드라이버를 참조하세요.

Registry를 배포할 때 로드 밸런싱 고려사항과 GitLab 통합 컨테이너 레지스트리의 스토리지 드라이버 설정 방법에 대해 알아보세요.

OCI 아티팩트를 지원하는 레지스트리

다음 레지스트리에서 OCI 아티팩트를 지원합니다:

  • CNCF Distribution - 로컬/오프라인 검증
  • Azure Container Registry (ACR)
  • Amazon Elastic Container Registry (ECR)
  • Google Artifact Registry (GAR)
  • GitHub Packages 컨테이너 레지스트리 (GHCR)
  • Bundle Bar

자세한 내용은 OCI Distribution Specification를 참조하세요.

컨테이너 레지스트리 복제 구성

스토리지에 독립적인 복제를 활성화할 수 있어 클라우드 또는 로컬 스토리지에 사용될 수 있습니다. 새로운 이미지가 기본 사이트에 푸시될 때마다 각 보조 사이트는 자신의 컨테이너 리포지토리로 이를 가져옵니다.

컨테이너 레지스트리 복제를 구성하려면:

  1. 기본 사이트를 구성합니다.
  2. 보조 사이트를 구성합니다.
  3. 컨테이너 레지스트리 복제 확인을 합니다.

기본 사이트 구성

다음 단계를 진행하기 전에 기본 사이트에서 컨테이너 레지스트리가 설정되고 작동 중인지 확인하세요.

새로운 컨테이너 이미지를 복제할 수 있으려면 컨테이너 레지스트리는 매 푸시마다 기본 사이트에 알림 이벤트를 전송해야 합니다. 컨테이너 레지스트리와 기본의 웹 노드 간에 공유되는 토큰은 통신을 더 안전하게 만드는 데 사용됩니다.

  1. GitLab 기본 서버에 SSH로 로그인하고 root로 로그인합니다( GitLab HA의 경우 Registry 노드만 필요합니다):

    sudo -i

  2. /etc/gitlab/gitlab.rb를 편집합니다:

    registry['notifications'] = [
  {
    'name' => 'geo_event',
    'url' => 'https://<example.com>/api/v4/container_registry_event/events',
    'timeout' => '500ms',
    'threshold' => 5,
    'backoff' => '1s',
    'headers' => {
      'Authorization' => ['<replace_with_a_secret_token>']
    }
  }
]
    note
    <example.com>를 기본 사이트의 /etc/gitlab/gitlab.rb 파일에 정의된 external_url로 바꾸고,
    <replace_with_a_secret_token>을 문자로 시작하는 대소문자 구분 알파벳 숫자 문자열로 바꾸세요.
    < /dev/urandom tr -dc _A-Z-a-z-0-9 | head -c 32 | sed "s/^[0-9]*//"; echo를 사용하여 생성할 수 있습니다.
    note
    GitLab과 통합되지 않은 외부 Registry를 사용하는 경우, /etc/gitlab/gitlab.rb 파일에
    알림 비밀(registry['notification_secret'])만 지정하면 됩니다.

  3. GitLab HA의 경우. 모든 웹 노드에서 /etc/gitlab/gitlab.rb를 편집합니다:

    registry['notification_secret'] = '<replace_with_a_secret_token_generated_above>'

  4. 업데이트한 각 노드를 재구성합니다:

    gitlab-ctl reconfigure

보조 사이트 구성

다음 단계를 따르기 전에 보조 사이트에 컨테이너 레지스트리가 설정되고 작동하는지 확인하세요.

다음 단계는 컨테이너 이미지가 복제될 것으로 예상되는 각 보조 사이트에서 수행되어야 합니다.

보조 사이트가 기본 사이트 컨테이너 레지스트리와 안전하게 통신할 수 있도록 하려면, 모든 사이트에 대해 단일 키 쌍이 필요합니다. 보조 사이트는 이 키를 사용하여 기본 사이트 컨테이너 레지스트리에 접근할 수 있는 짧은 수명의 JWT를 생성합니다.

보조 사이트의 각 애플리케이션 및 Sidekiq 노드에 대해:

  1. 노드에 SSH로 접속하고 root 사용자로 로그인합니다:

    sudo -i

  2. /var/opt/gitlab/gitlab-rails/etc/gitlab-registry.key를 기본 사이트에서 노드로 복사합니다.

  3. /etc/gitlab/gitlab.rb를 편집하고 다음을 추가합니다:

    gitlab_rails['geo_registry_replication_enabled'] = true

# 기본 레지스트리의 호스트네임 및 포트, 이는
# 보조 노드가 기본 레지스트리에 직접 통신하는 데 사용됩니다
gitlab_rails['geo_registry_replication_primary_api_url'] = 'https://primary.example.com:5050/'

  4. 변경 사항이 적용되도록 노드를 재구성합니다:

    gitlab-ctl reconfigure

복제 확인

보조 사이트에서 컨테이너 레지스트리 복제가 작동하는지 확인하려면:

  1. 왼쪽 사이드바에서 하단의 관리자를 선택합니다.
  2. Geo > Nodes를 선택합니다.

초기 복제 또는 “백필”은 아직 진행 중일 수 있습니다.

기본 사이트의 Geo Nodes 대시보드에서 각 Geo 사이트의 동기화 프로세스를 모니터링할 수 있습니다.

문제 해결

컨테이너 레지스트리 복제가 활성화되었는지 확인

이는 Rails 콘솔을 사용하여 확인할 수 있습니다:

Geo::ContainerRepositoryRegistry.replication_enabled?

컨테이너 레지스트리 알림 이벤트 누락

  1. 이미지가 기본 사이트의 컨테이너 레지스트리에 푸시되면 컨테이너 레지스트리 알림을 트리거해야 합니다.
  2. 기본 사이트의 컨테이너 레지스트리는 https://<example.com>/api/v4/container_registry_event/events에서 기본 사이트의 API를 호출합니다.
  3. 기본 사이트는 geo_events 테이블에 replicable_name: 'container_repository', model_record_id: <컨테이너 레포지토리의 ID>로 레코드를 삽입합니다.
  4. 이 레코드는 PostgreSQL에 의해 보조 사이트의 데이터베이스로 복제됩니다.
  5. Geo Log Cursor 서비스가 새 이벤트를 처리하고 Sidekiq 작업 Geo::EventWorker를 대기열에 추가합니다.

이것이 올바르게 작동하는지 확인하려면, 기본 사이트의 레지스트리에 이미지를 푸시하고 다음 명령어를 Rails 콘솔에서 실행하여 알림이 수신되었고 이벤트로 처리되었는지 확인합니다:

Geo::Event.where(replicable_name: 'container_repository')

이것을 further 확인하기 위해 geo.log에서 Geo::ContainerRepositorySyncService의 항목을 확인할 수 있습니다.

레지스트리 이벤트 로그 응답 상태 401 Unauthorized

401 Unauthorized 오류는 기본 사이트의 컨테이너 레지스트리 알림이 Rails 애플리케이션에 의해 수용되지 않음을 나타내며, 이는 GitLab에 무언가가 푸시되었다는 알림을 방지합니다.

이를 수정하려면, 레지스트리 알림과 함께 전송되는 권한 부여 헤더가 기본 사이트에 구성된 것과 일치하는지 확인해야 합니다. 이는 기본 사이트 구성 단계에서 수행되어야 합니다.

레지스트리 오류: 신뢰할 수 없는 발급자의 토큰: "<token>"

컨테이너 이미지를 복제하기 위해, Sidekiq는 JWT를 사용하여 컨테이너 레지스트리에 인증합니다. Geo 복제를 위해서는 컨테이너 레지스트리 구성이 올바르게 이루어져야 합니다.

두 사이트가 보조 사이트 구성에서 지시한 대로 단일 서명 키 쌍을 공유하고, 모든 컨테이너 레지스트리와 기본 및 보조 사이트가 같은 토큰 발급자를 사용하도록 구성되어 있는지 확인하십시오.

다중 노드 배포의 경우, Sidekiq 노드에 구성된 발급자와 레지스트리에 구성된 값이 일치하는지 확인해야 합니다.

수동으로 컨테이너 레지스트리 동기화 이벤트 트리거

문제 해결을 돕기 위해, 수동으로 컨테이너 레지스트리 복제 프로세스를 트리거할 수 있습니다:

  1. 왼쪽 사이드바에서 하단의 관리자를 선택합니다.

  2. Geo > 사이트를 선택합니다.

  3. 보조 사이트의 복제 세부정보에서 컨테이너 리포지토리를 선택합니다.

  4. 한 행에 대해 재동기화를 선택하거나 모두 재동기화를 선택합니다.

또한, 보조의 Rails 콘솔에서 다음 명령을 실행하여 수동으로 재동기화를 트리거할 수 있습니다:

registry = Geo::ContainerRepositoryRegistry.first # Geo 레지스트리 항목 선택
registry.replicator.sync # 컨테이너 리포지토리 재동기화
pp registry.reload # 복제 상태 필드 확인

#<Geo::ContainerRepositoryRegistry:0x00007f54c2a36060
 id: 1,
 container_repository_id: 1,
 state: "2",
 retry_count: 0,
 last_sync_failure: nil,
 retry_at: nil,
 last_synced_at: Thu, 28 Sep 2023 19:38:05.823680000 UTC +00:00,
 created_at: Mon, 11 Sep 2023 15:38:06.262490000 UTC +00:00>

state 필드는 동기화 상태를 나타냅니다:

  • "0": 대기 중인 동기화 (보통 동기화된 적이 없음을 의미)
  • "1": 동기화 시작 (현재 동기화 작업이 진행 중임)
  • "2": 성공적으로 동기화됨
  • "3": 동기화 실패