Rails 콘솔 세션에서 다음을 사용하여 그룹 임포트 시도의 실패 또는 오류 메시지를 확인할 수 있습니다.

# Get relevant import records
import = BulkImports::Entity.where(namespace_id: Group.id).map(&:bulk_import).last

# Alternative lookup by user
import = BulkImport.where(user_id: User.find(...)).last

# Get list of import entities. Each entity represents either a group or a project
entities = import.entities

# Get a list of entity failures
entities.map(&:failures).flatten

# Alternative failure lookup by status
entities.where(status: [-1]).pluck(:destination_name, :destination_namespace, :status)

API 엔드포인트를 사용하면 마이그레이션된 모든 엔터티와 그에 관련된 실패 내역을 함께 확인할 수도 있습니다.

마이그레이션이 느리거나 시간 초과#

마이그레이션 중에 속도가 매우 느리거나 시간 초과가 발생한다면 다음 전략으로 마이그레이션 시간을 줄일 수 있습니다.

대상 인스턴스에 Sidekiq 워커 추가#

GitLab Self-Managed 인스턴스로 마이그레이션하는 경우 대상 인스턴스에 Sidekiq 워커를 추가하여 마이그레이션 속도를 높일 수 있습니다. Sidekiq 워커 수를 늘릴 때는 다음 사항을 고려해야 합니다.

• 다이렉트 트랜스퍼 마이그레이션 하나는 대상 인스턴스에서 사용 가능한 Sidekiq 워커 수와 관계없이 한 번에 그룹 또는 프로젝트 다섯 개를 마이그레이션합니다.
• 대상 인스턴스가 더 많은 동시 job을 처리할 수 있어야 합니다. 그런 경우 Sidekiq 워커를 추가하면 각 그룹 또는 프로젝트를 임포트하는 시간을 줄일 수 있습니다.

대상 인스턴스에 Sidekiq 워커를 추가하는 방법에 대한 자세한 내용은 임포트를 위한 Sidekiq 구성을 참고합니다.

별도의 마이그레이션 시작#

소스 인스턴스에 그룹 다섯 개를 병렬로 내보낼 자원이 없다면 지연과 시간 초과가 발생할 수 있습니다. 소스 인스턴스의 자원이 부족하면 대상 인스턴스는 내보낸 데이터를 사용할 수 있을 때까지 기다려야 합니다.

병렬 내보내기로 인한 지연을 줄이려면 모든 그룹과 프로젝트를 동시에 마이그레이션하지 말고 그룹마다 별도의 마이그레이션을 시작합니다. GitLab UI는 최상위 그룹만 마이그레이션할 수 있으므로 하위 그룹의 프로젝트를 마이그레이션할 때는 API를 사용해야 할 수 있습니다.

오래된 임포트#

소스 또는 대상 인스턴스의 문제로 마이그레이션이 멈추거나 timeout 상태로 종료될 수 있습니다. 이러한 문제를 해결하려면 소스와 대상 인스턴스 양쪽의 로그를 확인합니다.

소스 인스턴스#

소스 인스턴스에서 임포트가 오래 멈추는 원인은 대개 과도한 메모리 사용입니다. 메모리 사용이 과도하면 Sidekiq 프로세스가 재시작되어 내보내기 job이 중단될 수 있습니다. 대상 인스턴스는 내보내기 파일을 기다리다가 결국 마이그레이션이 시간 초과될 수 있습니다.

그룹 또는 프로젝트 릴레이션이 정상적으로 내보내졌는지 확인하려면 다음 명령을 실행합니다.

curl --request GET --location "https://example.gitlab.com/api/v4/projects/:ID/export_relations/status" \
--header "PRIVATE-TOKEN: <your_access_token>"

의 상태가 1 이 아니라면 해당 릴레이션은 정상적으로 내보내지지 않았으며 문제는 소스 인스턴스에 있습니다.

다음 명령을 실행하여 중단된 내보내기 job을 검색할 수도 있습니다. Sidekiq 로그는 재시작 후 순환될 수 있으므로 순환된 로그도 함께 확인합니다.

grep `BulkImports::RelationBatchExportWorker` sidekiq.log | grep "interrupted_count"

Sidekiq 재시작이 문제의 원인이라면 다음과 같이 조치합니다.

• 내보내기 job 전용 Sidekiq 프로세스를 구성합니다. 자세한 내용은 임포트를 위한 Sidekiq 구성을 참고합니다. 문제가 계속되면 Sidekiq 동시성을 낮추어 동시에 처리하는 job 수를 제한합니다.

