GitLab 직접 전송을 통한 마이그레이션

Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated

GitLab 그룹을 다음과 같이 마이그레이션할 수 있습니다:

  • Self-managed GitLab에서 GitLab.com으로.
  • GitLab.com에서 self-managed GitLab으로.
  • 하나의 self-managed GitLab 인스턴스에서 다른 인스턴스로.
  • 동일한 GitLab 인스턴스 내의 그룹 간에.
caution
직접 전송을 사용하여 GitLab 그룹 및 프로젝트를 마이그레이션하는 것은 현재 사용 불가입니다. 해결 예상 시간은 없습니다. 자세한 내용은 지원팀에 문의하십시오.

직접 전송에 의한 마이그레이션은 그룹의 새로운 복사본을 만듭니다. 그룹을 복사하는 대신 이동하려면 동일한 GitLab 인스턴스 내에 있는 경우 그룹을 전송할 수 있습니다. 그룹을 마이그레이션하는 대신 전송하는 것이 더 빠르고 완전한 옵션입니다.

그룹을 다음 두 가지 방법으로 마이그레이션할 수 있습니다:

GitLab.com에서 self-managed GitLab으로 마이그레이션할 경우, 관리자는 self-managed GitLab 인스턴스에서 사용자 생성이 가능합니다.

Self-managed GitLab에서는 기본적으로 그룹 아이템 마이그레이션이 사용할 수 없습니다. 기능을 표시하려면 관리자가 응용 프로그램 설정에서 활성화할 수 있습니다.

직접 전송으로 그룹을 마이그레이션하면 그룹이 한 장소에서 다른 장소로 복사됩니다. 다음을 수행할 수 있습니다:

  • 한 번에 여러 그룹 복사.
  • GitLab UI에서 최상위 그룹 복사:
    • 또 다른 최상위 그룹으로.
    • 기존 최상위 그룹의 하위 그룹으로.
    • GitLab.com을 포함한 다른 GitLab 인스턴스로.
  • API에서 최상위 그룹과 하위 그룹을 이러한 위치로 복사합니다.
  • 프로젝트가 포함된 그룹( 베타이며 프로덕션 사용에 준비되지 않음) 또는 프로젝트가 없는 그룹 복사. 그룹과 함께 프로젝트 복사는:
    • GitLab.com에서 기본적으로 사용 가능합니다.

모든 그룹 및 프로젝트 리소스가 복사되는 것은 아닙니다. 아래에서 복사된 리소스 목록을 참조하십시오:

caution
프로젝트가 포함된 그룹을 가져오는 것은 베타입니다. 이 기능은 프로덕션 사용에 준비되지 않았습니다.

직접 전송을 통한 마이그레이션에 대한 피드백을 피드백 이슈에서 남겨주시기 바랍니다.

특정 프로젝트 마이그레이션

GitLab UI에서 직접 전송을 사용하여 그룹을 마이그레이션하면 그룹의 모든 프로젝트가 마이그레이션됩니다. 그룹에서 특정 프로젝트만 직접 전송을 사용하여 마이그레이션하려면 API를 사용해야 합니다.

알려진 문제

  • 이슈 406685 때문에 파일 이름이 255자를 초과하는 파일은 마이그레이션되지 않습니다.

  • GitLab 16.1 및 이전 버전에서는 예약된 스캔 실행 정책과 함께 직접 전송을 사용하지 않아야 합니다.

  • 기타 알려진 문제의 목록은 에픽 6629를 참조하세요.

  • GitLab 16.9 및 이전 버전에서는 이슈 438422로 인해 DiffNote::NoteDiffFileCreationError 오류가 발생할 수 있습니다. 이 오류가 발생하면 병합 요청의 diff의 노트가 누락되지만 노트와 병합 요청은 여전히 가져옵니다.

  • 소스 인스턴스에서 매핑된 경우, 공유 멤버는 대상에 이미 멤버십이 존재하지 않는 한 직접 멤버로 매핑됩니다. 이는 소스 인스턴스에서 상위 그룹을 대상 인스턴스의 상위 그룹으로 가져오면 항상 프로젝트의 직접 멤버에 매핑된다는 것을 의미합니다. 소스 상위 그룹이 필요한 공유 멤버십 계층 세부정보를 포함하고 있더라도 말입니다. 공유 멤버십의 전체 매핑 지원은 이슈 458345에서 제안되었습니다.

  • GitLab 17.0, 17.1 및 17.2에서는 가져온 에픽 및 작업 항목이 원래 작성자가 아닌 가져오는 사용자에 매핑됩니다.

마이그레이션 소요 시간 추정

