Migrer des tables depuis un lac de données HDFS

Ce document vous explique comment migrer vos tables de data lake Apache Hadoop Distributed File System (HDFS) vers Trusted Cloud.

Vous pouvez utiliser le connecteur de migration de data lake HDFS dans le service de transfert de données BigQuery pour migrer vos tables Hive et Iceberg depuis différentes distributions Hadoop, dans des environnements sur site et cloud, vers Trusted Cloud.

Avec le connecteur de lac de données HDFS, vous pouvez enregistrer vos tables de lac de données HDFS avec Dataproc Metastore et BigLake Metastore tout en utilisant Cloud Storage comme stockage sous-jacent pour vos fichiers.

Le schéma suivant présente le processus de migration des tables à partir du cluster Hadoop.

Présentation de la migration de tables du data lake Hive vers BigQuery.

Limites

Les transferts de data lake HDFS sont soumis aux limitations suivantes :

  • Pour migrer des tables Iceberg, vous devez les enregistrer dans le metastore BigLake afin d'autoriser l'accès en écriture pour les moteurs Open Source (tels que Spark ou Flink) et l'accès en lecture pour BigQuery.
  • Pour migrer des tables Hive, vous devez les enregistrer auprès de Dataproc Metastore afin d'autoriser l'accès en écriture pour les moteurs Open Source et l'accès en lecture pour BigQuery.
  • Vous devez utiliser l'outil de ligne de commande bq pour migrer une table de data lake HDFS vers BigQuery.

Avant de commencer

Avant de planifier un transfert de lac de données HDFS, vous devez effectuer les opérations suivantes :

Créer un bucket Cloud Storage pour les fichiers migrés

Créez un bucket Cloud Storage qui servira de destination pour les fichiers de votre lac de données migrés. Dans ce document, ce bucket est appelé MIGRATION_BUCKET.

Fichiers requis

Vous devez disposer des fichiers de migration suivants dans un bucket Cloud Storage avant de pouvoir planifier un transfert de lac de données HDFS :

  • Fichier de métadonnées extrait (hive-dumper-output.zip)
  • Fichier YAML de configuration de la traduction (*.config.yaml)
  • Fichiers YAML de mappage des tables

Les sections suivantes expliquent comment créer ces fichiers.

hive-dumper-output.zip

Exécutez l'outil dwh-migration-dumper pour extraire les métadonnées pour Apache Hive. L'outil génère un fichier nommé hive-dumper-output.zip dans un bucket Cloud Storage, appelé DUMPER_BUCKET dans ce document.

Fichier YAML de configuration de la traduction

Créez un fichier YAML de configuration de la traduction dont le nom contient le suffixe .config.yaml (par exemple, translation.config.yaml), puis importez-le dans le même bucket que hive-dumper-output.zip. Configurez le fichier YAML de configuration de la traduction pour mapper les chemins d'accès HDFS aux dossiers gérés Cloud Storage, comme dans l'exemple suivant :

type: object_rewriter
relation:
- match:
    relationRegex: ".*"
  external:
    location_expression: "'gs://MIGRATION_BUCKET/' + table.schema + '/' + table.name"

Remplacez MIGRATION_BUCKET par le nom du bucket Cloud Storage qui servira de destination pour vos fichiers migrés.

Le champ location_expression est une expression CEL (Common Expression Language).

Pour en savoir plus sur ce fichier YAML de configuration, consultez Consignes pour créer un fichier YAML de configuration.

Générer des fichiers YAML de mappage des tables

Pour générer un fichier YAML de mappage des tables, exécutez la commande suivante :

  curl -d '{
    "tasks": {
        "string": {
          "type": "HiveQL2BigQuery_Translation",
          "translation_details": {
              "target_base_uri": "TRANSLATION_OUTPUT_BUCKET",
              "source_target_mapping": {
                "source_spec": {
                    "base_uri": "DUMPER_BUCKET"
                }
              },
              "target_types": ["metadata"]
          }
        }
    }
    }' \
    -H "Content-Type:application/json" \
    -H "Authorization: Bearer TOKEN" -X POST https://bigquerymigration.googleapis.com/v2alpha/projects/PROJECT_ID/locations/LOCATION/workflows

