En este instructivo, se explica cómo ejecutar una canalización dsub
en Batch.
En particular, la canalización dsub
de ejemplo 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 deseen 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
- Ejecutar una canalización
dsub
en Batch que lea y escriba archivos en buckets de Cloud Storage - Visualizar 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.
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.
-
Para inicializar la CLI de gcloud, ejecuta el siguiente comando:
gcloud init
-
Crea o selecciona un proyecto de Google Cloud.
-
Crea un proyecto de Google Cloud:
gcloud projects create PROJECT_ID
Reemplaza
PROJECT_ID
por un nombre para el proyecto de Google Cloud que estás creando. -
Selecciona el proyecto de Google Cloud que creaste:
gcloud config set project PROJECT_ID
Reemplaza
PROJECT_ID
por el nombre del proyecto de Google Cloud.
-
-
Asegúrate de que la facturación esté habilitada para tu proyecto de Google Cloud.
-
Habilita las APIs de Batch, Cloud Storage, Compute Engine, and Logging:
gcloud services enable batch.googleapis.com
compute.googleapis.com logging.googleapis.com storage.googleapis.com - Instala Google Cloud CLI.
-
Para inicializar la CLI de gcloud, ejecuta el siguiente comando:
gcloud init
-
Crea o selecciona un proyecto de Google Cloud.
-
Crea un proyecto de Google Cloud:
gcloud projects create PROJECT_ID
Reemplaza
PROJECT_ID
por un nombre para el proyecto de Google Cloud que estás creando. -
Selecciona el proyecto de Google Cloud que creaste:
gcloud config set project PROJECT_ID
Reemplaza
PROJECT_ID
por el nombre del proyecto de Google Cloud.
-
-
Asegúrate de que la facturación esté habilitada para tu proyecto de Google Cloud.
-
Habilita las APIs de Batch, Cloud Storage, Compute Engine, and Logging:
gcloud services enable batch.googleapis.com
compute.googleapis.com logging.googleapis.com storage.googleapis.com -
Asegúrate de que tu proyecto tenga al menos una cuenta de servicio con los permisos necesarios para este instructivo.
Cada trabajo requiere una cuenta de servicio que le permita al agente de servicio de Batch crear los recursos necesarios para ejecutar el trabajo y acceder a ellos. Para 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 a fin de permitir que el agente de servicio de Batch cree y acceda a recursos para los trabajos de Batch, pídele a tu administrador que otorgue los siguientes roles de IAM a la cuenta de servicio predeterminada de Compute Engine:
-
Informante del agente por lotes (
roles/batch.agentReporter
) en el proyecto -
Administrador de almacenamiento (
roles/storage.admin
) en el proyecto -
Permitir que los trabajos generen registros en Cloud Logging:
Escritor de registros (
roles/logging.logWriter
) en el proyecto (recomendado)
Si quieres obtener más información para otorgar funciones, consulta Administra el acceso.
Es posible que el administrador también pueda otorgar los permisos necesarios a la cuenta de servicio predeterminada de Compute Engine mediante funciones personalizadas, o bien otras funciones predefinidas.
-
Informante del agente por lotes (
-
Asegúrate de tener los permisos necesarios para este instructivo.
A fin de 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; en este instructivo, es la cuenta de servicio predeterminada de Compute Engine -
Administrador de objetos de almacenamiento (
roles/storage.objectAdmin
) en el proyecto
-
Editor de trabajos por lotes (
-
Instala
dsub
y sus dependencias. Para obtener más información, consulta la documentación de instalación dedsub
.Asegúrate de tener versiones instaladas 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.Recomendación: Para evitar errores de conflictos de dependencias cuando instales
dsub
, crea y activa un entorno virtual de Python:python -m venv dsub_libs && source dsub_libs/bin/activate
Clona el repositorio
dsub
de GitHub congit
y ábrelo:git clone https://github.com/databiosphere/dsub.git && cd dsub
Instala
dsub
y sus dependencias:python -m pip install .
El resultado es 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 bucket de Cloud Storage
Si quieres crear un bucket de Cloud Storage para almacenar los archivos de salida de la
canalización dsub
de muestra con gcloud CLId, ejecuta el
comando gcloud storage buckets create
:
gcloud storage buckets create gs://BUCKET_NAME \
--project PROJECT_ID
Reemplaza lo siguiente:
BUCKET_NAME
: Es un nombre único a nivel global para el bucket.PROJECT_ID
: Es el ID del proyecto de Google Cloud.
El resultado es similar al siguiente:
Creating gs://BUCKET_NAME/...
Ejecuta la canalización dsub
La canalización dsub
de muestra indexa un archivo BAM del proyecto 1,000 Genomes y envía los resultados a un bucket de Cloud Storage.
Para ejecutar la canalización dsub
de muestra, 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 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, ingresaworkDir
.
La canalización dsub
ejecuta un trabajo por lotes que escribe el archivo BAI y los registros en el directorio especificado en tu bucket de Cloud Storage.
En particular, el repositorio dsub
contiene una imagen de Docker compilada previamente que usa samtools
para indexar el archivo BAM que especificaste en la marca --input
.
El comando no finaliza hasta que la canalización dsub
termine de ejecutarse, lo que puede variar según el momento en que se programó el trabajo por lotes.
Por lo general, el proceso tarda alrededor de 10 minutos: por lo general, Batch comienza a ejecutar el trabajo en unos minutos y el entorno 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.
Una vez que el trabajo finalice de forma correcta, el comando finalizará 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
: Es tu nombre de usuario de Google Cloud.PROJECT_ID
: Es el ID del proyecto de Google Cloud.
Cómo ver los archivos de salida
Para ver los archivos de salida que crea la canalización 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 comandodsub
.PROJECT_ID
: Es el ID del proyecto de Google Cloud.
El resultado es similar al siguiente:
gs://BUCKET_NAME/WORK_DIRECTORY/HG00114.mapped.ILLUMINA.bwa.GBR.low_coverage.20120522.bam.bai
gs://BUCKET_NAME/WORK_DIRECTORY/logs/
En este resultado, se incluye el archivo BAI y un directorio que contiene los registros del trabajo.
Limpia
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.
Borra un proyecto de Google Cloud:
gcloud projects delete PROJECT_ID
Borra los recursos individuales
Si deseas seguir usando el proyecto actual, borra los recursos individuales que usaste en este instructivo.
Borra el bucket
Cuando la canalización termina de ejecutarse, crea y almacena archivos de salida en el directorio WORK_DIRECTORY
de tu bucket de Cloud Storage.
Para reducir los cargos de Cloud Storage a la cuenta actual de Google Cloud, realiza una de las siguientes acciones:
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 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 directorioWORK_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 comandodsub
.PROJECT_ID
: Es el ID del 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 Google Cloud.
¿Qué sigue?
- Obtén más información sobre
dsub
ydsub
para Batch. - Obtén más información sobre cómo usar volúmenes de almacenamiento con Batch.