Lakehouse 리전 엔드포인트

이 문서에서는 Private Service Connect 리전 엔드포인트를 사용하여 Lakehouse 런타임 카탈로그의 리소스에 액세스하는 방법을 설명합니다. 리전 엔드포인트를 사용하면 데이터 상주 및 데이터 주권 요구사항을 준수하는 방식으로 워크로드를 실행할 수 있으며, 여기서 요청 트래픽은 엔드포인트에 지정된 리전으로 직접 라우팅됩니다.

개요

리전 엔드포인트는 영향을 받는 카탈로그 리소스가 엔드포인트에서 지정된 위치에 있는 경우에만 요청 처리를 제한합니다. 예를 들어 https://biglake.us-central1.rep.googleapis.com 엔드포인트를 사용하여 카탈로그, 네임스페이스 또는 테이블에 액세스하는 경우 카탈로그가 us-central1에 있는 경우에만 요청이 진행됩니다.

리소스가 있는 곳과 다른 위치를 통해 요청을 라우팅할 수 있는 전역 엔드포인트와 달리 리전 엔드포인트는 리소스가 있는 엔드포인트에서 지정한 위치로 요청을 제한합니다. 리전 엔드포인트는 인터넷, 기타 Google Cloud 리소스(예: Compute Engine 가상 머신), Cloud VPN 또는 Cloud Interconnect를 사용하는 온프레미스 서비스, Virtual Private Cloud(VPC)에서 수신된 요청에 대해 엔드포인트에서 지정된 위치에서 전송 계층 보안(TLS) 세션을 종료합니다.

리전 엔드포인트는 전송 중인 카탈로그 요청을 엔드포인트에서 지정한 위치 내에 유지하여 데이터 레지던시를 보장하는 데 도움이 됩니다. 서비스 메타데이터 처리 방법에 대한 자세한 내용은 서비스 데이터 참고사항을 참고하세요.

Lakehouse 런타임 카탈로그의 다음 카탈로그 엔드포인트는 리전 엔드포인트와 함께 사용할 수 있습니다.

카탈로그 엔드포인트 리전 엔드포인트 URL 참조
Apache Iceberg REST 카탈로그 엔드포인트 https://biglake.LOCATION.rep.googleapis.com/iceberg/v1/restcatalog REST
Apache Hive 카탈로그 엔드포인트 (미리보기) https://biglake.LOCATION.rep.googleapis.com/hive/v1 REST

지원되는 위치

다음 위치에서 Lakehouse 런타임 카탈로그와 함께 리전 엔드포인트를 사용할 수 있습니다.

  • 아시아 태평양

    • 델리 asia-south2
    • 뭄바이 asia-south1

  • 유럽

    • 벨기에 europe-west1
    • 프랑크푸르트 europe-west3
    • 런던 europe-west2
    • 밀라노 europe-west8
    • 네덜란드 europe-west4
    • 파리 europe-west9
    • 취리히 europe-west6

  • 중동

    • 담맘 me-central2

  • 미주

    • 오하이오 주 콜럼부스 us-east5
    • 댈러스 us-south1
    • 아이오와 us-central1
    • 라스베이거스 us-west4
    • 로스앤젤레스 us-west2
    • 몬트리올 northamerica-northeast1
    • 북 버지니아 us-east4
    • 오리건 us-west1
    • 솔트레이크시티 us-west3
    • 사우스캐롤라이나 us-east1
    • 토론토 northamerica-northeast2

지원되는 작업 및 스토리지 위치

