Activer la fédération de catalogue Google Cloud Lakehouse

info

Bêta

Cette fonctionnalité est en bêta. Les administrateurs de Workspace peuvent contrôler l'accès à cette fonctionnalité à partir de la page Aperçus . Voir Gérer les prévisualisations Databricks.

La fédération de catalogues Google Cloud Lakehouse permet à Unity Catalog de lire les tables Iceberg Google Cloud Lakehouse directement depuis le stockage cloud, ce qui peut offrir de meilleures performances et un coût inférieur à la fédération de queries.

Avec la fédération de catalogue, Unity Catalog accède directement à la table Iceberg du Google Cloud Lakehouse dans Google Cloud Storage (GCS), et la query s’exécute entièrement sur le compute Databricks. Les tables étrangères dans un catalogue Google Cloud Lakehouse sont en lecture seule.

La fédération Lakehouse sur Google Cloud utilise un type de connexion GOOGLE_CLOUD_LAKEHOUSE dédié. Il s'agit d'un type de connexion distinct de la fédération de query BigQuery.

Lorsque vous créez un catalogue étranger, vous spécifiez le chemin d'accès au warehouse Google Cloud Lakehouse. Unity Catalog découvre les espaces de noms et les tables sous ce warehouse et les mappe dans l'espace de noms standard à trois niveaux d'Unity Catalog :

Objet Google Cloud Lakehouse	Nom Unity Catalog
Warehouse	`<foreign-catalog>`
Espace de noms	`<foreign-catalog>.<schema>`
Table	`<foreign-catalog>.<schema>.<table>`

Par exemple, si vous fédérez un warehouse avec l'espace de noms analytics contenant la table orders, la table apparaît dans Unity Catalog sous la forme <foreign-catalog>.analytics.orders.

Avant de commencer

Examinez les exigences suivantes avant de configurer la fédération de catalogue Google Cloud Lakehouse.

Exigences du Workspace :

La fédération Lakehouse sur Google Cloud n'est prise en charge que sur les Workspace Databricks sur Google Cloud.
Le workspace doit être activé pour Unity Catalog. Consultez start Unity Catalog.
Comme cette fonctionnalité est en version bêta, un administrateur de workspace doit l’activer depuis la page Previews . Consultez Gérer les aperçus Databricks.

Exigences de compute :

Le compute Databricks doit utiliser Databricks Runtime 19 ou une version ultérieure.

Databricks Runtime 19 est un environnement d'exécution unifié qui reçoit des fonctionnalités sous forme de mises à jour datées plutôt que sous forme de nouvelles versions mineures. Voir Databricks Runtime 19.
Les SQL Warehouse doivent être Pro ou Serverless.
Les clusters dédiés (anciennement clusters mono-utilisateur) ne sont pas pris en charge. Consultez les limitations.

Exigences réseau :

Si vous appliquez des contrôles de service Virtual Private Cloud (VPC) Service Controls ou des règles de pare-feu dans Google Cloud, vous devez ajouter les plages d’adresses IP de sortie Databricks à la liste d’autorisation pour le plan de contrôle et le plan de données. Voir Recommandations réseau pour Lakehouse Federation.

Autorisations requises :

Pour créer une connexion, vous devez être administrateur de métastore ou un utilisateur disposant du privilège CREATE CONNECTION sur le métastore Unity Catalog attaché au workspace.
Pour créer un catalogue étranger, vous devez disposer de l’autorisation CREATE CATALOG sur le métastore. Vous devez également être propriétaire de la connexion ou disposer du privilège CREATE FOREIGN CATALOG sur celle-ci.
Pour saisir les chemins autorisés pour le catalogue étranger, vous devez disposer du privilège CREATE FOREIGN SECURABLE sur un emplacement externe qui couvre ces chemins. Le propriétaire de l'emplacement externe dispose de ce privilège default.

Chaque section basée sur les tâches qui suit précise les exigences en matière d'autorisations supplémentaires.

Étape 1 : Configurer les ressources Google Cloud

Effectuez les étapes suivantes dans Google Cloud. Aucune action Databricks n’est requise à cette étape.

Créez un warehouse Google Cloud Lakehouse.

Créez le warehouse et sélectionnez ou créez un compartiment GCS pour le prendre en charge. Par exemple, un warehouse pris en charge par le compartiment my-warehouse a pour chemin d'accès gs://my-warehouse.
Créer des tables Iceberg dans le warehouse.

