Utiliser les utilitaires UCX pour mettre à niveau votre espace de travail vers Unity Catalog

Cet article présente UCX, un projet Databricks Labs qui fournit des outils pour vous aider à mettre à niveau votre espace de travail non Unity Catalog vers Unity Catalog.

Remarque

UCX, comme tous les projets du compte GitHub databrickslabs, est fourni uniquement pour votre exploration et n’est pas officiellement pris en charge par Databricks avec des contrats de niveau de service (SLA). Il est fourni en l’état. Nous ne fournissons aucune garantie de quelque sorte que ce soit. N’envoyez pas de ticket de support Databricks relatif aux problèmes qui proviennent de l’utilisation de ce projet. Au lieu de cela, consignez un problème GitHub. Les problèmes seront examinés dans la mesure où le temps le permet, mais il n’existe aucun contrat SLA formel pour le support.

Le projet UCX fournit les outils et workflows de migration suivants :

1. Un workflow d’évaluation pour vous aider à planifier votre migration.
2. Un workflow de migration de groupe pour vous aider à mettre à niveau l’appartenance au groupe de votre espace de travail vers votre compte Databricks et à migrer les autorisations vers les nouveaux groupes au niveau du compte.
3. Un workflow de migration de table vous permet de mettre à niveau les tables inscrites dans le metastore Hive de votre espace de travail vers le metastore Unity Catalog. Ce workflow vous aide également à migrer les emplacements de stockage et les informations d’identification requises pour y accéder.

Ce diagramme montre le flux de migration global, identifiant les workflows de migration et les utilitaires par nom :

Remarque

Le workflow de migration de code représenté dans le diagramme reste en cours de développement et n’est pas encore disponible.

Avant de commencer

Avant de pouvoir installer UCX et exécuter les workflows UCX, votre environnement doit répondre aux exigences suivantes.

Packages installés sur l’ordinateur sur lequel vous exécutez UCX :

• Databricks CLI v0.213 ou version ultérieure. Consultez Installer ou mettre à jour l’interface CLI Databricks.

  Vous devez disposer d’un fichier de configuration Databricks avec des profils de configuration pour l’espace de travail et le compte Databricks.

• Python 3.10 ou version ultérieure.

• Si vous souhaitez exécuter le workflow UCX qui identifie les emplacements de stockage utilisés par les tables Hive dans votre espace de travail (recommandé, mais non requis), vous devez disposer de l’interface CLI pour votre fournisseur de stockage cloud (Azure CLI ou AWS CLI) installé sur l’ordinateur sur lequel vous exécutez les workflows UCX.

Accès réseau :

• Accès réseau à partir de l’ordinateur qui exécute l’installation UCX vers l’espace de travail Azure Databricks que vous migrez.
• Accès réseau à Internet à partir de l’ordinateur qui exécute l’installation UCX. Cela est nécessaire pour l’accès à pypi.org et github.com.
• Accès réseau à partir de votre espace de travail Azure Databricks à pypi.org pour télécharger les packages databricks-sdk et pyyaml.

Rôles et autorisations Databricks :

• Rôles d’administrateur de compte et d’administrateur d’espace de travail Azure Databricks pour l’utilisateur qui exécute l’installation UCX. Vous ne pouvez pas exécuter l’installation en tant que principal de service.

Autres prérequis Azure Databricks :

• Metastore Unity Catalog créé pour chaque région qui héberge un espace de travail que vous souhaitez mettre à niveau, avec chacun de ces espaces de travail Azure Databricks attachés à un metastore Unity Catalog.

  Pour savoir comment déterminer si vous disposez déjà d’un metastore Unity Catalog dans les régions d’espace de travail appropriées, comment créer un metastore et comment attacher un metastore Unity Catalog à un espace de travail, consultez Étape 1 : vérifier que votre espace de travail est activé pour Unity Calalog dans l’article de configuration de Unity Catalog. En guise d’alternative, UCX fournit un utilitaire permettant d’affecter des metastores Unity Calalog aux espaces de travail que vous pouvez utiliser une fois UCX installé.

  L’attachement d’un metastore Unity Calalog à un espace de travail permet également la fédération d’identités, dans laquelle vous centralisez la gestion des utilisateurs au niveau du compte Azure Databricks, qui est également un prérequis pour l’utilisation d’UCX. Consultez Activer la fédération d’identité.

• Si votre espace de travail utilise un metastore Hive externe (tel qu’AWS Glue) au lieu du metastore Hive local par défaut, vous devez effectuer la configuration requise. Consultez Intégration du metastore Hive externe dans le référentiel databrickslabs/ucx.