Remplacez les éléments suivants :

  • TRANSLATION_OUTPUT_BUCKET : URI de base d'un bucket Cloud Storage contenant le fichier YAML de mappage des tables. Exemple : gs://output_bucket/tables/.
  • DUMPER_BUCKET : URI de base du bucket Cloud Storage contenant le fichier YAML de configuration et hive-dumper-output.zip.
  • TOKEN : jeton OAuth. Vous pouvez le générer dans la ligne de commande avec la commande gcloud auth print-access-token.
  • PROJECT_ID : projet pour le traitement de la traduction.
  • LOCATION : emplacement où le job est traité. Par exemple, eu ou us.

Lors de l'exécution, l'API du service de traduction renvoie un WORKFLOW_ID et démarre un job en arrière-plan asynchrone. Vous pouvez surveiller l'état de ce job à l'aide de la commande suivante :

  curl \
  -H "Content-Type:application/json" \
  -H "Authorization:Bearer TOKEN" -X GET https://bigquerymigration.googleapis.com/v2alpha/projects/PROJECT_ID/locations/LOCATION/workflows/WORKFLOW_ID

Une fois l'opération terminée, vos fichiers YAML de mappage des tables sont créés. Vos fichiers YAML de mappage des tables peuvent se composer de plusieurs fichiers de mappage, un pour chaque table, stockés dans le dossier Cloud Storage.

Activer les API

Activez les API suivantes dans votre projetTrusted Cloud  :

  • API Data Transfer
  • API Storage Transfer

Un agent de service est créé lorsque vous activez l'API Data Transfer.

Configurer les autorisations

  1. Créez un compte de service et attribuez-lui le rôle Administrateur BigQuery (roles/bigquery.admin). Ce compte de service est utilisé pour créer la configuration du transfert.
  2. Un agent de service (P4SA) est créé lorsque vous activez l'API Data Transfer. Attribuez-lui les rôles suivants :
    • roles/metastore.metadataOwner
    • roles/storagetransfer.admin
    • roles/serviceusage.serviceUsageConsumer
    • roles/storage.objectViewer
      • Si vous migrez des métadonnées pour des tables BigLake Iceberg, accordez-lui les rôles roles/storage.objectAdmin et roles/bigquery.admin au lieu de roles/storage.objectViewer.

  3. Attribuez le rôle roles/iam.serviceAccountTokenCreator à l'agent de service à l'aide de la commande suivante :

    gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT --member serviceAccount:service-PROJECT_NUMBER@gcp-sa-bigquerydatatransfer.s3ns-system.iam.gserviceaccount.com --role roles/iam.serviceAccountTokenCreator

Configurer votre agent Storage Transfer

Pour configurer l'agent de transfert de stockage requis pour un transfert de data lake HDFS, procédez comme suit :

  1. Configurez les autorisations pour exécuter l'agent de transfert de stockage sur votre cluster Hadoop.
  2. Installez Docker sur les machines agents sur site.
  3. Créez un pool d'agents service de transfert de stockage Service dans votre projet Trusted Cloud by S3NS .
  4. Installez des agents sur vos machines d'agents sur site.

Programmer un transfert de lac de données HDFS

Pour planifier un transfert de lac de données HDFS, saisissez la commande bq mk et spécifiez l'indicateur de création de transfert --transfer_config :

  bq mk --transfer_config
  --data_source=hadoop
  --display_name='TRANSFER_NAME'
  --service_account_name='SERVICE_ACCOUNT'
  --project_id='PROJECT_ID'
  --location='REGION'
  --params='{"table_name_patterns":"LIST_OF_TABLES",
    "agent_pool_name":"AGENT_POOL_NAME",
    "destination_dataproc_metastore":"DATAPROC_METASTORE",
    "translation_output_gcs_path":"gs://TRANSLATION_OUTPUT_BUCKET/metadata/config/default_database/",
    "table_metadata_path":"gs://DUMPER_BUCKET/hive-dumper-output.zip"}'

