从 HDFS 数据湖迁移表

本文档介绍了如何将 Apache Hadoop 分布式文件系统 (HDFS) 数据湖表迁移到 Trusted Cloud。

您可以使用 BigQuery Data Transfer Service 中的 HDFS 数据湖迁移连接器，将 Hive 和 Iceberg 表从各种 Hadoop 发行版（包括本地环境和云环境）迁移到 Trusted Cloud。

借助 HDFS 数据湖连接器，您可以将 HDFS 数据湖表同时注册到 Dataproc Metastore 和 BigLake metastore，同时使用 Cloud Storage 作为文件的底层存储。

下图简要展示了从 Hadoop 集群迁移表的过程。

简要介绍如何将表从 Hive 数据湖迁移到 BigQuery。

限制

HDFS 数据湖转移作业受到以下限制：

  • 如需迁移 Iceberg 表，您必须向 BigLake metastore 注册这些表，以允许开源引擎（例如 Spark 或 Flink）进行写入访问，并允许 BigQuery 进行读取访问。
  • 如需迁移 Hive 表，您必须向 Dataproc Metastore 注册这些表，以允许开源引擎进行写入访问，并允许 BigQuery 进行读取访问。
  • 您必须使用 bq 命令行工具将 HDFS 数据湖表迁移到 BigQuery。

准备工作

在安排 HDFS 数据湖转移作业之前，您必须执行以下操作：

为迁移的文件创建 Cloud Storage 存储桶

创建 Cloud Storage 存储桶，作为迁移后的数据湖文件的目标位置。本文档中将此存储桶称为 MIGRATION_BUCKET。

必需的文件

在安排 HDFS 数据湖转移作业之前，您必须在 Cloud Storage 存储桶中准备好以下迁移文件：

  • 提取的元数据文件 (hive-dumper-output.zip)
  • 翻译配置 YAML 文件 (*.config.yaml)
  • 映射 YAML 文件的表格

以下部分介绍了如何创建这些文件。

hive-dumper-output.zip

运行 dwh-migration-dumper 工具以提取元数据（针对 Apache Hive）。该工具会生成一个名为 hive-dumper-output.zip 的文件，并将其保存到 Cloud Storage 存储桶（本文档中称为 DUMPER_BUCKET）中。

翻译配置 YAML 文件

创建包含后缀 .config.yaml 的翻译配置 YAML（例如 translation.config.yaml），并将其上传到包含 hive-dumper-output.zip 的同一存储桶。配置转换配置 YAML，以将 HDFS 路径映射到 Cloud Storage 受管文件夹，类似于以下示例：

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

将 MIGRATION_BUCKET 替换为迁移文件的目标 Cloud Storage 存储桶的名称。

location_expression 字段是一个通用表达式语言 (CEL) 表达式。

如需详细了解此配置 YAML，请参阅创建配置 YAML 文件的指南。

生成表映射 YAML 文件

如需生成表格映射 YAML 文件，请运行以下命令：

  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

替换以下内容：

  • TRANSLATION_OUTPUT_BUCKET：用于存放表映射 YAML 文件的 Cloud Storage 存储桶的基本 URI。例如 gs://output_bucket/tables/。
  • DUMPER_BUCKET：包含 hive-dumper-output.zip 和配置 YAML 文件的 Cloud Storage 存储桶的基本 URI。
  • TOKEN：OAuth 令牌。您可以在命令行中使用 gcloud auth print-access-token 命令生成此文件。
  • PROJECT_ID：处理翻译的项目。
  • LOCATION：处理作业的位置。例如 eu 或 us。

运行时，翻译服务 API 会返回 WORKFLOW_ID 并启动异步后台作业。您可以使用以下命令监控此作业的状态：

  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

完成后，系统会创建表映射 YAML 文件。 您的表格映射 YAML 文件可能包含多个映射文件（每个表格对应一个），这些文件存储在 Cloud Storage 文件夹中。

启用 API

在您的Trusted Cloud 项目中启用以下 API：

  • Data Transfer API
  • Storage Transfer API

启用 Data Transfer API 时，系统会创建一个服务代理。

配置权限

  1. 创建一个服务账号，并向其授予 BigQuery 管理员角色 (roles/bigquery.admin)。此服务账号用于创建转移配置。
  2. 启用 Data Transfer API 后，系统会创建一个服务代理 (P4SA)。向其授予以下角色：
    • roles/metastore.metadataOwner
    • roles/storagetransfer.admin
    • roles/serviceusage.serviceUsageConsumer
    • roles/storage.objectViewer
      • 如果您要迁移 BigLake Iceberg 表的元数据，请向该服务账号授予 roles/storage.objectAdmin 和 roles/bigquery.admin 角色，而不是 roles/storage.objectViewer 角色。

  3. 使用以下命令为服务代理授予 roles/iam.serviceAccountTokenCreator 角色：

    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

配置 Storage Transfer Service 代理

如需设置 HDFS 数据湖转移所需的存储转移代理，请执行以下操作：

  1. 配置权限，以便在 Hadoop 集群上运行存储空间转移代理。
  2. 在本地代理机器上安装 Docker。
  3. 在 Trusted Cloud by S3NS 项目中创建 Storage Transfer Service 代理池。
  4. 在本地代理机器上安装代理。

安排 HDFS 数据湖转移作业

如需安排 HDFS 数据湖转移，请输入 bq mk 命令并提供转移作业创建标志 --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"}'

