Créer un catalogue

Le catalogue d'environnements d'exécution Lakehouse vous permet de créer des points de terminaison de catalogue dans Lakehouse sans bordure.

Un point de terminaison de catalogue pointe vers un bucket Cloud Storage sous-jacent et fournit une couche de métadonnées qui permet aux moteurs de requête et aux charges de travail Open Source d'interagir directement avec vos tables. Lorsque vous créez un point de terminaison de catalogue, vous pouvez choisir entre les identifiants de l'utilisateur final et le mode de distribution d'identifiants pour la délégation de l'accès au stockage.

Avant de commencer

1. Lisez À propos du catalogue d'environnements d'exécution Lakehouse pour comprendre comment il fonctionne et quelles sont les limites du service.
Connectez-vous à votre Google Cloud compte. Si vous débutez sur Google Cloud, créez un compte pour évaluer les performances de nos produits en conditions réelles. Les nouveaux clients bénéficient également de 300 $ de crédits sans frais pour exécuter, tester et déployer des charges de travail.

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

Rôles requis

Pour obtenir les autorisations nécessaires pour créer un catalogue et enregistrer des tables, demandez à votre administrateur de vous accorder les rôles IAM suivants :

• Créer un catalogue :
  • Administrateur BigLake (roles/biglake.admin) sur votre projet
  • Administrateur de l'espace de stockage (roles/storage.admin) sur votre projet
• Créer (enregistrer) des tables : Administrateur BigLake (roles/biglake.admin) sur votre projet. L'enregistrement des tables nécessite l'autorisation spécifique d'enregistrement des tables (biglake.tables.register), qui est incluse dans le rôle d'administrateur BigLake.
• Utiliser le compte de service de catalogue provisionné automatiquement en mode de distribution d'identifiants : Utilisateur d'objets Storage (roles/storage.objectUser) sur les buckets Cloud Storage cibles. Après avoir créé le catalogue, accordez explicitement le rôle d'utilisateur d'objets Storage (roles/storage.objectUser) sur vos buckets de stockage au compte de service provisionné automatiquement.

Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Vous pouvez également obtenir les autorisations requises via des rôles personnalisés ou d'autres rôles prédéfinis.

Remarque : La création du compte de service de catalogue provisionné automatiquement est cohérente à terme, ce qui signifie qu'il faut du temps pour que le compte de service se propage dans le système. Si vous essayez d'accorder des rôles au compte de service immédiatement après sa création, la requête peut échouer. Pour connaître le temps moyen nécessaire pour que les modifications d'accès se propagent, consultez la section Propagation des modifications d'accès.

Créer un catalogue

Suivez ces étapes pour créer un catalogue en fonction du mode d'identifiants et du type de bucket de votre choix. Pour en savoir plus sur les différents types de catalogues, consultez À propos du point de terminaison du catalogue REST Apache Iceberg.

Remarque : Lorsque vous créez ou gérez un catalogue à plusieurs buckets dans Google Cloud, spécifiez des chemins d'accès Cloud Storage (gs://) pour les emplacements de stockage par défaut et restreints. Le format d'URI bl://projects/PROJECT_ID/catalogs/CATALOG_ID est utilisé exclusivement lors de la configuration du client pour identifier l'entrepôt de catalogue lors de la connexion à partir de moteurs de requête (tels qu' Apache Spark ou Trino).

Console

Créer un catalogue à plusieurs buckets (recommandé)

Cette configuration permet à votre catalogue d'associer plusieurs buckets et de le nommer indépendamment de tout nom de bucket.

1. Ouvrez la page Lakehouse dans la Google Cloud console.

   Accéder à Lakehouse

2. Cliquez sur Créer un catalogue, puis sélectionnez Catalogue d'environnements d'exécution Lakehouse.

3. Pour Type de catalogue, sélectionnez Catalogue REST Iceberg.

4. Pour Options de bucket de catalogue Lakehouse, sélectionnez Catalogue à plusieurs buckets.

5. Pour Chemin d'accès Cloud Storage du catalogue par défaut, saisissez le chemin d'accès Cloud Storage à utiliser avec votre catalogue ou recherchez-le.

6. Pour ID de catalogue, saisissez un nom personnalisé pour votre catalogue.

7. Pour Emplacement principal, sélectionnez un emplacement. L'emplacement doit se trouver à proximité des régions du bucket principal.

8. Cliquez sur Continuer.

9. À l'étape Chemins d'accès aux données , si vous souhaitez ajouter d'autres chemins d'accès Cloud Storage, cliquez sur Ajouter un chemin d'accès , puis saisissez un chemin d'accès ou recherchez-le.

10. Cliquez sur Continuer.

11. Pour Méthode d'authentification, sélectionnez Identifiants de l'utilisateur final ou Mode de distribution d'identifiants.

12. Cliquez sur Créer.

    Votre catalogue est créé et la page Détails du catalogue s'ouvre.

13. Si vous avez sélectionné Mode de distribution d'identifiants, procédez comme suit :

    1. Sous Méthode d'authentification, cliquez sur Définir les autorisations de bucket (ou Définir les autorisations pour les buckets si votre catalogue utilise plusieurs buckets).
    2. Dans la boîte de dialogue, cliquez sur Confirmer.

Créer un catalogue à bucket unique

Attention : Évitez d'utiliser la configuration à bucket unique pour les nouveaux projets. Cette configuration limite votre catalogue à un seul bucket et verrouille le nom du catalogue sur le nom du bucket.

