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 subyacente de Cloud Storage, lo que proporciona una capa de metadatos que permite que los motores de consultas y las cargas de trabajo de código abierto interactúen directamente con tus tablas.

Cuando crees tu extremo de catálogo para Lakehouse sin fronteras, puedes elegir entre las credenciales de usuario final o el modo de venta de credenciales para la delegación del 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.
Accede a tu cuenta de Google Cloud . Si es la primera vez que usas Google Cloud, crea una cuenta para evaluar el rendimiento de nuestros productos en situaciones reales. Los clientes nuevos también obtienen $300 en créditos gratuitos para ejecutar, probar y, además, implementar cargas de trabajo.

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, if it is not already enabled.

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.

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, if it is not already enabled.

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

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:

• Crea un catálogo:
  • Administrador de BigLake (roles/biglake.admin) en tu proyecto
  • Administrador de almacenamiento (roles/storage.admin) en tu proyecto
• Crear (registrar) tablas: Administrador de BigLake (roles/biglake.admin) en tu proyecto Para registrar tablas, se requiere el permiso específico de registro de tablas (biglake.tables.register), que se incluye en el rol de administrador de BigLake.
• Usa 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 a través de roles personalizados o cualquier otro rol predefinido.

Nota: La creación de la cuenta de servicio del catálogo aprovisionada automáticamente es eventualmente coherente. 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 crearla, 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.

Crear un catálogo

Crea un catálogo.

Crear un catálogo

Sigue estos pasos para crear un catálogo según el modo de credenciales y el tipo de bucket que prefieras. Para obtener más información sobre los diferentes tipos de catálogos, consulta Acerca del extremo del catálogo de REST de Apache Iceberg.

