Crea un catálogo

El catálogo de tiempo de ejecución de Lakehouse te permite crear extremos de catálogo en Lakehouse sin límites.

Un extremo de catálogo apunta a un bucket de Cloud Storage subyacente y 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 un extremo de catálogo, puedes elegir entre las credenciales de usuario final y el modo de venta de credenciales para la delegación de acceso al almacenamiento.

Antes de comenzar

1. Lee Acerca del catálogo de tiempo de ejecución de Lakehouse para comprender cómo funciona y las limitaciones del servicio.
Accede a tu cuenta de Google Cloud . Si eres nuevo en 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
• Crea (registra) 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 coherente de forma eventual, lo que 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

Sigue estos pasos para crear un catálogo según el modo de credencial 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 REST de Apache Iceberg.

Nota: Cuando crees o administres un catálogo de varios bucket en Google Cloud, especifica las rutas de acceso 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 consulta (como Apache Spark o Trino).

Console

Crea un catálogo de varios bucket (recomendado)

Esta configuración permite que tu catálogo asocie varios buckets y te permite asignarle un nombre a tu catálogo de forma 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 y, luego, selecciona Catálogo de tiempo de ejecución de Lakehouse.

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 usarás 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, si quieres agregar rutas de acceso adicionales a Cloud Storage, haz clic en Agregar ruta de acceso y, luego, ingresa o busca una ruta de acceso.

10. Haz clic en Continuar.

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

    Nota: Si seleccionas Credenciales de usuario final, el catálogo de tiempo de ejecución de Lakehouse no administra automáticamente las tablas del catálogo. No puedes habilitar las tareas de administración de tablas, como la compactación y el vencimiento de instantáneas.

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 (o Establecer permisos para los buckets si tu catálogo usa más de un bucket).
    2. En el cuadro de diálogo, haz clic en Confirmar.

Crea un catálogo de un solo bucket

Precaución: Evita 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 del bucket.

1. En la página Lakehouse, haz clic en Crear catálogo y, luego, selecciona Catálogo de tiempo de ejecución de Lakehouse.
2. En Tipo de catálogo, selecciona Catálogo de REST de Iceberg o Hive Metastore.
3. Si seleccionaste Catálogo de REST de Iceberg, en Opciones de bucket para el catálogo de Lakehouse, selecciona Catálogo de bucket único.
4. En Bucket de Cloud Storage del catálogo predeterminado (o Ruta de acceso predeterminada de Cloud Storage para el catálogo para un extremo de catálogo de Apache Hive), ingresa o busca el bucket de Cloud Storage que usarás con tu catálogo. Para un catálogo de un solo bucket, solo puedes tener un catálogo por bucket, y el nombre del catálogo coincide con el nombre del bucket.
5. Haz clic en Continuar.
6. En Método de autenticación, selecciona Credenciales de usuario final o Modo de venta de credenciales.
7. Haz clic en Crear.
8. 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 cuadro de diálogo, haz clic en Confirmar.

gcloud

Crea un catálogo de varios bucket (recomendado)

Esta configuración permite que tu catálogo asocie varios buckets y te permite asignarle un nombre a tu catálogo de forma 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: Es un nombre para tu catálogo. Para los catálogos de varios bucket (recomendado), este es el nombre de tu catálogo personalizado.
• PROJECT_ID: Es el ID del proyecto de Google Cloud.
• DEFAULT_LOCATION: Es la ubicación de almacenamiento predeterminada para el catálogo. Puedes especificar un bucket (gs://my-bucket) o una ruta de acceso secundaria (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 las credenciales de usuario final o vended-credentials para el modo de venta de credenciales. Si especificas end-user, el catálogo de tiempo de ejecución de Lakehouse no administra automáticamente las tablas en el catálogo. No puedes habilitar las tareas de administración de tablas, como la compactación y el vencimiento de instantáneas.

  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 tiempo de ejecución de Lakehouse aprovisionada automáticamente de tu catálogo.

• RESTRICTED_LOCATIONS: opcional, una lista separada por comas de ubicaciones de almacenamiento adicionales permitidas, en el formato gs://my-bucket-1/...,gs://my-bucket-2/.... Si especificas una ruta de acceso (como gs://my-bucket/path), los espacios de nombres o las tablas dentro de ese bucket deben estar en esa ruta de acceso. Todas las ubicaciones de Cloud Storage 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 de EE.UU. con uno de Europa. Para obtener una lista de las ubicaciones compatibles, consulta Ubicaciones de Lakehouse.

  Advertencia: Evita configurar rutas de acceso 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: la región principal del catálogo para garantizar la interoperabilidad con BigQuery. Para 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

Precaución: Evita 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 del bucket.

Para crear un catálogo de un solo bucket, 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: Es un nombre para tu catálogo. En el caso de los catálogos de un solo bucket, este coincide con el ID de bucket de Cloud Storage que se usa con el catálogo.
• PROJECT_ID: Es el ID del proyecto de Google Cloud.
• CREDENTIAL_MODE: Es el método de autenticación. Usa end-user para las credenciales de usuario final o vended-credentials para el modo de venta de credenciales.

REST

Crea un extremo de catálogo de REST de Apache Iceberg

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

POST /iceberg/v1/restcatalog/extensions/projects/PROJECT_ID/catalogs?iceberg-catalog-id=CATALOG_ID

El cuerpo de la solicitud debe contener una carga útil de JSON IcebergCatalog que defina la configuración del catálogo, como el almacén del bucket de Cloud Storage subyacente 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 de tiempo de ejecución de Lakehouse.