카탈로그 만들기

카탈로그 엔드포인트 (예: Apache Iceberg REST 카탈로그 엔드포인트 또는 Apache Hive 카탈로그 엔드포인트)를 만들면 레이크하우스 런타임 카탈로그 내에 관리 엔드포인트가 설정됩니다.

이 엔드포인트는 기본 Cloud Storage 버킷을 가리키며, 쿼리 엔진과 오픈소스 워크로드가 테이블과 직접 상호작용할 수 있는 메타데이터 레이어를 제공합니다.

Lakehouse for Apache Iceberg의 카탈로그 엔드포인트를 만들 때 스토리지 액세스 위임을 위해 최종 사용자 사용자 인증 정보 또는 사용자 인증 정보 벤딩 모드 중에서 선택할 수 있습니다.

시작하기 전에

  1. 레이크하우스 런타임 카탈로그 정보를 읽고 레이크하우스 런타임 카탈로그의 작동 방식과 서비스의 제한사항을 알아보세요.
    2. Google Cloud 계정에 로그인합니다. Google Cloud를 처음 사용하는 경우 계정을 만들고 Google 제품의 실제 성능을 평가해 보세요. 신규 고객에게는 워크로드를 실행, 테스트, 배포하는 데 사용할 수 있는 $300의 무료 크레딧이 제공됩니다.

    In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

    Verify that billing is enabled for your Google Cloud project.

    Enable the BigLake API.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the API

    In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

    Verify that billing is enabled for your Google Cloud project.

    Enable the BigLake API.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the API

필요한 역할

카탈로그를 만들고 테이블을 등록하는 데 필요한 권한을 얻으려면 관리자에게 다음 IAM 역할을 부여해 달라고 요청하세요.

  • 카탈로그 만들기:
  • 테이블 등록: 프로젝트에 대한 BigLake 관리자 (roles/biglake.admin) 다중 버킷 카탈로그에 테이블을 등록하려면 BigLake 관리자 역할에 포함된 특정 테이블 등록 권한 (biglake.tables.register)이 필요합니다.
  • 인증 정보 제공 모드에서 자동 프로비저닝된 카탈로그 서비스 계정을 사용합니다. 대상 Cloud Storage 버킷에 대한 스토리지 객체 사용자 (roles/storage.objectUser) 카탈로그를 만든 후 스토리지 버킷에 대한 스토리지 객체 사용자 역할 (roles/storage.objectUser)을 자동 프로비저닝된 서비스 계정에 명시적으로 부여합니다.

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

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

카탈로그 만들기

카탈로그를 만듭니다.

콘솔

