• 지원되는 컨테이너 레지스트리
• 지원되는 이미지 형식
• 지원되는 저장소
  • Docker
  • OCI 아티팩트를 지원하는 레지스트리
• 컨테이너 레지스트리 복제 구성
  • 주 사이트 구성
  • 보조 사이트 구성
  • 복제 확인
• 문제 해결
  • 컨테이너 레지스트리 복제 활성화 확인
  • 컨테이너 레지스트리 알림 이벤트 누락
  • 레지스트리 이벤트 로그 응답 상태 401 Unauthorized unaccepted
    • 레지스트리 오류: token from untrusted issuer: "<token>"
  • 컨테이너 레지스트리 동기화 이벤트 수동 트리거

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

주의: 컨테이너 레지스트리 복제는 재해 복구 목적으로만 사용됩니다. 우리는 보조 사이트에서 컨테이너 레지스트리 데이터를 가져오지 않는 것을 권장합니다. 향후 이를 구현하기 위한 기능 제안에 대해서는 세부 내용은 Geo: Accelerate container images by serving read request from secondary site를 참조하세요. 이 기능에 투표하여 귀사나 귀사의 GitLab 대표가 귀사의 흥미를 등록하도록 권장합니다.

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

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

• Docker
• OCI

지원되는 이미지 형식

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

• Docker V2, 스키마 1
• Docker V2, 스키마 2
• OCI (Open Container Initiative)

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

지원되는 저장소

Docker

지원되는 레지스트리 저장소 드라이버에 대한 자세한 내용은 Docker registry storage drivers를 참조하세요.

레지스트리를 배포할 때 로드 밸런싱 고려 사항 및 GitLab 통합 컨테이너 레지스트리의 저장소 드라이버 설정 방법을 확인하세요.

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

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

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

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

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

저장소에 구애받지 않는 복제를 활성화하여 클라우드 또는 로컬 저장소에 사용할 수 있습니다. 새 이미지가 주 사이트로 푸시될 때마다 각 보조 사이트는 각각의 컨테이너 레지스트리로 풀립니다.

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

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

주 사이트 구성

다음 단계를 따르기 전에 주 사이트에 컨테이너 레지스트리가 설정되어 있는지 확인하세요.

새 컨테이너 이미지를 복제하려면 컨테이너 레지스트리는 각 푸시마다 주 사이트에 알림 이벤트를 보내야 합니다. 주 사이트의 컨테이너 레지스트리와 웹 노드 간 통신을 더 안전하게 만들기 위해 공유되는 토큰이 사용됩니다.

1. GitLab 주 서버에 SSH로 로그인하고 root로 전환합니다 (GitLab HA의 경우, 레지스트리 노드만 필요합니다):

   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>']
       }
     }
   ]
   

   주의: <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를 사용하여 생성할 수 있습니다.

   주의: 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
   

보조 사이트 구성

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

다음 단계는 복제되는 컨테이너 이미지를 보여줄 예상 보조 사이트 각각에서 수행해야 합니다.

보조 사이트가 주 사이트의 컨테이너 레지스트리와 안전하게 통신할 수 있도록 하려면 모든 사이트에 대해 하나의 키 쌍이 있어야 합니다. 보조 사이트는 이 키를 사용하여 주 사이트 컨테이너 레지스트리에 액세스할 수 있는 풀 전용 토큰을 생성합니다.

각 보조 사이트의 애플리케이션 및 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 > 노드를 선택합니다. 초기 복제 또는 “백필”이 아직 진행 중일 수 있습니다.

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

문제 해결

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

Rails console을 사용하여 다음을 확인할 수 있습니다:

Geo::ContainerRepositoryRegistry.replication_enabled?

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

1. 주 사이트의 컨테이너 레지스트리에 이미지를 푸시하면 컨테이너 레지스트리 알림이 트리거되어야 합니다.
2. 주 사이트의 컨테이너 레지스트리는 주 사이트의 API를 호출합니다. https://<example.com>/api/v4/container_registry_event/events
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')

또한 Geo::ContainerRepositorySyncService 엔트리에서 geo.log를 확인하여 추가로 확인할 수 있습니다.

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

401 Unauthorized 오류는 주 사이트의 컨테이너 레지스트리 알림이 레일즈 애플리케이션에 의해 수락되지 않아 GitLab에게 푸시된 내용을 알리지 못한다는 것을 나타냅니다.

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

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

컨테이너 이미지를 복제하기 위해 Sidekiq는 컨테이너 레지스트리로의 인증을 위해 JWT를 사용합니다. Geo 복제는 컨테이너 레지스트리 구성이 올바르게 수행되었음을 전제로 합니다.

양쪽 사이트가 동일한 서명 키 쌍을 공유하도록 하고 보조 사이트 구성 아래에서 안내된 대로 두 레지스트리와 주/보조 사이트가 동일한 토큰 발급자를 사용하도록 구성되었는지 확인하십시오.

멀티노드 배포의 경우 Sidekiq 노드에 구성된 발급자가 레지스트리에 구성된 값과 일치하는지 확인하십시오.

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

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

1. 왼쪽 사이드바에서 Admin을 선택합니다.
2. Geo > Sites를 선택합니다.
3. 보조 사이트의 Replication Details에서 Container Repositories를 선택합니다.
4. 하나의 행에 대해 Resync 또는 Resync all을 선택합니다.

또는 보조 사이트의 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": 동기화 실패