Migra las tablas administradas de Hive a Google Cloud

En este documento, se muestra cómo migrar tus tablas administradas de Hive a Google Cloud.

Puedes usar el conector de migración de tablas administradas de Hive en el Servicio de transferencia de datos de BigQuery para migrar sin problemas tus tablas administradas por el metastore de Hive, que admite los formatos de Hive y Iceberg desde entornos locales y de nube a Google Cloud. El conector de migración de tablas administradas de Hive admite archivos almacenados en las siguientes fuentes de datos:

HDFS
Amazon S3
Azure Blob Storage o Azure Data Lake Storage Gen2

Con el conector de migración de tablas administradas de Hive, puedes registrar tus tablas administradas de Hive en Dataproc Metastore o en el catálogo de Iceberg de BigLake metastore REST mientras usas Cloud Storage como almacenamiento de archivos.

Este conector admite transferencias completas y solo de metadatos. Las transferencias completas transferirán tus datos y metadatos de las tablas de origen al metastore de destino. Puedes realizar una transferencia solo de metadatos si ya migraste tus datos a Cloud Storage.

En el siguiente diagrama, se proporciona una descripción general del proceso de migración de tablas desde el clúster de Hadoop.

Descripción general de la migración de tablas del data lake de Hive a BigQuery.

Limitaciones

Las transferencias de tablas administradas de Hive están sujetas a las siguientes limitaciones:

Para migrar tablas de Apache Iceberg, debes registrarlas en el catálogo de Iceberg REST del metastore de BigLake para permitir el acceso de escritura a los motores de código abierto (como Apache Spark o Flink).
Para migrar tablas administradas de Hive, debes registrarlas en Dataproc Metastore para permitir el acceso de escritura a los motores de código abierto y el acceso de lectura a BigQuery.
Los nombres de los archivos deben cumplir con los requisitos para nombrar objetos de Cloud Storage.
El Servicio de transferencia de almacenamiento tiene comportamientos específicos si los datos cambian en la fuente mientras se realiza una transferencia. No recomendamos escribir en las tablas mientras se migran de forma activa.
Cloud Storage tiene un límite de 5 TiB para objetos individuales. No se podrán transferir los archivos de más de 5 TiB que se encuentren en tus tablas de Apache Hive.

Para obtener una lista de otras limitaciones, consulta Limitaciones conocidas del servicio de transferencia de almacenamiento.

Cuotas y límites de simultaneidad

Cuando migras datos de tablas administradas de Hive, se aplican las cuotas y los límites del Servicio de transferencia de almacenamiento. Para obtener más información, consulta Cuotas y límites.

Antes de comenzar

Antes de programar la transferencia de tablas administradas de Hive, debes realizar las siguientes acciones:

Genera un archivo de metadatos para Apache Hive

Ejecuta la herramienta dwh-migration-dumper para extraer metadatos de Apache Hive. La herramienta genera un archivo llamado hive-dumper-output.zip en un bucket de Cloud Storage, al que se hace referencia en este documento como DUMPER_BUCKET.

Habilita las APIs

Habilita las siguientes APIs en tu proyecto deGoogle Cloud :

API de Data Transfer
API de Storage Transfer

Cuando habilitas la API de Data Transfer, se crea un agente de servicio.

Configura permisos

Crea una cuenta de servicio y otórgale el rol de administrador de BigQuery (roles/bigquery.admin). Esta cuenta de servicio se usa para crear la configuración de transferencia.
Cuando se habilita la API de Data Transfer, se crea un agente de servicio (P4SA). Otorga los siguientes roles:
- roles/metastore.metadataOwner
- roles/storagetransfer.admin
- roles/serviceusage.serviceUsageConsumer
- roles/storage.objectAdmin
- roles/storage.admin
  - Si migras metadatos al catálogo REST de Iceberg de BigLake Metastore, también debes otorgar el rol roles/biglake.admin.

Otorga al agente de servicio el rol roles/iam.serviceAccountTokenCreator con el siguiente comando:

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

Otorga al agente de servicio del Servicio de transferencia de almacenamiento (project-<var>PROJECT_NUMBER</var>@storage-transfer-service.iam.gserviceaccount.com) los siguientes roles en el proyecto:
- roles/storage.admin
- Si migras desde HDFS, también debes otorgar el rol roles/storagetransfer.serviceAgent.
También puedes configurar permisos más detallados. Para obtener más información, consulta las guías de permisos específicos de la fuente:
- Permisos de HDFS
- Permisos de Amazon S3 y Microsoft Azure

Configura Storage Transfer Agent para los data lakes de HDFS

Se requiere cuando el archivo se almacena en HDFS. Para configurar el agente de transferencia de almacenamiento necesario para una transferencia de data lake de HDFS, haz lo siguiente:

Instala Docker en las máquinas de agentes locales.
Crea un grupo de agentes del Servicio de transferencia de almacenamiento en tu Google Cloud proyecto.
Instala agentes en tus máquinas de agentes locales.

Configura los permisos del Servicio de transferencia de almacenamiento para Amazon S3

Se requiere cuando el archivo se almacena en Amazon S3. Las transferencias de Amazon S3 son transferencias sin agente que requieren permisos específicos. Para configurar el Servicio de transferencia de almacenamiento para una transferencia de Amazon S3, haz lo siguiente:

Configura las credenciales de acceso para AWS Amazon S3.
- Toma nota del ID de clave de acceso y la clave de acceso secreta después de configurar tus credenciales de acceso.
Agrega los rangos de IP que usan los trabajadores del Servicio de transferencia de almacenamiento a tu lista de IPs permitidas si tu proyecto de AWS usa restricciones de IP.

Configura los permisos del Servicio de transferencia de almacenamiento para Microsoft Azure Storage

Se requiere cuando el archivo se almacena en Azure Blob Storage o Azure Data Lake Storage Gen2. Las transferencias desde Microsoft Azure Storage son transferencias sin agentes que requieren permisos específicos. Para configurar el Servicio de transferencia de almacenamiento para una transferencia de Microsoft Azure Storage, haz lo siguiente:

Genera un token de firma de acceso compartido (SAS) para tu cuenta de almacenamiento de Microsoft Azure.
- Toma nota del token SAS después de generarlo.
Agrega los rangos de IP que usan los trabajadores del Servicio de transferencia de almacenamiento a tu lista de IPs permitidas si tu cuenta de almacenamiento de Microsoft Azure usa restricciones de IP.

Programa la transferencia de tablas administradas de Hive

Selecciona una de las siguientes opciones:

Console

Ve a la página Transferencia de datos en la Google Cloud consola.

Ir a Transferencias de datos
Haz clic en Crear transferencia.
En la sección Tipo de fuente, selecciona Tablas administradas de Hive en la lista Fuente.
En Ubicación, selecciona un tipo de ubicación y, luego, una región.
En la sección Nombre de configuración de la transferencia, en Nombre visible, ingresa el nombre de la transferencia de datos.
En la sección Opciones de programación, haz lo siguiente:
- En la lista Frecuencia de repetición, selecciona una opción para especificar la frecuencia con la que se ejecuta esta transferencia de datos. Para especificar una frecuencia de repetición personalizada, selecciona Personalizado. Si seleccionas Según demanda, esta transferencia se ejecuta cuando activas la transferencia de forma manual.
- Si corresponde, selecciona Comenzar ahora o Comenzar a una hora determinada y proporciona una fecha de inicio y una hora de ejecución.
En la sección Detalles de fuente de datos, haz lo siguiente:
1. En Estrategia de transferencia, selecciona una de las siguientes opciones:
  - FULL_TRANSFER: Transfiere todos los datos y registra los metadatos en el metastore de destino. Esta es la opción predeterminada.
  - METADATA_ONLY: Solo registra metadatos. Debes tener datos presentes en la ubicación correcta de Cloud Storage a la que se hace referencia en los metadatos.
2. En Patrones de nombres de tablas, especifica las tablas del lago de datos de HDFS que se transferirán. Para ello, proporciona nombres de tablas o patrones que coincidan con las tablas de la base de datos de HDFS. Debes usar la sintaxis de expresiones regulares de Java para especificar patrones de tablas. Por ejemplo:
  - db1..* coincide con todas las tablas de db1.
  - db1.table1;db2.table2 coincide con table1 en db1 y table2 en db2.
3. En BQMS discovery dump gcs path, ingresa la ruta de acceso al archivo hive-dumper-output.zip que generaste cuando creaste un archivo de metadatos para Apache Hive. Si usas la orquestación de salida del volcado con cron, proporciona la ruta de acceso a la carpeta de Cloud Storage configurada en --gcs-base-path, que contiene archivos ZIP de salida del volcado.
4. Elige el tipo de metastore en la lista desplegable:
  - DATAPROC_METASTORE: Selecciona esta opción para almacenar tus metadatos en Dataproc Metastore. Debes proporcionar la URL de Dataproc Metastore en URL de Dataproc Metastore.
  - BIGLAKE_REST_CATALOG: Selecciona esta opción para almacenar tus metadatos en el catálogo de REST de Iceberg de BigLake Metastore.
5. En Ruta de acceso de GCS de destino, ingresa una ruta de acceso a un bucket de Cloud Storage para almacenar los datos migrados.
6. Opcional: En Cuenta de servicio, ingresa una cuenta de servicio para usar con esta transferencia de datos. La cuenta de servicio debe pertenecer al mismo proyecto deGoogle Cloud en el que se crean la configuración de transferencia y el conjunto de datos de destino.
7. En Tipo de almacenamiento, selecciona una de las siguientes opciones. Este campo solo está disponible si Estrategia de transferencia está configurado como FULL_TRANSFER:
  - HDFS: Selecciona esta opción si tu almacenamiento de archivos es HDFS. En el campo Nombre del grupo de agentes de STS, debes proporcionar el nombre del grupo de agentes que creaste cuando configuraste tu agente de transferencia de Storage.
  - S3: Selecciona esta opción si tu almacenamiento de archivos es Amazon S3. En los campos ID de clave de acceso y Clave de acceso secreta, debes proporcionar el ID de clave de acceso y la clave de acceso secreta que creaste cuando configuraste tus credenciales de acceso.
  - AZURE: Selecciona esta opción si tu almacenamiento de archivos es Azure Blob Storage. En el campo Token SAS, debes proporcionar el token SAS que creaste cuando configuraste tus credenciales de acceso.