직접 전송을 통한 마이그레이션 기간을 추정하는 것은 어렵습니다. 마이그레이션 기간에 영향을 미치는 요인은 다음과 같습니다:

  • 소스 및 대상 GitLab 인스턴스에서 사용 가능한 하드웨어 및 데이터베이스 리소스. 소스 및 대상 인스턴스에서 더 많은 리소스가 있을 경우, 마이그레이션 기간이 짧아질 수 있습니다. 이유는 다음과 같습니다:

    • 소스 인스턴스는 API 요청을 받고, 엔티티를 추출하고 직렬화하여 내보냅니다.

    • 대상 인스턴스는 작업을 실행하고 해당 데이터베이스에 엔티티를 생성합니다.

  • 내보낼 데이터의 복잡성과 크기. 예를 들어, 두 개의 서로 다른 프로젝트에서 각각 1000개의 병합 요청을 마이그레이션하려고 한다고 가정해 보세요. 프로젝트 중 하나가 많은 첨부파일, 댓글 및 기타 항목이 있는 경우 두 프로젝트는 마이그레이션에 걸리는 시간이 매우 다를 수 있습니다. 따라서 프로젝트의 병합 요청 수는 마이그레이션에 얼마나 걸릴지를 예측하는 데 좋은 기준이 아닙니다.

마이그레이션을 신뢰성 있게 추정하는 정확한 공식은 없습니다. 그러나 각 파이프라인 작업자가 프로젝트 관계를 가져오는데 걸리는 평균 시간을 통해 프로젝트를 가져오는 데 얼마나 걸릴지를 대략적으로 알 수 있습니다:

프로젝트 리소스 유형 레코드를 가져오는 평균 시간(초)
빈 프로젝트 2.4
리포지토리 20
프로젝트 속성 1.5
멤버 0.2
라벨 0.1
마일스톤 0.07
배지 0.1
이슈 0.1
스니펫 0.05
스니펫 리포지토리 0.5
보드 0.1
병합 요청 1
외부 풀 요청 0.5
보호 브랜치 0.1
프로젝트 기능 0.3
컨테이너 만료 정책 0.3
서비스 데스크 설정 0.3
릴리즈 0.1
CI 파이프라인 0.2
커밋 노트 0.05
위키 10
업로드 0.5
LFS 객체 0.5
디자인 0.1
자동 DevOps 0.1
파이프라인 일정 0.5
참조 5
푸시 규칙 0.1

마이그레이션 소요 시간을 예측하기는 어렵지만, 우리는 다음과 같은 사례를 보았습니다:

  • 100개의 프로젝트(19.9k 이슈, 83k 병합 요청, 100k 이상의 파이프라인)가 8시간 동안 마이그레이션되었습니다.

  • 1926개의 프로젝트(22k 이슈, 160k 병합 요청, 110만 파이프라인)가 34시간 동안 마이그레이션되었습니다.

큰 프로젝트를 마이그레이션하고 타임아웃이나 마이그레이션 소요 시간에 대한 문제가 발생하는 경우, 마이그레이션 소요 시간 단축을 참조하세요.

마이그레이션 기간 단축

직접 전송을 사용하는 마이그레이션의 기간을 단축하기 위한 몇 가지 전략입니다.

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

단일 직접 전송 마이그레이션은 한 번에 5개의 엔터티(그룹 또는 프로젝트)를 가져오며, 이는 대상 인스턴스에서 사용 가능한 워커의 수와 무관합니다.

즉, 대상 인스턴스에 더 많은 Sidekiq 워커 프로세스를 추가하면 각 엔터티를 가져오는 시간이 줄어들어 마이그레이션 속도가 빨라집니다.

대상 인스턴스에 더 많은 Sidekiq 워커를 추가하려면 다음 중 하나를 수행할 수 있습니다:

  1. 라우팅 규칙 사용. 이 방법은 직접 전송 작업에 전념하는 추가 Sidekiq 워커를 생성합니다.
  2. 여러 Sidekiq 프로세스 시작. 이 방법은 GitLab의 모든 대기열이 추가 Sidekiq 워커 프로세스를 사용할 수 있게 합니다.

라우팅 규칙 사용에 대한 예시는 아래와 같습니다. 이 예시는:

  • 대상 인스턴스의 /etc/gitlab/gitlab.rb 파일에 추가할 수 있으며, 변경 사항을 적용하기 위해 다음 리컨피그를 수행해야 합니다.
  • 네 개의 Sidekiq 워커 프로세스를 생성합니다. 세 개의 프로세스는 직접 전송 수입자 대기열 전용으로 사용되며, 마지막 프로세스는 모든 다른 대기열에 사용됩니다.
  • 프로세스 수는 최대한 CPU 코어 수와 같거나 초과하지 않도록 설정되어야 합니다. Sidekiq 워커 프로세스는 1개의 CPU 코어를 초과하여 사용하지 않습니다.
