Crea un catálogo

Crear 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 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.
Accede a tu Google Cloud cuenta de. 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.

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.

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:

• Crear 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 en un catálogo de varios bucket, se 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 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 el tiempo. Esto significa que la cuenta de servicio tarda en propagarse a través del 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.

Crear un catálogo

Crea un catálogo.

Crear un catálogo

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

Console

Crear un catálogo de varios bucket (bl://) (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 Google Cloud console.

   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 del 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 de datos, agrega rutas de acceso adicionales de 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 crea tu catálogo y se abre la página Detalles del catálogo.

13. 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.

Crear 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 al nombre del bucket.

1. En Tipo de catálogo, selecciona Catálogo de REST de Iceberg o Metastore de Hive.
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. (Para un catálogo de un solo bucket (gs://), solo puedes tener un catálogo por bucket, y el nombre del catálogo coincide 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

Crear un catálogo de varios bucket (bl://) (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 (bl://) (recomendado), ejecuta el gcloud biglake iceberg catalogs create comando.

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 (bl://) (recomendado), este es el nombre personalizado del catálogo.
• PROJECT_ID: Es el ID de tu Google Cloud proyecto.
• 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 de usuario final o vended-credentials para Modo de venta de credenciales.

  Nota: Si usas el Modo de venta de credenciales, debes otorgar de forma explícita el rol 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 aprovisionada automáticamente.

• RESTRICTED_LOCATIONS: (Opcional) Es una 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 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 en EE.UU. con un bucket en 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) Es 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.

Crear 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 al 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: Es un nombre para tu catálogo. Para los catálogos de un solo bucket (gs://), este coincide con el ID de bucket de Cloud Storage que se usa con el catálogo de REST.
• PROJECT_ID: Es el ID del proyecto. 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

Crear 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 de tu Google Cloud proyecto.
• CATALOG_ID: Es el ID de tu catálogo de entorno de ejecución de Lakehouse.