8. Opcional: En Ruta de acceso de GCS al filtro de partición, ingresa una ruta de acceso completa de Cloud Storage a un archivo JSON de filtro personalizado para filtrar particiones.

bq

Para programar la transferencia de tablas administradas de Hive, ingresa el comando bq mk y proporciona la marca de creación de transferencias --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='{
    "transfer_strategy":"TRANSFER_STRATEGY",
    "table_name_patterns":"LIST_OF_TABLES",
    "table_metadata_path":"gs://DUMPER_BUCKET/hive-dumper-output.zip",
    "target_gcs_file_path":"gs://MIGRATION_BUCKET",
    "metastore":"METASTORE",
    "destination_dataproc_metastore":"DATAPROC_METASTORE_URL",
    "destination_bigquery_dataset":"BIGLAKE_METASTORE_DATASET",
    "translation_output_gcs_path":"gs://TRANSLATION_OUTPUT_BUCKET/metadata/config/default_database/",
    "storage_type":"STORAGE_TYPE",
    "agent_pool_name":"AGENT_POOL_NAME",
    "aws_access_key_id":"AWS_ACCESS_KEY_ID",
    "aws_secret_access_key":"AWS_SECRET_ACCESS_KEY",
    "azure_sas_token":"AZURE_SAS_TOKEN",
    "partition_filter_gcs_path":"FILTER_GCS_PATH"
    }'

Reemplaza lo siguiente:

TRANSFER_NAME es el nombre visible de la configuración de transferencia. El nombre de la transferencia puede ser cualquier valor que te permita identificarla si es necesario hacerle modificaciones más tarde.
SERVICE_ACCOUNT: El nombre de la cuenta de servicio que se usa para autenticar tu transferencia. La cuenta de servicio debe ser propiedad del mismo project_id que se usa para crear la transferencia y debe tener todos los permisos necesarios.
PROJECT_ID: Es el ID del proyecto de Google Cloud . Si no se proporciona --project_id para especificar un proyecto en particular, se usa el proyecto predeterminado.
REGION: Es la ubicación de esta configuración de transferencia.
TRANSFER_STRATEGY: (Opcional) Especifica uno de los siguientes valores:
- FULL_TRANSFER: Transfiere todos los datos y registra los metadatos en el metastore de destino. Este es el valor predeterminado.
- METADATA_ONLY: Solo registra metadatos. Debes tener datos presentes en la ubicación correcta de Cloud Storage a la que se hace referencia en los metadatos.
LIST_OF_TABLES: Es una lista de entidades que se transferirán. Usa una especificación de nombres jerárquica: database.table. Este campo admite expresiones regulares de RE2 para especificar tablas. Por ejemplo:
- db1..*: Especifica todas las tablas de la base de datos.
- db1.table1;db2.table2: Una lista de tablas
DUMPER_BUCKET: Es el bucket de Cloud Storage que contiene el archivo hive-dumper-output.zip. Si usas la orquestación de salida de volcado con cron, cambia table_metadata_path para que sea la ruta de acceso de la carpeta de Cloud Storage configurada con --gcs-base-path en la configuración de cron, por ejemplo: "table_metadata_path":"<var>GCS_PATH_TO_UPLOAD_DUMPER_OUTPUT</var>".
MIGRATION_BUCKET: Es la ruta de acceso de GCS de destino en la que se cargarán todos los archivos subyacentes. Solo está disponible si transfer_strategy es FULL_TRANSFER.
METASTORE: Es el tipo de metastore al que se migrará. Establece este parámetro en uno de los siguientes valores:
- DATAPROC_METASTORE: Para transferir metadatos a Dataproc Metastore.
- BIGLAKE_REST_CATALOG: Para transferir metadatos al catálogo de Iceberg de BigLake Metastore REST.
DATAPROC_METASTORE_URL: Es la URL de tu Dataproc Metastore. Obligatorio si metastore es DATAPROC_METASTORE.
BIGLAKE_METASTORE_DATASET: Es el conjunto de datos de BigQuery para tu metastore de BigLake. Obligatorio si metastore es BIGLAKE_METASTORE y transfer_strategy es FULL_TRANSFER.
STORAGE_TYPE: Especifica el almacenamiento de archivos subyacente para tus tablas. Los tipos admitidos son HDFS, S3 y AZURE. Obligatorio si transfer_strategy es FULL_TRANSFER.
AGENT_POOL_NAME: Es el nombre del grupo de agentes que se usa para crear agentes. Obligatorio si storage_type es HDFS.
AWS_ACCESS_KEY_ID: Es el ID de la clave de acceso de las credenciales de acceso. Obligatorio si storage_type es S3.
AWS_SECRET_ACCESS_KEY: Es la clave de acceso secreta de las credenciales de acceso. Obligatorio si storage_type es S3.
AZURE_SAS_TOKEN: Es el token de SAS de las credenciales de acceso. Obligatorio si storage_type es AZURE.
FILTER_GCS_PATH: (Opcional) Ruta de acceso completa de Cloud Storage a un archivo JSON de filtro personalizado para filtrar particiones.

