Organizar tareas ejecutando flujos de procesamiento de dsub en Batch

---

En este tutorial se explica cómo ejecutar una dsub canalización en Batch. En concreto, el ejemplo de flujo de procesamiento dsub procesa datos de secuenciación de ADN en un archivo de mapa de alineación binario (BAM) para crear un archivo de índice BAM (BAI).

Este tutorial está dirigido a los usuarios de Batch que quieran usar dsub con Batch. dsub es un programador de tareas de código abierto para orquestar flujos de trabajo de procesamiento por lotes en Google Cloud. Para obtener más información sobre cómo usar Batch con dsub, consulta la documentación de dsub sobre Batch.

Objetivos

• Ejecuta una canalización de dsub en Batch que lee y escribe archivos en segmentos de Cloud Storage.
• Ver los archivos de salida en un segmento de Cloud Storage.

Costes

En este documento, se utilizan los siguientes componentes facturables de Google Cloud:

• Batch
• Cloud Storage

Para generar una estimación de costes basada en el uso previsto, utiliza la calculadora de precios.

Los usuarios nuevos Google Cloud pueden disfrutar de una prueba gratuita.

Los recursos creados en este tutorial suelen costar menos de un dólar, siempre que completes todos los pasos (incluida la limpieza) a tiempo.

Antes de empezar

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

Install the Google Cloud CLI.

Si utilizas un proveedor de identidades (IdP) externo, primero debes iniciar sesión en la CLI de gcloud con tu identidad federada.

Para inicializar gcloud CLI, ejecuta el siguiente comando:

gcloud init

Create or select a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

• Create a Google Cloud project:

  gcloud projects create PROJECT_ID

  Replace PROJECT_ID with a name for the Google Cloud project you are creating.

• Select the Google Cloud project that you created:

  gcloud config set project PROJECT_ID

  Replace PROJECT_ID with your Google Cloud project name.

Verify that billing is enabled for your Google Cloud project.

Enable the Batch, Cloud Storage, Compute Engine, and Logging APIs:

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

gcloud services enable batch.googleapis.com compute.googleapis.com logging.googleapis.com storage.googleapis.com

Install the Google Cloud CLI.

Si utilizas un proveedor de identidades (IdP) externo, primero debes iniciar sesión en la CLI de gcloud con tu identidad federada.

Para inicializar gcloud CLI, ejecuta el siguiente comando:

gcloud init

Create or select a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

• Create a Google Cloud project:

  gcloud projects create PROJECT_ID

  Replace PROJECT_ID with a name for the Google Cloud project you are creating.

• Select the Google Cloud project that you created:

  gcloud config set project PROJECT_ID

  Replace PROJECT_ID with your Google Cloud project name.

Verify that billing is enabled for your Google Cloud project.

Enable the Batch, Cloud Storage, Compute Engine, and Logging APIs:

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

gcloud services enable batch.googleapis.com compute.googleapis.com logging.googleapis.com storage.googleapis.com

1. Asegúrate de que tu proyecto tenga al menos una cuenta de servicio con los permisos necesarios para este tutorial.

   Nota: Si usas un proyecto nuevo, no es necesario que sigas este paso a menos que tu organización impida que se asignen roles automáticamente a las cuentas de servicio predeterminadas. De forma predeterminada, la cuenta de servicio predeterminada de Compute Engine tiene asignado automáticamente el rol Editor (roles/editor) de IAM, que ya incluye todos los permisos necesarios para este tutorial.

   Cada trabajo requiere una cuenta de servicio que permita al agente de servicio de Batch crear y acceder a los recursos necesarios para ejecutar el trabajo. En este tutorial, la cuenta de servicio del trabajo es la cuenta de servicio predeterminada de Compute Engine.

   Para asegurarte de que la cuenta de servicio predeterminada de Compute Engine tiene los permisos necesarios para que el agente de servicio de Batch cree recursos y acceda a ellos para los trabajos de Batch, pide a tu administrador que asigne a la cuenta de servicio predeterminada de Compute Engine los siguientes roles de gestión de identidades y accesos:

   Importante: Debes asignar estos roles a la cuenta de servicio predeterminada de Compute Engine, no a tu cuenta de usuario. Si no se conceden los roles a la entidad correcta, pueden producirse errores de permisos.
   • Reporter de agente de Batch (roles/batch.agentReporter) en el proyecto
   • Administrador de Storage (roles/storage.admin) en el proyecto
   • (Recomendado) Permite que los trabajos generen registros en Cloud Logging: Escritor de registros (roles/logging.logWriter) en el proyecto

   Para obtener más información sobre cómo conceder roles, consulta el artículo Gestionar el acceso a proyectos, carpetas y organizaciones.

   Es posible que tu administrador también pueda conceder los permisos necesarios a la cuenta de servicio predeterminada de Compute Engine a través de roles personalizados u otros roles predefinidos.

