Importa archivos Avro desde Cloud Spanner

En esta página, se describe cómo importar bases de datos de Cloud Spanner a Cloud Spanner con Google Cloud Console. Para importar archivos Avro desde otra fuente, consulta la página sobre cómo importar datos de bases de datos ajenas a Cloud Spanner.

En el proceso, se usa Dataflow; importa datos desde una carpeta de depósito de Cloud Storage que contiene un conjunto de archivos Avro y archivos de manifiesto JSON. Para el proceso de importación solo se admiten archivos Avro exportados desde Cloud Spanner.

Para importar una base de datos de Cloud Spanner con la API de REST o la herramienta de línea de comandos de gcloud, completa los pasos de la sección Antes de comenzar en esta página y consulta las instrucciones detalladas en Cloud Storage Avro a Cloud Spanner.

Antes de comenzar

Para importar una base de datos de Cloud Spanner, primero debes habilitar las API de Cloud Spanner, Cloud Storage, Compute Engine y Dataflow:

Habilita las API

También necesitas una cuota suficiente y los permisos de IAM necesarios.

Requisitos de cuota

Los requisitos de cuota para los trabajos de importación por parte del servicio de Google Cloud son los siguientes:

  • Cloud Spanner: Debes tener suficientes nodos para admitir la cantidad de datos que deseas importar. No se requieren nodos adicionales para importar una base de datos, aunque es posible que debas agregar más nodos a fin de que el trabajo se complete en un tiempo razonable. Consulta la sección Optimiza los trabajos de importación de ejecución lenta para obtener más detalles.
  • Cloud Storage: Para importar, debes tener un depósito que contenga los archivos exportados con anterioridad. No es necesario que establezcas un tamaño para tu depósito.
  • Dataflow: Los trabajos de importación están sujetos a las mismas cuotas de Compute Engine de direcciones IP, uso del disco y CPU que otros trabajos de Dataflow.
  • Compute Engine: Antes de ejecutar el trabajo de importación, debes establecer las cuotas iniciales para Compute Engine, que Dataflow usa. Estas cuotas representan la cantidad máxima de recursos que permites que Dataflow use para tu trabajo. Los valores iniciales recomendados son los siguientes:

    • CPU: 200
    • Direcciones IP en uso: 200
    • Disco persistente estándar: 50 TB

    Por lo general, no es necesario hacer ningún otro ajuste. Dataflow proporciona ajuste de escala automático para que solo pagues por los recursos que sí se usan durante la importación. Si tu trabajo puede hacer uso de más recursos, la IU de Dataflow muestra un ícono de advertencia. El trabajo debería completarse incluso si hay un ícono de advertencia.

Requisitos de IAM

Para importar una base de datos, también necesitas tener funciones de IAM con permisos suficientes para usar todos los servicios involucrados en un trabajo de importación. Para obtener información sobre cómo otorgar permisos y funciones, consulta la página sobre cómo aplicar funciones de IAM.

Para importar una base de datos, necesitas las funciones mencionadas a continuación:

  • A nivel de proyecto de Google Cloud:
    • Visualizador de Cloud Spanner
    • Administrador de Dataflow
    • Administrador de almacenamiento
  • A nivel de la base de datos de Cloud Spanner o de la instancia, o a nivel de proyecto de Google Cloud:
    • Lector de Cloud Spanner
    • Administrador de base de datos de Cloud Spanner (obligatorio solo para trabajos de importación)

Encuentra la carpeta de tu base de datos en Cloud Storage (opcional)

Para encontrar la carpeta que contiene tu base de datos exportada en Cloud Console, dirígete al navegador de Cloud Storage y haz clic en el depósito que contiene la carpeta exportada.

Ir al navegador de Cloud Storage

El nombre de la carpeta que contiene los datos exportados comienza con el ID de la instancia, el nombre de la base de datos y la marca de tiempo de tu trabajo de exportación. La carpeta contiene estos archivos:

  • Un archivo spanner-export.json
  • Un archivo TableName-manifest.json para cada tabla de la base de datos que exportaste
  • Uno o más archivos TableName.avro-#####-of-#####. El primer número de la extensión .avro-#####-of-##### representa el índice del archivo Avro y comienza en cero; el segundo representa la cantidad de archivos Avro generados para cada tabla.

    Por ejemplo, Songs.avro-00001-of-00002 es el segundo de dos archivos que contienen los datos de la tabla Songs.

Importa una base de datos

