카탈로그 만들기

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

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

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

시작하기 전에

  1. Lakehouse 런타임 카탈로그 정보를 읽고 Lakehouse 런타임 카탈로그의 작동 방식과 서비스 제한사항을 파악합니다.
    2. 계정에 로그인합니다. Google Cloud 를 처음 사용하는 경우 Google Cloud 계정을 만들어 실제 시나리오에서 제품이 어떻게 작동하는지 평가합니다. 신규 고객에게는 워크로드를 실행, 테스트, 배포하는 데 사용할 수 있는 $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 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 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 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 API

필요한 역할

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

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

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

커스텀 역할 또는 기타 사전 정의된 역할을 통해 필요한 권한을 얻을 수도 있습니다.

카탈로그 만들기

카탈로그를 만듭니다.

카탈로그 만들기

선호하는 사용자 인증 정보 모드 및 버킷 유형에 따라 다음 단계에 따라 카탈로그를 만듭니다. 다양한 카탈로그 유형에 대한 자세한 내용은 Apache Iceberg REST 카탈로그 엔드포인트 정보를 참조하세요.

콘솔

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

이 구성을 사용하면 카탈로그가 여러 버킷을 연결하고 버킷 이름과 독립적으로 카탈로그 이름을 지정할 수 있습니다.

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

    Lakehouse로 이동

  2. 카탈로그 만들기 를 클릭합니다.

  3. 카탈로그 유형에서 Iceberg Rest 카탈로그를 선택합니다.

  4. Lakehouse 카탈로그 버킷 옵션에서 여러 버킷 카탈로그를 선택합니다.

  5. 기본 카탈로그 Cloud Storage 경로에서 카탈로그에 사용할 Cloud Storage 경로를 입력하거나 찾아봅니다.

  6. 카탈로그 ID에 카탈로그의 커스텀 이름을 입력합니다.

  7. 기본 위치에서 위치를 선택합니다. 위치는 기본 버킷의 리전과 가까워야 합니다.

  8. 계속 을 클릭합니다.

  9. 필요한 경우 데이터 경로 단계에서 추가 Cloud Storage 경로를 추가합니다.

  10. 계속 을 클릭합니다.

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

  12. 만들기 를 클릭합니다.

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

  13. 사용자 인증 정보 벤더 제공 모드를 선택한 경우 다음 추가 단계를 수행합니다.

    1. 인증 방법에서 버킷 권한 설정을 클릭합니다.
    2. 대화상자에서 확인 을 클릭합니다.

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

  1. 카탈로그 유형에서 Iceberg Rest 카탈로그 또는 Hive Metastore를 선택합니다.
  2. Lakehouse 카탈로그 버킷 옵션에서 단일 버킷 카탈로그를 선택합니다.
  3. 기본 카탈로그 Cloud Storage 경로에서 카탈로그에 사용할 Cloud Storage 경로를 입력하거나 찾아봅니다. 단일 버킷(gs://) 카탈로그의 경우 버킷당 하나의 카탈로그만 있을 수 있으며 카탈로그 이름은 버킷 이름과 일치합니다.
  4. 계속 을 클릭합니다.
  5. 인증 방법에서 최종 사용자 인증 정보 또는 사용자 인증 정보 벤더 제공 모드를 선택합니다.
  6. 만들기 를 클릭합니다.
  7. 사용자 인증 정보 벤더 제공 모드를 선택한 경우 다음 추가 단계를 수행합니다.
    1. 인증 방법에서 버킷 권한 설정을 클릭합니다.
    2. 대화상자에서 확인 을 클릭합니다.

gcloud

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

이 구성을 사용하면 카탈로그가 여러 버킷을 연결하고 버킷 이름과 독립적으로 카탈로그 이름을 지정할 수 있습니다.

여러 버킷 (bl://) 카탈로그 (권장)를 만들려면 gcloud biglake iceberg catalogs create 명령어를 실행합니다.

gcloud biglake iceberg catalogs create \
    CATALOG_NAME \
    --project PROJECT_ID \
    --catalog-type biglake \
    --default-location DEFAULT_LOCATION \
    --credential-mode CREDENTIAL_MODE \
    [--restricted-locations RESTRICTED_LOCATIONS] \
    [--primary-location LOCATION]

다음을 바꿉니다.

  • CATALOG_NAME: 카탈로그의 이름입니다. 여러 버킷 (bl://) 카탈로그 (권장)의 경우 이는 커스텀 카탈로그 이름입니다.
  • PROJECT_ID: Google Cloud프로젝트 ID입니다.
  • DEFAULT_LOCATION: 카탈로그의 기본 스토리지 위치를 지정합니다. 버킷 (gs://my-bucket) 또는 하위 경로 (gs://my-bucket/path)를 지정할 수 있습니다. 카탈로그의 모든 네임스페이스와 테이블은 지정된 경로 아래에 있어야 합니다. 예를 들어 gs://my-bucket/path를 지정하면 gs://my-bucket/another/path 아래에 네임스페이스 또는 테이블을 만들 수 없습니다.

  • CREDENTIAL_MODE: 인증 방법입니다. 최종 사용자 인증 정보 에는 end-user를 사용하고 사용자 인증 정보 벤더 제공 모드 에는 vended-credentials를 사용합니다.

    참고: 사용자 인증 정보 벤더 제공 모드를 사용하는 경우 연결된 모든 스토리지 버킷에 대한 스토리지 객체 사용자 역할 (roles/storage.objectUser)을 카탈로그의 자동 프로비저닝된 Lakehouse 런타임 카탈로그 서비스 계정에 명시적으로 부여해야 합니다.

  • RESTRICTED_LOCATIONS: (선택사항) 허용되는 추가 스토리지 위치의 쉼표로 구분된 목록입니다(형식: gs://my-bucket-1/...,gs://my-bucket-2/...). 경로(예: gs://my-bucket/path)를 지정하면 해당 버킷 내의 모든 네임스페이스 또는 테이블이 해당 경로 아래에 있어야 합니다. 기본 위치와 제한된 위치에 구성된 모든 Cloud Storage 위치는 동일한 지리적 리전 그룹 또는 관할권 (예: 미국, 유럽, 캐나다 또는 아시아)에 있어야 합니다. 예를 들어 미국의 버킷과 유럽의 버킷을 혼합할 수 없습니다. 지원되는 위치 목록은 Lakehouse 위치를 참조하세요.

    경고: 무단 사용자 인증 정보 노출을 방지하려면 다른 카탈로그와 겹치는 경로를 구성하지 마세요. 자세한 내용은 여러 버킷의 스토리지를 참조하세요.

  • LOCATION: (선택사항) BigQuery와의 상호 운용성을 보장하는 카탈로그의 기본 리전입니다. 미국 리전 (예: US 또는 us-central1) 또는 EU 리전 (예: EU 또는 europe-west4)의 Cloud Storage 버킷의 경우 카탈로그에 액세스할 수 있고 해당 BigQuery 멀티 리전에서 쿼리할 수 있도록 각각 US 또는 EU를 지정합니다. 자세한 내용은 버킷 및 카탈로그 리전을 참조하세요.

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

단일 버킷 (gs://) 카탈로그를 만들려면 다음 명령어를 실행합니다.

gcloud biglake iceberg catalogs create \
    CATALOG_NAME \
    --project PROJECT_ID \
    --catalog-type gcs-bucket \
    --credential-mode CREDENTIAL_MODE

다음을 바꿉니다.

  • CATALOG_NAME: 카탈로그의 이름입니다. 단일 버킷 (gs://) 카탈로그의 경우 이는 REST 카탈로그에 사용되는 Cloud Storage 버킷 ID와 일치합니다.
  • PROJECT_ID: Google Cloud프로젝트 ID입니다.
  • CREDENTIAL_MODE: 인증 방법입니다. _최종 사용자 인증 정보_ end-user에는 end-user를 사용하고vended-credentials _사용자 인증 정보 벤더 제공 모드_에는 vended-credentials를 사용합니다.

REST

Iceberg REST 카탈로그 만들기

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

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입니다.