• Sidekiq 메모리 한도를 높입니다. 인스턴스에 여유 메모리가 있다면 Sidekiq 프로세스의 최대 RSS 한도를 높입니다. 예를 들어 한도를 2GB에서 3GB로 늘리면 잦은 재시작을 막을 수 있습니다.

• 최대 중단 횟수를 늘립니다. job이 실패하기 전까지 허용하는 중단 횟수를 늘리려면 BulkImports::RelationBatchExportWorker의 최대 중단 횟수를 높입니다.

  1. 한도를 20으로 높이려면 다음 구성을 추가합니다(기본값은 3 입니다).

     sidekiq_options max_retries_after_interruption: 20
     

  2. 변경 사항을 적용하려면 Sidekiq를 재시작합니다.

이제 새 마이그레이션을 실행하거나 프로젝트 릴레이션 내보내기 API로 내보내기를 수동으로 실행할 수 있습니다. 릴레이션이 정상적으로 내보내지고 있는지는 내보내기 상태에서 확인합니다.

예를 들어 특정 프로젝트의 내보내기를 실행하려면 다음 명령을 실행합니다.

curl --request POST --location "https://example.gitlab.com/api/v4/projects/:ID/export_relations" \
--header "PRIVATE-TOKEN: <your_access_token>" \
--form 'batched="true"'

대상 인스턴스#

드물게 대상 인스턴스가 그룹 또는 프로젝트를 정상적으로 마이그레이션하지 못할 수 있습니다. 자세한 내용은 이슈 498720을 참고합니다.

이 문제를 해결하려면 임포트 API를 사용하여 실패한 그룹 또는 프로젝트를 마이그레이션합니다. 이 API를 사용하면 특정 그룹과 프로젝트를 개별적으로 마이그레이션할 수 있습니다.

기타 404 오류#

그룹을 임포트할 때 다음과 같은 다른 404 오류가 발생할 수 있습니다.

"exception_message": "Unsuccessful response 404 from [FILTERED] Bo...",
"exception_class": "BulkImports::NetworkError",

이 오류는 소스 인스턴스에서 전송하는 과정에 문제가 있음을 의미합니다. 이를 해결하려면 소스 인스턴스에서 사전 요구 사항을 충족했는지 확인합니다.

일치하지 않는 그룹 또는 프로젝트 경로 이름#

소스 그룹 또는 프로젝트 경로가 명명 규칙에 맞지 않으면 경로가 유효하도록 정규화됩니다. 예를 들어 Destination-Project-Path는 destination-project-path로 정규화됩니다.

오류: command exited with error code 15 and Unable to save [FILTERED] into [FILTERED]#

다이렉트 트랜스퍼로 프로젝트를 마이그레이션할 때 로그에 command exited with error code 15 and Unable to save [FILTERED] into [FILTERED] 오류가 표시될 수 있습니다. 이 오류는 무시해도 됩니다. GitLab이 종료된 명령을 다시 시도합니다.

오류: Batch export [batch_number] from source instance failed#

대상 인스턴스에서 다음 오류가 발생할 수 있습니다.

Batch export [batch_number] from source instance failed: [source instance error]

이 오류는 소스 인스턴스가 일부 레코드를 내보내지 못할 때 발생합니다. 가장 흔한 원인은 다음과 같습니다.

• 디스크 공간 부족
• 메모리 부족으로 인한 Sidekiq job의 반복적인 중단
• 데이터베이스 구문 시간 초과

이 문제를 해결하려면 다음 단계를 수행합니다.

1. 소스 인스턴스의 문제를 파악하여 해결합니다.
2. 대상 인스턴스에서 일부만 임포트된 프로젝트 또는 그룹을 삭제하고 새 임포트를 시작합니다.

내보내기에 실패한 릴레이션과 배치에 대한 자세한 내용은 소스 인스턴스에서 프로젝트와 그룹의 내보내기 상태 API 엔드포인트로 확인합니다.

오류: duplicate key value violates unique constraint#

레코드를 임포트할 때 다음 오류가 발생할 수 있습니다.

PG::UniqueViolation: ERROR:  duplicate key value violates unique constraint

이 오류는 다음과 같은 경우에 발생할 수 있습니다.

• 임포트를 처리하는 Sidekiq 워커가 높은 메모리 또는 CPU 사용량 때문에 재시작되는 경우. 임포트 중 Sidekiq 자원 문제를 줄이려면 다음과 같이 조치합니다.
  • 임포트를 위한 Sidekiq 구성을 최적화합니다.
  • bulk_import_concurrent_pipeline_batch_limit 애플리케이션 설정에서 동시 job 수를 제한합니다.