sidekiq['routing_rules'] = [
  ['feature_category=importers', 'importers'],
  ['*', 'default']
]

sidekiq['queue_groups'] = [
  # 수입자 전용으로 두 프로세스를 실행합니다.
  'importers',
  'importers',
  'importers',

  # 기본 및 메일러 대기열에서 'catchall' 프로세스를 하나 실행합니다.
  'default,mailers'
]

GitLab 16.11 및 이전 버전을 사용하는 경우 모든 대기열 선택기를 명시적으로 비활성화하세요:

sidekiq['queue_selector'] = false

대상 인스턴스의 워커 수를 늘리면 원본 인스턴스의 하드웨어 리소스가 포화 상태에 이르기까지 마이그레이션 기간을 줄이는 데 도움이 됩니다. GitLab 16.8부터 기본 제공되는 배치로 관계를 내보내고 가져오는 기능은 대상 인스턴스에서 충분한 사용 가능한 워커를 갖는 것이 더욱 유용합니다.

대규모 프로젝트 재배포 또는 개별 마이그레이션 시작

원본 인스턴스의 워커 수는 각 실행 중인 수입에 대해 5개의 동시 엔터티를 병렬로 내보내기에 충분해야 합니다. 그렇지 않으면 대상이 내보낸 데이터를 사용할 수 있도록 대기하면서 지연이나 잠재적인 타임아웃이 발생할 수 있습니다.

프로젝트를 서로 다른 그룹에 배포하면 타임아웃을 피할 수 있습니다. 여러 대규모 프로젝트가 동일한 그룹에 있는 경우:

  1. 대규모 프로젝트를 서로 다른 그룹이나 하위 그룹으로 이동합니다.
  2. 각 그룹 및 하위 그룹에서 개별 마이그레이션을 시작합니다.

GitLab UI는 최상위 그룹만 마이그레이션할 수 있습니다. API를 사용하면 하위 그룹도 마이그레이션할 수 있습니다.

한계

  • GitLab 16.7에서 마이그레이션의 8시간 시간 제한 제거됨.

직접 전송에 대한 하드코딩된 한계가 적용됩니다.

한계 설명
6 사용자가 수신할 수 있는 GitLab 인스턴스에서 허용되는 최대 마이그레이션 수(분당). GitLab 15.9에서 도입됨.
210초 아카이브 파일 압축을 해제하는 데 기다릴 수 있는 최대 초 수.
50MB NDJSON 행의 최대 길이.
5분 원본 인스턴스에서 빈 내보내기 상태가 발생할 때까지 최대 초 수.

구성 가능한 한계도 사용할 수 있습니다.

GitLab 16.3 이후, 다음과 같은 이전의 하드코딩된 설정이 구성 가능합니다:

  • 원본 인스턴스에서 다운로드할 수 있는 최대 관계 크기 (5 GiB로 설정).
  • 압축 해제된 아카이브의 최대 크기 (10 GiB로 설정).

최대 관계 크기 한도를 테스트하려면 다음 API를 사용하세요:

어느 API든 최대 관계 크기 한도를 초과하는 파일을 생성하면 직접 전송을 통한 그룹 마이그레이션이 실패합니다.

가시성 규칙

마이그레이션 후:

  • 개인 그룹 및 프로젝트는 개인 상태를 유지합니다.
  • 내부 그룹 및 프로젝트:
    • 내부 가시성이 제한되지 않은 경우, 내부 그룹으로 복사될 때 내부 상태를 유지합니다. 그 경우, 그룹과 프로젝트는 개인이 됩니다.
    • 개인 그룹으로 복사될 때 개인이 됩니다.
  • 공개 그룹 및 프로젝트:
    • 공개 가시성이 제한되지 않은 경우, 공개 그룹으로 복사될 때 공개 상태를 유지합니다. 그 경우, 그룹과 프로젝트는 내부가 됩니다.
    • 내부 가시성이 제한되지 않은 경우, 내부 그룹으로 복사될 때 내부가 됩니다. 그 경우, 그룹과 프로젝트는 개인이 됩니다.
    • 개인 그룹으로 복사될 때 개인이 됩니다.

내용을 일반 대중으로부터 숨기기 위해 소스 인스턴스에서 개인 네트워크를 사용했다면,

대상 인스턴스에서도 유사한 설정을 하거나 개인 그룹으로 가져오도록 하세요.

직접 전송 프로세스로 마이그레이션

직접 전송을 사용하여 그룹과 프로젝트 마이그레이션하기를 참조하세요.