Aller au contenu principal
Dernière mise à jour le

Utilisez les utilitaires UCX pour mettre à niveau votre Workspace vers Unity Catalog

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

remarque

UCX, comme tous les projets du compte GitHub databrickslabs, est fourni à titre d'exploration uniquement et n'est pas officiellement pris en charge par Databricks avec des accords de niveau de service (SLA). Il est fourni tel quel. Nous ne donnons aucune garantie d'aucune sorte. Ne soumettez pas de ticket de support Databricks concernant les problèmes liés à l'utilisation de ce projet. Au lieu de cela, déposez un problème GitHub. Les problèmes seront examinés lorsque le temps le permettra, mais il n'existe pas de SLA formels pour le support.

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

  1. Workflow d'évaluation pour vous aider à planifier votre migration.
  2. Workflow de migration des groupes pour vous aider à mettre à niveau l'appartenance à un groupe de votre workspace vers votre compte Databricks et à migrer les autorisations vers les nouveaux groupes au niveau du compte.
  3. Flux de travail de migration de table pour vous aider à mettre à niveau les tables enregistrées dans le Hive metastore de votre Workspace vers le Unity Catalog. Ce flux de travail vous aide également à migrer les emplacements de stockage et les identifiants nécessaires pour y accéder.

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

Diagramme des workflows de migration UCX

remarque

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

Pour une démonstration de la mise à niveau de votre Workspace à l'aide d'UXC, consultez Mise à niveau du schéma à l'aide d'UCX.

Avant de commencer​

Avant de pouvoir installer UCX et d'exécuter les workflows UCX, votre environnement doit satisfaire aux exigences suivantes.

**Packages installés sur l’ordinateur où vous exécutez UCX** :

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

    Vous devez disposer d'un fichier de configuration Databricks avec des profils de configuration pour le Workspace 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 workspace (recommandé, mais non obligatoire), vous devez avoir la CLI de votre fournisseur de stockage cloud (Azure CLI ou AWS CLI) installée sur l’ordinateur où vous exécutez les workflows UCX.

Accès réseau :

  • Accès réseau depuis l’ordinateur qui exécute l’installation UCX vers le Workspace Databricks que vous migrez.
  • Accès réseau à internet depuis l'ordinateur qui exécute l'installation UCX. Ceci est requis pour l'accès à pypi.org et github.com.
  • Accès réseau de votre Workspace Databricks à pypi.org pour download les packages databricks-sdk et pyyaml.

Rôles et autorisations Databricks :

  • Rôles d'administrateur de compte Databricks et d'administrateur de workspace pour l'utilisateur qui exécute l'installation UCX. Vous ne pouvez pas exécuter l'installation en tant que Service Principal.