2. Asegúrate de que tienes los permisos necesarios para seguir este tutorial.

   Nota: Si has creado este proyecto, no es necesario que sigas este paso. Como creador del proyecto, se te asigna automáticamente el rol de gestión de identidades y accesos Propietario (roles/owner), que ya tiene todos los permisos necesarios para este tutorial.

   Para obtener los permisos que necesitas para completar este tutorial, pide a tu administrador que te conceda los siguientes roles de gestión de identidades y accesos:

   • Editor de trabajos por lotes (roles/batch.jobsEditor) en el proyecto
   • Usuario de cuenta de servicio (roles/iam.serviceAccountUser) en la cuenta de servicio del trabajo, que en este tutorial es la cuenta de servicio predeterminada de Compute Engine
   • Administrador de objetos de Storage (roles/storage.objectAdmin) en el proyecto

3. Instala dsub y sus dependencias. Para obtener más información, consulta la documentación de instalación de dsub.

   1. Asegúrate de haber instalado versiones de Python y pip que sean compatibles con la versión más reciente de dsub. Para ver las versiones instaladas, ejecuta el siguiente comando:

      pip --version
      

      Si necesitas instalar o actualizar pip o Python, sigue los pasos para instalar Python.

   2. Recomendación: Para evitar errores de conflicto de dependencias al instalar dsub, crea y activa un entorno virtual de Python:

      python -m venv dsub_libs && source dsub_libs/bin/activate
      

   3. Clona el repositorio de GitHub dsub con git y ábrelo:

      git clone https://github.com/databiosphere/dsub.git && cd dsub
      

   4. Instala dsub y sus dependencias:

      python -m pip install .
      

      El resultado debería ser similar al siguiente:

      ...
      Successfully installed cachetools-5.3.1 certifi-2023.7.22 charset-normalizer-3.3.1 dsub-0.4.9 funcsigs-1.0.2 google-api-core-2.11.0 google-api-python-client-2.85.0 google-auth-2.17.3 google-auth-httplib2-0.1.0 google-cloud-batch-0.10.0 googleapis-common-protos-1.61.0 grpcio-1.59.0 grpcio-status-1.59.0 httplib2-0.22.0 idna-3.4 mock-4.0.3 parameterized-0.8.1 proto-plus-1.22.3 protobuf-4.24.4 pyasn1-0.4.8 pyasn1-modules-0.2.8 pyparsing-3.1.1 python-dateutil-2.8.2 pytz-2023.3 pyyaml-6.0 requests-2.31.0 rsa-4.9 six-1.16.0 tabulate-0.9.0 tenacity-8.2.2 uritemplate-4.1.1 urllib3-2.0.7
      

Crea un segmento de Cloud Storage

Para crear un segmento de Cloud Storage en el que almacenar los archivos de salida de la canalización de ejemplo dsub con la CLI de gcloud, ejecuta el comando gcloud storage buckets create:

gcloud storage buckets create gs://BUCKET_NAME \
    --project PROJECT_ID

Haz los cambios siguientes:

• BUCKET_NAME: un nombre único a nivel global para tu contenedor.

• PROJECT_ID: el ID de proyecto de tu Google Cloud proyecto.

El resultado debería ser similar al siguiente:

Creating gs://BUCKET_NAME/...

Ejecuta el flujo de procesamiento dsub.

El flujo de procesamiento de dsub de ejemplo indexa un archivo BAM del proyecto 1000 Genomas y envía los resultados a un segmento de Cloud Storage.

Para ejecutar la canalización de ejemplo dsub, ejecuta el siguiente comando dsub:

dsub \
    --provider google-batch \
    --project PROJECT_ID \
    --logging gs://BUCKET_NAME/WORK_DIRECTORY/logs \
    --input BAM=gs://genomics-public-data/1000-genomes/bam/HG00114.mapped.ILLUMINA.bwa.GBR.low_coverage.20120522.bam \
    --output BAI=gs://BUCKET_NAME/WORK_DIRECTORY/HG00114.mapped.ILLUMINA.bwa.GBR.low_coverage.20120522.bam.bai \
    --image quay.io/cancercollaboratory/dockstore-tool-samtools-index \
    --command 'samtools index ${BAM} ${BAI}' \
    --wait

Haz los cambios siguientes:

• PROJECT_ID: el ID de proyecto de tu Google Cloud proyecto.

• BUCKET_NAME: el nombre del segmento de Cloud Storage que has creado.

• WORK_DIRECTORY: el nombre de un nuevo directorio que la canalización puede usar para almacenar registros y resultados. Por ejemplo, escribe workDir.

El flujo de procesamiento dsub ejecuta una tarea por lotes que escribe el archivo BAI y los registros en el directorio especificado de tu segmento de Cloud Storage. En concreto, el repositorio dsub contiene una imagen de Docker prediseñada que usa samtools para indexar el archivo BAM que has especificado en la marca --input.

El comando no finaliza hasta que se completa la ejecución de la canalización dsub, lo que puede variar en función de cuándo se programe el trabajo por lotes. Por lo general, este proceso tarda unos 10 minutos: Batch suele empezar a ejecutar el trabajo en unos minutos y el tiempo de ejecución del trabajo es de unos 8 minutos.

Al principio, el comando sigue ejecutándose y el resultado es similar al siguiente:

Job properties:
  job-id: JOB_NAME
  job-name: samtools
  user-id: USERNAME
