기본 Geo 사이트의 컨테이너 이미지를 복제하는 보조 Geo 사이트에서 컨테이너 레지스트리를 설정할 수 있습니다. 이 컨테이너 이미지 복제는 재해 복구 목적으로만 사용됩니다.

데이터가 기본 사이트로 전파되지 않으므로 보조 Geo 사이트의 컨테이너 레지스트리에 push하지 마세요.

보조 사이트의 컨테이너 레지스트리 데이터가 오래될 수 있으므로 이 사이트에서 pull하는 것은 권장하지 않습니다. 기능 요청 이슈 365864가 이 문제를 해결할 예정입니다. 관심을 표명하기 위해 이슈에 투표하는 것을 권장합니다.

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

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

• Docker
• OCI

지원되는 이미지 형식#

다음 컨테이너 이미지 형식은 Geo에서 지원됩니다:

• Docker V2, schema 1
• Docker V2, schema 2
• OCI (Open Container Initiative)

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

지원되는 스토리지#

Docker#

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

레지스트리를 배포할 때 부하 분산 고려 사항을 읽고, GitLab 통합 컨테이너 레지스트리의 스토리지 드라이버 설정 방법을 알아보세요.

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

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

• CNCF Distribution - 로컬/오프라인 검증
• Azure Container Registry (ACR)
• Amazon Elastic Container Registry (ECR)
• Google Artifact Registry (GAR)
• GitHub Packages container registry (GHCR)
• Bundle Bar

자세한 내용은 OCI 배포 사양을 참조하세요.

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

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

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

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

기본 사이트 구성#

다음 단계를 따르기 전에 기본 사이트에서 컨테이너 레지스트리가 설정되어 작동하는지 확인합니다.

새 컨테이너 이미지를 복제할 수 있으려면 컨테이너 레지스트리가 모든 push에 대해 기본 사이트에 알림 이벤트를 보내야 합니다. 컨테이너 레지스트리와 기본 사이트의 웹 노드 간에 공유된 토큰은 통신을 더 안전하게 만드는 데 사용됩니다.

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

   sudo -i
   

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

   # Configure the registry to listen on the public/internal interface
   # Replace with the appropriate interface (for example, '0.0.0.0' for all interfaces)
   registry['registry_http_addr'] = '0.0.0.0:5000'
   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>']
       }
     }
   ]
   

   <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과 통합된 것이 아닌)를 사용하는 경우 /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
   

보조 사이트 구성#

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

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

보조 사이트가 기본 사이트 컨테이너 레지스트리와 안전하게 통신할 수 있도록 하려면 모든 사이트에 대한 단일 키 쌍이 필요합니다. 보조 사이트는 이 키를 사용하여 기본 사이트 컨테이너 레지스트리에 액세스하는 pull 전용의 단기 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
   
   # Primary registry's hostname and port, it will be used by
   # the secondary node to directly communicate to primary registry
   gitlab_rails['geo_registry_replication_primary_api_url'] = 'https://primary.example.com:5050/'
   

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

   gitlab-ctl reconfigure
   

복제 확인#

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

1. 오른쪽 상단 모서리에서 Admin을 선택합니다.
2. 왼쪽 사이드바에서 Geo > Nodes를 선택합니다. 초기 복제 또는 "백필"이 아직 진행 중일 수 있습니다.

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

문제 해결#

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

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

Geo::ContainerRepositoryRegistry.replication_enabled?

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

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

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

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

geo.log에서 Geo::ContainerRepositorySyncService의 항목을 확인하여 추가로 검증할 수 있습니다.

레지스트리 이벤트 로그 응답 상태 401 Unauthorized 미허용#

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

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

레지스트리 오류: token from untrusted issuer: "<token>"#

Geo에서 컨테이너 이미지를 복제할 때 token from untrusted issuer: "<token>" 오류가 표시될 수 있습니다.

이 문제는 컨테이너 레지스트리 구성이 잘못되어 Sidekiq의 JWT 인증이 실패하는 경우에 발생합니다.

이 문제를 해결하려면:

1. 보조 사이트 구성에 설명된 대로 두 사이트가 단일 서명 키 쌍을 공유하는지 확인합니다.
2. 두 컨테이너 레지스트리와 기본 및 보조 사이트 모두 동일한 토큰 발급자를 사용하도록 구성되어 있는지 확인합니다. 자세한 내용은 별도의 노드에서 GitLab 및 레지스트리 구성을 참조하세요.
3. 다중 노드 배포의 경우 Sidekiq 노드에 구성된 발급자가 레지스트리에 구성된 값과 일치하는지 확인합니다.

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

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

1. 오른쪽 상단 모서리에서 Admin을 선택합니다.
2. 왼쪽 사이드바에서 Geo > Sites를 선택합니다.
3. 보조 사이트의 Replication Details에서 Container Repositories를 선택합니다.
4. 한 행에 대해 Resync를 선택하거나 Resync all을 선택합니다.

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

registry = Geo::ContainerRepositoryRegistry.first # Choose a Geo registry entry
registry.replicator.sync # Resync the container repository
pp registry.reload # Look at replication state fields

#

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

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

다운타임 후 리포지토리가 재동기화되지 않음#

컨테이너 레지스트리 복제가 geo_container_repository_replication 기능 플래그 또는 잘못된 구성으로 인해 일정 기간 동안 비활성화된 경우, 해당 기간 동안 push된 이미지가 보조 사이트로 자동으로 동기화되지 않을 수 있습니다.

다운타임 중에 생성된 새 컨테이너 리포지토리는 복제가 재활성화된 후 백필 워커에 의해 자동으로 선택됩니다. 그러나 기존 컨테이너 리포지토리에 대한 업데이트 (예: 기존 리포지토리에 push된 새 태그)는 자동으로 재동기화되지 않습니다. Geo 관리 UI는 동기화 상태가 레지스트리 항목 상태를 기반으로 하고 콘텐츠 검증이 아니므로 여전히 100% 복제를 보고할 수 있습니다.

업데이트된 컨테이너 리포지토리는 기본 사이트 재검증 사이클이 체크섬 불일치를 감지한 후 결국 재동기화됩니다. 재검증 간격에 대한 자세한 내용은 리포지토리 재검증을 참조하세요.

재검증을 기다리는 대신 즉각적인 재동기화를 강제하려면 복제 또는 검증 수동 재시도를 참조하세요.