다중 버킷 (bl://) 카탈로그 만들기 (권장)

단일 버킷 (gs://) 카탈로그 만들기

  1. Google Cloud 콘솔에서 Lakehouse 페이지를 엽니다.

    레이크하우스로 이동

  2. 카탈로그 만들기를 선택합니다. 카탈로그 만들기 페이지가 열립니다.

  3. 카탈로그 구성을 선택합니다.

    • Apache Iceberg REST 카탈로그를 만들려면 Iceberg REST 카탈로그를 선택합니다.

  4. 카탈로그를 구성합니다.

    • Iceberg REST 카탈로그를 선택하는 경우 카탈로그 유형으로 Cloud Storage 버킷을 선택하고 카탈로그와 함께 사용할 Cloud Storage 버킷을 선택합니다.
    • Hive 카탈로그를 선택하는 경우 고유한 카탈로그 이름을 입력하고 연결된 Cloud Storage 경로를 선택합니다.

  5. 인증 방법에서 최종 사용자 인증 정보 또는 사용자 인증 정보 벤더 제공 모드를 선택합니다.

    인증 정보 판매 모드를 선택하면 자동 프로비저닝된 Lakehouse 런타임 카탈로그 서비스 계정에 연결된 모든 Cloud Storage 버킷에 대한 명시적 스토리지 객체 사용자 역할 (roles/storage.objectUser)이 필요합니다. 기본적으로 액세스 권한이 전혀 없습니다. 이 역할이 없으면 제공된 사용자 인증 정보에 저장소 쓰기를 실행할 범위가 충분하지 않습니다.

  6. 만들기를 선택합니다.

    카탈로그가 생성되고 카탈로그 세부정보 페이지가 열립니다.

  7. 인증 방법에서 버킷 권한 설정을 선택합니다.

  8. 대화상자에서 확인을 선택합니다.

    이렇게 하면 연결된 모든 스토리지 버킷에 카탈로그의 서비스 계정에 스토리지 객체 사용자 역할 (roles/storage.objectUser)이 있는지 확인됩니다. gcloud 또는 Terraform을 사용하여 카탈로그를 만드는 경우 이 역할을 수동으로 부여해야 합니다.

gcloud

다중 버킷 (bl://) 카탈로그 만들기 (권장)

gcloud biglake iceberg catalogs create CATALOG_ID \
    --project="PROJECT_ID" \
    --catalog-type="biglake" \
    --default-location="DEFAULT_LOCATION" \
    [--restricted-locations="RESTRICTED_LOCATIONS"] \
    [--credential-mode="CREDENTIAL_MODE"] \
    [--primary-location="PRIMARY_LOCATION"]

다음을 바꿉니다.

  • CATALOG_ID: Lakehouse 런타임 카탈로그의 ID입니다.
  • PROJECT_ID: Google Cloud 프로젝트 ID입니다.
  • DEFAULT_LOCATION: 카탈로그 데이터 및 메타데이터의 기본 Cloud Storage 경로(gs://my-bucket/path 또는 gs://my-bucket 형식) 카탈로그의 모든 네임스페이스와 테이블은 이 경로 아래에 있어야 합니다. 예를 들어 gs://my-bucket/path를 지정하면 gs://my-bucket/another/path 아래에 네임스페이스나 테이블을 호스팅할 수 없습니다.
  • RESTRICTED_LOCATIONS: (선택사항) 허용된 추가 스토리지 버킷 또는 경로의 쉼표로 구분된 목록입니다. 마찬가지로 gs://my-bucket/path와 같은 경로를 지정하면 해당 경로의 버킷 아래에 생성된 모든 네임스페이스와 테이블이 해당 경로 내에 있어야 합니다. 보안 경고: 무단 사용자 인증 정보 노출을 방지하려면 다른 카탈로그와 중복되는 경로를 구성하지 마세요. 자세한 내용은 여러 버킷에 걸친 스토리지를 참고하세요.
  • CREDENTIAL_MODE: 인증 방법입니다. 최종 사용자 인증 정보의 경우 end-user를 사용하고 사용자 인증 정보 벤더 제공 모드의 경우 vended-credentials를 사용합니다.
  • PRIMARY_LOCATION: (선택사항) BigQuery와의 호환성을 보장하기 위한 카탈로그의 기본 리전입니다 (예: US 또는 EU).

단일 버킷 (gs://) 카탈로그 만들기

단일 버킷 (gs://) 카탈로그를 만들려면 --catalog-type을 gcs-bucket로 설정하세요.

gcloud biglake iceberg catalogs create CATALOG_ID \
    --project="PROJECT_ID" \
    --catalog-type="gcs-bucket" \
    [--credential-mode="CREDENTIAL_MODE"]

다음을 바꿉니다.

  • CATALOG_ID: Lakehouse 런타임 카탈로그의 ID입니다. 단일 버킷 (gs://) 카탈로그의 경우 Cloud Storage 버킷 이름과 일치해야 합니다.
  • PROJECT_ID: Google Cloud 프로젝트 ID입니다.
  • CREDENTIAL_MODE: 인증 방법입니다. 최종 사용자 인증 정보의 경우 end-user를 사용하고 사용자 인증 정보 벤더 제공 모드의 경우 vended-credentials를 사용합니다.

REST

Iceberg REST 카탈로그 만들기

REST API를 사용하여 카탈로그 관리 엔드포인트를 만들려면 CreateIcebergCatalog 엔드포인트에 POST 요청을 수행합니다.

POST /iceberg/v1/restcatalog/extensions/projects/PROJECT_ID/catalogs?icebergCatalogId=CATALOG_ID

요청 본문에는 기본 Cloud Storage 버킷 데이터 웨어하우스 및 인증 모드와 같은 카탈로그 구성을 정의하는 IcebergCatalog JSON 페이로드가 포함되어야 합니다.

다음을 바꿉니다.

  • PROJECT_ID: Google Cloud 프로젝트 ID입니다.
  • CATALOG_ID: Lakehouse 런타임 카탈로그의 ID입니다.