Ejecuta este comando para crear la configuración de transferencia y comenzar la transferencia de las tablas administradas de Hive. De forma predeterminada, las transferencias se programan para ejecutarse cada 24 horas, pero se pueden configurar con opciones de programación de transferencias.

Cuando se complete la transferencia, tus tablas del clúster de Hadoop se migrarán a MIGRATION_BUCKET.

Opciones de transferencia de datos

En las siguientes secciones, se proporciona más información sobre cómo puedes configurar tus transferencias de tablas administradas de Hive.

Transferencias incrementales

Cuando se configura una transferencia con un programa recurrente, cada transferencia posterior actualiza la tabla en Google Cloud con las actualizaciones más recientes realizadas en la tabla de origen. Por ejemplo, todas las operaciones de inserción, eliminación o actualización con cambios de esquema se reflejan en Google Cloud con cada transferencia.

Opciones de programación de transferencias

De forma predeterminada, las transferencias se programan para ejecutarse cada 24 horas. Para configurar la frecuencia con la que se ejecutan las transferencias, agrega la marca --schedule a la configuración de la transferencia y especifica un programa de transferencia con la sintaxis schedule. Las transferencias de tablas administradas por Hive deben tener un mínimo de 24 horas entre ejecuciones.

En el caso de las transferencias únicas, puedes agregar la marca end_time a la configuración de transferencia para que esta se ejecute solo una vez.

Filtrar particiones

Puedes transferir un subconjunto de particiones de tus tablas administradas de Hive si proporcionas un archivo JSON de filtro personalizado almacenado en Cloud Storage. Cuando programes la transferencia, proporciona la ruta de acceso completa de Cloud Storage a este archivo JSON con el parámetro partition_filter_gcs_path.

A continuación, se muestra un ejemplo de la estructura del archivo JSON de filtro:

{
  "filters": [
    {
      "table": "db1.table1",
      "condition": "IN",
      "partition": ["partition1=value1/partition2=value2"]
    },
    {
      "table": "db1.table2",
      "condition": "LESS_THAN",
      "partition": ["partition1;value1"]
    },
    {
      "table": "db1.table3",
      "condition": "GREATER_THAN",
      "partition": ["partition1;value1"]
    },
    {
      "table": "db1.table4",
      "condition": "RANGE",
      "partition": ["partition1;value1;value2"]
    }
  ]
}

Condiciones de filtro

El campo condition del archivo JSON admite los siguientes valores, cada uno con un formato específico para el array partition:

IN: Especifica las rutas de partición exactas que se deben incluir. El array partition contiene cadenas que representan la estructura de directorios exacta de las particiones en relación con la ruta base de la tabla (por ejemplo, ["partition_key1=value1/partition_key2=value2"]). Puedes especificar varias rutas de acceso en el array.
LESS_THAN: Incluye las particiones en las que el valor de la clave de partición principal es menor o igual que el valor especificado. El array partition debe contener una sola cadena en el formato ["<partition_key>;<value>"].
GREATER_THAN: Incluye las particiones en las que el valor de la clave de partición principal es mayor o igual que el valor especificado. El array partition debe contener una sola cadena con el formato ["<partition_key>;<value>"].
RANGE: Incluye particiones en las que el valor de la clave de partición principal se encuentra dentro del rango especificado (inclusivo). El array partition debe contener una sola cadena en el formato ["<partition_key>;<start_value>;<end_value>"].

Las condiciones del filtro están sujetas a las siguientes reglas y restricciones:

Valores inclusivos: Las condiciones de filtro para GREATER_THAN, LESS_THAN y RANGE incluyen los valores proporcionados. Por ejemplo, un filtro LESS_THAN con un valor de 2023 incluye particiones hasta 2023 inclusive.
Borrado de particiones: Si una partición de destino existente satisface el filtro de partición y ya no está presente en la fuente, se quita del metastore de destino. Sin embargo, los archivos de datos subyacentes de esa partición no se borran del bucket de destino de Cloud Storage.
Restricciones de una sola tabla:
- No se permiten varios filtros en la misma tabla.
- No puedes mezclar diferentes tipos de condiciones (por ejemplo, GREATER_THAN y IN) en la misma tabla.
Columna de partición de destino: Las condiciones de filtro como GREATER_THAN, LESS_THAN y RANGE deben segmentarse para la columna de partición principal.
Limitaciones de prefijos: La combinación de filtros especificada no debe resolverse en más de 1,000 prefijos por tabla. Por ejemplo, un filtro como year>2020 en una tabla particionada por year/month/day debe generar menos de 1,000 prefijos year= únicos.

Configura el resultado de la traducción

Puedes configurar una ruta de acceso y una base de datos de Cloud Storage únicas para cada tabla migrada. Para ello, sigue estos pasos para generar un archivo YAML de asignación de tablas que puedas usar en la configuración de tu transferencia.

