Geo를 사용하여 GitLab Dedicated로 마이그레이션
Offering: GitLab Dedicated
Geo 마이그레이션을 위해서는 GitLab Self-Managed 기본 인스턴스의 시크릿이 필요합니다. SSH 호스트 키는 선택 사항이지만 강력히 권장됩니다. 수집 스크립트는 파일 암호화 도구인 age를 사용하여 Switchboard에 업로드하기 전에 시크릿을 안전하게 암호화합니다.
Geo 마이그레이션을 위해서는 GitLab Self-Managed 기본 인스턴스의 시크릿이 필요합니다. 마이그레이션 후 GitLab Dedicated가 데이터를 복호화할 수 있도록 하기 위해서입니다. 이 시크릿에는 데이터베이스 암호화 키, CI/CD 변수 및 기타 민감한 구성 세부 정보가 포함됩니다.
SSH 호스트 키는 선택 사항이지만 강력히 권장됩니다. SSH 호스트 키를 보존하면 마이그레이션 후 사용자가 SSH로 git clone 또는 git pull을 실행할 때 SSH 호스트 키 확인 실패를 방지할 수 있습니다. 자체 도메인을 사용할 계획이라면 특히 중요합니다.
수집 스크립트는 파일 암호화 도구인 age를 사용하여 Switchboard에 업로드하기 전에 시크릿을 안전하게 암호화합니다.
마이그레이션 시크릿 수집 및 업로드#
GitLab Dedicated 인스턴스 생성 시 Geo 마이그레이션 시크릿을 수집하고 업로드합니다.
사전 요건:
- GitLab Self-Managed 기본 인스턴스에 대한 관리자 액세스
- Python 3.x
- Switchboard의 Geo migration secrets 페이지에서
age공개 키 - GitLab 클러스터에 액세스하도록 구성된
kubectl(Kubernetes 설치의 경우만)
마이그레이션 시크릿을 수집하고 업로드하려면:
-
Switchboard에 로그인합니다.
-
Geo migration secrets 페이지에서 설치 유형에 맞는 수집 스크립트를 다운로드합니다.
-
선택 사항. 오프라인 환경의 경우, 실행하기 전에
age바이너리를 수집 스크립트에 포함시킵니다. 자세한 내용은 오프라인 환경을 참조하십시오. -
설치 유형에 맞는 수집 스크립트를 실행하고
<age_public_key>를 페이지에 표시된 키로 교체합니다:-
Linux 패키지 설치의 경우, Rails 노드에서 다음 명령을 실행합니다:
python3 collect_secrets_linux_package.py <age_public_key>/etc/gitlab/gitlab-secrets.json,/var/opt/gitlab/gitlab-rails/etc/database.yml, 및/etc/ssh/에 대한 읽기 액세스가 필요합니다. -
Kubernetes 설치의 경우,
kubectl액세스 권한이 있는 워크스테이션에서 다음 명령을 실행합니다:python3 collect_secrets_k8s.py <age_public_key>기본값을 재정의하려면 추가 플래그를 전달할 수 있습니다. 자세한 내용은 Kubernetes 수집 스크립트 플래그를 참조하십시오.
-
-
선택 사항. SSH 호스트 키만 수집하려면 명령에
--hostkeys-only플래그를 추가합니다.스크립트는 다음을 생성합니다:
migration_secrets.json.age: GitLab 시크릿(필수)ssh_host_keys.json.age: SSH 호스트 키(선택 사항이지만 권장)
-
migration_secrets.json.age파일을 업로드합니다. -
선택 사항.
ssh_host_keys.json.age파일을 업로드합니다. -
유효성 검사가 완료될 때까지 기다립니다. 유효성 검사는 파일당 약 10-20초 소요됩니다.
-
표시된 파일명과 핑거프린트가 업로드된 파일과 일치하는지 확인합니다.
유효성 검사는 파일이 올바르게 암호화되었는지, 예상 구조를 포함하는지 확인합니다. 파일의 내용을 복호화하거나 노출하지 않습니다.
시크릿을 업로드한 후, 테넌트 생성을 위한 나머지 단계를 완료합니다.
Kubernetes 수집 스크립트 플래그#
기본값을 재정의하기 위해 collect_secrets_k8s.py와 함께 다음 선택적 플래그를 사용합니다:
| 플래그 | 기본값 | 설명 |
|---|---|---|
--namespace NAME |
현재 컨텍스트 | Kubernetes 네임스페이스. |
--release NAME |
gitlab |
Helm 릴리스 이름 접두사. |
--rails-secret NAME |
없음 | Rails 시크릿 이름. |
--registry-secret NAME |
없음 | 레지스트리 시크릿 이름. |
--postgres-secret NAME |
없음 | Postgres 비밀번호 시크릿 이름. |
--hostkeys-secret NAME |
없음 | SSH 호스트 키 시크릿 이름. |
오프라인 환경#
GitLab Self-Managed 인스턴스에 인터넷 액세스가 없는 경우, 수집 스크립트를 실행하기 전에 age 바이너리를 수동으로 다운로드합니다.
오프라인 환경을 위한 수집 스크립트를 설정하려면:
-
인터넷 액세스가 있는 기계에서
age바이너리를 다운로드합니다:python3 download_age_binaries.py이는 여러 플랫폼의
age바이너리가 포함된age_binaries.tar.gz파일을 생성합니다. -
age_binaries.tar.gz파일을 오프라인 환경으로 전송합니다. -
바이너리를 수집 스크립트에 포함시킵니다:
python3 embed_age_binary.py --binaries age_binaries.tar.gz이는
age바이너리를 포함하는 독립적인 스크립트를 만듭니다. -
마이그레이션 시크릿 수집 및 업로드에서 설명한 대로 GitLab Self-Managed 인스턴스에서 포함된 스크립트를 실행합니다.
포함된 스크립트는 자동으로 포함된 age 바이너리를 추출하고 사용합니다.
문제 해결#
Geo 마이그레이션을 사용할 때 다음과 같은 문제가 발생할 수 있습니다.
오류: 수집 스크립트 실행 시 Permission denied#
수집 스크립트가 GitLab 구성 파일에 액세스하려 할 때 권한 오류가 발생할 수 있습니다.
이 문제는 스크립트가 필요한 파일을 읽기에 충분한 권한 없이 실행될 때 발생합니다.
이 문제를 해결하려면:
- Linux 패키지 설치의 경우,
root사용자로 스크립트를 실행하거나sudo를 사용합니다. - Kubernetes 설치의 경우,
kubectl컨텍스트가 GitLab 네임스페이스에 액세스할 수 있는지 확인합니다. - 필요한 파일이 예상 경로에 있는지 확인합니다.
수집 스크립트가 GitLab 설치를 찾을 수 없음#
스크립트가 GitLab 설치 또는 구성 파일을 찾을 수 없다는 오류가 발생할 수 있습니다.
이 문제는 다음 시나리오에서 발생합니다:
- 스크립트가 GitLab이 설치되지 않은 기계에서 실행됩니다.
- GitLab이 비표준 위치에 설치되어 있습니다.
- 필수 구성 파일이 없거나 이동되었습니다.
일반적인 오류 메시지는 다음과 같습니다:
- Linux 패키지:
Error: database.yml not found: /var/opt/gitlab/gitlab-rails/etc/database.yml다음에✗ Failed to collect GitLab secrets - Kubernetes:
Error: Could not retrieve gitlab-rails-secrets
이 문제를 해결하려면:
- 스크립트가 올바른 기계에서 실행되는지 확인합니다(Linux 패키지 설치의 경우 Rails 노드).
- GitLab이 올바르게 설치되고 구성되어 있는지 확인합니다.
- GitLab이 비표준 위치에 설치된 경우, 구성 파일 경로가 설치와 일치하는지 확인합니다.
- 필수 파일이 없거나 손상된 경우, 마이그레이션을 진행하기 전에 Professional Services에 연락하여 설치 상태 점검을 수행합니다.