Crea un catálogo

La creación de un extremo de catálogo (como un extremo de catálogo de REST de Apache Iceberg o un extremo de catálogo de Apache Hive) establece un extremo de administración dentro del catálogo de entorno de ejecución de Lakehouse.

Este extremo apunta a un bucket de Cloud Storage subyacente, lo que proporciona una capa de metadatos que permite que los motores de consulta y las cargas de trabajo de código abierto interactúen directamente con tus tablas.

Cuando creas tu extremo de catálogo para Lakehouse para Apache Iceberg, puedes elegir entre las credenciales de usuario final o el modo de venta de credenciales para la delegación de acceso al almacenamiento.

Antes de comenzar

1. Lee Acerca del catálogo de entorno de ejecución de Lakehouse para comprender cómo funciona el catálogo de entorno de ejecución de Lakehouse y las limitaciones del servicio.

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.
Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

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

Roles obligatorios

Para obtener los permisos que necesitas para crear un catálogo y registrar tablas, pídele a tu administrador que te otorgue los siguientes roles de IAM:

• Crear un catálogo:
  • Administrador de BigLake (roles/biglake.admin) en tu proyecto
  • Administrador de almacenamiento (roles/storage.admin) en tu proyecto
• Registrar tablas: Administrador de BigLake (roles/biglake.admin) en tu proyecto. El registro de tablas en un catálogo de varios bucket requiere el permiso específico de registro de tablas (biglake.tables.register), que se incluye en el rol Administrador de BigLake.
• Usar la cuenta de servicio del catálogo aprovisionada automáticamente en el modo de venta de credenciales: Usuario de objetos de almacenamiento (roles/storage.objectUser) en los buckets de Cloud Storage de destino. Después de crear el catálogo, otorga de forma explícita el rol de Usuario de objetos de almacenamiento (roles/storage.objectUser) en tus buckets de almacenamiento a la cuenta de servicio aprovisionada automáticamente.

Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

También puedes obtener los permisos necesarios mediante roles personalizados o cualquier otro rol predefinido.

Nota: La creación de la cuenta de servicio del catálogo aprovisionada automáticamente es coherente en última instancia. Esto significa que la cuenta de servicio tarda en propagarse por el sistema. Si intentas otorgar roles a la cuenta de servicio inmediatamente después de la creación, es posible que la solicitud falle. Para saber cuánto tiempo tardan, en promedio, en propagarse los cambios de acceso, consulta Propagación de cambios de acceso.

Crea un catálogo

Crea un catálogo.

Console

Crea un catálogo de varios bucket (bl://) (recomendado)

Nota: Los catálogos de varios bucket (bl://) (recomendados) no son compatibles con la Google Cloud consola de. Para actualizar este tipo de catálogo, usa gcloud o la API de REST.

Crea un catálogo de un solo bucket (gs://)

1. En la Google Cloud consola de, abre la página Lakehouse.

   Ir a Lakehouse

2. Selecciona Crear catálogo. Se abrirá la página Crear catálogo.

3. Selecciona la configuración del catálogo:

   • Para crear un catálogo de REST de Apache Iceberg, selecciona Catálogo de REST de Iceberg.

4. Configura el catálogo:

   • Si eliges Catálogo de REST de Iceberg, selecciona Bucket de Cloud Storage para el tipo de catálogo y selecciona el bucket de Cloud Storage que deseas usar con tu catálogo.
   • Si eliges Catálogo de Hive, ingresa un nombre de catálogo único y selecciona la ruta de Cloud Storage asociada.

5. En Método de autenticación, selecciona Credenciales de usuario final o Modo de venta de credenciales.

   Si seleccionas Modo de venta de credenciales, la cuenta de servicio del catálogo de entorno de ejecución de Lakehouse aprovisionada automáticamente requiere el rol explícito de Usuario de objetos de almacenamiento (roles/storage.objectUser) en todos los buckets de Cloud Storage asociados. De forma predeterminada, no tiene acceso en absoluto. Sin este rol, las credenciales vendidas no tienen un alcance suficiente para realizar escrituras de almacenamiento.

6. Selecciona Crear.

   Se creará tu catálogo y se abrirá la página Detalles del catálogo.

7. En Método de autenticación, selecciona Establecer permisos del bucket.

8. En el diálogo, selecciona Confirmar.

   Esto verifica que la cuenta de servicio de tu catálogo tenga el rol de Usuario de objetos de almacenamiento (roles/storage.objectUser) en todos los buckets de almacenamiento asociados. Si creas catálogos con gcloud o Terraform, debes otorgar este rol de forma manual.

gcloud

Crea un catálogo de varios bucket (bl://) (recomendado)

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"]

Reemplaza lo siguiente:

• CATALOG_ID: El ID de tu catálogo de entorno de ejecución de Lakehouse.
• PROJECT_ID: Es el ID del Google Cloud proyecto de.
• DEFAULT_LOCATION: La ruta base de Cloud Storage para los datos y metadatos del catálogo, en el formato gs://my-bucket/path o gs://my-bucket. Todos los espacios de nombres y las tablas del catálogo deben ubicarse en esta ruta. Por ejemplo, si especificas gs://my-bucket/path, no puedes alojar espacios de nombres ni tablas en gs://my-bucket/another/path.
• RESTRICTED_LOCATIONS: (Opcional) Una lista separada por comas de buckets o rutas de almacenamiento permitidos adicionales. Del mismo modo, si especificas una ruta de acceso (como gs://my-bucket/path), todos los espacios de nombres y las tablas creados en el bucket de esa ruta deben residir en esa ruta. Advertencia de seguridad: Evita configurar rutas superpuestas con otros catálogos para evitar la exposición no autorizada de credenciales. Para obtener más información, consulta Almacenamiento en varios buckets.
• CREDENTIAL_MODE: El método de autenticación. Usa end-user para Credenciales de usuario final o vended-credentials para Modo de venta de credenciales.
• PRIMARY_LOCATION: (Opcional) La región principal del catálogo (como US o EU) para garantizar la compatibilidad con BigQuery.

Crea un catálogo de un solo bucket (gs://)

Nota: Catálogo de un solo bucket. No se recomienda usar la configuración de un solo bucket para proyectos nuevos. Esta configuración restringe tu catálogo a un solo bucket y bloquea el nombre del catálogo al nombre del bucket.

Para crear un catálogo de un solo bucket (gs://), establece --catalog-type en gcs-bucket:

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

Reemplaza lo siguiente:

• CATALOG_ID: El ID de tu catálogo de entorno de ejecución de Lakehouse. Para los catálogos de un solo bucket (gs://), debe coincidir con el nombre del bucket de Cloud Storage.
• PROJECT_ID: Es el ID del Google Cloud proyecto de.
• CREDENTIAL_MODE: El método de autenticación. Usa end-user para Credenciales de usuario final o vended-credentials para Modo de venta de credenciales.

REST

Crea un catálogo de REST de Iceberg

Para crear un extremo de administración de catálogos con la API de REST, realiza una POST solicitud al CreateIcebergCatalog extremo:

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

El cuerpo de la solicitud debe contener una carga útil JSON IcebergCatalog que defina la configuración del catálogo, como el almacén de bucket de Cloud Storage subyacente y el modo de autenticación.

Reemplaza lo siguiente:

• PROJECT_ID: Es el ID del Google Cloud proyecto de.
• CATALOG_ID: El ID de tu catálogo de entorno de ejecución de Lakehouse.