InfoGrab DocsInfoGrab Docs

Geo 마이그레이션 시크릿 수집

요약

GitLab Dedicated for Government는 지속적인 Geo 복제나 Geo 기반 장애 조치(failover)를 지원하지 않습니다. Geo 마이그레이션에는 GitLab Self-Managed 기본 인스턴스의 시크릿이 필요합니다.

Note

GitLab Dedicated for Government는 지속적인 Geo 복제나 Geo 기반 장애 조치(failover)를 지원하지 않습니다. 신규 테넌트 온보딩을 위한 Geo 마이그레이션은 지원하지만 VPN 연결이 필요합니다. 설정하려면 GitLab Dedicated for Government 온보딩 팀에 문의합니다.

Geo 마이그레이션에는 GitLab Self-Managed 기본 인스턴스의 시크릿이 필요합니다. 그래야 마이그레이션 후에 GitLab Dedicated가 데이터를 복호화할 수 있습니다. 이 시크릿에는 데이터베이스 암호화 키, CI/CD 변수, 기타 민감한 구성 정보가 포함됩니다.

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 설치에만 해당)

마이그레이션 시크릿을 수집하고 업로드하려면 다음을 수행합니다.

  1. Switchboard에 로그인합니다.

  2. Geo migration secrets 페이지에서 설치 유형에 맞는 수집 스크립트를 다운로드합니다.

  3. 선택 사항. 오프라인 환경에서는 수집 스크립트를 실행하기 전에 age 바이너리를 스크립트에 내장합니다. 자세한 내용은 오프라인 환경을 참고합니다.

  4. 설치 유형에 맞는 수집 스크립트를 실행하고, <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 수집 스크립트 플래그를 참고합니다.

  5. 선택 사항. SSH 호스트 키만 수집하려면 명령에 --hostkeys-only 플래그를 추가합니다.

    스크립트는 다음 파일을 생성합니다.

    • migration_secrets.json.age: GitLab 시크릿(필수)
    • ssh_host_keys.json.age: SSH 호스트 키(선택 사항이지만 권장)
  6. migration_secrets.json.age 파일을 업로드합니다.

  7. 선택 사항. ssh_host_keys.json.age 파일을 업로드합니다.

  8. 검증이 완료될 때까지 기다립니다. 검증에는 파일당 약 10~20초가 걸립니다.

  9. 표시된 파일 이름과 지문이 업로드한 파일과 일치하는지 확인합니다.

Note

검증은 파일이 올바르게 암호화되어 있고 예상한 구조를 갖추고 있는지 확인합니다. 파일 내용을 복호화하거나 노출하지 않습니다.

시크릿을 업로드한 후 나머지 단계를 완료해 테넌트를 생성합니다.

Kubernetes 수집 스크립트 플래그#

기본값을 재정의하려면 collect_secrets_k8s.py에 다음 선택 플래그를 사용합니다.

플래그 기본값 설명
--namespace NAME 현재 컨텍스트 Kubernetes 네임스페이스입니다.
--release NAME gitlab Helm 릴리스 이름 접두사입니다.
--rails-secret NAME 없음 Rails 시크릿의 Secret 이름입니다.
--registry-secret NAME 없음 레지스트리 Secret 이름입니다.
--postgres-secret NAME 없음 Postgres 비밀번호 Secret 이름입니다.
--hostkeys-secret NAME 없음 SSH 호스트 키 Secret 이름입니다.

오프라인 환경#

GitLab Self-Managed 인스턴스가 인터넷에 연결되어 있지 않다면, 수집 스크립트를 실행하기 전에 age 바이너리를 스크립트에 내장합니다.