Crea un archivo YAML de configuración (con el sufijo config.yaml) en DUMPER_BUCKET que contenga lo siguiente:
```
    type: object_rewriter
    relation:
    - match:
        relationRegex: ".*"
      external:
        location_expression: "'gs://MIGRATION_BUCKET/' + table.schema + '/' + table.name"
```
- Reemplaza MIGRATION_BUCKET por el nombre del bucket de Cloud Storage que es el destino de los archivos de la tabla migrada. El campo location_expression es una expresión del lenguaje de expresiones comunes (CEL).
Crea otro archivo YAML de configuración (con el sufijo config.yaml) en DUMPER_BUCKET que contenga lo siguiente:
```
    type: experimental_object_rewriter
    relation:
      - match:
          schema: SOURCE_DATABASE
        outputName:
          database: null
          schema: TARGET_DATABASE
```
- Reemplaza SOURCE_DATABASE y TARGET_DATABASE por el nombre de la base de datos de origen y la base de datos de Dataproc Metastore o el conjunto de datos de BigQuery, según el metastore elegido. Asegúrate de que exista el conjunto de datos de BigQuery si configuras la base de datos para BigLake Metastore.
Para obtener más información sobre estos archivos YAML de configuración, consulta Lineamientos para crear un archivo YAML de configuración.

Genera el archivo YAML de asignación de tablas con el siguiente comando:

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

Reemplaza lo siguiente:

TRANSLATION_OUTPUT_BUCKET: (Opcional) Especifica un bucket de Cloud Storage para el resultado de la traducción. Para obtener más información, consulta Cómo usar el resultado de la traducción.
DUMPER_BUCKET: Es el URI base del bucket de Cloud Storage que contiene el archivo YAML de hive-dumper-output.zip y de configuración.
TOKEN: Es el token de OAuth. Puedes generar este archivo en la línea de comandos con el comando gcloud auth print-access-token.
PROJECT_ID: Es el proyecto que procesará la traducción.
LOCATION: Es la ubicación en la que se procesa el trabajo. Por ejemplo, eu o us.

Supervisa el estado de este trabajo. Cuando se completa, se genera un archivo de asignación para cada tabla de una base de datos dentro de una ruta predefinida en TRANSLATION_OUTPUT_BUCKET.

Orquesta la ejecución del volcado con el comando `cron`

Puedes automatizar las transferencias incrementales con un trabajo de cron para ejecutar la herramienta dwh-migration-dumper. Al automatizar la extracción de metadatos, te aseguras de que haya disponible un volcado actualizado de Hadoop para las ejecuciones de transferencia incremental posteriores.

Antes de comenzar

Antes de usar esta secuencia de comandos de automatización, debes hacer lo siguiente:

Completa todos los requisitos previos para la instalación del volcado, incluida la instalación de la herramienta dwh-migration-dumper y la configuración de los permisos de IAM.
Instala Google Cloud CLI. La secuencia de comandos usa la herramienta de línea de comandos gsutil para subir el resultado de dumper a Cloud Storage.
Autentícate con Google Cloud para permitir que gsutil suba archivos a Cloud Storage con el siguiente comando:
```
gcloud auth application-default login
```

Cómo programar la automatización

Guarda la siguiente secuencia de comandos en un archivo local. Esta secuencia de comandos está diseñada para que un daemon cron la configure y ejecute para automatizar el proceso de extracción y carga del resultado del volcado:

#!/bin/bash

# Exit immediately if a command exits with a non-zero status.
set -e
# Treat unset variables as an error when substituting.
set -u
# Pipelines return the exit status of the last command to exit with a non-zero status.
set -o pipefail

# These values are used if not overridden by command-line options.
DUMPER_EXECUTABLE="DUMPER_PATH/dwh-migration-dumper"
GCS_BASE_PATH="gs://PATH_TO_DUMPER_OUTPUT"
LOCAL_BASE_DIR="LOCAL_BASE_DIRECTORY_PATH"

# Optional arguments for cloud environments
DUMPER_HOST=""
DUMPER_PORT=""
HIVE_KERBEROS_URL=""
HIVEQL_RPC_PROTECTION=""
KERBEROS_AUTHENTICATION="false"

# Function to display usage information
usage() {
  echo "Usage: $0 [options]"
  echo ""
  echo "Runs the dwh-migration-dumper tool and uploads its output to provided Cloud Storage path."
  echo ""
  echo "Required Options:"
  echo "  --dumper-executable   The full path to the dumper executable."
  echo "  --gcs-base-path       The base Cloud Storage folder to upload dumper output files to. The script generates timestamped ZIP files in this folder."
  echo "  --local-base-dir      The local base directory for logs and temp files."
  echo ""
  echo "Optional Hive connection options:"
  echo "  --host              The hostname for the dumper connection."
  echo "  --port              The port number for the dumper connection."
  echo ""
  echo "To use Kerberos authentication, include the following options."
  echo "If --kerberos-authentication is specified, then --host, --port,"
  echo "--hive-kerberos-url and --hiveql-rpc-protection are all required:"
  echo ""
  echo "  --kerberos-authentication   Enable Kerberos authentication."
  echo "  --hive-kerberos-url    The Hive Kerberos URL."
  echo "  --hiveql-rpc-protection "
  echo "                            The hiveql-rpc-protection level, equal to the value of"
  echo "                            'hadoop.rpc.protection' in '/etc/hadoop/conf/core-site.xml',"
  echo "                            with one of the following values:"
  echo "                            - authentication"
  echo "                            - integrity"
  echo "                            - privacy"
  echo ""
  echo "Other Options:"
  echo "  -h, --help                  Display this help message and exit."
  exit 1
}