Remplacez les éléments suivants :

  • TRANSFER_NAME : nom à afficher de la configuration de transfert. Ce nom peut correspondre à toute valeur permettant d'identifier le transfert si vous devez le modifier ultérieurement.
  • SERVICE_ACCOUNT : nom du compte de service utilisé pour authentifier le transfert. Le compte de service doit appartenir au même project_id que celui utilisé pour créer le transfert et doit disposer de toutes les autorisations requises.
  • PROJECT_ID : ID de votre projet Trusted Cloud by S3NS . Si vous ne fournissez pas de --project_id afin de spécifier un projet particulier, le projet par défaut est utilisé.
  • REGION : emplacement de cette configuration de transfert.
  • LIST_OF_TABLES : liste des entités à transférer. Utilisez une spécification de nommage hiérarchique : database.table. Ce champ accepte les expressions régulières RE2 pour spécifier les tables. Exemple :
    • db1..* : spécifie toutes les tables de la base de données.
    • db1.table1;db2.table2 : liste de tables
  • AGENT_POOL_NAME : nom du pool d'agents utilisé pour créer des agents.
  • DATAPROC_METASTORE : Dataproc Metastore de destination pour la destination OSS gérée. Pour utiliser BigLake Metastore à la place, vous pouvez omettre ce champ de cette configuration de transfert. Pour en savoir plus sur l'utilisation de BigLake Metastore pour migrer des métadonnées, consultez Migration des métadonnées.

Exécutez cette commande pour créer la configuration de transfert et démarrer le transfert du lac de données HDFS. Par défaut, les transferts sont planifiés pour s'exécuter toutes les 24 heures, mais ils peuvent être configurés avec les options de planification des transferts.

Une fois le transfert terminé, vos tables du cluster Hadoop seront migrées vers MIGRATION_BUCKET.

Options d'ingestion de données

Les sections suivantes fournissent plus d'informations sur la configuration de vos transferts de data lake HDFS.

Migration des métadonnées

Les métadonnées peuvent être migrées vers Dataproc Metastore ou BigLake Metastore, avec les données sous-jacentes stockées dans Cloud Storage.

Pour transférer des métadonnées vers Dataproc Metastore, spécifiez l'URL de votre metastore dans le champ destination_dataproc_metastore.

Pour transférer des métadonnées vers le métastore BigLake, vous n'avez pas besoin de spécifier de champ destination_dataproc_metastore dans votre configuration de transfert. Le système détermine automatiquement l'ensemble de données BigQuery de destination à partir du champ targetName dans les fichiers de mappage YAML générés. Le champ targetName est mis en forme en tant qu'identifiant en deux parties, par exemple bigquery_dataset_name.bigquery_table_name. Par défaut, la nomenclature correspond à celle de votre système source. Vous devez vous assurer que l'ensemble de données BigQuery portant le nom du schéma source existe. Si ce n'est pas le cas, créez-le avant d'exécuter le transfert.

Pour utiliser un autre ensemble de données BigQuery, vous devez fournir un fichier YAML de configuration supplémentaire (suffixé par config.yaml) dans DUMPER_BUCKET contenant un ensemble de règles de réécriture d'objets, puis générer les mappages de traduction. L'exemple suivant est un ensemble de règles qui mappe la base de données source nommée my_hive_db à un ensemble de données BigQuery nommé my_bq_dataset :

relation:
  - match:
      schema: my_hive_db
    outputName:
      database: null
      schema: my_bq_dataset

Le paramètre schema doit correspondre au nom de l'ensemble de données BigQuery et le paramètre relation doit correspondre au nom de la table. Pour en savoir plus, consultez Mappage des noms de sortie.

Le paramètre database doit également être défini sur null.

Transferts incrémentiels

Lorsqu'une configuration de transfert est configurée avec une programmation récurrente, chaque transfert ultérieur met à jour le tableau sur Trusted Cloud by S3NS avec les dernières modifications apportées au tableau source. Par exemple, toutes les opérations d'insertion, de suppression ou de mise à jour avec des modifications de schéma sont reflétées dans Trusted Cloud by S3NS à chaque transfert.

