Ejecuta canalizaciones de dsub en Batch para organizar trabajos

En este instructivo, se explica cómo ejecutar una canalización de dsub en Batch. Específicamente, la canalización de ejemplo dsub procesa datos de secuenciación de ADN en un archivo de mapa de alineación binaria (BAM) para crear un archivo de índice BAM (BAI).

Este instructivo está dirigido a los usuarios de Batch que desean usar dsub con Batch. dsub es un programador de trabajos de código abierto para organizar 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 para Batch.

Objetivos

• Ejecuta una canalización de dsub en Batch que lee y escribe archivos en buckets de Cloud Storage.
• Visualiza los archivos de salida en un bucket de Cloud Storage.

Costos

En este documento, usarás los siguientes componentes facturables de Google Cloud:

• Batch
• Cloud Storage

Para generar una estimación de costos en función del uso previsto, usa la calculadora de precios.

Es posible que los usuarios nuevos de Google Cloud cumplan con los requisitos para acceder a una prueba gratuita.

Los recursos creados en este instructivo suelen costar menos de un dólar, suponiendo que completas todos los pasos, incluida la limpieza, de manera oportuna.

Antes de comenzar

Accede a tu cuenta de Google Cloud . Si eres nuevo en Google Cloud, crea una cuenta para evaluar el rendimiento de nuestros productos en situaciones reales. Los clientes nuevos también obtienen $300 en créditos gratuitos para ejecutar, probar y, además, implementar cargas de trabajo.

Instala Google Cloud CLI.

Si usas un proveedor de identidad externo (IdP), primero debes acceder a la gcloud CLI con tu identidad federada.

Para inicializar gcloud CLI, ejecuta el siguiente comando:

gcloud init

Crea o selecciona un Google Cloud proyecto.

Roles necesarios para seleccionar o crear un proyecto

• Selecciona un proyecto: Para seleccionar un proyecto, no se requiere un rol de IAM específico. Puedes seleccionar cualquier proyecto en el que se te haya otorgado un rol.
• Crear un proyecto: Para crear un proyecto, necesitas el rol de Creador de proyectos (roles/resourcemanager.projectCreator), que contiene el permiso resourcemanager.projects.create. Obtén más información para otorgar roles.

Nota: Si no planeas conservar los recursos que creaste durante este procedimiento, crea un proyecto en lugar de seleccionar uno existente. Cuando termines, puedes borrar el proyecto y quitar todos los recursos asociados con él.

• Crea un proyecto de Google Cloud :

  gcloud projects create PROJECT_ID

  Reemplaza PROJECT_ID por un nombre para el proyecto Google Cloud que estás creando.

• Selecciona el proyecto Google Cloud que creaste:

  gcloud config set project PROJECT_ID

  Reemplaza PROJECT_ID por el nombre de tu Google Cloud proyecto.

Verifica que la facturación esté habilitada para tu proyecto de Google Cloud .

Habilita las APIs de Batch, Cloud Storage, Compute Engine y Logging:

Roles necesarios para habilitar las APIs

Para habilitar las APIs, necesitas el rol de IAM de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin), que contiene el permiso serviceusage.services.enable. Obtén más información para otorgar roles.

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

Instala Google Cloud CLI.

Si usas un proveedor de identidad externo (IdP), primero debes acceder a la gcloud CLI con tu identidad federada.

Para inicializar gcloud CLI, ejecuta el siguiente comando:

gcloud init

Crea o selecciona un Google Cloud proyecto.

Roles necesarios para seleccionar o crear un proyecto

• Selecciona un proyecto: Para seleccionar un proyecto, no se requiere un rol de IAM específico. Puedes seleccionar cualquier proyecto en el que se te haya otorgado un rol.
• Crear un proyecto: Para crear un proyecto, necesitas el rol de Creador de proyectos (roles/resourcemanager.projectCreator), que contiene el permiso resourcemanager.projects.create. Obtén más información para otorgar roles.

Nota: Si no planeas conservar los recursos que creaste durante este procedimiento, crea un proyecto en lugar de seleccionar uno existente. Cuando termines, puedes borrar el proyecto y quitar todos los recursos asociados con él.

• Crea un proyecto de Google Cloud :

  gcloud projects create PROJECT_ID

  Reemplaza PROJECT_ID por un nombre para el proyecto Google Cloud que estás creando.

• Selecciona el proyecto Google Cloud que creaste:

  gcloud config set project PROJECT_ID

  Reemplaza PROJECT_ID por el nombre de tu Google Cloud proyecto.

Verifica que la facturación esté habilitada para tu proyecto de Google Cloud .

Habilita las APIs de Batch, Cloud Storage, Compute Engine y Logging:

Roles necesarios para habilitar las APIs