• Un entrepôt SQL Pro ou serverless s’exécutant sur l’espace de travail où vous exécutez des workflows UCX, requis pour afficher le rapport généré par le workflow d’évaluation.

Installer UCX

Pour installer UCX, utilisez l’interface CLI Databricks :

databricks labs install ucx

Vous êtes invité à sélectionner les éléments suivants :

1. Le profil de configuration Databricks pour l’espace de travail que vous souhaitez mettre à niveau. Le fichier de configuration doit également inclure un profil de configuration pour le compte Databricks parent de l’espace de travail.

2. Le nom de la base de données d’inventaire qui sera utilisée pour stocker la sortie des workflows de migration. En règle générale, il est recommandé de sélectionner la valeur par défaut, c’est-à-dire ucx.

3. Un entrepôt SQL sur lequel exécuter le processus d’installation.

4. La liste des groupes locaux d’espace de travail que vous souhaitez migrer vers des groupes au niveau du compte. Si vous conservez cette valeur par défaut (<ALL>), tout groupe de niveau compte existant dont le nom correspond à un groupe local d’espace de travail sera traité comme le remplacement de ce groupe local d’espace de travail et héritera de toutes ses autorisations d’espace de travail lorsque vous exécutez le workflow de migration de groupe après l’installation.

   Vous avez la possibilité de modifier le mappage entre groupe d’espace de travail et groupe de comptes après avoir exécuté le programme d’installation et avant d’exécuter la migration de groupe. Consultez Résolution des conflits de noms de groupe dans le référentiel UCX.

5. Si vous disposez d’un metastore Hive externe, tel qu’AWS Glue, vous avez la possibilité de vous y connecter ou non. Consultez Intégration du metastore Hive externe dans le référentiel databrickslabs/ucx.

6. S’il faut ouvrir ou non le notebook README généré.

Une fois l’installation terminée, elle déploie un notebook README, des tableaux de bord, des bases de données, des bibliothèques, des travaux et d’autres ressources dans votre espace de travail.

Pour plus d’informations, consultez les instructions d’installation dans le fichier readme du projet. Vous pouvez également installer UCX sur tous les espaces de travail de votre compte Databricks.

Ouvrir le notebook README

Chaque installation crée un notebook README qui fournit une description détaillée de tous les workflows et tâches, avec des liens rapides vers les workflows et les tableaux de bord. Consultez Notebook Readme.

Étape 1. Exécuter le workflow d’évaluation

Le workflow d’évaluation évalue la compatibilité avec Unity Calalog des identités de groupe, des emplacements de stockage, des informations d’identification de stockage, des contrôles d’accès et des tables dans l’espace de travail actuel et fournit les informations nécessaires pour planifier la migration vers Unity Calalog. Les tâches du workflow d’évaluation peuvent être exécutées en parallèle ou séquentiellement, en fonction des dépendances spécifiées. Une fois le workflow d’évaluation terminé, un tableau de bord d’évaluation est rempli avec les résultats et les recommandations courantes.

La sortie de chaque tâche de workflow est stockée dans les tables Delta dans le schéma $inventory_database que vous spécifiez lors de l’installation. Vous pouvez utiliser ces tables pour effectuer une analyse approfondie et une prise de décision éclairée à l’aide d’un rapport d’évaluation. Vous pouvez exécuter le workflow d’évaluation plusieurs fois pour vous assurer que toutes les entités incompatibles sont identifiées et comptabilisées avant de démarrer le processus de migration.

Vous pouvez déclencher le workflow d’évaluation à partir du notebook README généré par UCX et de l’interface utilisateur Azure Databricks (Workflows > Travaux > Évaluation [UCX]), ou exécuter la commande CLI Databricks suivante :

databricks labs ucx ensure-assessment-run

Pour obtenir des instructions détaillées, consultez Workflow d’évaluation.

Étape 2. Exécuter le workflow de migration de groupe

Le workflow de migration de groupe met à niveau les groupes locaux d’espace de travail vers des groupes de niveau compte pour prendre en charge Unity Calalog. Il garantit que les groupes de niveau compte appropriés sont disponibles dans l’espace de travail et réplique toutes les autorisations. Il supprime également les groupes et autorisations inutiles de l’espace de travail. Les tâches du workflow de migration de groupe dépendent de la sortie du workflow d’évaluation.

La sortie de chaque tâche de workflow est stockée dans les tables Delta dans le schéma $inventory_database que vous spécifiez lors de l’installation. Vous pouvez utiliser ces tables pour une analyse approfondie et une prise de décision éclairée. Vous pouvez exécuter le workflow de migration de groupe plusieurs fois pour vous assurer que tous les groupes sont correctement mis à niveau et que toutes les autorisations nécessaires sont attribuées.

