Dataproc Metastore에서 Lakehouse로 메타데이터 마이그레이션

이 문서에서는 Dataproc Metastore 서비스에서 테두리 없는 레이크하우스에 빌드된 Apache Iceberg REST 카탈로그 엔드포인트 또는 Hive 카탈로그 엔드포인트로 메타데이터를 마이그레이션하는 방법을 설명합니다.

사용 사례

• 서버리스 현대화: 기존 Hive Metastore(HMS)에서 자동으로 확장되는 완전 관리형 카탈로그로 전환하여 메타스토어 관리의 운영 오버헤드를 없앱니다.
• 다중 엔진 공동작업: Apache Spark, Apache Flink, Apache Hive, BigQuery를 비롯한 여러 엔진 간에 데이터 공유를 지원하므로 데이터 과학자와 분석가가 파일 중복 없이 동일한 테이블에서 동시에 작업할 수 있습니다.
• BigQuery 직접 통합: 고성능 실행으로 BigQuery에서 직접 오픈소스 테이블을 쿼리합니다.
• 통합 거버넌스: 간소화된 데이터 탐색과 일관된 정책 적용을 위해 메타데이터를 단일 정보 소스로 통합합니다.
• 최신 테이블 형식: 기존 Hive 워크로드와의 완전한 호환성을 유지하면서 Apache Iceberg와 같은 고급 개방형 형식을 원활하게 채택합니다.

시작하기 전에