1. Sur la page Lakehouse, cliquez sur Créer un catalogue, puis sélectionnez Catalogue d'environnements d'exécution Lakehouse.
2. Pour Type de catalogue, sélectionnez Catalogue REST Iceberg ou Hive Metastore.
3. Si vous avez sélectionné Catalogue REST Iceberg, pour Options de bucket de catalogue Lakehouse, sélectionnez Catalogue à bucket unique.
4. Pour Bucket Cloud Storage du catalogue par défaut (ou Chemin d'accès Cloud Storage du catalogue par défaut pour un point de terminaison de catalogue Apache Hive), saisissez le bucket Cloud Storage à utiliser avec votre catalogue ou recherchez-le. Pour un catalogue à bucket unique, vous ne pouvez avoir qu'un seul catalogue par bucket, et le nom du catalogue correspond au nom du bucket.
5. Cliquez sur Continuer.
6. Pour Méthode d'authentification, sélectionnez Identifiants de l'utilisateur final ou Mode de distribution d'identifiants.
7. Cliquez sur Créer.
8. Si vous avez sélectionné Mode de distribution d'identifiants, procédez comme suit :
   1. Sous Méthode d'authentification, cliquez sur Définir les autorisations de bucket.
   2. Dans la boîte de dialogue, cliquez sur Confirmer.

gcloud

Créer un catalogue à plusieurs buckets (recommandé)

Cette configuration permet à votre catalogue d'associer plusieurs buckets et de le nommer indépendamment de tout nom de bucket.

Pour créer un catalogue à plusieurs buckets (recommandé), exécutez la gcloud biglake iceberg catalogs create commande :

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]

Remplacez les éléments suivants :

• CATALOG_NAME : nom de votre catalogue. Pour les catalogues à plusieurs buckets (recommandé), il s'agit de votre nom de catalogue personnalisé.
• PROJECT_ID : ID de votre Google Cloud projet.
• DEFAULT_LOCATION: emplacement de stockage par défaut du catalogue. Vous pouvez spécifier un bucket (gs://my-bucket) ou un sous-chemin d'accès (gs://my-bucket/path). Tous les espaces de noms et toutes les tables du catalogue doivent se trouver sous le chemin d'accès spécifié. Par exemple, si vous spécifiez gs://my-bucket/path, vous ne pouvez pas créer d'espaces de noms ni de tables sous gs://my-bucket/another/path.

• CREDENTIAL_MODE : méthode d'authentification. Utilisez end-user pour les identifiants de l'utilisateur final ou vended-credentials pour le mode de distribution d'identifiants.

  Remarque : Si vous utilisez le mode de distribution d'identifiants, vous devez explicitement accorder le rôle d'utilisateur d'objets Storage (roles/storage.objectUser) sur tous les buckets de stockage associés au compte de service de catalogue d'environnements d'exécution Lakehouse provisionné automatiquement de votre catalogue.

• RESTRICTED_LOCATIONS: facultatif : liste d'emplacements de stockage supplémentaires autorisés, séparés par une virgule, au format gs://my-bucket-1/...,gs://my-bucket-2/.... Si vous spécifiez un chemin d'accès (tel que gs://my-bucket/path), tous les espaces de noms ou toutes les tables de ce bucket doivent se trouver sous ce chemin d'accès. Tous les emplacements Cloud Storage configurés dans l'emplacement par défaut et les emplacements restreints doivent se trouver dans le même groupe de régions géographiques ou la même juridiction (par exemple, les États-Unis, l'Europe, le Canada ou l'Asie). Par exemple, vous ne pouvez pas mélanger un bucket aux États-Unis avec un bucket en Europe. Pour obtenir la liste des emplacements compatibles, consultez Emplacements Lakehouse.

  Avertissement : Évitez de configurer des chemins d'accès qui se chevauchent avec d'autres catalogues pour éviter l'exposition non autorisée des identifiants. Pour en savoir plus, consultez Stockage sur plusieurs buckets.

• LOCATION: facultatif : région principale du catalogue pour assurer l'interopérabilité avec BigQuery. Pour les buckets Cloud Storage situés dans la région des États-Unis (par exemple, US ou us-central1) ou dans la région de l'UE (par exemple, EU ou europe-west4), spécifiez US ou EU, respectivement, pour vous assurer que le catalogue est accessible et disponible pour les requêtes à partir des emplacements multirégionaux BigQuery correspondants. Pour en savoir plus, consultez Régions des buckets et des catalogues.

Créer un catalogue à bucket unique

Attention : Évitez d'utiliser la configuration à bucket unique pour les nouveaux projets. Cette configuration limite votre catalogue à un seul bucket et verrouille le nom du catalogue sur le nom du bucket.

Pour créer un catalogue à bucket unique, exécutez la commande suivante :

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

Remplacez les éléments suivants :

• CATALOG_NAME : nom de votre catalogue. Pour les catalogues à bucket unique, il correspond à l'ID de bucket Cloud Storage utilisé avec le catalogue.
• PROJECT_ID : votre Google Cloud ID de projet.
• CREDENTIAL_MODE : méthode d'authentification. Utilisez end-user pour les identifiants de l'utilisateur final ou vended-credentials pour le mode de distribution d'identifiants.

REST

Créer un catalogue REST Iceberg

Pour créer un point de terminaison de gestion de catalogue à l'aide de l'API REST, envoyez une POST requête au CreateIcebergCatalog point de terminaison :

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

Le corps de la requête doit contenir une charge utile JSON IcebergCatalog définissant la configuration du catalogue, telle que l'entrepôt de bucket Cloud Storage sous-jacent et le mode d'authentification.

Remplacez les éléments suivants :

• PROJECT_ID: ID de votre Google Cloud projet.
• CATALOG_ID: ID de votre catalogue d'environnements d'exécution Lakehouse.