Options de planification des transferts

Par défaut, les transferts sont planifiés toutes les 24 heures. Pour configurer la fréquence d'exécution des transferts, ajoutez l'option --schedule à la configuration de transfert et spécifiez une programmation de transfert à l'aide de la syntaxe schedule. Les transferts de data lake HDFS doivent être espacés d'au moins 24 heures.

Pour les transferts ponctuels, vous pouvez ajouter l'indicateur end_time à la configuration du transfert pour qu'il ne s'exécute qu'une seule fois.

Surveiller les transferts de lacs de données HDFS

Une fois que vous avez planifié un transfert de data lake HDFS, vous pouvez surveiller le job de transfert à l'aide des commandes de l'outil de ligne de commande bq. Pour en savoir plus sur la surveillance de vos tâches de transfert, consultez Afficher vos transferts.

Suivre l'état de la migration des tables

Vous pouvez également exécuter l'outil dwh-dts-status pour surveiller l'état de toutes les tables transférées dans une configuration de transfert ou une base de données spécifique. Vous pouvez également utiliser l'outil dwh-dts-status pour lister toutes les configurations de transfert d'un projet.

Avant de commencer

Avant de pouvoir utiliser l'outil dwh-dts-status, procédez comme suit :

  1. Obtenez l'outil dwh-dts-status en téléchargeant le package dwh-migration-tool à partir du dépôt GitHub dwh-migration-tools.

  2. Authentifiez votre compte auprès de Trusted Cloud by S3NS à l'aide de la commande suivante :

    gcloud auth application-default login

    Pour en savoir plus, consultez Fonctionnement des identifiants par défaut de l'application.

  3. Vérifiez que l'utilisateur dispose des rôles bigquery.admin et logging.viewer. Pour en savoir plus sur les rôles IAM, consultez la documentation de référence sur le contrôle des accès.

Lister toutes les configurations de transfert d'un projet

Pour répertorier toutes les configurations de transfert d'un projet, exécutez la commande suivante :

  ./dwh-dts-status --list-transfer-configs --project-id=[PROJECT_ID] --location=[LOCATION]

Remplacez les éléments suivants :

  • PROJECT_ID : ID du projet Trusted Cloud by S3NS qui exécute les transferts.
  • LOCATION : emplacement où la configuration de transfert a été créée.

Cette commande génère une table contenant une liste des noms et des ID des configurations de transfert.

Afficher l'état de toutes les tables d'une configuration

Pour afficher l'état de toutes les tables incluses dans une configuration de transfert, utilisez la commande suivante :

  ./dwh-dts-status --list-status-for-config --project-id=[PROJECT_ID] --config-id=[CONFIG_ID] --location=[LOCATION]

Remplacez les éléments suivants :

  • PROJECT_ID : ID du projet Trusted Cloud by S3NS qui exécute les transferts.
  • LOCATION : emplacement où la configuration de transfert a été créée.
  • CONFIG_ID : ID de la configuration de transfert spécifiée.

Cette commande génère un tableau listant les tables et leur état de transfert dans la configuration de transfert spécifiée. L'état du transfert peut être l'une des valeurs suivantes : PENDING, RUNNING, SUCCEEDED, FAILED ou CANCELLED.

Afficher l'état de toutes les tables d'une base de données

Pour afficher l'état de toutes les tables transférées à partir d'une base de données spécifique, utilisez la commande suivante :

  ./dwh-dts-status --list-status-for-database --project-id=[PROJECT_ID] --database=[DATABASE]

Remplacez les éléments suivants :

  • PROJECT_ID : ID du projet Trusted Cloud by S3NS qui exécute les transferts.
  • DATABASE : nom de la base de données spécifiée.

Cette commande génère un tableau listant les tables et leur état de transfert dans la base de données spécifiée. L'état du transfert peut être l'une des valeurs suivantes : PENDING, RUNNING, SUCCEEDED, FAILED ou CANCELLED.