Pour plus d’informations sur l’exécution du workflow de migration de groupe, consultez votre notebook README généré par UCX et le workflow de migration de groupe dans le fichier readme UCX.

Étape 3. Exécuter le workflow de migration de table

Le workflow de migration de table met à niveau les tables du metastore Hive vers le metastore Unity Calalog. Les tables externes du metastore Hive sont mises à niveau en tant que tables externes dans Unity Calalog, à l’aide de SYNC. Les tables managées dans le metastore Hive stockées dans le stockage d’espace de travail (également appelée racine DBFS) sont mises à niveau en tant que tables managées dans Unity Calalog, à l’aide de DEEP CLONE.

Les tables managées Hive doivent être au format Delta ou Parquet pour être mises à niveau. Les tables Hive externes doivent se trouver dans l’un des formats de données répertoriés dans les tables externes.

Exécuter les commandes préparatoires

La migration de table comprend plusieurs tâches préparatoires que vous effectuez avant d’exécuter le workflow de migration de table. Vous effectuez ces tâches à l’aide des commandes CLI Databricks suivantes :

• La commande create-table-mapping, qui crée un fichier CSV qui mappe un catalogue Unity Catalog cible, un schéma et une table à chaque table Hive qui est mise à niveau. Vous devez passer en revue et mettre à jour le fichier de mappage avant de continuer avec le workflow de migration.
• La commande create-uber-principal qui crée un principal de service avec un accès en lecture seule à tous les stockages utilisés par les tables de cet espace de travail. La ressource de calcul du travail de workflow utilise ce principal pour mettre à niveau les tables de l’espace de travail. Déprovisionnez ce principal de service lorsque vous avez terminé votre mise à niveau.
• (Facultatif) La commande principal-prefix-access, qui identifie les comptes de stockage et les informations d’identification d’accès au stockage utilisées par les tables Hive dans l’espace de travail.
• (Facultatif) La commande migrate-credentials, qui crée les informations d’identification de stockage Unity Calalog à partir des informations d’identification d’accès au stockage identifiées par principal-prefix-access.
• (Facultatif) La commande migration locations, qui crée des emplacements externes Unity Calalog à partir des emplacements de stockage identifiés par le workflow d’évaluation, à l’aide des informations d’identification de stockage créées par migrate-credentials.
• (Facultatif) La commande create-catalogs-schemas, qui crée des catalogues et des schémas Unity Calalog qui contiennent les tables mises à niveau.

Pour plus d’informations, notamment sur les commandes et les options supplémentaires de workflow de migration de table, consultez Table migration commands (Commandes de migration de table) dans le fichier readme UCX.

Exécuter la migration de table

Une fois que vous avez exécuté les tâches préparatoires, vous pouvez exécuter le workflow de migration de table à partir du notebook README généré par UCX ou à partir de Workflows > Travaux dans l’interface utilisateur de l’espace de travail.

La sortie de chaque tâche de workflow est stockée dans les tables Delta dans le schéma $inventory_database que vous spécifiez lors de l’installation. Vous pouvez utiliser ces tables pour une analyse approfondie et une prise de décision éclairée. Vous devrez peut-être exécuter le workflow de migration de table plusieurs fois pour vous assurer que toutes les tables sont correctement mises à niveau.

Pour obtenir des instructions complètes sur la migration de table, consultez votre notebook README généré par UCX et Table Migration Workflow (Workflow de migration de table) dans le fichier lisez-moi UCX.

Outils supplémentaires

UCX inclut également des outils de débogage et d’autres utilitaires pour vous aider à réussir votre migration. Pour plus d’informations, consultez votre notebook README généré par UCX et le fichier readme du projet UCX.

Mettre à niveau votre installation UCX

Le projet UCX est mis à jour régulièrement. Pour mettre à niveau votre installation UCX vers la dernière version :

1. Vérifiez qu’UCX est installé.

   databricks labs installed
   
   Name  Description                            Version
   ucx   Unity Catalog Migration Toolkit (UCX)  0.20.0
   

2. Exécutez la mise à niveau :

   databricks labs upgrade ucx
   

Obtenir de l’aide

Pour obtenir de l’aide sur l’interface CLI UCX, exécutez :

databricks labs ucx --help

Pour obtenir de l’aide sur une commande UCX spécifique, exécutez :

databricks labs ucx <command> --help

Pour résoudre les problèmes :

• Exécutez --debug avec n’importe quelle commande pour activer les journaux de débogage.
• Utilisez le notebook de débogage généré automatiquement par UCX.

Pour soumettre un problème ou une demande de fonctionnalité, consignez un problème GitHub.

Notes de publication UCX

Consultez le journal des modifications dans le référentiel GitHub UCX.