Crea un catálogo

El catálogo de entorno de ejecución de Lakehouse te permite crear extremos de catálogo en Lakehouse sin bordes.

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 consultas 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 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, 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:

• 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. El registro de tablas requiere el permiso de registro de tabla específico (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 coherencia eventual. 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

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 del catálogo de REST de Apache Iceberg.

Nota: Cuando crees o administres un catálogo de varios bucket en Google Cloud, especifica las 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

Crear un catálogo de varios bucket (recomendado)

Esta configuración permite que tu catálogo asocie varios buckets y te permite nombrar tu catálogo de forma independiente de cualquier nombre de bucket.

1. Abre la página de 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 Cloud Storage para 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 datos, agrega rutas de Cloud Storage adicionales 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 Cloud Storage para 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 (recomendado)

Esta configuración permite que tu catálogo asocie varios buckets y te permite nombrar tu catálogo de forma independiente de cualquier nombre de bucket.

Para crear un catálogo de varios bucket (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: Un nombre para tu catálogo. Para los catálogos de varios bucket (recomendado), este es el nombre personalizado del catálogo.
• PROJECT_ID: tu Google Cloud ID del 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: 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) 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 o jurisdicción de región geográfica (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) 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: Un nombre para tu catálogo. Para los catálogos de un solo bucket (gs://), esto coincide con el ID de bucket de Cloud Storage que se usa con el catálogo de REST.
• PROJECT_ID: tu Google Cloud ID del proyecto.
• 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

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