# This loop processes command-line options and overrides the default configuration.
while [[ "$#" -gt 0 ]]; do
  case $1 in
      --dumper-executable)
          DUMPER_EXECUTABLE="$2"
          shift # past argument
          shift # past value
          ;;
      --gcs-base-path)
          GCS_BASE_PATH="$2"
          shift
          shift
          ;;
      --local-base-dir)
          LOCAL_BASE_DIR="$2"
          shift
          shift
          ;;
      --host)
          DUMPER_HOST="$2"
          shift
          shift
          ;;
      --port)
          DUMPER_PORT="$2"
          shift
          shift
          ;;
      --hive-kerberos-url)
          HIVE_KERBEROS_URL="$2"
          shift
          shift
          ;;
      --hiveql-rpc-protection)
          HIVEQL_RPC_PROTECTION="$2"
          shift
          shift
          ;;
      --kerberos-authentication)
          KERBEROS_AUTHENTICATION="true"
          shift
          ;;
      -h|--help)
          usage
          ;;
      *)
          echo "Unknown option: $1"
          usage
          ;;
  esac
done

# This runs AFTER parsing arguments to ensure no placeholder values are left.
if [[ "$DUMPER_EXECUTABLE" == "DUMPER_PATH"* || "$GCS_BASE_PATH" == "gs://PATH_TO_DUMPER_OUTPUT" || "$LOCAL_BASE_DIR" == "LOCAL_BASE_DIRECTORY_PATH" ]]; then
  echo "ERROR: One or more configuration variables have not been set. Please provide them as command-line arguments or edit the script." >&2
  echo "Run with --help for more information." >&2
  exit 1
fi

# If Kerberos authentication is enabled, check for required fields.
if [[ "$KERBEROS_AUTHENTICATION" == "true" ]]; then
  if [[ -z "$DUMPER_HOST" || -z "$DUMPER_PORT" || -z "$HIVE_KERBEROS_URL" || -z "$HIVEQL_RPC_PROTECTION" ]]; then
      echo "ERROR: If --kerberos-authentication is enabled, --host, --port, --hive-kerberos-url and --hiveql-rpc-protection must be provided." >&2
      echo "Run with --help for more information." >&2
      exit 1
  fi
fi

# Remove trailing slashes from GCS_BASE_PATH, if any.
GCS_BASE_PATH=$(echo "${GCS_BASE_PATH}" | sed 's:/*$::')

# Create unique timestamp and directories for this run
EPOCH=$(date +%s)
LOCAL_LOG_DIR="${LOCAL_BASE_DIR}/logs"
mkdir -p "${LOCAL_LOG_DIR}" # Ensures the base and logs directories exist

# Define the unique log and zip file path for this run
LOG_FILE="${LOCAL_LOG_DIR}/dumper_execution_${EPOCH}.log"
ZIP_FILE_NAME="dts-cron-dumper-output_${EPOCH}.zip"
LOCAL_ZIP_PATH="${LOCAL_BASE_DIR}/${ZIP_FILE_NAME}"

echo "Script execution started. All subsequent output will be logged to: ${LOG_FILE}"

# --- Helper Functions ---

log() { echo "$(date '+%Y-%m-%d %H:%M:%S') - $@" >> "${LOG_FILE}"; }

cleanup() {
  local path_to_remove="$1"
  log "Cleaning up local file/directory: ${path_to_remove}..."
  rm -rf "${path_to_remove}"
}

# This function is called when the script exits to ensure cleanup and logging happen reliably.
handle_exit() {
  local exit_code=$?
  # Only run the failure logic if the script is exiting with an error
  if [[ ${exit_code} -ne 0 ]]; then
      log "ERROR: Script is exiting with a failure code (${exit_code})."
      local gcs_log_path_on_failure="${GCS_BASE_PATH}/logs/$(basename "${LOG_FILE}")"
      log "Uploading log file to ${gcs_log_path_on_failure} for debugging..."
      # Attempt to upload the log file on failure, but don't let this command cause the script to exit.
      gsutil cp "${LOG_FILE}" "${gcs_log_path_on_failure}" > /dev/null 2>&1 || log "WARNING: Failed to upload log file to Cloud Storage."

  else
      # SUCCESS PATH
      log "Script finished successfully. Now cleaning up local zip file...."
      # Clean up the local zip file ONLY on success
      cleanup "${LOCAL_ZIP_PATH}"
  fi

  log "*****Script End*****"
  exit ${exit_code}
}

# Trap the EXIT signal to run the handle_exit function, ensuring cleanup always happens.
trap handle_exit EXIT

# Validates the dumper log file based on a strict set of rules.
validate_dumper_output() {
  local log_file_to_check="$1"

  # Check for the specific success message from the dumper tool.
  if grep -q "Dumper execution: SUCCEEDED" "${log_file_to_check}"; then
      log "Validation Successful: Found 'Dumper execution: SUCCEEDED' message."
      return 0 # Success
  else
      log "ERROR: Validation failed. The 'Dumper execution: SUCCEEDED' message was not found."
      return 1 # Failure
  fi
}