Para importar tu base de datos de Cloud Spanner desde Cloud Storage hasta tu instancia, sigue estos pasos.

  1. Ve a la página Instancias de Cloud Spanner.

    Ir a la página Instancias

  2. Haz clic en el nombre de la instancia que contendrá la base de datos importada.

  3. Haz clic en la pestaña Importar/Exportar y, luego, en el botón Importar.

  4. En Elegir una carpeta fuente, haz clic en Explorar.

  5. Busca el depósito que contiene tu exportación en la lista inicial o haz clic en Buscar Captura de pantalla del elemento de IU de búsqueda para filtrar la lista y encontrar el depósito. Haz doble clic en el depósito para ver las carpetas que contiene.

  6. Busca la carpeta con tus archivos exportados y haz clic en ella para seleccionarla.

  7. Haz clic en Seleccionar.

  8. Escribe un nombre para la base de datos nueva, que Cloud Spanner crea durante el proceso de importación. El nombre de la base de datos no puede existir en tu instancia.

  9. En el menú desplegable Elegir una región para el trabajo de importación, selecciona una región.

  10. Selecciona la casilla de verificación en Confirmar cargos para confirmar que existen cargos adicionales a los incurridos por tus nodos actuales de Cloud Spanner.

  11. Haz clic en Importar.

    Cloud Console muestra la página Detalles de la base de datos, que ahora muestra un cuadro que describe tu trabajo de importación, incluido el tiempo transcurrido del trabajo:

    Captura de pantalla del trabajo en curso

Cuando el trabajo finaliza, Cloud Console muestra un mensaje en la página Detalles de la base de datos. Si el trabajo se realiza de forma correcta, aparecerá un mensaje como el siguiente:

Mensaje de éxito del trabajo de importación

Si el trabajo no se realiza correctamente, aparece un mensaje de error:

Mensaje de error sobre el trabajo de importación

Si tu trabajo falla, revisa los registros de Dataflow del trabajo para ver los detalles del error y consulta Solución de problemas de trabajos de importación con errores.

Elige una región para tu trabajo de importación

Se recomienda elegir una región diferente en función de si el depósito de Cloud Storage usa una configuración regional o multirregional. Para evitar los cargos de salida de red, elige una región que se superponga con la ubicación del depósito de Cloud Storage.

Ubicaciones de depósitos regionales

Si la ubicación del depósito de Cloud Storage es regional, elige la misma región para tu trabajo de importación si esa región está disponible a fin de aprovechar el uso gratuito de la red.

Si la misma región no está disponible, se aplicarán cargos de salida. Consulta los precios de salida de red de Cloud Storage para elegir la región que tenga los cargos de salida de red más bajos.

Ubicaciones del depósito multirregional

Si la ubicación de tu depósito de Cloud Storage es multirregional, elige una de las regiones que conforman la ubicación multirregional para aprovechar el uso gratuito de red.

Si una región superpuesta no está disponible, se aplicarán los cargos de salida. Consulta los precios de salida de red de Cloud Storage para elegir una región que incurrirá en los cargos de salida de red más bajos.

Visualiza o soluciona problemas de trabajos en la IU de Dataflow

Después de iniciar un trabajo de importación, podrás ver los detalles del trabajo, incluidos los registros, en la sección de Dataflow de Cloud Console.

Visualiza los detalles del trabajo de Dataflow

Para ver los detalles de un trabajo en ejecución, sigue estos pasos:

  1. Navega hasta la página Detalles de la base de datos de la base de datos.
  2. Haz clic en Ver detalles del trabajo en Dataflow (View job details in Dataflow) en el mensaje de estado del trabajo, que se parece al siguiente:

    Mensaje de estado del trabajo en curso

    Cloud Console muestra los detalles del trabajo de Dataflow.

Para ver un trabajo que ejecutaste hace poco tiempo, haz lo siguiente:

  1. Navega hasta la página Detalles de la base de datos de la base de datos.
  2. Haz clic en la pestaña Importar/Exportar.
  3. Haz clic en el nombre de tu trabajo en la lista.

    Cloud Console muestra los detalles del trabajo de Dataflow.

Para ver un trabajo que ejecutaste hace más de una semana, sigue estos pasos:

  1. Ve a la página Trabajos de Dataflow en Cloud Console.

    Ir a la página Trabajos

  2. Busca tu trabajo en la lista y haz clic sobre su nombre.

    Cloud Console muestra los detalles del trabajo de Dataflow.

Visualiza registros de Dataflow para tu trabajo

Para ver los registros de un trabajo de Dataflow, navega hasta la página de detalles del trabajo como se describió con anterioridad y, luego, haz clic en Registros a la derecha del nombre del trabajo.

Si un trabajo falla, busca errores en los registros. Si hay errores, el recuento de errores se muestra junto a Registros (Logs):

Ejemplo de recuento de errores junto al botón Registros (Logs)

Para ver los errores del trabajo, sigue estos pasos:

  1. Haz clic en el recuento de errores junto a Registros (Logs).

    Cloud Console muestra los registros del trabajo. Es posible que debas desplazarte para ver los errores.

  2. Identifica las entradas con el ícono de error Ícono de error.

  3. Haz clic en una entrada de registro individual para expandir su contenido.

Para obtener más información sobre cómo solucionar problemas de trabajos de Dataflow, consulta Solución de problemas y depuración.

Solucionar problemas de trabajos de importación que fallaron

Si ves los siguientes errores en tus registros de trabajos, haz lo siguiente:

com.google.cloud.spanner.SpannerException: NOT_FOUND: Session not found

--or--

com.google.cloud.spanner.SpannerException: DEADLINE_EXCEEDED: Deadline expired before operation could complete.