오프라인 환경용 수집 스크립트를 설정하려면 다음을 수행합니다.

  1. 인터넷에 연결된 머신에서 Geo secrets collection 프로젝트의 download_age_binaries.py와 embed_age_binary.py를 다운로드하고, Switchboard에서 내려받은 수집 스크립트와 같은 디렉터리에 둡니다.

  2. age 바이너리를 다운로드하고 인코딩합니다.

    python3 download_age_binaries.py > age_binaries.txt
    

    스크립트는 Linux AMD64와 ARM64용 base64 인코딩 age 바이너리를 표준 출력으로 출력하므로, 출력을 age_binaries.txt로 리디렉션해야 합니다.

  3. 수집 스크립트에 바이너리를 내장합니다.

    python3 embed_age_binary.py
    

    스크립트는 현재 디렉터리의 age_binaries.txt를 읽고, collect_secrets_linux_package.py와 collect_secrets_k8s.py를 바이너리가 내장된 버전으로 덮어씁니다.

  4. 업데이트된 수집 스크립트를 오프라인 환경으로 옮깁니다.

  5. 마이그레이션 시크릿 수집 및 업로드에 설명된 대로 GitLab Self-Managed 인스턴스에서 스크립트를 실행합니다.

업데이트된 스크립트는 독립적으로 동작하며 내장된 age 바이너리를 자동으로 추출해 사용합니다.

문제 해결#

Geo 마이그레이션 작업 중에 다음과 같은 문제가 발생할 수 있습니다.

오류: 수집 스크립트 실행 시 Permission denied#

수집 스크립트가 GitLab 구성 파일에 액세스할 때 권한 오류가 발생할 수 있습니다.

이 문제는 필요한 파일을 읽을 만큼 충분한 권한 없이 스크립트를 실행할 때 발생합니다.

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

  1. Linux 패키지 설치에서는 root 사용자로 스크립트를 실행하거나 sudo를 사용합니다.
  2. Kubernetes 설치에서는 kubectl 컨텍스트가 GitLab 네임스페이스에 액세스할 수 있는지 확인합니다.
  3. 필요한 파일이 예상 경로에 있는지 확인합니다.

수집 스크립트가 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

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

  1. 올바른 머신(Linux 패키지 설치에서는 Rails 노드)에서 스크립트를 실행하는지 확인합니다.
  2. GitLab이 올바르게 설치되고 구성되어 있는지 확인합니다.
  3. GitLab이 표준이 아닌 위치에 설치된 경우 구성 파일 경로가 설치 환경과 일치하는지 확인합니다.
  4. 필요한 파일이 없거나 손상된 경우, 마이그레이션을 진행하기 전에 Professional Services에 문의해 설치 상태를 점검합니다.

Geo 마이그레이션 시크릿 수집

GitLab v19.6
Tier: Ultimate
Offering: GitLab Dedicated
원문 보기

요약

GitLab Dedicated for Government는 지속적인 Geo 복제나 Geo 기반 장애 조치(failover)를 지원하지 않습니다. Geo 마이그레이션에는 GitLab Self-Managed 기본 인스턴스의 시크릿이 필요합니다.

Note

GitLab Dedicated for Government는 지속적인 Geo 복제나 Geo 기반 장애 조치(failover)를 지원하지 않습니다. 신규 테넌트 온보딩을 위한 Geo 마이그레이션은 지원하지만 VPN 연결이 필요합니다. 설정하려면 GitLab Dedicated for Government 온보딩 팀에 문의합니다.

Geo 마이그레이션에는 GitLab Self-Managed 기본 인스턴스의 시크릿이 필요합니다. 그래야 마이그레이션 후에 GitLab Dedicated가 데이터를 복호화할 수 있습니다. 이 시크릿에는 데이터베이스 암호화 키, CI/CD 변수, 기타 민감한 구성 정보가 포함됩니다.

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 설치에만 해당)

마이그레이션 시크릿을 수집하고 업로드하려면 다음을 수행합니다.

  1. Switchboard에 로그인합니다.

  2. Geo migration secrets 페이지에서 설치 유형에 맞는 수집 스크립트를 다운로드합니다.

  3. 선택 사항. 오프라인 환경에서는 수집 스크립트를 실행하기 전에 age 바이너리를 스크립트에 내장합니다. 자세한 내용은 오프라인 환경을 참고합니다.

  4. 설치 유형에 맞는 수집 스크립트를 실행하고, <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 수집 스크립트 플래그를 참고합니다.

  5. 선택 사항. SSH 호스트 키만 수집하려면 명령에 --hostkeys-only 플래그를 추가합니다.

    스크립트는 다음 파일을 생성합니다.

    • migration_secrets.json.age: GitLab 시크릿(필수)
    • ssh_host_keys.json.age: SSH 호스트 키(선택 사항이지만 권장)
  6. migration_secrets.json.age 파일을 업로드합니다.

  7. 선택 사항. ssh_host_keys.json.age 파일을 업로드합니다.

  8. 검증이 완료될 때까지 기다립니다. 검증에는 파일당 약 10~20초가 걸립니다.

  9. 표시된 파일 이름과 지문이 업로드한 파일과 일치하는지 확인합니다.

