--- title: "GitLab 그룹과 프로젝트를 더 효율적으로 마이그레이션 하는 방법" description: "앞서 GitLab은 모든 사람이 사용할 수 있는 베타 기능으로 프로젝트 마이그레이션을 선보였습니다. 이후 GitLab은 대규모 프로젝트의 효율적이고 안정적인 마이그레이션에 초점을 맞추어 추가 개선 작업을 진행하였습니다. 이 글에서는 이러한 개선 사항과 전반적인 프로세스, 마이그레이션 속도에 미치는 영향, 마이그레이션 시간 추정치를 다뤘습니다." url: https://insight.infograb.net/blog/2023/09/15/gitlab-migration/ source: content/generated/blog/2023-09-15-gitlab-migration.md --- 그룹과 프로젝트를 직접 전송으로 마이그레이션 하면, UI 또는 API를 사용하여 GitLab 인스턴스 간에 GitLab 리소스를 쉽게 이전할 수 있습니다. [이전 블로그 게시물](https://about.gitlab.com/blog/2023/01/18/try-out-new-way-to-migrate-projects/)에서 GitLab은 **모든 사람이 사용할 수 있는** 베타 기능으로 프로젝트 마이그레이션을 발표했습니다. 아울러 이 방법의 이점과 마이그레이션 단계도 설명했습니다. 이후 GitLab은 특히 대규모 프로젝트의 [효율적](https://gitlab.com/groups/gitlab-org/-/epics/8983)이고 [안정적](https://gitlab.com/groups/gitlab-org/-/epics/8927)인 마이그레이션에 초점을 맞추어 추가 개선 작업을 진행하였습니다. 이 글에서는 이러한 개선 사항과 전반적인 프로세스, 마이그레이션 속도에 미치는 영향을 자세히 설명하려고 합니다. 또한 마이그레이션 시간 추정치도 다루겠습니다. ## CI/CD 파이프라인 가져오기 ### Timeout **문제** GitLab은 [CI/CD 파이프라인의 가져오기가 Timeout으로 실패하는 버그 보고](https://gitlab.com/gitlab-org/gitlab/-/issues/365702)를 받았고, 기본 마이그레이션 프로세스를 개선할 필요가 있다고 판단했습니다. 이에 문제의 근본 원인과 가능한 해결책을 고려하고 PoC(Proof of Concept)를 진행했습니다. 그리고 GitLab은 ‘특정 관계 유형(예: 파이프라인)의 대량 프로젝트에 대한 하나의 거대 아카이브 파일 문제를 해결해야 한다’라고 결론 내렸습니다. ### **개선 사항** Timeout 문제를 해결하기 위해, 관계(예: Merge Request(MR) 또는 파이프라인)를 내보내고 가져오는 과정에 배치(Batch)를 도입하기로 결정했습니다. 그리고 [배치 도입을 위한 에픽](https://gitlab.com/groups/gitlab-org/-/epics/9036)을 완전히 완료하기 전에, CI/CD 파이프라인을 내보내는 과정에 몇 가지 다른 최적화를 도입해야 했습니다. GitLab 15.10에서는: - [CI/CD 파이프라인을 내보낼 때 연관 관계를 사전 로드하기 시작했습니다.](https://gitlab.com/gitlab-org/gitlab/-/issues/391593) - [Commit 노트를 별도의 관계로 내보냅니다.](https://gitlab.com/gitlab-org/gitlab/-/issues/391601) 이러한 최적화로 인해 CI/CD 파이프라인의 내보내기 속도가 크게 빨라졌습니다. 이에 따라 프로젝트의 대량 파이프라인을 아카이브 파일로 내보낼 수 있었고 그 다음, 목적지 인스턴스에도 가져올 수 있었습니다. 하지만 파이프라인을 최종적으로 가져왔기 때문에 마이그레이션의 전체 시간은 증가했습니다. GitLab 16.3에서는 [배치로 관계를 내보내고 가져오기 기능](https://gitlab.com/groups/gitlab-org/-/epics/9036)을 도입했습니다. 이는 두 가지 이점이 있습니다: - 한 번의 관계 당 하나의 파일 대신 더 작은 아카이브 파일을 만들고 전송하여 마이그레이션 성능을 향상합니다. 프로젝트에 수천 개의 파이프라인이 있으면 이러한 파일은 매우 클 수 있습니다. - 더 많은 병렬 처리를 가능하게 합니다. 예를 들어, CI 파이프라인 데이터는 이제 여러 배치로 나누어지며, 동시 Sidekiq job(목적지 인스턴스에서 Sidekiq Worker를 사용할 수 있을 때, 아래 참조)이 각 배치를 가져옵니다. 이 개선 사항은 GitLab.com에서 이미 기본으로 사용할 수 있습니다. - **자체 관리형 GitLab 인스턴스에서 GitLab.com으로 마이그레이션 하는 사용자**는 배치 내보내기를 사용할 수 있는 GitLab 16.2 이상 버전에 자체 관리형 인스턴스가 있어야 이 개선 사항의 이점을 누릴 수 있습니다. - **GitLab.com에서 자체 관리형 GitLab 인스턴스로 마이그레이션 하는 사용자**는 GitLab 16.2 이상 버전에 자체 관리형 인스턴스가 있어야 하고,  `bulk_imports_batched_import_export` [기능 플래그(Feature Flag)](https://docs.gitlab.com/ee/administration/feature_flags.html)를 활성화해야 이 개선 사항의 이점을 활용할 수 있습니다. ## **마이그레이션 시간을 추정할 수 있을까요?** 이 질문은 자주 제기되었습니다. 답변은 ‘직접 전송으로 마이그레이션 한 시간이 다양한 요인에 따라 달라진다’라는 것입니다. 이러한 요인 중 일부는 다음과 같습니다: - **소스와 목적지 GitLab 인스턴스에서 사용할 수 있는 하드웨어와 데이터베이스 리소스** - 소스와 목적지 인스턴스의 리소스가 더 많을수록 마이그레이션 시간이 더 짧아질 수 있습니다. 이유는 다음과 같습니다. - 소스 인스턴스는 API 요청을 받고, 내보낼 엔티티를 추출하며 직렬화해야 합니다. - 목적지 인스턴스는 job을 실행하고 해당 데이터베이스에 엔티티를 생성해야 합니다. - **내보낼 데이터의 복잡성과 크기** - 예를 들어, 각각 1000개의 MR이 있는 두 개의 다른 프로젝트를 마이그레이션 한다고 생각해 보세요. 프로젝트 중 하나가 MR에 첨부 파일, 댓글, 기타 항목이 아주 많다면, 두 프로젝트는 마이그레이션 시간이 매우 다를 수 있습니다. 따라서 프로젝트의 MR 수는 ‘프로젝트를 마이그레이션 하는 데 시간이 얼마나 걸릴지’ 예측하는 데 적합하지 않습니다. 마이그레이션을 신뢰할 만하게 추정할 정확한 공식은 없습니다. 그러나 GitLab은 프로젝트 관계를 가져오는 각 job의 지속 시간을 확인하여 평균 수치를 공유하므로 ‘프로젝트를 가져오는 데 시간이 얼마나 걸릴지’ 아이디어를 얻을 수 있습니다. GitLab이 발견한 내용은 다음과 같습니다: - 빈 프로젝트를 가져오는 데 약 2.4초 걸립니다. - 하나의 MR을 가져오는 데 약 1초 걸립니다. - 하나의 이슈를 가져오는 데 약 0.1초 걸립니다. 아래 표에서 프로젝트 관계와 이를 가져오는 데 걸리는 평균 시간을 더 찾아볼 수 있습니다. | 프로젝트 리소스 유형 | 단일 레코드를 가져오는 데 걸리는 평균 시간 (초 단위) | | --------------------------- | ------------------------------- | | Empty project | 2.4 | | Repository | 20 | | Project attributes | 1.5 | | Members | 0.2 | | Labels | 0.1 | | Milestones | 0.07 | | Badges | 0.1 | | Issues | 0.1 | | Snippets | 0.05 | | Snippet repositories | 0.5 | | Boards | 0.1 | | Merge requests | 1 | | External pull requests | 0.5 | | Protected branches | 0.1 | | Project feature | 0.3 | | Container expiration policy | 0.3 | | Service desk setting | 0.3 | | Releases | 0.1 | | CI/CD pipelines | 0.2 | | Commit notes | 0.05 | | Wiki | 10 | | Uploads | 0.5 | | LFS objects | 0.5 | | Design | 0.1 | | Auto DevOps | 0.1 | | Pipeline schedules | 0.5 | | References | 5 | | Push rule | 0.1 | ## **효율적으로 마이그레이션 하는 방법은?** GitLab은 가장 효율적인 마이그레이션을 달성하기 위해 필요한 것을 알고 있습니다. 단일 직접 전송 마이그레이션은 목적지 인스턴스에서 사용할 수 있는 Sidekiq Worker 수와 관계없이 한 번에 import당 최대 5개의 엔티티(그룹 또는 프로젝트)를 실행합니다. 직접 전송을 사용한 마이그레이션당 가져올 수 있는 동시 엔티티 수는 최대 5개입니다. 이 제한을 없애면 소스 인스턴스에서 네트워크 Timeout 문제가 생깁니다. 이에 GitLab은 소스 GitLab 인스턴스에 과부하가 걸리지 않도록 이 제한을 설정하였습니다. 목적지 인스턴스에 5개 이상의 Sidekiq Worker를 사용할 수 있다고 해서 이 Worker가 마이그레이션 동안 활용되지 않는다는 의미는 아닙니다. 반대로, Sidekiq Worker가 더 많으면 각 엔티티를 가져오는 시간이 줄어 마이그레이션 속도가 높아집니다. 관계 가져오기는 여러 작업으로 분산되며 단일 프로젝트 엔티티는 마이그레이션 할 관계가 30개 이상 있습니다. 위에서 언급한 대로 [배치로 관계를 내보내고 가져오기 기능](https://gitlab.com/groups/gitlab-org/-/epics/9036)으로 인해 Sidekiq Worker가 처리해야 할 job은 훨씬 더 많아집니다. 목적지 인스턴스에서 Sidekiq Worker 수를 늘리면 소스 인스턴스 하드웨어 리소스가 포화 상태에 도달할 때까지 마이그레이션 속도가 높아집니다. Sidekiq Worker 수를 늘리는 방법(동시성 늘리기)의 자세한 내용은 [Sidekiq 인스턴스 설정](https://docs.gitlab.com/ee/administration/sidekiq/#set-up-sidekiq-instance)을 참조하세요. 소스 인스턴스의 Sidekiq Worker 수는 최소 5개의 동시 엔티티를 실행 중인 각 가져오기에 대해 동시에 내보낼 수 있을 정도로 충분해야 합니다. 그렇지 않으면 목적지가 ‘내보낸 데이터’를 사용할 수 있도록 기다리는 동안 지연과 잠재 Timeout이 발생할 것입니다. 프로젝트를 다른 그룹에 분산하면 Timeout을 피하는 데 도움이 될 수 있습니다. 여러 대규모 프로젝트가 같은 그룹에 있으면 다음 작업을 수행할 수 있습니다. 1. 대규모 프로젝트를 다른 그룹 또는 하위 그룹으로 이동 2. 각 그룹과 하위 그룹에 별도의 마이그레이션을 시작 GitLab UI는 최상위 그룹만 마이그레이션 할 수 있습니다. API를 사용하면 하위 그룹도 마이그레이션 할 수 있습니다. ## **직접 전송으로 마이그레이션 하는 다음 단계는?** 물론, 아직 끝나지 않았습니다! GitLab은 베타 버전에서 일반적으로 사용할 수 있는(GA) 버전으로 만드는 걸 목표로 직접 전송 방법을 계속 개선할 것입니다. 다음은 GitLab이 작업하고 있는 기능입니다. - [**직접 전송의 하드 코딩된 제한을 설정으로 이동**](https://gitlab.com/gitlab-org/gitlab/-/issues/384976) - 직접 전송을 사용한 마이그레이션에는 자체 관리형 GitLab 관리자가 필요에 따라 조정하도록 구성할 수 있는 하드 코딩된 제한이 일부 있습니다. GitLab.com에서는 이러한 제한을 하드 코딩된 설정보다 더 높게 조정할 수 있습니다. - [**90분 내보내기 Timeout 제거**](https://gitlab.com/gitlab-org/gitlab/-/issues/392725) - 이 제한을 제거하면 현재 지원하는 90분 이내에 마이그레이션 할 수 있는 프로젝트뿐만 아니라 훨씬 더 큰 프로젝트의 내보내기가 가능해집니다. GitLab은 여러분 의견을 듣길 원합니다. 가장 중요한, 누락된 부분은 무엇인가요? GitLab이 어떻게 더 개선할 수 있을까요? [피드백 이슈](https://gitlab.com/gitlab-org/gitlab/-/issues/284495)에 이를 알려주거나 [시간을 예약](https://calendly.com/gitlab-magdalenafrankiewicz/45mins)하여 Import와 Integrations 그룹 제품 관리자와 함께 상의할 수 있습니다. GitLab은 계속 반복하여 개선할 것입니다! ::cta:: _✔️ 이 블로그에는 향후 출시될 제품, 특징, 기능 정보가 포함되어 있습니다. 이 블로그 게시물의 목적은 오직 ‘정보 제공’임을 유의하세요. 구매 또는 계획 수립을 목적으로 이 정보에 의존하지 마세요. 모든 프로젝트와 마찬가지로 이 블로그 및 링크된 페이지에 언급된 사항은 변경되거나 지연될 수 있습니다. 제품, 특징 또는 기능의 개발, 출시 및 시기는 GitLab의 단독 재량에 따라 결정됩니다._ > 이 포스트는 GitLab의 동의를 받아 공식 블로그의 [영문 포스트](https://about.gitlab.com/blog/2023/08/02/how-to-migrate-gitlab-groups-and-projects-more-efficiently/)를 우리말로 번역한 글입니다. ::button::[GitLab 그룹과 프로젝트를 효율적으로 이전하고 싶으신가요? GitLab 공식 파트너 인포그랩과 상담하세요!](https://insight.infograb.net/contact/)::