Verifica la latencia de escritura del 99% en la pestaña Supervisión de tu base de datos de Cloud Spanner en Cloud Console. Si se muestran valores altos (de varios segundos), eso indica que la instancia está sobrecargada, lo que hace que las escrituras agoten el tiempo de espera y fallen.

Una de las causas de la latencia alta es que el trabajo de Dataflow se ejecuta con demasiados trabajadores, lo que pone demasiada carga en la instancia de Cloud Spanner.

Para especificar un límite en la cantidad de trabajadores de Dataflow, en lugar de usar la pestaña Importar/Exportar en la página de detalles de la instancia de Cloud Spanner en Cloud Console, debes iniciar la importación con la plantilla de Avro de Cloud Storage a Cloud Spanner de Dataflow y especificar la cantidad máxima de trabajadores como se describe a continuación:
  • Si usas la consola de Dataflow, el parámetro Cantidad máxima de trabajadores se encuentra en la sección Parámetros opcionales de la página Crear un trabajo a partir de una plantilla.

  • Si usas gcloud, especifica el argumento max-workers. Por ejemplo:

    gcloud dataflow jobs run my-import-job \
    --gcs-location='gs://dataflow-templates/latest/GCS_Avro_to_Cloud_Spanner' \
    --region=us-central1 \
    --parameters='instanceId=test-instance,databaseId=example-db,inputDir=gs://my-gcs-bucket' \
    --max-workers=10
    

La cantidad máxima de trabajadores depende en gran medida del tamaño de los datos, pero el uso total de CPU de Spanner ideal debe estar entre el 70% y el 90%. Esto proporciona un buen balance entre la eficiencia de Spanner y la finalización de trabajos sin errores.

Para lograr ese objetivo de uso en la mayoría de los esquemas o situaciones, recomendamos una cantidad máxima de CPU virtuales de trabajador de entre 4 y 6 veces la cantidad de nodos de Spanner.

Por ejemplo, para una instancia de Spanner de 10 nodos, con trabajadores n1-standard-2, deberías establecer el máximo de trabajadores en 25, lo que daría 50 CPU virtuales.

Optimiza los trabajos de importación de ejecución lenta

Si seguiste las sugerencias de la configuración inicial, por general, no se debe realizar ningún otro ajuste. Si tu trabajo se ejecuta a poca velocidad, existen otras optimizaciones que puedes probar:

  • Optimiza el trabajo y la ubicación de los datos: Ejecuta tu trabajo de Dataflow en la misma región donde se encuentran tu instancia de Cloud Spanner y el depósito de Cloud Storage.

  • Garantiza recursos suficientes de Dataflow: Si las cuotas relevantes de Compute Engine limitan los recursos de tu trabajo de Dataflow, la página de Dataflow del trabajo en Google Cloud Console muestra un ícono de advertencia Ícono de advertencia y mensajes de registro:

    Captura de pantalla de la advertencia de límite de cuota

    En esta situación, aumentar las cuotas para CPU, direcciones IP en uso y el disco persistente estándar podría acortar el tiempo de ejecución del trabajo, pero se podrían generar más cargos de Compute Engine.

  • Comprueba el uso de CPU de Cloud Spanner: Si ves que el uso de CPU de la instancia supera el 65%, puedes aumentar la cantidad de nodos en esa instancia. Los nodos adicionales agregan más recursos de Cloud Spanner, por lo que el trabajo debería acelerarse, pero se te cobrarán más cargos de Cloud Spanner.

Factores que afectan el rendimiento del trabajo de importación

Varios factores influyen en el tiempo que tarda en completarse un trabajo de importación.

  • Tamaño de la base de datos de Cloud Spanner: Procesar más datos requiere más tiempo y recursos.

  • Esquema de la base de datos de Cloud Spanner: La cantidad de tablas, el tamaño de las filas, la cantidad de índices secundarios y la cantidad de claves externas son factores que influyen en el tiempo que toma la ejecución de un trabajo de importación. Ten en cuenta que la creación del índice y de la clave externa continúa después de que se completa el trabajo de importación de Dataflow.

  • Ubicación de los datos: Los datos se transfieren entre Cloud Spanner y Cloud Storage mediante Dataflow. Lo ideal es que los tres componentes se ubiquen en la misma región. Si los componentes no están en la misma región, mover los datos entre las regiones hace que la ejecución del trabajo sea más lenta.

  • Cantidad de trabajadores de Dataflow: Mediante el ajuste de escala automático, Dataflow elige la cantidad de trabajadores en función de la cantidad de trabajo que se debe realizar. Sin embargo, la cantidad de trabajadores estará limitada por las cuotas de las CPU, las direcciones IP en uso y el disco persistente estándar. La IU de Dataflow muestra un ícono de advertencia si se alcanzan los límites de cuota. En esta situación, el progreso es más lento, pero el trabajo se completará de todos modos.

  • Carga existente en Cloud Spanner: Un trabajo de importación agrega una carga de CPU significativa en una instancia de Cloud Spanner. Si la instancia ya tiene una carga sustancial existente, el trabajo se ejecutará más lento.

  • Cantidad de nodos de Cloud Spanner: Si el uso de CPU de la instancia supera el 65%, el trabajo se ejecutará más lento.