Utilisez n'importe quel moteur compatible Iceberg, tel que Spark, Flink ou BigQuery SQL. Vérifiez que les tables sont lisibles depuis BigQuery. Par exemple :
SQL
```
SELECT * FROM `PROJECT_ID.NAMESPACE.TABLE`;
```
Créez deux comptes de service avec le moindre privilège.

Les rôles de gestion des identités et des accès (IAM) de Google Cloud Lakehouse utilisent l’espace de noms biglake ; les rôles figurant dans le tableau suivant apparaissent donc sous BigLake dans la console Google Cloud.

Compte de service	Usage	Rôles IAM requis
Compte de service de connexion	Lit les métadonnées du catalogue.	`roles/biglake.viewer` sur le projet.
Compte de service de stockage	Lit les données de table dans GCS.	`roles/storage.objectViewer` sur le compartiment GCS. Ajoutez `roles/bigquery.dataViewer` si les tables sont gérées par BigQuery.

Compte de service	Usage	Rôles IAM requis
Compte de service de connexion	Lit les métadonnées du catalogue.	`roles/biglake.viewer` sur le projet.
Compte de service de stockage	Lit les données de table dans GCS.	`roles/storage.objectViewer` sur le compartiment GCS. Ajoutez `roles/bigquery.dataViewer` si les tables sont gérées par BigQuery.

Générez une clé JSON pour le compte de service de connexion.

Dans la console Google Cloud, générez et download une clé JSON pour le compte de service de connexion. Vous fournissez cette clé lorsque vous créez la connexion Unity Catalog à l'étape Étape 2 : Créer une connexion. Stockez la clé de manière sécurisée.

Pour obtenir des instructions sur la création de comptes de service, l’attribution de rôles IAM et la génération de clés, consultez la documentation Google Cloud IAM.

Étape 2 : Créer une connexion

Une connexion spécifie un chemin d’accès et des identifiants pour accéder à un système externe. Créez une connexion à l’aide de Catalog Explorer ou de la commande SQL CREATE CONNECTION dans un notebook Databricks ou dans l’éditeur de query Databricks SQL.

remarque

Vous pouvez également utiliser l’API REST Databricks ou la CLI Databricks pour créer une connexion. Voir POST /api/2.1/unity-catalog/connections et les commandes Unity Catalog.

Autorisations requises : administrateur de métastore ou utilisateur disposant du privilège CREATE CONNECTION.

Catalog Explorer
SQL

Dans votre workspace Databricks, cliquez sur Catalog .
En haut du volet Catalog, cliquez sur l'icône Add et sélectionnez Create a connection dans le menu.
Sur la page Connection basics de l’assistant Set up connection , saisissez un Connection name convivial.
Sélectionnez un Type de connexion Google Cloud Lakehouse , puis cliquez sur Suivant .
Sur la page Authentification , saisissez l’ ID de projet Google Cloud et la clé JSON du compte de service pour le compte de service de connexion que vous avez créé à l’ Étape 1 : Configurer les ressources Google Cloud.
(Facultatif) Ajouter un commentaire.
Cliquez sur Créer une connexion .

Exécutez la commande suivante dans un notebook ou dans l'éditeur de requêtes Databricks SQL. Remplacez les valeurs des espaces réservés :

<connection-name>: Nom de la connexion dans Databricks.
<gcp-project-id>: l’ID de projet Google Cloud qui contient le catalogue Google Cloud Lakehouse.
<secret-scope> et <secret-key>: le Secret Scope et la clé qui stockent la clé JSON du compte de service de connexion.

SQL
CREATE CONNECTION <connection-name> TYPE GOOGLE_CLOUD_LAKEHOUSE
OPTIONS (
  gcp_project_id '<gcp-project-id>',
  service_account_json secret('<secret-scope>','<secret-key>')
);

Databricks vous recommande d'utiliser des secrets plutôt que des chaînes en texte brut pour les valeurs sensibles telles que la clé de compte de service. Pour plus d'informations sur la configuration des secrets, reportez-vous à la rubrique Gestion des secrets.

Étape 3 : Créer un identifiant de stockage et un emplacement externe

Configurez un identifiant de stockage et un emplacement externe dans Unity Catalog pour régir l’accès aux buckets GCS qui contiennent vos tables Google Cloud Lakehouse. Les emplacements externes sont des objets sécurisables Unity Catalog qui associent des identifiants de stockage à des chemins de conteneurs de stockage cloud.