1. 활성 Dataproc Metastore 서비스가 마이그레이션 소스로 존재하는지 확인합니다.
2. 대상 Hive 카탈로그 또는 Iceberg 카탈로그가 존재하고 소스 테이블 데이터와 메타데이터가 있는 Cloud Storage 버킷 또는 경로 (예: Dataproc Metastore 웨어하우스 버킷, 예를 들어 gs://gcs-your-project-name-0825d7b3-0627-4637-8fd0-cc6271d00eb4/hive-warehouse)가 포함되어 있는지 확인합니다.

   대상 카탈로그에 데이터 위치가 포함되어 있지 않으면 대상 카탈로그에서 테이블을 등록할 수 없으므로 테이블 마이그레이션이 실패합니다. Iceberg 카탈로그를 만들려면 Iceberg REST 카탈로그 엔드포인트 설정을 참조하세요.

   Hive 카탈로그를 만들려면 Create a Lakehouse Hive catalog를 참조하세요.
계정에 로그인합니다. Google Cloud 를 처음 사용하는 경우 Google Cloud, 계정을 만들고 Google 제품의 실제 성능을 평가해 보세요. 신규 고객에게는 워크로드를 실행, 테스트, 배포하는 데 사용할 수 있는 $300의 무료 크레딧이 제공됩니다.

Verify that billing is enabled for your Google Cloud project.

Enable the Lakehouse for Apache Iceberg, Dataproc Metastore APIs.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the APIs

Verify that billing is enabled for your Google Cloud project.

Enable the Lakehouse for Apache Iceberg, Dataproc Metastore APIs.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the APIs

필요한 역할

마이그레이션을 트리거하는 데 필요한 권한을 얻으려면 관리자에게 Dataproc Metastore 서비스에 다음 IAM 역할을 부여해 달라고 요청하세요.

• 마이그레이션 시작: Dataproc Metastore 편집자 (roles/metastore.editor)
• Hive 또는 Iceberg 카탈로그 만들기: BigLake 관리자 (roles/biglake.admin)
• 대상 프로젝트를 사용하여 메타데이터를 대상 카탈로그로 마이그레이션: Dataproc Metastore 서비스 에이전트 (service-PROJECT_NUMBER@gcp-sa-metastore.iam.gserviceaccount.com)에 대한 BigLake 관리자 (roles/biglake.admin)
• 서비스 아티팩트 버킷을 사용하지 않는 경우 보고서 버킷의 마이그레이션 보고서 작성: Dataproc Metastore 서비스 에이전트(service-PROJECT_NUMBER@gcp-sa-metastore.iam.gserviceaccount.com)에 대한 스토리지 객체 관리자(roles/storage.objectAdmin)

역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

커스텀 역할이나 다른 사전 정의된 역할을 통해 필요한 권한을 얻을 수도 있습니다.

마이그레이션 작동 방식

마이그레이션 프로세스는 다음과 같이 작동합니다.

1. 대상 카탈로그 선택: 마이그레이션의 대상 Hive 카탈로그 엔드포인트 또는 Apache Iceberg REST 카탈로그 엔드포인트를 선택합니다.
2. 마이그레이션 트리거: Dataproc Metastore 서비스에서 gcloud beta metastore services migrations start 명령어를 실행하거나 startMigration 메서드를 호출하여 마이그레이션을 시작합니다.
3. 상태 폴링: gcloud beta metastore services migrations describe 명령어를 사용하거나 대상 실행을 폴링하여 마이그레이션 진행률을 모니터링합니다.
4. 보고서 검토: 지정된 Cloud Storage 경로에 작성된 상세 JSON 보고서를 검토하여 결과를 확인합니다.

마이그레이션 실행

마이그레이션을 실행하려면 마이그레이션 프로세스를 트리거한 후 진행률을 모니터링합니다.

마이그레이션 시작

Dataproc Metastore 서비스에서 메타데이터 마이그레이션을 트리거하려면 gcloud CLI 또는 REST API를 사용합니다.

gcloud beta metastore services migrations start SERVICE_ID \
    --location=REGION \
    --hive-catalog="projects/PROJECT_ID/catalogs/HIVE_CATALOG_ID" \
    --hive-databases="HIVE_DB_1,HIVE_DB_2" \
    --iceberg-catalog="projects/PROJECT_ID/catalogs/ICEBERG_CATALOG_ID" \
    --iceberg-namespaces="ICEBERG_NAMESPACE_1,ICEBERG_NAMESPACE_2" \
    --async

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{
      "migrationExecution": {
        "biglakeMetastoreMigrationConfig": {
          "mode": "BACKFILL",
          "dryRun": false,
          "reportPath": "gs://BUCKET_NAME/PATH/",
          "conflictPolicy": "SKIP",
          "hiveConfig": {
            "catalog": "projects/PROJECT_ID/catalogs/HIVE_CATALOG_ID",
            "databases": ["HIVE_DB_1", "HIVE_DB_2"]
          },
          "icebergConfig": {
            "catalog": "projects/PROJECT_ID/catalogs/ICEBERG_CATALOG_ID",
            "namespaces": ["ICEBERG_NAMESPACE_1", "ICEBERG_NAMESPACE_2"]
          }
        }
      }
    }' \
    "https://metastore.googleapis.com/v1beta/projects/PROJECT_ID/locations/REGION/services/SERVICE_ID:startMigration"

마이그레이션 실행 폴링

요청은 장기 실행 작업 (LRO)을 시작하고 고유한 마이그레이션 실행 ID를 반환합니다. gcloud CLI 또는 REST API를 사용하여 실행 진행률을 모니터링할 수 있습니다.

gcloud beta metastore services migrations describe MIGRATION_EXECUTION_ID \
    --service=SERVICE_ID \
    --location=REGION

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://metastore.googleapis.com/v1beta/projects/PROJECT_ID/locations/REGION/services/SERVICE_ID/migrationExecutions/MIGRATION_EXECUTION_ID"

상세 마이그레이션 보고서

마이그레이션 (백필 또는 드라이 런)이 완료되면 마이그레이션 도구는 두 개의 상세 JSON 보고서 파일을 MigrationReport 스키마를 기반으로 reportPath에 지정된 대상 Cloud Storage 경로에 작성합니다.

• summary.json: 상위 수준 집계 MigrationSummary 구조를 포함합니다.
• full_report.json: 상세하고 세분화된 마이그레이션 보고서를 포함합니다. 자세한 내용은 CatalogReport를 참조하세요.

제한사항

• 대상 카탈로그에는 소스 테이블 데이터와 메타데이터가 있는 Cloud Storage 버킷 또는 경로 (예: Dataproc Metastore 웨어하우스 버킷)가 포함되어야 합니다. 대상 카탈로그가 데이터 버킷 위치로 구성되지 않은 경우 대상 카탈로그에서 테이블을 등록할 수 없으며 테이블 마이그레이션이 실패합니다.
• 이 도구는 일회성 백필만 지원합니다. 마이그레이션 후 소스 Dataproc Metastore에 대한 메타데이터 변경사항은 자동으로 전파되지 않습니다. 마이그레이션을 다시 실행하여 대상 카탈로그를 소스와 동기화해야 합니다.
• 마이그레이션은 대상 카탈로그의 제한사항에 따라 달라집니다. Dataproc Metastore 테이블에 대상 카탈로그에서 지원하지 않는 스키마 구조 또는 속성 (예: 복잡한 유형)이 포함되어 있으면 특정 테이블의 마이그레이션이 실패합니다.
• 테이블 또는 데이터베이스에 대한 Dataproc Metastore 권한은 레이크하우스로 마이그레이션되지 않습니다.

다음 단계

• 레이크하우스 런타임 카탈로그에 대해 자세히 알아보세요.
• 레이크하우스 런타임 카탈로그로 Spark 및 Hive를 설정하는 방법을 알아보세요.
• 레이크하우스 런타임 카탈로그, Spark, BigQuery로 Iceberg 테이블을 쿼리하는 방법을 알아보세요.