Note

검증은 파일이 올바르게 암호화되어 있고 예상한 구조를 갖추고 있는지 확인합니다. 파일 내용을 복호화하거나 노출하지 않습니다.

시크릿을 업로드한 후 나머지 단계를 완료해 테넌트를 생성합니다.

Kubernetes 수집 스크립트 플래그#

기본값을 재정의하려면 collect_secrets_k8s.py에 다음 선택 플래그를 사용합니다.

플래그 기본값 설명
--namespace NAME 현재 컨텍스트 Kubernetes 네임스페이스입니다.
--release NAME gitlab Helm 릴리스 이름 접두사입니다.
--rails-secret NAME 없음 Rails 시크릿의 Secret 이름입니다.
--registry-secret NAME 없음 레지스트리 Secret 이름입니다.
--postgres-secret NAME 없음 Postgres 비밀번호 Secret 이름입니다.
--hostkeys-secret NAME 없음 SSH 호스트 키 Secret 이름입니다.

오프라인 환경#

GitLab Self-Managed 인스턴스가 인터넷에 연결되어 있지 않다면, 수집 스크립트를 실행하기 전에 age 바이너리를 스크립트에 내장합니다.

오프라인 환경용 수집 스크립트를 설정하려면 다음을 수행합니다.

  1. 인터넷에 연결된 머신에서 Geo secrets collection 프로젝트의 download_age_binaries.py와 embed_age_binary.py를 다운로드하고, Switchboard에서 내려받은 수집 스크립트와 같은 디렉터리에 둡니다.

  2. age 바이너리를 다운로드하고 인코딩합니다.

    python3 download_age_binaries.py > age_binaries.txt
    

    스크립트는 Linux AMD64와 ARM64용 base64 인코딩 age 바이너리를 표준 출력으로 출력하므로, 출력을 age_binaries.txt로 리디렉션해야 합니다.

  3. 수집 스크립트에 바이너리를 내장합니다.

    python3 embed_age_binary.py
    

    스크립트는 현재 디렉터리의 age_binaries.txt를 읽고, collect_secrets_linux_package.py와 collect_secrets_k8s.py를 바이너리가 내장된 버전으로 덮어씁니다.

  4. 업데이트된 수집 스크립트를 오프라인 환경으로 옮깁니다.

  5. 마이그레이션 시크릿 수집 및 업로드에 설명된 대로 GitLab Self-Managed 인스턴스에서 스크립트를 실행합니다.

업데이트된 스크립트는 독립적으로 동작하며 내장된 age 바이너리를 자동으로 추출해 사용합니다.

문제 해결#

Geo 마이그레이션 작업 중에 다음과 같은 문제가 발생할 수 있습니다.

오류: 수집 스크립트 실행 시 Permission denied#

수집 스크립트가 GitLab 구성 파일에 액세스할 때 권한 오류가 발생할 수 있습니다.

이 문제는 필요한 파일을 읽을 만큼 충분한 권한 없이 스크립트를 실행할 때 발생합니다.

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

  1. Linux 패키지 설치에서는 root 사용자로 스크립트를 실행하거나 sudo를 사용합니다.
  2. Kubernetes 설치에서는 kubectl 컨텍스트가 GitLab 네임스페이스에 액세스할 수 있는지 확인합니다.
  3. 필요한 파일이 예상 경로에 있는지 확인합니다.

수집 스크립트가 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

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

  1. 올바른 머신(Linux 패키지 설치에서는 Rails 노드)에서 스크립트를 실행하는지 확인합니다.
  2. GitLab이 올바르게 설치되고 구성되어 있는지 확인합니다.
  3. GitLab이 표준이 아닌 위치에 설치된 경우 구성 파일 경로가 설치 환경과 일치하는지 확인합니다.
  4. 필요한 파일이 없거나 손상된 경우, 마이그레이션을 진행하기 전에 Professional Services에 문의해 설치 상태를 점검합니다.