Vous devez créer au moins les éléments suivants :

Un identifiant et un emplacement externe couvrant la racine de stockage des métadonnées du catalogue. Cet emplacement stocke les métadonnées des tables Iceberg dans le catalogue ; le compte de service géré par Databricks doit donc disposer d’un accès en lecture-écriture. Il peut s’agir de n’importe quel compartiment GCS. Il n’a pas besoin d’être lié aux compartiments de table. Vous spécifiez cet emplacement en tant qu’option storage_root lors de la création du catalogue étranger.
Un ou plusieurs identifiants et emplacements externes couvrant les emplacements de stockage des tables. Ceux-ci peuvent être en lecture seule.

Pour créer un identifiant de stockage et un emplacement externe, utilisez Catalog Explorer ou SQL. Par exemple, pour créer un emplacement externe à l’aide de SQL :

SQL
CREATE EXTERNAL LOCATION <name>
URL 'gs://<bucket-path>'
WITH (STORAGE CREDENTIAL <gcp-storage-credential>);

Pour des instructions détaillées, consultez Se connecter à un emplacement externe Google Cloud Storage (GCS).

Étape 4 : Créer un catalogue étranger

Un catalogue étranger reflète votre catalogue Google Cloud lakehouse afin que vous puissiez query et gérer l'accès à ses tables à l'aide de Databricks et de Unity Catalog. Pour créer un catalogue étranger, utilisez la connexion que vous avez créée à l'Étape 2 : Créer une connexion.

Créez un catalogue étranger en utilisant l’explorateur de catalogues ou la commande SQL CREATE FOREIGN CATALOG dans un notebook Databricks ou dans l’éditeur de query Databricks SQL.

Autorisations requises : autorisation CREATE CATALOG sur le métastore et soit la propriété de la connexion, soit le privilège CREATE FOREIGN CATALOG sur la connexion.

Catalog Explorer
SQL

Dans votre workspace Databricks, cliquez sur Catalog pour ouvrir l’explorateur de catalogues.
En haut du volet Catalog , cliquez sur l’icône Add et sélectionnez Add a catalog dans le menu.
Saisissez un Catalog name et sélectionnez un Type de catalogue Foreign .
Sélectionnez la Connexion que vous avez créée à l’ étape 2 : Créer une connexion dans le menu déroulant.
Pour Warehouse , saisissez le chemin du warehouse Google Cloud Lakehouse à fédérer. Utilisez un chemin gs:// pour un warehouse Cloud Storage ou un chemin bq:// pour un warehouse BigQuery.
Pour les chemins autorisés , saisissez les chemins de stockage cloud accessibles via le catalogue. Seules les tables situées sous ces chemins peuvent être interrogées via le catalogue étranger. Les chemins doivent être couverts par des emplacements externes. Voir Qu'est-ce que les chemins autorisés ?.

Vous pouvez modifier les chemins d’accès autorisés après la création du catalogue.
Dans le champ Emplacement de stockage , spécifiez l’emplacement GCS accessible en écriture qui stocke les métadonnées des tables Iceberg dans ce catalogue.
Cliquez sur Créer un catalogue .
Attribuez l’accès au workspace, un propriétaire et des privilèges comme demandé.

Exécutez la commande suivante dans un Notebook ou dans l’éditeur de query Databricks SQL. Les éléments entre crochets sont facultatifs. Remplacez les valeurs des espaces réservés :

<catalog-name>: nom du catalogue dans Databricks.
<connection-name>: Le nom de la connexion que vous avez créée à l'étape 2 : Créer une connexion.
<warehouse-path>: le chemin du warehouse Google Cloud Lakehouse. Utilisez un chemin gs:// pour un warehouse Cloud Storage ou un chemin bq:// pour un warehouse BigQuery.
<path1>,<path2>: Chemins de stockage cloud accessibles via le catalogue. Les chemins d’accès doivent être couverts par des emplacements externes. Voir Que sont les chemins d’accès autorisés ?.
<storage-location>: un emplacement GCS accessible en écriture où les métadonnées du catalogue sont stockées.

SQL
CREATE FOREIGN CATALOG [IF NOT EXISTS] <catalog-name>
USING CONNECTION <connection-name>
OPTIONS (
  warehouse '<warehouse-path>',
  authorized_paths '<path1>,<path2>',
  storage_root '<storage-location>'
);