• 서로 다른 소스 그룹의 그룹 또는 프로젝트를 하나의 대상 그룹으로 통합하는 경우. 서로 다른 소스 그룹의 에픽이 같은 내부 ID(단일 그룹 안에서만 고유함)를 가지면 이를 하나의 대상 그룹으로 임포트할 때 충돌이 발생합니다. 이 충돌은 index_issues_on_namespace_id_iid_unique 또는 index_epics_on_group_id_and_iid를 참조하는 PG::UniqueViolation: ERROR: duplicate key value violates unique constraint 오류를 일으킵니다.

오류: Import::BulkImports::FileDownloadStrategy::ServiceError Invalid content type#

GitLab 인스턴스 간에 다이렉트 트랜스퍼를 사용할 때 다음 오류가 발생할 수 있습니다.

Import::BulkImports::FileDownloadStrategy::ServiceError Invalid content type

이 오류는 인스턴스 간 네트워크 트래픽의 라우팅 방식과 관련이 있습니다. application/gzip 이 아닌 콘텐츠 유형이 반환된다면 네트워크 요청이 GitLab Workhorse를 우회하고 있을 수 있습니다.

이 문제를 해결하려면 다음과 같이 조치합니다.

• Ingress가 트래픽을 Puma로 직접 보내지 않고 포트 8181의 GitLab Workhorse를 거치도록 구성되어 있는지 확인합니다.
• 오브젝트 스토리지에 대해 프록시 다운로드 활성화를 고려합니다.

(imported-xx-datetime)이 추가된 마일스톤 제목#

그룹을 임포트할 때 그룹 및 프로젝트 마일스톤 제목이 대상 네임스페이스의 기존 제목과 충돌하면 임포트된 마일스톤 제목에 고유한 접미사가 추가됩니다. 예를 들면 18.0 (imported-3d-1770206299) 입니다.

이러한 마일스톤을 찾으려면 대상 인스턴스의 log/importer.log 파일에서 다음 내용을 검색합니다.

Updating milestone title - source title used by existing group or project milestone

로그 항목에는 다음 정보가 포함됩니다.

• importable_id: 임포트 중인 그룹의 ID입니다.
• milestone_title: 이름이 변경되는 마일스톤의 제목입니다.
• existing_group_id 또는 existing_project_id: 기존 마일스톤이 있는 그룹 또는 프로젝트의 ID입니다.

이 정보를 사용하면 해당 마일스톤을 찾아 원하는 제목으로 변경할 수 있습니다.

오류: Destination belongs to a different organization than the current one#

소스 네임스페이스와 대상 네임스페이스가 서로 다른 조직에 속하고 둘 중 한쪽 조직이 격리 상태로 지정되어 있으면 다이렉트 트랜스퍼 마이그레이션이 실패합니다.

이 오류를 해결하려면 현재 조직에 속한 대상 네임스페이스로 마이그레이션합니다. 자세한 내용은 이슈 595674를 참고합니다.

다운로드된 파일이 최대 다운로드 파일 크기를 초과하면 다이렉트 트랜스퍼가 실패함#

소스 인스턴스에서 다운로드한 파일이 최대 다운로드 파일 크기(기본값 5GiB)보다 크면 다이렉트 트랜스퍼가 실패합니다. 다이렉트 트랜스퍼는 대부분의 데이터를 작은 배치로 내보내므로 대부분의 파일은 이 제한을 넘지 않습니다. repository, lfs, uploads 릴레이션만 이 제한을 넘을 가능성이 있습니다.

GitLab Self-Managed와 GitLab Dedicated에서는 관리자가 최대 다운로드 파일 크기를 늘릴 수 있습니다.

GitLab.com에서는 이 제한이 고정되어 있어 늘릴 수 없습니다. 제한을 초과하는 프로젝트를 마이그레이션하려면 마이그레이션 전에 해당 릴레이션의 크기를 줄입니다.

• repository: Git 히스토리를 다시 작성하여 큰 파일을 제거합니다. 이 작업은 모든 커밋 SHA를 변경합니다. 자세한 내용은 리포지터리 크기를 줄이는 방법을 참고합니다.
• lfs: 프로젝트를 마이그레이션한 다음 누락된 LFS 오브젝트를 대상에 수동으로 푸시합니다. 자세한 내용은 푸시 시 LFS 오브젝트 누락을 참고합니다.
• uploads: 사용 가능한 우회 방법이 없습니다. 자세한 내용은 이슈 526344를 참고합니다.