替换以下内容：

  • TRANSFER_NAME：此标志表示转移配置的显示名称。转移作业名称可以是任何可让您在需要修改转移作业时识别该转移作业的名称。
  • SERVICE_ACCOUNT：用于对转移作业进行身份验证的服务账号名称。该服务账号应属于用于创建转移作业的同一 project_id，并且应具有所有必需的权限。
  • PROJECT_ID：您的 Trusted Cloud by S3NS 项目 ID。 如果未提供 --project_id 来指定具体项目，则系统会使用默认项目。
  • REGION：相应转移配置的位置。
  • LIST_OF_TABLES：要转移的实体列表。使用分层命名规范 - database.table。此字段支持使用 RE2 正则表达式指定表。例如：
    • db1..*：指定数据库中的所有表
    • db1.table1;db2.table2：表格列表
  • AGENT_POOL_NAME：用于创建代理的代理池的名称。
  • DATAPROC_METASTORE：托管 OSS 目标位置的目标 Dataproc Metastore。如需改用 BigLake Metastore，您可以从相应转移配置中省略此字段。如需详细了解如何使用 BigLake Metastore 迁移元数据，请参阅元数据迁移。

运行此命令以创建转移配置并开始 HDFS 数据湖转移。默认情况下，转移作业安排为每 24 小时运行一次，但可以通过转移作业调度选项进行配置。

转移完成后，Hadoop 集群中的表将迁移到 MIGRATION_BUCKET。

数据注入选项

以下部分详细介绍了如何配置 HDFS 数据湖迁移。

元数据迁移

元数据可以迁移到 Dataproc Metastore 或 BigLake Metastore，而底层数据存储在 Cloud Storage 中。

如需将元数据转移到 Dataproc Metastore，请在 destination_dataproc_metastore 字段中指定 metastore 的网址。

如需将元数据转移到 BigLake metastore，您无需在转移配置中指定 destination_dataproc_metastore 字段。系统会根据生成的 YAML 映射文件中的 targetName 字段自动确定目标 BigQuery 数据集。 targetName 字段的格式为两部分标识符，例如 bigquery_dataset_name.bigquery_table_name。默认情况下，命名将与您的源系统保持一致。您必须确保具有源架构名称的 BigQuery 数据集存在，否则请在运行转移作业之前创建该数据集。

如需使用其他 BigQuery 数据集，您必须在 DUMPER_BUCKET 中提供一个额外的配置 YAML 文件（以 config.yaml 为后缀），其中包含对象重写器规则集，然后生成转换映射。以下示例是一个规则集，用于将名为 my_hive_db 的源数据库映射到名为 my_bq_dataset 的 BigQuery 数据集：

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

schema 参数必须与 BigQuery 数据集名称相对应，而 relation 参数必须与表名称相对应。如需了解详情，请参阅输出名称映射。

database 参数还必须设置为 null。

增量转移

如果转移配置是按周期性时间表设置的，则每次后续转移都会使用源表的最新更新来更新 Trusted Cloud by S3NS 中的表。例如，所有包含架构变更的插入、删除或更新操作都会在每次转移时反映在 Trusted Cloud by S3NS 中。

转移时间安排选项

默认情况下，转移作业计划每 24 小时运行一次。如需配置转移作业的运行频率，请将 --schedule 标志添加到转移作业配置中，并使用 schedule 语法指定转移作业的运行时间表。HDFS 数据湖转移作业的运行间隔时间必须至少为 24 小时。

对于一次性转移，您可以向转移配置添加 end_time 标志，以仅运行一次转移。

监控 HDFS 数据湖转移

在安排 HDFS 数据湖转移作业后，您可以使用 bq 命令行工具命令监控转移作业。如需了解如何监控转移作业，请参阅查看转移作业。

跟踪表迁移状态

您还可以运行 dwh-dts-status 工具来监控转移配置或特定数据库中所有已转移表的状态。您还可以使用 dwh-dts-status 工具列出项目中的所有转移作业配置。

准备工作

在使用 dwh-dts-status 工具之前，请执行以下操作：

  1. 通过从 dwh-migration-tools GitHub 代码库下载 dwh-migration-tool 软件包来获取 dwh-dts-status 工具。

  2. 使用以下命令对您的账号进行身份验证，以访问 Trusted Cloud by S3NS ：

    gcloud auth application-default login

    如需了解详情，请参阅应用默认凭据的工作原理。

  3. 验证用户是否具有 bigquery.admin 和 logging.viewer 角色。如需详细了解 IAM 角色，请参阅访问权限控制参考文档。

列出项目中的所有转移配置

如需列出项目中的所有转移配置，请使用以下命令：

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

替换以下内容：

  • PROJECT_ID：正在运行转移操作的 Trusted Cloud by S3NS 项目 ID。
  • LOCATION：创建转移作业配置的位置。

此命令会输出一个表格，其中包含转移配置名称和 ID 的列表。

查看配置中所有表格的状态

如需查看转移配置中包含的所有表的状态，请使用以下命令：

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

替换以下内容：

  • PROJECT_ID：正在运行转移的 Trusted Cloud by S3NS 项目 ID。
  • LOCATION：创建转移作业配置的位置。
  • CONFIG_ID：指定转移配置的 ID。

此命令会输出一个表格，其中包含指定转移配置中的表列表及其转移状态。转移状态可以是以下值之一：PENDING、RUNNING、SUCCEEDED、FAILED、CANCELLED。

查看数据库中所有表的状态

如需查看从特定数据库转移的所有表的状态，请使用以下命令：

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

替换以下内容：

  • PROJECT_ID：正在运行转移的 Trusted Cloud by S3NS 项目 ID。
  • DATABASE：指定数据库的名称。

此命令会输出一个表格，其中包含指定数据库中的表列表及其转移状态。转移状态可以是以下值之一：PENDING、RUNNING、SUCCEEDED、FAILED、CANCELLED。