리전 엔드포인트는 엔드포인트로 지정된 위치에 복제된 카탈로그 리소스에 액세스하거나 이를 변형하는 작업을 수행하는 데만 사용할 수 있습니다.

  • 지역 카탈로그 격리: https://biglake.LOCATION.rep.googleapis.com를 통해 카탈로그를 나열하면 LOCATION에 있는 카탈로그만 반환됩니다. LOCATION 외부에 있는 카탈로그, 네임스페이스 또는 테이블을 가져오거나 업데이트하거나 삭제하는 요청은 404 NOT_FOUND 오류를 반환합니다.
  • 기본 스토리지 위치: 리전 엔드포인트를 사용하여 카탈로그를 만들 때 다중 버킷 카탈로그 (CATALOG_TYPE_BIGLAKE)의 경우 default_location에 지정된 Cloud Storage 버킷 또는 단일 버킷 카탈로그(CATALOG_TYPE_GCS_BUCKET)와 연결된 버킷이 LOCATION에 있어야 합니다.
  • 여러 버킷 카탈로그 제한된 위치: 여러 버킷 카탈로그의 경우 버킷이 LOCATION과 동일한 지리적 관할권 (예: 미국 또는 유럽) 내에 있는 한 restricted_locations에 추가 Cloud Storage 버킷을 구성할 수 있습니다. 자세한 내용은 다중 버킷 카탈로그를 참고하세요.

제한 및 제약사항

리전 엔드포인트는 다음 작업을 수행하는 데 사용할 수 없습니다.

  • 엔드포인트로 지정된 리전 외부에 있는 카탈로그, 네임스페이스 또는 테이블을 읽거나 수정하는 작업
  • 멀티 리전 엔드포인트 라우팅 (예: US 또는 EU). 리전 엔드포인트는 단일 리전을 지정해야 합니다.

리전 엔드포인트를 사용할 때 다음 제한사항에 유의하세요.

도구 및 쿼리 엔진 구성

리전 엔드포인트를 사용하도록 Google Cloud CLI, Apache Spark, Trino, 직접 REST API 요청을 구성할 수 있습니다.

gcloud CLI

gcloud biglake 명령어로 리전 엔드포인트를 사용하도록 gcloud CLI를 구성하려면 api_endpoint_overrides/biglake 속성을 사용할 리전 엔드포인트로 설정합니다.

gcloud config set api_endpoint_overrides/biglake https://biglake.LOCATION.rep.googleapis.com/

또는 개별 명령어에 대해 CLOUDSDK_API_ENDPOINT_OVERRIDES_BIGLAKE 환경 변수를 설정할 수 있습니다.

CLOUDSDK_API_ENDPOINT_OVERRIDES_BIGLAKE=https://biglake.LOCATION.rep.googleapis.com/ \
    gcloud biglake iceberg catalogs list --project=PROJECT_ID

다음을 바꿉니다.

  • LOCATION: 카탈로그에 사용할 지원되는 리전입니다 (예: us-central1).
  • PROJECT_ID: Google Cloud 프로젝트 ID입니다.

Apache Spark

Apache Iceberg REST 카탈로그 엔드포인트에 연결하도록 Spark 세션을 구성할 때는 spark.sql.catalog.CATALOG_NAME.uri 속성을 리전 엔드포인트 URL로 설정합니다.

from pyspark.sql import SparkSession

catalog_name = "CATALOG_NAME"
spark = SparkSession.builder.appName("APP_NAME") \
    .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
    .config(f'spark.sql.catalog.{catalog_name}', 'org.apache.iceberg.spark.SparkCatalog') \
    .config(f'spark.sql.catalog.{catalog_name}.type', 'rest') \
    .config(f'spark.sql.catalog.{catalog_name}.uri', 'https://biglake.LOCATION.rep.googleapis.com/iceberg/v1/restcatalog') \
    .config(f'spark.sql.catalog.{catalog_name}.warehouse', 'bl://projects/PROJECT_ID/catalogs/CATALOG_ID') \
    .config(f'spark.sql.catalog.{catalog_name}.header.x-goog-user-project', 'PROJECT_ID') \
    .config(f'spark.sql.catalog.{catalog_name}.rest.auth.type', 'org.apache.iceberg.gcp.auth.GoogleAuthManager') \
    .config(f'spark.sql.catalog.{catalog_name}.io-impl', 'org.apache.iceberg.gcp.gcs.GCSFileIO') \
    .config(f'spark.sql.catalog.{catalog_name}.header.X-Iceberg-Access-Delegation', 'vended-credentials') \
    .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
    .getOrCreate()