Provider internal-id (operation): projects/PROJECT_ID/locations/us-central1/jobs/JOB_NAME
Launched job-id: JOB_NAME
To check the status, run:
  dstat --provider google-batch --project PROJECT_ID --location us-central1 --jobs 'JOB_NAME' --users 'USERNAME' --status '*'
To cancel the job, run:
  ddel --provider google-batch --project PROJECT_ID --location us-central1 --jobs 'JOB_NAME' --users 'USERNAME'
Waiting for job to complete...
Waiting for: JOB_NAME.

Después de que el trabajo se haya completado correctamente, el comando finaliza y el resultado es similar al siguiente:

  JOB_NAME: SUCCESS
JOB_NAME

Esta salida incluye los siguientes valores:

• JOB_NAME: el nombre del puesto.

• USERNAME: tu nombre de usuario Google Cloud .

• PROJECT_ID: el ID de proyecto de tu Google Cloud proyecto.

Ver los archivos de salida

Para ver los archivos de salida creados por el flujo de trabajo dsub de ejemplo con gcloud CLI, ejecuta el comando gcloud storage ls:

gcloud storage ls gs://BUCKET_NAME/WORK_DIRECTORY \
    --project PROJECT_ID

Haz los cambios siguientes:

• BUCKET_NAME: el nombre del segmento de Cloud Storage que has creado.

• WORK_DIRECTORY: el directorio que has especificado en el comando dsub.

• PROJECT_ID: el ID de proyecto de tu Google Cloud proyecto.

El resultado debería ser similar al siguiente:

gs://BUCKET_NAME/WORK_DIRECTORY/HG00114.mapped.ILLUMINA.bwa.GBR.low_coverage.20120522.bam.bai
gs://BUCKET_NAME/WORK_DIRECTORY/logs/

Esta salida incluye el archivo BAI y un directorio que contiene los registros del trabajo.

Limpieza

Para evitar que los recursos utilizados en este tutorial se cobren en tu cuenta de Google Cloud, elimina el proyecto que contiene los recursos o conserva el proyecto y elimina los recursos.

Eliminar el proyecto

La forma más fácil de evitar que te cobren es eliminar el proyecto actual.

Precaución: Eliminar un proyecto tiene los siguientes efectos:

• Se elimina todo el contenido del proyecto. Si has usado un proyecto que ya existía para las tareas de este documento, cuando lo elimines, también se eliminará cualquier otro trabajo que hayas realizado en él.
• Se pierden los IDs de proyecto personalizados. Cuando creaste este proyecto, es posible que hayas creado un ID de proyecto personalizado que quieras usar en el futuro. Para conservar las URLs que usan el ID del proyecto, como una URL appspot.com, elimina los recursos seleccionados dentro del proyecto en lugar de eliminar todo el proyecto.

Si tienes previsto consultar varias arquitecturas, tutoriales o guías de inicio rápido, reutilizar los proyectos puede ayudarte a no superar los límites de cuota de proyectos.

Delete a Google Cloud project:

gcloud projects delete PROJECT_ID

Eliminar recursos concretos

Si quieres seguir usando el proyecto actual, elimina los recursos que se han utilizado en este tutorial.

Eliminar el segmento

Una vez que se haya ejecutado la canalización, se crearán y almacenarán archivos de salida en el directorio WORK_DIRECTORY de tu segmento de Cloud Storage.

Para reducir los cargos de Cloud Storage en la cuenta actual, haz una de las siguientes acciones:Google Cloud

• Si ya no necesitas el segmento que has usado en este tutorial, utiliza el comando gcloud storage rm con la marca --recursive para eliminar el segmento y todo su contenido:

  gcloud storage rm gs://BUCKET_NAME \
      --recursive \
      --project PROJECT_ID
  

  Haz los cambios siguientes:

  • BUCKET_NAME: el nombre del segmento de Cloud Storage que has creado.

  • PROJECT_ID: el ID de proyecto de tu Google Cloud proyecto.

• De lo contrario, si sigues necesitando el segmento, usa el comando gcloud storage rm con la marca --recursive para eliminar solo el directorio WORK_DIRECTORY y todo su contenido:

  gcloud storage rm gs://BUCKET_NAME/WORK_DIRECTORY \
      --recursive \
      --project PROJECT_ID
  

  Haz los cambios siguientes:

  • BUCKET_NAME: el nombre del segmento de Cloud Storage que has creado.

  • WORK_DIRECTORY: el directorio que has especificado en el comando dsub.

  • PROJECT_ID: el ID de proyecto de tu Google Cloud proyecto.

Eliminar el trabajo

Para eliminar un trabajo con gcloud CLI, ejecuta el comando gcloud batch jobs delete.

gcloud batch jobs delete JOB_NAME \
    --location us-central1 \
    --project PROJECT_ID

Haz los cambios siguientes:

• JOB_NAME: el nombre del puesto.
• PROJECT_ID: el ID de proyecto de tu Google Cloud proyecto.

Siguientes pasos

• Consulta más información sobre dsub y dsub para Batch.
• Más información sobre cómo usar volúmenes de almacenamiento con Batch