# --- Main Script Logic ---

log "*****Script Start*****"
log "Dumper Executable: ${DUMPER_EXECUTABLE}"
log "Cloud Storage Base Path: ${GCS_BASE_PATH}"
log "Local Base Directory: ${LOCAL_BASE_DIR}"

# Use an array to build the command safely
dumper_command_args=(
  "--connector" "hiveql"
  "--output" "${LOCAL_ZIP_PATH}"
)

# Add optional arguments if they are provided
if [[ -n "${DUMPER_HOST}" ]]; then
dumper_command_args+=("--host" "${DUMPER_HOST}")
log "Using Host: ${DUMPER_HOST}"
fi
if [[ -n "${DUMPER_PORT}" ]]; then
dumper_command_args+=("--port" "${DUMPER_PORT}")
log "Using Port: ${DUMPER_PORT}"
fi
if [[ -n "${HIVE_KERBEROS_URL}" ]]; then
dumper_command_args+=("--hive-kerberos-url" "${HIVE_KERBEROS_URL}")
log "Using Hive Kerberos URL: ${HIVE_KERBEROS_URL}"
fi
if [[ -n "${HIVEQL_RPC_PROTECTION}" ]]; then
dumper_command_args+=("-Dhiveql.rpc.protection=${HIVEQL_RPC_PROTECTION}")
log "Using HiveQL RPC Protection: ${HIVEQL_RPC_PROTECTION}"
fi

log "Starting dumper tool execution..."
log "COMMAND: JAVA_OPTS=\"-Djavax.security.auth.useSubjectCredsOnly=false\" ${DUMPER_EXECUTABLE} ${dumper_command_args[*]}"

JAVA_OPTS="-Djavax.security.auth.useSubjectCredsOnly=false" "${DUMPER_EXECUTABLE}" "${dumper_command_args[@]}" >> "${LOG_FILE}" 2>&1

log "Dumper process finished."

# Validate the output from the dumper execution for success or failure.
validate_dumper_output "${LOG_FILE}"

# Upload the ZIP file to Cloud Storage
gcs_zip_path="${GCS_BASE_PATH}/${ZIP_FILE_NAME}"
log "Uploading ${LOCAL_ZIP_PATH} to ${gcs_zip_path}..."

if [ ! -f "${LOCAL_ZIP_PATH}" ]; then
  log "ERROR: Expected ZIP file ${LOCAL_ZIP_PATH} not found after dumper execution."
  # The script will exit here with an error code, and the trap will run.
  exit 1
fi

gsutil cp "${LOCAL_ZIP_PATH}" "${gcs_zip_path}" >> "${LOG_FILE}" 2>&1
log "Upload to Cloud Storage successful."

# The script will now exit with code 0. The trap will call cleanup and log the script end.

Ejecuta el siguiente comando para hacer que la secuencia de comandos sea ejecutable:
```
chmod +x PATH_TO_SCRIPT
```

Programa la secuencia de comandos con crontab y reemplaza las variables por los valores adecuados para tu trabajo. Agrega una entrada para programar el trabajo. En los siguientes ejemplos, se ejecuta la secuencia de comandos todos los días a las 2:30 a.m.:

Si ejecutas el comando en un host que tiene acceso directo a Apache Hive y no requiere autenticación de Kerberos, usa el siguiente comando:

Sin autenticación de Kerberos

# Run the Hive dumper daily at 2:30 AM for incremental BigQuery transfer.
30 2 * * * PATH_TO_SCRIPT 

  --dumper-executable PATH_TO_DUMPER_EXECUTABLE 

  --gcs-base-path GCS_PATH_TO_UPLOAD_DUMPER_OUTPUT 

  --local-base-dir LOCAL_PATH_TO_SAVE_INTERMEDIARY_FILES

Si tu instancia de Apache Hive requiere autenticación de Kerberos, usa el siguiente comando:

Con autenticación de Kerberos

# Run the Hive dumper daily at 2:30 AM for incremental BigQuery transfer with Kerberos authentication.
30 2 * * * PATH_TO_SCRIPT 

  --dumper-executable PATH_TO_DUMPER_EXECUTABLE 

  --gcs-base-path GCS_PATH_TO_UPLOAD_DUMPER_OUTPUT 

  --local-base-dir LOCAL_PATH_TO_SAVE_INTERMEDIARY_FILES 

  --kerberos-authentication 

  --host HIVE_HOST 

  --port HIVE_PORT 

  --hive-kerberos-url HIVE_KERBEROS_URL 

  --hiveql-rpc-protection HIVEQL_RPC_PROTECTION

Cuando crees la transferencia, asegúrate de que el campo table_metadata_path esté configurado con la misma ruta de Cloud Storage que configuraste para GCS_PATH_TO_UPLOAD_DUMPER_OUTPUT. Es la ruta de acceso que contiene los archivos ZIP de salida del volcado.

Consideraciones de programación

Para evitar la obsolescencia de los datos, el volcado de metadatos debe estar listo antes de que comience la transferencia programada. Configura la frecuencia del trabajo cron según corresponda.

