Google Cloud CLI를 사용하여 Lakehouse에서 Iceberg 테이블 만들기 및 쿼리
경계 없는 레이크하우스를 사용하면Google Cloud 및 Apache Spark, Trino, Apache Flink와 같은 오픈소스 엔진에서 Apache Iceberg 테이블을 공유할 수 있습니다. Lakehouse 런타임 카탈로그는 Apache Iceberg REST 카탈로그 엔드포인트를 통해 스키마, 스냅샷, Cloud Storage 위치를 포함한 메타데이터를 추적합니다.
이 빠른 시작에서는 Google Cloud CLI를 사용하여 멀티 버킷 카탈로그를 구성하고 Managed Service for Apache Spark에서 PySpark 작업을 실행합니다. 작업에서 Iceberg 테이블을 만든 후에는 데이터를 이동하거나 등록하지 않고 4단계로 구성된 P.C.N.T (Project.Catalog.Namespace.Table) 문법을 사용하여 BigQuery에서 직접 쿼리합니다.
시작하기 전에
- Google Cloud 계정에 로그인합니다. Google Cloud를 처음 사용하는 경우 계정을 만들고 Google 제품의 실제 성능을 평가해 보세요. 신규 고객에게는 워크로드를 실행, 테스트, 배포하는 데 사용할 수 있는 $300의 무료 크레딧이 제공됩니다.
-
Google Cloud CLI를 설치합니다.
-
외부 ID 공급업체 (IdP)를 사용하는 경우 먼저 제휴 ID로 gcloud CLI에 로그인해야 합니다.
-
gcloud CLI를 초기화하려면, 다음 명령어를 실행합니다.
gcloud init -
Google Cloud 프로젝트를 만들거나 선택합니다.
프로젝트를 선택하거나 만드는 데 필요한 역할
- 프로젝트 선택: 프로젝트를 선택하는 데 특정 IAM 역할이 필요하지 않습니다. 역할이 부여된 모든 프로젝트를 선택할 수 있습니다.
-
프로젝트 만들기: 프로젝트를 만들려면
resourcemanager.projects.create권한이 포함된 프로젝트 생성자 역할(roles/resourcemanager.projectCreator)이 필요합니다. 역할 부여 방법 알아보기
-
Google Cloud 프로젝트를 만듭니다.
gcloud projects create PROJECT_ID
PROJECT_ID를 만들려는 Google Cloud 프로젝트의 이름으로 바꿉니다. -
만든 Google Cloud 프로젝트를 선택합니다.
gcloud config set project PROJECT_ID
PROJECT_ID을 Google Cloud 프로젝트 이름으로 바꿉니다.
BigLake, Managed Service for Apache Spark, Cloud Storage, BigQuery, Compute Engine API가 아직 사용 설정되지 않은 경우 사용 설정합니다.
API 사용 설정에 필요한 역할
API를 사용 설정하려면
serviceusage.services.enable권한이 필요합니다. 프로젝트를 만든 경우 소유자 역할 (roles/owner)을 통해 이 권한이 이미 있을 수 있습니다. 그렇지 않으면 서비스 사용량 관리자 역할 (roles/serviceusage.serviceUsageAdmin)을 통해 이 권한을 얻을 수 있습니다. 역할 부여 방법 알아보기gcloud services enable biglake.googleapis.com
dataproc.googleapis.com storage.googleapis.com bigquery.googleapis.com compute.googleapis.com -
사용자 계정에 역할을 부여합니다. 다음 각 IAM 역할에 대해 다음 명령어를 한 번씩 실행합니다.
roles/biglake.admin, roles/storage.admin, roles/dataproc.editor, roles/resourcemanager.projectIamAdmin, roles/bigquery.jobUsergcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_IDENTIFIER" --role=ROLE
다음을 바꿉니다.
PROJECT_ID: 프로젝트 ID입니다.USER_IDENTIFIER: 사용자 계정의 식별자입니다. 예를 들면myemail@example.com입니다.ROLE: 사용자 계정에 부여하는 IAM 역할입니다.
-
Google Cloud CLI를 설치합니다.
-
외부 ID 공급업체 (IdP)를 사용하는 경우 먼저 제휴 ID로 gcloud CLI에 로그인해야 합니다.
-
gcloud CLI를 초기화하려면, 다음 명령어를 실행합니다.
gcloud init -
Google Cloud 프로젝트를 만들거나 선택합니다.
프로젝트를 선택하거나 만드는 데 필요한 역할
- 프로젝트 선택: 프로젝트를 선택하는 데 특정 IAM 역할이 필요하지 않습니다. 역할이 부여된 모든 프로젝트를 선택할 수 있습니다.
-
프로젝트 만들기: 프로젝트를 만들려면
resourcemanager.projects.create권한이 포함된 프로젝트 생성자 역할(roles/resourcemanager.projectCreator)이 필요합니다. 역할 부여 방법 알아보기
-
Google Cloud 프로젝트를 만듭니다.
gcloud projects create PROJECT_ID
PROJECT_ID를 만들려는 Google Cloud 프로젝트의 이름으로 바꿉니다. -
만든 Google Cloud 프로젝트를 선택합니다.
gcloud config set project PROJECT_ID
PROJECT_ID을 Google Cloud 프로젝트 이름으로 바꿉니다.
BigLake, Managed Service for Apache Spark, Cloud Storage, BigQuery, Compute Engine API가 아직 사용 설정되지 않은 경우 사용 설정합니다.
API 사용 설정에 필요한 역할
API를 사용 설정하려면
serviceusage.services.enable권한이 필요합니다. 프로젝트를 만든 경우 소유자 역할 (roles/owner)을 통해 이 권한이 이미 있을 수 있습니다. 그렇지 않으면 서비스 사용량 관리자 역할 (roles/serviceusage.serviceUsageAdmin)을 통해 이 권한을 얻을 수 있습니다. 역할 부여 방법 알아보기gcloud services enable biglake.googleapis.com
dataproc.googleapis.com storage.googleapis.com bigquery.googleapis.com compute.googleapis.com -
사용자 계정에 역할을 부여합니다. 다음 각 IAM 역할에 대해 다음 명령어를 한 번씩 실행합니다.
roles/biglake.admin, roles/storage.admin, roles/dataproc.editor, roles/resourcemanager.projectIamAdmin, roles/bigquery.jobUsergcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_IDENTIFIER" --role=ROLE
다음을 바꿉니다.
PROJECT_ID: 프로젝트 ID입니다.USER_IDENTIFIER: 사용자 계정의 식별자입니다. 예를 들면myemail@example.com입니다.ROLE: 사용자 계정에 부여하는 IAM 역할입니다.
환경 설정 및 버킷 만들기
Cloud Shell을 열고 PySpark 스크립트와 Iceberg 테이블 데이터를 보관할 Cloud Storage 버킷을 만듭니다.
Google Cloud 콘솔에서 Cloud Shell 활성화를 클릭합니다.
메시지가 표시되면 승인을 클릭합니다.
이 빠른 시작에서 재사용할 수 있도록 프로젝트, 리전, 버킷, 카탈로그 이름의 환경 변수를 설정합니다.
export PROJECT_ID=$(gcloud config get-value project) export REGION="us-central1" export BUCKET_NAME="${PROJECT_ID}-lakehouse-quickstart" export LAKEHOUSE_CATALOG_ID="quickstart_catalog"선택한 리전에 Cloud Storage 버킷을 만듭니다.
gcloud storage buckets create gs://${BUCKET_NAME} \ --project=${PROJECT_ID} \ --location=${REGION}
Spark 서비스 계정에 권한 부여
기본적으로 Managed Service for Apache Spark는 프로젝트의 Compute Engine 기본 서비스 계정을 사용하여 일괄 작업을 실행합니다. 이 서비스 계정에 다음 IAM 역할을 부여하여 Cloud Storage에서 PySpark 스크립트를 읽고 Lakehouse 런타임 카탈로그 및 BigQuery와 상호작용할 수 있도록 합니다.
| 역할 | 리소스 | 목적 |
|---|---|---|
| Dataproc 작업자 ( roles/dataproc.worker) |
프로젝트 | Managed Service for Apache Spark 일괄 워크로드를 실행합니다. |
| 서비스 사용량 소비자 ( roles/serviceusage.serviceUsageConsumer) |
프로젝트 | 프로젝트 API 및 할당량을 사용합니다. |
| BigLake 편집자 ( roles/biglake.editor) |
프로젝트 | 카탈로그 리소스를 만들고 공급된 스토리지 사용자 인증 정보를 요청합니다. |
| BigQuery 데이터 편집자 ( roles/bigquery.dataEditor) |
프로젝트 | 테이블의 BigQuery 메타데이터를 관리합니다. |
| 스토리지 객체 뷰어 ( roles/storage.objectViewer) |
버킷 | Cloud Storage 버킷에서 PySpark 스크립트를 읽습니다. |
Spark 서비스 계정에는 PySpark 스크립트를 읽기 위한 스토리지 객체 뷰어 역할 (roles/storage.objectViewer)만 필요합니다. 작업이 실행될 때 Lakehouse 런타임 카탈로그가 임시 테이블 범위 쓰기 사용자 인증 정보를 제공하므로 버킷에 대한 직접 쓰기 액세스 권한이 필요하지 않습니다.
Cloud Shell에서 다음 스크립트를 실행하여 이러한 역할을 부여합니다.
PROJECT_NUMBER=$(gcloud projects describe ${PROJECT_ID} \
--format='value(projectNumber)')
SPARK_SA="${PROJECT_NUMBER}-compute@developer.gserviceaccount.com"
for ROLE in \
"roles/dataproc.worker" \
"roles/serviceusage.serviceUsageConsumer" \
"roles/biglake.editor" \
"roles/bigquery.dataEditor"; do
gcloud projects add-iam-policy-binding ${PROJECT_ID} \
--member="serviceAccount:${SPARK_SA}" \
--role="${ROLE}"
done
gcloud storage buckets add-iam-policy-binding gs://${BUCKET_NAME} \
--member="serviceAccount:${SPARK_SA}" \
--role="roles/storage.objectViewer"Lakehouse 런타임 카탈로그에서 카탈로그 만들기
Apache Iceberg 테이블의 Lakehouse 런타임 카탈로그에 카탈로그를 만듭니다.
Cloud Shell에서 멀티 버킷 카탈로그를 만듭니다. 다중 버킷 카탈로그를 사용하면 버킷 이름과 관계없이 카탈로그 이름을 지정하고 여러 Cloud Storage 버킷을 단일 카탈로그와 연결할 수 있습니다. Lakehouse 런타임 카탈로그가 사용자를 대신하여 Spark에 임시 스토리지 사용자 인증 정보를 안전하게 발급할 수 있도록 사용자 인증 정보 제공 모드를 사용 설정합니다.
gcloud biglake iceberg catalogs create ${LAKEHOUSE_CATALOG_ID} \ --project=${PROJECT_ID} \ --catalog-type=biglake \ --default-location=gs://${BUCKET_NAME} \ --credential-mode=vended-credentials
카탈로그에 버킷에 대한 액세스 권한을 부여합니다.
사용자 인증 정보 제공을 사용하면 카탈로그의 자동 프로비저닝된 서비스 계정에 버킷에 대한 스토리지 객체 사용자 역할 (
roles/storage.objectUser)이 필요하므로 클라이언트 엔진의 임시 액세스 토큰을 생성할 수 있습니다.# Retrieve the auto-provisioned catalog service account email CATALOG_SA=$(gcloud biglake iceberg catalogs describe ${LAKEHOUSE_CATALOG_ID} \ --project=${PROJECT_ID} \ --format='value(biglake-service-account)') # Grant the Storage Object User role to the catalog service account on your bucket gcloud storage buckets add-iam-policy-binding gs://${BUCKET_NAME} \ --member="serviceAccount:${CATALOG_SA}" \ --role="roles/storage.objectUser"
PySpark 작업으로 Iceberg 테이블 만들기
카탈로그와 권한이 준비되면 Managed Service for Apache Spark에서 PySpark 작업을 실행하여 Iceberg 테이블을 만들고 샘플 데이터를 삽입할 수 있습니다.
PySpark 스크립트 만들기 및 업로드
Cloud Shell에서
quickstart.py이라는 파일을 만듭니다.cat << 'EOF' > quickstart.py from pyspark.sql import SparkSession spark = SparkSession.builder.appName("quickstart").getOrCreate() # Create a namespace spark.sql("CREATE NAMESPACE IF NOT EXISTS `quickstart_catalog`.quickstart_namespace") # Create the table spark.sql(""" CREATE OR REPLACE TABLE `quickstart_catalog`.quickstart_namespace.quickstart_table ( id INT, name STRING ) USING iceberg """) # Insert data into the table spark.sql(""" INSERT INTO `quickstart_catalog`.quickstart_namespace.quickstart_table VALUES (1, 'one'), (2, 'two'), (3, 'three') """) EOF이 스크립트는 Spark 세션을 시작하고
quickstart_namespace라는 네임스페이스와quickstart_table라는 Iceberg 테이블을 만들고 샘플 데이터 3행을 삽입합니다. SQL 문은 버킷 경로 (LOCATION)를 지정하지 않으므로 Lakehouse 런타임 카탈로그는 네임스페이스 및 테이블 파일을 카탈로그의--default-location버킷(gs://${BUCKET_NAME})에 자동으로 저장합니다.Managed Service for Apache Spark에서 액세스할 수 있도록
quickstart.py를 Cloud Storage 버킷에 복사합니다.gcloud storage cp quickstart.py gs://${BUCKET_NAME}/quickstart.py
PySpark 스크립트 실행
PySpark 스크립트를 Managed Service for Apache Spark 일괄 작업으로 제출합니다. 이 작업은 클러스터를 프로비저닝할 필요 없이 사전 설치된 Iceberg 라이브러리를 사용하여 코드를 실행합니다.
--properties 플래그는 Apache Iceberg REST 카탈로그 엔드포인트를 사용하여 Lakehouse 런타임 카탈로그의 카탈로그에 연결하도록 Spark를 구성합니다.
Cloud Shell에서 일괄 작업을 제출합니다.
gcloud dataproc batches submit pyspark gs://${BUCKET_NAME}/quickstart.py \ --project=${PROJECT_ID} \ --region=${REGION} \ --version=2.2 \ --properties="spark.sql.catalog.quickstart_catalog=org.apache.iceberg.spark.SparkCatalog,\ spark.sql.catalog.quickstart_catalog.type=rest,\ spark.sql.catalog.quickstart_catalog.uri=https://biglake.googleapis.com/iceberg/v1/restcatalog,\ spark.sql.catalog.quickstart_catalog.warehouse=bl://projects/${PROJECT_ID}/catalogs/${LAKEHOUSE_CATALOG_ID},\ spark.sql.catalog.quickstart_catalog.io-impl=org.apache.iceberg.gcp.gcs.GCSFileIO,\ spark.sql.catalog.quickstart_catalog.header.x-goog-user-project=${PROJECT_ID},\ spark.sql.catalog.quickstart_catalog.rest.auth.type=org.apache.iceberg.gcp.auth.GoogleAuthManager,\ spark.sql.extensions=org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions,\ spark.sql.catalog.quickstart_catalog.header.X-Iceberg-Access-Delegation=vended-credentials,\ spark.sql.catalog.quickstart_catalog.gcs.oauth2.refresh-credentials-endpoint=https://oauth2.googleapis.com/token"
표준 Iceberg 설정 (
SparkCatalog,type=rest,IcebergSparkSessionExtensions) 외에도 다음 속성은 Lakehouse 런타임 카탈로그 연결을 구성합니다.uri및warehouse(bl://...): Spark를 Lakehouse 런타임 카탈로그 Apache Iceberg REST 카탈로그 엔드포인트에 연결하고 요청을 멀티 버킷 카탈로그로 라우팅합니다.rest.auth.type및header.x-goog-user-project: Spark 서비스 계정의 사용자 인증 정보를 사용하여 REST 요청을 인증하고 API 할당량을 프로젝트에 청구합니다.header.X-Iceberg-Access-Delegation,io-impl,gcs.oauth2.refresh-credentials-endpoint: 카탈로그에서 임시로 제공되는 Cloud Storage 사용자 인증 정보를 요청하고 Iceberg의GCSFileIO클라이언트를 구성하여 해당 토큰을 사용해 데이터 파일을 작성합니다.
이러한 설정에 대한 자세한 내용은 클라이언트 애플리케이션 구성 및 Apache Iceberg Spark 구성 문서를 참조하세요.
작업이 완료되면 출력은 다음과 비슷합니다.
Batch [cb9d84e9489d408baca4f9e7ab4c64ff] finished. metadata: '@type': type.googleapis.com/google.cloud.dataproc.v1.BatchOperationMetadata batch: projects/PROJECT_ID/locations/us-central1/batches/cb9d84e9489d408baca4f9e7ab4c64ff batchUuid: 54b0b9d2-f0a1-4fdf-ae44-eead3f8e60e9 createTime: '2026-01-24T00:10:50.224097Z' description: Batch labels: goog-dataproc-batch-id: cb9d84e9489d408baca4f9e7ab4c64ff goog-dataproc-batch-uuid: 54b0b9d2-f0a1-4fdf-ae44-eead3f8e60e9 goog-dataproc-drz-resource-uuid: batch-54b0b9d2-f0a1-4fdf-ae44-eead3f8e60e9 goog-dataproc-location: us-central1 operationType: BATCH name: projects/PROJECT_ID/regions/us-central1/operations/32287926-5f61-3572-b54a-fbad8940d6ef
BigQuery에서 테이블 쿼리
Spark가 Iceberg 테이블을 작성했으므로 이제 4단계로 구성된 P.C.N.T(Project.Catalog.Namespace.Table) 문법을 사용하여 BigQuery에서 바로 쿼리할 수 있습니다.
Cloud Shell에서 다음
bq query명령어를 실행합니다.bq query --project_id=${PROJECT_ID} --location=${REGION} --use_legacy_sql=false \ "SELECT * FROM \`${PROJECT_ID}.${LAKEHOUSE_CATALOG_ID}.quickstart_namespace.quickstart_table\`"출력에는 PySpark 작업으로 삽입한 세 개의 행이 표시됩니다.
+----+-------+ | id | name | +----+-------+ | 1 | one | | 2 | two | | 3 | three | +----+-------+
Lakehouse 런타임 카탈로그는 Iceberg 메타데이터를 추적하고 스토리지 액세스를 처리하므로 Spark가 스냅샷을 커밋하는 즉시 BigQuery가 Cloud Storage의 기본 파일을 읽습니다.
이 시점에서 Trino, Flink, 자체 관리형 Spark 클러스터와 같은 다른 Iceberg 호환 엔진을 사용하여 quickstart_table에서 읽거나 쓸 수도 있습니다. 카탈로그에서 사용자 인증 정보 판매가 사용 설정되어 있으므로 외부 엔진은 테이블을 읽기 위해 프로젝트에 대한 BigLake 뷰어 역할 (roles/biglake.viewer)만 필요하거나 데이터를 쓰고 새 스냅샷을 커밋하기 위해 BigLake 편집자 역할 (roles/biglake.editor)이 필요합니다. 다른 엔진을 연결하는 방법은 Apache Iceberg REST 카탈로그 엔드포인트 설정을 참조하세요.
삭제
Google Cloud 계정에 불필요한 요금이 청구되지 않도록 하려면 이 빠른 시작에서 만든 리소스를 삭제합니다. 테이블, 네임스페이스, 카탈로그를 삭제하면 Lakehouse 런타임 카탈로그에서 메타데이터 등록이 삭제되고, 버킷을 삭제하면 Cloud Storage에 저장된 기본 Parquet 데이터와 Iceberg 메타데이터 파일이 삭제됩니다.
Cloud Shell에서 카탈로그의 테이블을 삭제합니다.
gcloud biglake iceberg tables delete quickstart_table \ --project=${PROJECT_ID} \ --catalog=${LAKEHOUSE_CATALOG_ID} \ --namespace=quickstart_namespace \ --quiet카탈로그에서 네임스페이스를 삭제합니다.
gcloud biglake iceberg namespaces delete quickstart_namespace \ --project=${PROJECT_ID} \ --catalog=${LAKEHOUSE_CATALOG_ID} \ --quiet카탈로그를 삭제합니다.
gcloud biglake iceberg catalogs delete ${LAKEHOUSE_CATALOG_ID} \ --project=${PROJECT_ID} --quietCloud Storage 버킷과 모든 콘텐츠를 삭제합니다.
gcloud storage rm -r gs://${BUCKET_NAME}
다음 단계
- Google Cloud 콘솔을 사용하여 Iceberg 테이블 만들기 및 쿼리 빠른 시작을 통해 UI에서 네임스페이스와 Iceberg 테이블을 만들고 BigQuery 데이터 조작 언어 (DML)를 사용하여 데이터를 수정해 보세요.
- 크로스 클라우드 데이터 액세스 설정 Codelab을 사용해 ETL 없이 Amazon Web Services (AWS), PostgreSQL용 AlloyDB, Cloud Storage에서 데이터를 쿼리해 보세요.
- 여러 버킷 카탈로그 및 Apache Iceberg REST 카탈로그 엔드포인트 알아보기
- Lakehouse 런타임 카탈로그에서 카탈로그를 관리하는 방법 알아보기
- Lakehouse에서 관리하는 Apache Iceberg 테이블 알아보기