Unity Catalog découvre tous les espaces de noms et toutes les tables sous le catalogue :

Les espaces de noms Google Cloud Lakehouse deviennent des schémas Unity Catalog.
Les tables Google Cloud Lakehouse Iceberg deviennent des tables étrangères Unity Catalog.

Accorder des autorisations et query le catalogue

Une fois la fédération de catalogue configurée, les utilisateurs doivent disposer des autorisations Unity Catalog appropriées pour accéder aux tables fédérées :

Tous les utilisateurs ont besoin des autorisations USE CATALOG et USE SCHEMA sur le catalogue et le schéma, respectivement.
Pour lire à partir d’une table fédérée, les utilisateurs doivent disposer de l’autorisation SELECT.

Pour plus d'informations sur les privilèges Unity Catalog et sur la façon de les accorder, reportez-vous à la rubrique Gérer les privilèges dans Unity Catalog.

Une fois les autorisations accordées, les utilisateurs peuvent query les tables étrangères depuis Databricks :

SQL
SELECT * FROM <catalog-name>.<schema>.<table>;

Contrôle d’accès basé sur les attributs et contrôle d’accès précis

Les tables étrangères prennent en charge le contrôle d’accès basé sur les attributs (ABAC) et le contrôle d’accès précis (FGAC). Ajoutez des tags à l’aide de Catalog Explorer ou de la commande ALTER TABLE ... SET TAGS. Voir Appliquer des tags aux objets sécurisables de Unity Catalog.

Limitations

La fédération de catalogues Google Cloud Lakehouse présente les limitations suivantes :

Les noms de schéma et de table respectent les limitations de nommage standard d’Unity Catalog. Databricks ne prend pas en charge les noms contenant un point (.), un espace () ou une barre oblique (/).
Les tables étrangères dans un catalogue Google Cloud Lakehouse sont en lecture seule.
Les tables contenant une colonne de type TIME ne sont pas prises en charge.
Les compartiments GCS doivent être mono-région. Les compartiments multi-région et bi-région ne sont pas pris en charge.
Les clusters dédiés (anciennement clusters mono-utilisateur) ne sont pas pris en charge.

Consultez Limitations pour connaître les limitations liées à Iceberg.

Dépannage

La section suivante décrit les erreurs courantes et leurs résolutions.

`Catalog not found` ou `Failed to load catalog`

Causes courantes :

L'option warehouse ne correspond pas à un chemin de warehouse Google Cloud Lakehouse dans le projet Google Cloud.
Il manque au compte de service de connexion le rôle roles/biglake.viewer sur le projet.

`403 Forbidden` lors de la lecture des données de table

Causes courantes :

Le compte de service de stockage ne dispose pas du rôle roles/storage.objectViewer sur le bucket GCS.
Si les tables sont gérées par BigQuery, le compte de service de stockage ne possède pas non plus le rôle roles/bigquery.dataViewer.

`DBR version not supported`

Le compute utilise une version de Databricks Runtime inférieure au minimum pris en charge. Utilisez Databricks Runtime 19 ou une version ultérieure. Voir Avant de commencer.

Les schémas apparaissent mais pas les tables

Vérifiez qu’un emplacement externe couvre le chemin de stockage où résident les tables, et que l’option authorized_paths couvre tous les chemins de compartiment que les tables utilisent réellement. Voir Étape 3 : Créer un identifiant de stockage et un emplacement externe.

`Authentication failed` lors de la création de la connexion

La clé de compte de service JSON n’est pas valide ou a expiré, ou il manque au compte de service le rôle roles/biglake.viewer. Régénérez la clé dans la console Google Cloud et confirmez les rôles du compte de service. Voir Étape 1 : Configurer les ressources Google Cloud.

Avant de commencer​

Étape 1 : Configurer les ressources Google Cloud​

Étape 2 : Créer une connexion​

Étape 3 : Créer un identifiant de stockage et un emplacement externe​

Étape 4 : Créer un catalogue étranger​

Accorder des autorisations et query le catalogue​

Contrôle d’accès basé sur les attributs et contrôle d’accès précis​

Limitations​

Dépannage​

Catalog not found ou Failed to load catalog​

403 Forbidden lors de la lecture des données de table​

DBR version not supported​

Les schémas apparaissent mais pas les tables​

Authentication failed lors de la création de la connexion​