Te recomendamos que ejecutes algunas pruebas del script de forma manual para determinar el tiempo promedio que tarda la herramienta de volcado en generar su resultado. Usa este tiempo para establecer un programa de cron que preceda de forma segura la ejecución de la transferencia de DTS y garantice la actualización.

Supervisa y consulta el estado de la transferencia

Puedes supervisar las transferencias a nivel de recursos para tablas individuales y, así, hacer un seguimiento del progreso, ver detalles de errores específicos y consultar el estado de los recursos específicos que se están migrando.

Para ver el progreso y el estado de tus recursos, selecciona una de las siguientes opciones:

Console

En la consola de Google Cloud , ve a la página Transferencia de datos.

Ir a Transferencias de datos
Haz clic en la configuración de transferencia en la lista.
En la página Detalles de la transferencia, haz clic en la pestaña Tablas transferidas.
Consulta la lista de recursos que se transfieren. Puedes ver detalles como los siguientes:
- Estado de la última transferencia: Es el estado actual del recurso según la transferencia de recursos más reciente, incluido el progreso de la finalización.
- Nombre de la tabla: Es el nombre del recurso que se está transfiriendo. Haz clic en el nombre del recurso para ver una vista detallada.
- Última ejecución: Es la última ejecución de transferencia que actualizó el recurso.
- Resumen del estado: Métricas de progreso detalladas o mensajes de error si falló la transferencia.
- Última ejecución exitosa: Es la última ejecución que transfirió correctamente el recurso.

Usa la barra de filtros para buscar recursos específicos por nombre o filtrar por su estado actual, por ejemplo, Transferencias fallidas. El filtro Nombre de la tabla admite la coincidencia con comodines (por ejemplo, con *), pero esta no se admite para otros campos de filtro.

API

Puedes consultar el estado de los recursos de transferencia con la API del Servicio de transferencia de datos de BigQuery.

Enumera todos los recursos y sus estados

Para enumerar todos los recursos y sus estados, usa el método projects.locations.transferConfigs.transferResources.list.

Ejecuta la solicitud a la API con la siguiente información:

  GET https://bigquerydatatransfer.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/transferConfigs/CONFIG_ID/transferResources
  Example Response (abridged) (JSON):
  {
    "transferResources": [
      {
        "name": "projects/.../transferResources/table1",
        "latestStatusDetail": {
          "state": "RESOURCE_TRANSFER_SUCCEEDED",
          "completedPercentage": 100.0
        },
        "updateTime": "2026-02-03T22:42:06Z"
      }
    ]
  }

Comando curl:

  curl -X GET 

  "https://bigquerydatatransfer.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/transferConfigs/CONFIG_ID/transferResources" 

  -H "Authorization: Bearer $(gcloud auth print-access-token)" 

  -H "Accept: application/json"

Puedes filtrar los resultados por nombre o estado del recurso. Por ejemplo, para encontrar todas las transferencias fallidas, agrega ?filter=latest_status_detail.state="RESOURCE_TRANSFER_FAILED" a la URL de la solicitud.

Reemplaza lo siguiente:

CONFIG_ID: Es el ID de la configuración de transferencia.
LOCATION: Es la ubicación en la que se creó la configuración de transferencia.
PROJECT_ID: Es el ID del proyecto de Google Cloud que ejecuta las transferencias.

Obtén un recurso específico

Para obtener el estado de una tabla o partición específica, usa el método projects.locations.transferConfigs.transferResources.get.

Ejecuta la solicitud a la API con la siguiente información:

  GET https://bigquerydatatransfer.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/transferConfigs/CONFIG_ID/transferResources/RESOURCE_ID

Comando curl:

  curl -X GET 

  "https://bigquerydatatransfer.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/transferConfigs/CONFIG_ID/transferResources/RESOURCE_ID" 

  -H "Authorization: Bearer $(gcloud auth print-access-token)" 

  -H "Accept: application/json"

Reemplaza lo siguiente:

CONFIG_ID: Es el ID de la configuración de transferencia.
LOCATION: Es la ubicación en la que se creó la configuración de transferencia.
PROJECT_ID: Es el ID del proyecto de Google Cloud que ejecuta las transferencias.
RESOURCE_ID: Es el ID del recurso, por ejemplo, el nombre de la tabla.

Migra las tablas administradas de Hive a Google Cloud

Limitaciones

Cuotas y límites de simultaneidad

Antes de comenzar

Genera un archivo de metadatos para Apache Hive

Habilita las APIs

Configura permisos

Configura Storage Transfer Agent para los data lakes de HDFS

Configura los permisos del Servicio de transferencia de almacenamiento para Amazon S3

Configura los permisos del Servicio de transferencia de almacenamiento para Microsoft Azure Storage

Programa la transferencia de tablas administradas de Hive

Console

bq

Opciones de transferencia de datos

Transferencias incrementales

Opciones de programación de transferencias

Filtrar particiones

Condiciones de filtro

Configura el resultado de la traducción

Orquesta la ejecución del volcado con el comando cron

Antes de comenzar

Cómo programar la automatización

Consideraciones de programación

Supervisa y consulta el estado de la transferencia

Console

API

Orquesta la ejecución del volcado con el comando `cron`