다음을 바꿉니다.

  • CATALOG_NAME: 로컬 Spark 카탈로그의 이름 (예: my_catalog)
  • APP_NAME: Spark 세션의 이름입니다.
  • LOCATION: 카탈로그가 있는 지원되는 지역 (예: us-central1)
  • PROJECT_ID: Google Cloud 프로젝트 ID입니다.
  • CATALOG_ID: 다중 버킷 카탈로그의 ID입니다.

구성 옵션에 관한 자세한 내용은 Apache Iceberg REST 카탈로그 엔드포인트 설정을 참고하세요.

Trino

Trino 구성요소로 Managed Service for Apache Spark 클러스터를 만들 때 trino-catalog:CATALOG_NAME.iceberg.rest-catalog.uri을 리전 엔드포인트 URL로 설정합니다.

gcloud dataproc clusters create CLUSTER_NAME \
    --enable-component-gateway \
    --region=LOCATION \
    --image-version=DATAPROC_VERSION \
    --network=NETWORK_ID \
    --optional-components=TRINO \
    --properties="\
    trino-catalog:CATALOG_NAME.connector.name=iceberg,\
    trino-catalog:CATALOG_NAME.iceberg.catalog.type=rest,\
    trino-catalog:CATALOG_NAME.iceberg.rest-catalog.uri=https://biglake.LOCATION.rep.googleapis.com/iceberg/v1/restcatalog,\
    trino-catalog:CATALOG_NAME.iceberg.rest-catalog.warehouse=bl://projects/PROJECT_ID/catalogs/CATALOG_ID,\
    trino-catalog:CATALOG_NAME.iceberg.rest-catalog.biglake.project-id=PROJECT_ID,\
    trino-catalog:CATALOG_NAME.iceberg.rest-catalog.rest.auth.type=org.apache.iceberg.gcp.auth.GoogleAuthManager"

다음을 바꿉니다.

  • CLUSTER_NAME: 클러스터 이름입니다.
  • LOCATION: 클러스터 및 카탈로그에 사용할 지원되는 지역입니다.
  • DATAPROC_VERSION: Managed Service for Apache Spark 이미지 버전 (예: 2.2)
  • NETWORK_ID: 클러스터 네트워크 ID입니다.
  • CATALOG_NAME: Trino 카탈로그의 이름입니다.
  • PROJECT_ID: Google Cloud 프로젝트 ID입니다.
  • CATALOG_ID: 다중 버킷 카탈로그의 ID입니다.

REST API

전역 엔드포인트(https://biglake.googleapis.com)에 REST 요청을 보내는 대신 다음 형식(https://biglake.LOCATION.rep.googleapis.com)으로 리전 엔드포인트에 요청을 보냅니다.

예를 들어 Apache Iceberg REST 카탈로그 엔드포인트 확장 프로그램 API를 사용하여 LOCATION의 카탈로그를 나열하려면 다음을 실행합니다.

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "x-goog-user-project: PROJECT_ID" \
    "https://biglake.LOCATION.rep.googleapis.com/iceberg/v1/restcatalog/extensions/projects/PROJECT_ID/catalogs"

전역 API 엔드포인트 사용 제한

리전 엔드포인트 사용을 강제하려면 constraints/gcp.restrictEndpointUsage 조직 정책 제약 조건을 사용하여 전역 API 엔드포인트 (biglake.googleapis.com)에 대한 요청을 차단하세요. 자세한 내용은 엔드포인트 사용 제한을 참고하세요.

다음 예시 조직 정책 YAML 파일은 전역 biglake.googleapis.com 엔드포인트에 대한 요청은 거부하지만 리전 엔드포인트에 대한 요청은 허용합니다.

name: projects/PROJECT_ID/policies/gcp.restrictEndpointUsage
spec:
  rules:
  - values:
      deniedValues:
      - under:services/biglake.googleapis.com

다음 단계