Autres prérequis Databricks :

  • Un metastore Unity Catalog créé pour chaque région qui héberge un Workspace que vous souhaitez mettre à niveau, chacun de ces Workspaces Databricks étant attaché à un metastore Unity Catalog.

    Pour savoir comment déterminer si vous avez déjà un metastore Unity Catalog dans les régions du Workspace pertinentes, comment créer un metastore si ce n’est pas le cas, et comment attacher un metastore Unity Catalog à un Workspace, consultez l’ Étape 1 : Confirmer que votre Workspace est activé pour Unity Catalog dans l’article de configuration de Unity Catalog. Comme alternative, UCX fournit un utilitaire pour l'assignation de metastores Unity Catalog aux workspaces que vous pouvez utiliser après l'installation de UCX.

    L'attachement d'un metastore Unity Catalog à un workspace active également la *fédération d'identités*, dans laquelle vous centralisez la gestion des utilisateurs au niveau du compte Databricks, ce qui est également un prérequis pour l'utilisation d'UCX. Consultez Activer la fédération d'identités.

  • Si votre Workspace utilise un Hive metastore externe (tel qu'AWS Glue) au lieu du Hive metastore local par default du Workspace, vous devez effectuer une configuration préalable. Consultez Intégration de Hive Metastore externe dans la documentation UCX.

  • Un SQL Warehouse Pro ou Serverless exécuté sur le workspace 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 la CLI Databricks :

Bash
databricks labs install ucx

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

  1. Le profil de configuration Databricks pour le Workspace que vous souhaitez mettre à niveau. Le fichier de configuration doit également inclure un profil de configuration pour le compte Databricks parent du workspace.

  2. Un nom pour la base de données d'inventaire qui sera utilisée pour stocker la sortie des flux de travail de migration. Il est généralement préférable de sélectionner la valeur default, qui est ucx.

  3. Un SQL warehouse pour exécuter le processus d'installation.

  4. Une liste de groupes locaux de Workspace que vous souhaitez migrer vers des groupes de niveau compte. Si vous laissez cette option par default (<ALL>), tout groupe de niveau compte existant dont le nom correspond à un groupe local au niveau du Workspace sera traité comme le remplacement de ce groupe local au niveau du Workspace et héritera de toutes ses autorisations de Workspace lorsque vous exécuterez le flux de travail de migration de groupe après l'installation.

    Vous avez la possibilité de modifier le mappage de groupe de Workspace à groupe de comptes après avoir exécuté l'installateur et avant d'exécuter la migration de groupe. Consultez Résolution des conflits de noms de groupe dans le dépôt UCX.

  5. Si vous avez un externe Hive metastore, tel qu’AWS Glue, vous avez la possibilité de vous y connecter ou non. Voir External Hive Metastore Integration dans le dépôt databrickslabs/ucx.

  6. S'il faut ouvrir le notebook README généré.

Une fois l’installation terminée, elle déploie un Notebook Lisez-moi, des tableaux de bord, des bases de données, des bibliothèques, des Jobs et d’autres assets dans votre Workspace.

Pour plus d'informations, consultez les instructions d'installation dans le fichier README du projet. Vous pouvez également installer UCX sur tous les workspaces 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 Links rapides vers les workflows et les tableaux de bord. Consultez le Notebook Readme.

Étape 1. Exécutez le workflow d'évaluation​

Le workflow d'évaluation examine la compatibilité avec Unity Catalog 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 le Workspace actuel et fournit les informations nécessaires à la planification de la migration vers Unity Catalog. 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 conclusions et les recommandations courantes.

La sortie de chaque tâche de workflow est stockée dans des 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 plus approfondie et une prise de décision à l'aide d'un rapport d'évaluation. Vous pouvez exécuter le flux de travail d'évaluation plusieurs fois pour vous assurer que toutes les entités incompatibles sont identifiées et prises en compte avant de start le processus de migration.

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

Bash
databricks labs ucx ensure-assessment-run

Pour obtenir des instructions détaillées, consultez le flux de travail d’évaluation.

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

Le workflow de migration de groupe met à niveau les groupes locaux de workspace vers des groupes au niveau du compte pour prendre en charge Unity Catalog. Il garantit que les groupes de niveau compte appropriés sont disponibles dans le workspace et réplique toutes les autorisations. Cela supprime également les groupes et autorisations inutiles du workspace. 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 des tables Delta dans le schéma $inventory_database que vous spécifiez lors de l'installation. Vous pouvez utiliser ces tables pour effectuer des analyses et prendre des décisions supplémentaires. Vous pouvez exécuter le workflow de migration de groupe plusieurs fois pour vous assurer que tous les groupes sont mis à niveau avec succès et que toutes les autorisations nécessaires sont attribuées.

Pour plus d'information sur l'exécution du workflow de migration de groupe, consultez votre Notebook README généré par UCX et Workflow de migration de groupe dans le fichier README d'UCX.

Étape 3. Exécutez le workflow de migration de table​

Le flux de travail de migration de tables met à niveau les tables du Hive metastore vers le metastore Unity Catalog. Les tables externes dans le Hive metastore sont mises à niveau en tant que tables externes dans Unity Catalog, en utilisant SYNC. Les tables gérées dans le Hive metastore, stockées dans le stockage Workspace (également appelé racine DBFS), sont mises à niveau en tant que tables gérées dans Unity Catalog, à l’aide de DEEP CLONE.

Les tables gérées Hive doivent être au format Delta ou Parquet pour être mises à niveau. Les tables Hive externes doivent être dans l’un des formats de données listés dans Travailler avec des tables externes.

Exécutez les commandes préparatoires.​

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

  • La commande create-table-mapping, qui crée un fichier CSV qui mappe un catalogue, un schéma et une table Unity Catalog cibles à chaque table Hive qui sera mise à niveau. Vous devez examiner et mettre à jour le fichier de mappage avant de poursuivre le workflow de migration.
  • La commande create-uber-principal, qui crée un Service Principal avec un accès en lecture seule à tout le stockage utilisé par les tables dans ce Workspace. La ressource de compute du job de workflow utilise ce principal pour mettre à niveau les tables dans le Workspace. Désapprovisionnez ce Service Principal une fois votre mise à niveau terminée.
  • (Facultatif) La commande principal-prefix-access, qui identifie les comptes de stockage et les informations d'identification d'accès au stockage utilisés par les tables Hive dans le workspace.
  • (Facultatif) La commande migrate-credentials, qui crée des identifiants de stockage Unity Catalog à partir des identifiants d'accès au stockage identifiés par principal-prefix-access.
  • (Facultatif) La commande migration locations, qui crée des emplacements externes Unity Catalog à partir des emplacements de stockage identifiés par le workflow d'évaluation, en utilisant les identifiants de stockage créés par migrate-credentials.
  • (Facultatif) La create-catalogs-schemascommande, qui crée des catalogues et des schémas Unity Catalog qui contiendront les tables mises à niveau.

Pour plus de détails, y compris les commandes et options de workflow de migration de table supplémentaires, consultez les commandes de migration de table dans le fichier README UCX.

Exécuter la migration de la table​

Une fois que vous avez exécuté les tâches préparatoires, vous pouvez exécuter le flux de travail de migration de table à partir du Notebook README généré par UCX ou à partir de **Jobs & Pipelines** dans l’interface utilisateur du Workspace.

La sortie de chaque tâche de workflow est stockée dans des tables Delta dans le schéma $inventory_database que vous spécifiez lors de l'installation. Vous pouvez utiliser ces tables pour effectuer des analyses et prendre des décisions supplémentaires. Vous pourriez avoir besoin d'exécuter le workflow de migration de table plusieurs fois pour vous assurer que toutes les tables sont mises à niveau avec succès.

Pour des instructions complètes sur la migration de table, consultez votre Notebook README généré par UCX et les flux de travail de migration de table dans le fichier README d’UCX.

Outils supplémentaires​

UCX comprend également :

  • Infrastructures publiques pour l'activation de la fédération de Hive metastore, l'outil d'intégration Databricks qui permet à Unity Catalog de régir les tables enregistrées dans un Hive metastore :

    • enable-hms-federation
    • create-federated-catalog

    La fédération Hive metastore facilite la migration en vous permettant d'exécuter des charges de travail à la fois sur votre métastore Hive hérité et son miroir dans Unity Catalog, facilitant ainsi la transition vers Unity Catalog. Pour plus d'informations sur l'utilisation de la fédération Hive metastore dans un scénario de migration, consultez Comment utiliser la fédération Hive metastore lors de la migration vers Unity Catalog ?

  • Outils de debugging et autres infrastructures publiques pour vous aider à réussir votre migration.

Pour plus d'information, consultez votre Notebook README généré par UCX et la documentation 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 que UCX est installé.

    Bash
    databricks labs installed

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

  2. Exécutez la mise à niveau :

    Bash
    databricks labs upgrade ucx

Obtenir de l'aide​

Pour obtenir de l'aide avec le CLI UCX, exécutez :

Bash
databricks labs ucx --help

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

Bash
databricks labs ucx <command> --help

Pour résoudre les problèmes :

Pour signaler un problème ou demander une fonctionnalité, créez un problème GitHub.

Notes de version UCX​

Consultez le journal des modifications dans le dépôt GitHub UCX.

Sur cette page