Para habilitar las APIs, necesitas el rol de IAM de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin), que contiene el permiso serviceusage.services.enable. Obtén más información para otorgar 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 instructivo.

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

   Cada trabajo requiere una cuenta de servicio que permita que el agente de servicio de Batch cree los recursos necesarios para ejecutar el trabajo y acceda a ellos. En este instructivo, 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 tenga los permisos necesarios para permitir que el agente de servicio de Batch cree recursos para los trabajos de Batch y acceda a ellos, pídele a tu administrador que otorgue los siguientes roles de IAM a la cuenta de servicio predeterminada de Compute Engine:

   Importante: Debes otorgar estos roles a la cuenta de servicio predeterminada de Compute Engine, no a tu cuenta de usuario. Si no se otorgan los roles a la principal correcta, es posible que se produzcan errores de permisos.
   • Informante del agente por lotes (roles/batch.agentReporter) en el proyecto
   • Administrador de almacenamiento (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 otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

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

2. Asegúrate de tener los permisos necesarios para este instructivo.

   Nota: Si creaste este proyecto, no es necesario que realices este paso. Como creador del proyecto, se te otorga automáticamente el rol de IAM de propietario (roles/owner), que ya tiene todos los permisos necesarios para este instructivo.

   Si quieres obtener los permisos que necesitas para completar este instructivo, pídele a tu administrador que te otorgue los siguientes roles de IAM:

   • 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, para este instructivo, es la cuenta de servicio predeterminada de Compute Engine
   • Administrador de objetos de almacenamiento (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 tener instaladas versiones de Python y pip que sean compatibles con la versión más reciente de dsub. Para ver las versiones instaladas actualmente, 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 cuando instales 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 es similar a lo 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
      

Cree un bucket de Cloud Storage

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

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

Reemplaza lo siguiente:

• BUCKET_NAME: Un nombre único a nivel global para tu bucket.

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

El resultado es similar a lo siguiente:

Creating gs://BUCKET_NAME/...

Ejecuta la canalización dsub

La canalización de muestra dsub indexa un archivo BAM del Proyecto 1,000 Genomas y genera los resultados en un bucket de Cloud Storage.

Para ejecutar la canalización de muestra de dsub, ejecuta el siguiente comando de 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

Reemplaza lo siguiente:

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

• BUCKET_NAME: Es el nombre del bucket de Cloud Storage que creaste.

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

La canalización dsub ejecuta un trabajo por lotes que escribe el archivo y los registros de BAI en el directorio especificado de tu bucket de Cloud Storage. Específicamente, el repositorio dsub contiene una imagen de Docker prediseñada que usa samtools para indexar el archivo BAM que especificaste en la marca --input.

El comando no finaliza hasta que se termina de ejecutar la canalización dsub, lo que puede variar según el momento en que se programe el trabajo por lotes. Por lo general, esto tarda unos 10 minutos: Batch suele comenzar 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 en ejecución 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.

Luego, después de que el trabajo finalice correctamente, el comando se detendrá y el resultado será similar al siguiente:

  JOB_NAME: SUCCESS
JOB_NAME

En esta salida, se incluyen los siguientes valores:

• JOB_NAME: Es el nombre del trabajo.

• USERNAME: Tu Google Cloud nombre de usuario.

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

Cómo ver los archivos de salida

Para ver los archivos de salida creados por la canalización de dsub de muestra con gcloud CLI, ejecuta el comando gcloud storage ls:

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

Reemplaza lo siguiente:

• BUCKET_NAME: Es el nombre del bucket de Cloud Storage que creaste.

• WORK_DIRECTORY: Es el directorio que especificaste en el comando dsub.

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

El resultado es similar a lo siguiente:

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

Este resultado incluye el archivo BAI y un directorio que contiene los registros del trabajo.

Realiza una limpieza

Para evitar que se apliquen cargos a tu cuenta de Google Cloud por los recursos usados en este instructivo, borra el proyecto que contiene los recursos o conserva el proyecto y borra los recursos individuales.

Borra el proyecto

La manera más fácil de eliminar la facturación es borrar el proyecto actual.

Precaución: Borrar un proyecto tiene las siguientes consecuencias:

• Se borra todo su contenido. Si usaste un proyecto existente para las tareas de este documento, cuando lo borres, también se borrará cualquier otro trabajo que hayas realizado en el proyecto.
• Se pierden los IDs personalizados de los proyectos. Cuando creaste este proyecto, es posible que hayas creado un ID personalizado del proyecto que desees utilizar en el futuro. Para conservar las URLs que usan el ID del proyecto, como una URL appspot.com, borra los recursos seleccionados dentro del proyecto, en lugar de todo el proyecto.

Si planeas explorar varios instructivos, arquitecturas o guías de inicio rápido, reutilizar proyectos puede ser útil para no exceder los límites de cuota de los proyectos.

Borra un Google Cloud proyecto:

gcloud projects delete PROJECT_ID

Borra los recursos individuales

Si deseas seguir usando el proyecto actual, borra los recursos individuales que se usaron en este instructivo.

Borra el bucket

Una vez que finaliza la ejecución de la canalización, se crean y almacenan archivos de salida en el directorio WORK_DIRECTORY de tu bucket de Cloud Storage.

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

• Si ya no necesitas el bucket que usaste en este instructivo, usa el comando gcloud storage rm con la marca --recursive para borrar el bucket y todo su contenido:

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

  Reemplaza lo siguiente:

  • BUCKET_NAME: Es el nombre del bucket de Cloud Storage que creaste.

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

• De lo contrario, si aún necesitas el bucket, usa el comando gcloud storage rm con la marca --recursive para borrar solo el directorio WORK_DIRECTORY y todo su contenido:

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

  Reemplaza lo siguiente:

  • BUCKET_NAME: Es el nombre del bucket de Cloud Storage que creaste.

  • WORK_DIRECTORY: Es el directorio que especificaste en el comando dsub.

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

Borra el trabajo

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

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

Reemplaza lo siguiente:

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

¿Qué sigue?

• Obtén más información sobre dsub y dsub para Batch.
• Obtén más información para usar volúmenes de almacenamiento con Batch.