Dataproc Metastore 서비스에서 경계 없는 레이크하우스에 빌드된 Apache Iceberg REST 카탈로그 엔드포인트 또는 Hive 카탈로그 엔드포인트로 메타데이터를 마이그레이션할 수 있습니다. 이 마이그레이션을 통해 개방형 테이블 형식으로 현대화하고 여러 분석 엔진에서 카탈로그 액세스를 통합할 수 있습니다.
사용 사례
- 서버리스 현대화: 기존 Hive Metastore(HMS)에서 자동으로 확장되는 관리형 카탈로그로 전환하여 메타스토어 관리 오버헤드를 없앨 수 있습니다.
- 멀티 엔진 공동작업: Apache Spark, Apache Flink, Apache Hive, BigQuery를 비롯한 여러 엔진에서 데이터를 공유하므로 데이터 과학자와 분석가가 파일 중복 없이 동일한 테이블에서 동시에 작업할 수 있습니다.
- BigQuery 직접 통합: BigQuery에서 직접 오픈소스 테이블을 쿼리합니다.
- 통합 거버넌스: 데이터 검색 및 일관된 정책 시행을 위해 메타데이터를 단일 정보 소스로 통합합니다.
- 최신 테이블 형식: 기존 Hive 워크로드와의 호환성을 유지하면서 Apache Iceberg와 같은 개방형 형식을 채택합니다.
시작하기 전에
- 활성 Dataproc Metastore 서비스가 마이그레이션 소스로 존재하는지 확인합니다.
- 대상 Hive 카탈로그 또는 Iceberg 카탈로그가 존재하고 소스 테이블 데이터 및 메타데이터가 있는 Cloud Storage 버킷 또는 경로(예: Dataproc Metastore 웨어하우스 버킷(예:
gs://gcs-your-project-name-0825d7b3-0627-4637-8fd0-cc6271d00eb4/hive-warehouse))를 포함하는지 확인합니다.대상 카탈로그에 데이터 위치가 포함되지 않은 경우 대상 카탈로그에서 테이블을 등록할 수 없으므로 테이블 마이그레이션이 실패합니다. Iceberg 카탈로그 생성은 Iceberg REST 카탈로그 엔드포인트 설정을 참조하세요.
Hive 카탈로그를 만들려면 레이크하우스 Hive 카탈로그 만들기를 참조하세요. - Google Cloud 계정에 로그인합니다. Google Cloud를 처음 사용하는 경우 계정을 만들고 Google 제품의 실제 성능을 평가해 보세요. 신규 고객에게는 워크로드를 실행, 테스트, 배포하는 데 사용할 수 있는 $300의 무료 크레딧이 제공됩니다.
-
Verify that billing is enabled for your Google Cloud project.
Enable the Lakehouse, Dataproc Metastore APIs, if any are not already enabled.
Roles required to enable APIs
To enable APIs, you need the
serviceusage.services.enablepermission. 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.-
Verify that billing is enabled for your Google Cloud project.
Enable the Lakehouse, Dataproc Metastore APIs, if any are not already enabled.
Roles required to enable APIs
To enable APIs, you need the
serviceusage.services.enablepermission. 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.
필요한 역할
마이그레이션을 트리거하는 데 필요한 권한을 얻으려면 관리자에게 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)
역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.
커스텀 역할이나 다른 사전 정의된 역할을 통해 필요한 권한을 얻을 수도 있습니다.
이전 작동 방식
이전 프로세스는 다음과 같이 작동합니다.
- 대상 카탈로그 선택: 마이그레이션의 대상 Hive 카탈로그 엔드포인트 또는 Apache Iceberg REST 카탈로그 엔드포인트를 선택합니다.
- 마이그레이션 트리거:
gcloud metastore services migrations start명령어를 실행하거나 Dataproc Metastore 서비스에서startMigration메서드를 호출하여 마이그레이션을 시작합니다. - 상태 폴링:
gcloud metastore services migrations describe명령어를 사용하거나 대상 실행을 폴링하여 마이그레이션 진행 상황을 모니터링합니다. - 보고서 검토: 지정된 Cloud Storage 경로에 작성된 세부 JSON 보고서를 검토하여 결과를 확인합니다.
이전 실행하기
마이그레이션을 실행하려면 마이그레이션 프로세스를 트리거한 후 진행 상황을 모니터링합니다.
마이그레이션 시작
Dataproc Metastore 서비스에서 메타데이터 마이그레이션을 트리거하려면 Google Cloud 콘솔, gcloud CLI 또는 REST API를 사용합니다.
콘솔
Google Cloud 콘솔에서 Dataproc Metastore 페이지로 이동합니다.
메타스토어 서비스 목록에서 마이그레이션할 서비스 이름을 클릭합니다.
서비스 세부정보 페이지의 상단 탐색 메뉴에서 Lakehouse로 마이그레이션을 클릭합니다.
마이그레이션 이름에 마이그레이션의 표시 이름을 입력합니다.
마이그레이션 유형에서 백필 마이그레이션을 선택하여 마이그레이션을 수행하거나 드라이 런을 선택하여 대상 카탈로그에 메타데이터를 쓰지 않고 마이그레이션을 검증합니다.
대상 설정을 구성합니다.
- 보고서: (선택사항) 마이그레이션 상태 보고서를 저장할 Cloud Storage 경로를 선택합니다. 지정하지 않으면 Dataproc Metastore 서비스의 아티팩트 버킷에 보고서가 생성됩니다.
- 충돌 처리: 중복 데이터베이스 항목을 건너뛰거나 덮어쓸지 선택합니다.
대상에서 마이그레이션할 카탈로그 유형(Iceberg REST 카탈로그 엔드포인트 또는 Hive metastore)을 선택합니다. 소스 데이터베이스에서 마이그레이션해야 하는 테이블 유형에 따라 한 번에 하나의 카탈로그 또는 두 카탈로그 모두로 마이그레이션할 수 있습니다.
Iceberg REST 카탈로그로 마이그레이션하는 경우:
- 프로젝트에서 마이그레이션할 카탈로그가 포함된 프로젝트를 선택합니다.
- Iceberg REST 카탈로그에서 마이그레이션할 카탈로그를 선택하거나 카탈로그 만들기를 클릭하여 새 카탈로그를 만듭니다.
Hive 카탈로그로 마이그레이션하는 경우:
- 프로젝트에서 마이그레이션할 카탈로그가 포함된 프로젝트를 선택합니다.
- Hive 카탈로그에서 마이그레이션할 카탈로그를 선택하거나 카탈로그 만들기를 클릭하여 새 카탈로그를 만듭니다.
마이그레이션 시작을 클릭합니다.
마이그레이션 탭으로 자동 리디렉션됩니다. 관리형 마이그레이션 아래에 마이그레이션이 나열되고 마이그레이션이 완료될 때까지 상태가 계속 업데이트됩니다.
gcloud
gcloud를 사용하여 마이그레이션을 시작하려면 gcloud metastore
services migrations
start 명령어를 실행합니다.
gcloud 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
다음을 바꿉니다.
SERVICE_ID: Dataproc Metastore 서비스의 ID입니다.REGION: Dataproc Metastore 서비스의 리전입니다.PROJECT_ID: Google Cloud 프로젝트 IDHIVE_CATALOG_ID: 대상 Hive 카탈로그 IDHIVE_DB_1,HIVE_DB_2: 마이그레이션할 Hive 데이터베이스입니다.ICEBERG_CATALOG_ID: 대상 Iceberg 카탈로그 IDICEBERG_NAMESPACE_1,ICEBERG_NAMESPACE_2: 마이그레이션할 Iceberg 네임스페이스입니다.
REST
REST API를 사용하여 메타데이터 마이그레이션을 트리거하려면 BigLakeMetastoreMigrationConfig 구성으로 startMigration 메서드를 호출합니다.
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/v1/projects/PROJECT_ID/locations/REGION/services/SERVICE_ID:startMigration"
다음을 바꿉니다.
BUCKET_NAME: 보고서의 Cloud Storage 버킷 이름PATH: 보고서의 버킷 경로PROJECT_ID: Google Cloud 프로젝트 IDHIVE_CATALOG_ID: 대상 Hive 카탈로그 IDHIVE_DB_1,HIVE_DB_2: 마이그레이션할 Hive 데이터베이스입니다.ICEBERG_CATALOG_ID: 대상 Iceberg 카탈로그 IDICEBERG_NAMESPACE_1,ICEBERG_NAMESPACE_2: 마이그레이션할 Iceberg 네임스페이스입니다.REGION: Dataproc Metastore 서비스의 리전입니다.SERVICE_ID: Dataproc Metastore 서비스의 ID입니다.
마이그레이션 실행 폴링
이 요청은 장기 실행 작업(LRO)을 시작하고 고유한 마이그레이션 실행 ID를 반환합니다. gcloud CLI 또는 REST API를 사용하여 실행 진행 상황을 모니터링할 수 있습니다.
gcloud
gcloud를 사용하여 마이그레이션 실행을 설명하려면 gcloud
metastore services migrations
describe 명령어를 실행합니다.
gcloud metastore services migrations describe MIGRATION_EXECUTION_ID \
--service=SERVICE_ID \
--location=REGION
다음을 바꿉니다.
MIGRATION_EXECUTION_ID: 이전 단계에서 반환된 마이그레이션 실행 ID입니다.SERVICE_ID: Dataproc Metastore 서비스의 ID입니다.REGION: Dataproc Metastore 서비스의 리전입니다.
REST
REST API를 사용하여 실행 진행 상황을 모니터링하려면 해당 실행 경로에서 get 메서드를 호출합니다.
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://metastore.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/services/SERVICE_ID/migrationExecutions/MIGRATION_EXECUTION_ID"
다음을 바꿉니다.
PROJECT_ID: Google Cloud 프로젝트 IDREGION: Dataproc Metastore 서비스의 리전입니다.SERVICE_ID: Dataproc Metastore 서비스의 ID입니다.MIGRATION_EXECUTION_ID: 이전 단계에서 반환된 마이그레이션 실행 ID입니다.
상세 이전 보고서
마이그레이션 (백필 또는 드라이 런)이 완료되면 마이그레이션 도구는 MigrationReport 스키마를 기반으로 하는 두 개의 세부 JSON 보고서 파일을 reportPath에 지정된 대상 Cloud Storage 경로에 작성합니다.
summary.json: 상위 수준의 집계된MigrationSummary구조를 포함합니다.full_report.json: 더 세분화된 상세 이전 보고서가 포함되어 있습니다. 자세한 내용은CatalogReport을 참조하세요.
Google Cloud 콘솔에서 보고서를 보려면 다음 단계를 따르세요.
Google Cloud 콘솔에서 Dataproc Metastore 페이지로 이동합니다.
메타스토어 서비스 목록에서 보고서가 포함된 서비스의 표시 이름을 클릭합니다.
마이그레이션 페이지가 열립니다.
관리형 마이그레이션에서 보고서가 포함된 마이그레이션 이름을 선택합니다.
마이그레이션 세부정보 페이지가 열리고 마이그레이션된 데이터베이스 및 테이블과 마이그레이션 상태에 대한 세부정보가 표시됩니다.
제한사항
- 대상 카탈로그에는 소스 테이블 데이터 및 메타데이터가 있는 Cloud Storage 버킷 또는 경로 (예: Dataproc Metastore 웨어하우스 버킷)가 포함되어야 합니다. 대상 카탈로그가 데이터 버킷 위치로 구성되지 않은 경우 대상 카탈로그에서 테이블을 등록할 수 없고 테이블 마이그레이션이 실패합니다.
- 이 도구는 일회성 백필만 지원합니다. 마이그레이션 후 소스 Dataproc Metastore의 메타데이터 변경사항은 자동으로 전파되지 않습니다. 대상 카탈로그를 소스와 동기화하려면 마이그레이션을 다시 실행해야 합니다.
- 마이그레이션은 대상 카탈로그의 제한사항에 따라 제한됩니다. Dataproc Metastore 테이블에 대상 카탈로그에서 지원하지 않는 스키마 구조 또는 속성 (예: 복합 유형)이 포함된 경우 해당 특정 테이블의 마이그레이션이 실패합니다.
- 테이블 또는 데이터베이스에 대한 Dataproc Metastore 권한은 레이크하우스로 마이그레이션되지 않습니다.
다음 단계
- Lakehouse 런타임 카탈로그 자세히 알아보기
- Lakehouse 런타임 카탈로그를 사용하여 Spark 및 Hive를 설정하는 방법을 알아보세요.
- Lakehouse 런타임 카탈로그, Spark, BigQuery를 사용하여 Iceberg 테이블을 쿼리하는 방법 알아보기