Nota: Cuando crees o administres un catálogo de varios bucket en Google Cloud, especifica rutas de Cloud Storage (gs://) para las ubicaciones de almacenamiento predeterminadas y restringidas. El formato de URI bl://projects/PROJECT_ID/catalogs/CATALOG_ID se usa exclusivamente durante la configuración del cliente para identificar el almacén del catálogo cuando se conecta desde motores de consultas (como Spark o Trino).

Console

Crea un catálogo de varios bucket (recomendado)

Esta configuración permite que tu catálogo asocie varios buckets y que le asignes un nombre independiente de cualquier nombre de bucket.

1. Abre la página Lakehouse en la consola de Google Cloud .

   Ir a Lakehouse

2. Haz clic en Crear catálogo.

3. En Tipo de catálogo, selecciona Catálogo de REST de Iceberg.

4. En Opciones de bucket para el catálogo de Lakehouse, selecciona Catálogo de varios buckets.

5. En Ruta de acceso predeterminada de Cloud Storage para el catálogo, ingresa o busca la ruta de acceso de Cloud Storage que se usará con tu catálogo.

6. En ID de catálogo, ingresa un nombre personalizado para tu catálogo.

7. En Ubicación principal, selecciona una ubicación. La ubicación debe estar cerca de las regiones del bucket principal.

8. Haz clic en Continuar.

9. En el paso Rutas de acceso a los datos, agrega rutas de acceso adicionales a Cloud Storage si es necesario.

10. Haz clic en Continuar.

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

12. Haz clic en Crear.

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

13. Si seleccionaste Modo de venta de credenciales, sigue estos pasos adicionales:

    1. En Método de autenticación, haz clic en Establecer permisos del bucket.
    2. En el diálogo, haz clic en Confirmar.

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

Precaución: 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 para que coincida con el nombre del bucket.

1. En Tipo de catálogo, selecciona Catálogo de REST de Iceberg o Hive Metastore.
2. En Opciones de bucket para el catálogo de Lakehouse, selecciona Catálogo de un solo bucket.
3. En Ruta de acceso predeterminada de Cloud Storage para el catálogo, ingresa o busca la ruta de acceso de Cloud Storage que se usará con tu catálogo. (En el caso de un catálogo de un solo bucket (gs://), solo puedes tener un catálogo por bucket, y el nombre del catálogo debe coincidir con el nombre del bucket).
4. Haz clic en Continuar.
5. En Método de autenticación, selecciona Credenciales de usuario final o Modo de venta de credenciales.
6. Haz clic en Crear.
7. Si seleccionaste Modo de venta de credenciales, realiza los siguientes pasos adicionales:
   1. En Método de autenticación, haz clic en Establecer permisos del bucket.
   2. En el diálogo, haz clic en Confirmar.

gcloud

Crea un catálogo con varios bucket (recomendado)

Esta configuración permite que tu catálogo asocie varios buckets y que le asignes un nombre independiente de cualquier nombre de bucket.

Para crear un catálogo de varios bucket (recomendado), ejecuta el comando 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]

Reemplaza lo siguiente:

• CATALOG_NAME: Un nombre para tu catálogo. En el caso de los catálogos con varios buckets (recomendado), este es el nombre del catálogo personalizado.
• PROJECT_ID: Es el ID del proyecto de Google Cloud.
• DEFAULT_LOCATION: Especifica la ubicación de almacenamiento predeterminada para el catálogo. Puedes especificar un bucket (gs://my-bucket) o una subruta de acceso (gs://my-bucket/path). Todos los espacios de nombres y las tablas del catálogo deben residir en la ruta de acceso especificada. Por ejemplo, si especificas gs://my-bucket/path, no puedes crear espacios de nombres ni tablas en gs://my-bucket/another/path.

• CREDENTIAL_MODE: Es el método de autenticación. Usa end-user para Credenciales del usuario final o vended-credentials para el Modo de venta de credenciales.

  Nota: Si usas el modo de venta de credenciales, debes otorgar de forma explícita el rol de usuario de objetos de almacenamiento (roles/storage.objectUser) en todos los buckets de almacenamiento asociados a la cuenta de servicio del catálogo de entorno de ejecución de Lakehouse aprovisionado automáticamente de tu catálogo.

• RESTRICTED_LOCATIONS: (Opcional) Lista separada por comas de ubicaciones de almacenamiento permitidas adicionales, en el formato gs://my-bucket-1/...,gs://my-bucket-2/.... Si especificas una ruta de acceso (como gs://my-bucket/path), todos los espacios de nombres o las tablas dentro de ese bucket deben estar en esa ruta de acceso. Todas las ubicaciones de almacenamiento en la nube configuradas en la ubicación predeterminada y las ubicaciones restringidas deben estar en el mismo grupo de regiones geográficas o jurisdicción (como Estados Unidos, Europa, Canadá o Asia). Por ejemplo, no puedes mezclar un bucket en EE.UU. con uno en Europa. Para obtener una lista de las ubicaciones compatibles, consulta Ubicaciones de Lakehouse.

  Advertencia: 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.

• LOCATION: (Opcional) Es la región principal del catálogo para garantizar la interoperabilidad con BigQuery. En el caso de los buckets de Cloud Storage en la región de EE.UU. (por ejemplo, US o us-central1) o la región de la UE (por ejemplo, EU o europe-west4), especifica US o EU, respectivamente, para garantizar que se pueda acceder al catálogo y que esté disponible para realizar consultas desde las multirregiones de BigQuery correspondientes. Para obtener más información, consulta Regiones de buckets y catálogos.

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

Precaución: 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 con el nombre del bucket.

Para crear un catálogo de un solo bucket (gs://), ejecuta el siguiente comando:

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

Reemplaza lo siguiente:

• CATALOG_NAME: Un nombre para tu catálogo. En el caso de los catálogos de un solo bucket (gs://), este valor coincide con el ID de bucket de Cloud Storage que se usa con el catálogo de REST.
• PROJECT_ID: ID del proyecto de Google Cloud.
• CREDENTIAL_MODE: Es 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 del catálogo con la API de REST, realiza una solicitud POST al extremo CreateIcebergCatalog:

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

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

Reemplaza lo siguiente:

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