Neste tutorial, explicamos como executar um pipeline
dsub
no Batch.
Especificamente, o pipeline dsub
de exemplo processa dados de sequenciamento de DNA em um arquivo de mapa de alinhamento binário (BAM, na sigla em inglês) para criar um arquivo de índice BAM (BAI, na sigla em inglês).
Este tutorial é destinado a usuários do Batch que querem usar dsub
com o Batch.
O dsub
é um programador de jobs de código aberto para orquestrar fluxos de trabalho de processamento em lote no Google Cloud.
Para saber mais sobre como usar
o Batch com dsub
, consulte a
documentação dsub
para o Batch.
Objetivos
- executar um pipeline
dsub
no Batch que lê e grava arquivos em buckets do Cloud Storage; - Confira os arquivos de saída em um bucket do Cloud Storage.
Custos
Neste documento, você usará os seguintes componentes faturáveis do Google Cloud:
- Lote
- Cloud Storage
Para gerar uma estimativa de custo baseada na projeção de uso deste tutorial, use a calculadora de preços.
Os recursos criados neste tutorial geralmente custam menos do que um dólar, supondo que você conclua todas as etapas, incluindo a limpeza, em tempo hábil.
Antes de começar
- Faça login na sua conta do Google Cloud. Se você começou a usar o Google Cloud agora, crie uma conta para avaliar o desempenho de nossos produtos em situações reais. Clientes novos também recebem US$ 300 em créditos para executar, testar e implantar cargas de trabalho.
- Install the Google Cloud CLI.
-
To initialize the gcloud CLI, run the following command:
gcloud init
-
Crie ou selecione um projeto do Google Cloud.
-
Crie um projeto do Google Cloud:
gcloud projects create PROJECT_ID
Substitua
PROJECT_ID
por um nome para o projeto do Google Cloud que você está criando. -
Selecione o projeto do Google Cloud que você criou:
gcloud config set project PROJECT_ID
Substitua
PROJECT_ID
pelo nome do projeto do Google Cloud.
-
-
Verifique se a cobrança está ativada para o seu projeto do Google Cloud.
-
Ative as APIs Batch, Cloud Storage, Compute Engine, and Logging:
gcloud services enable batch.googleapis.com
compute.googleapis.com logging.googleapis.com storage.googleapis.com - Install the Google Cloud CLI.
-
To initialize the gcloud CLI, run the following command:
gcloud init
-
Crie ou selecione um projeto do Google Cloud.
-
Crie um projeto do Google Cloud:
gcloud projects create PROJECT_ID
Substitua
PROJECT_ID
por um nome para o projeto do Google Cloud que você está criando. -
Selecione o projeto do Google Cloud que você criou:
gcloud config set project PROJECT_ID
Substitua
PROJECT_ID
pelo nome do projeto do Google Cloud.
-
-
Verifique se a cobrança está ativada para o seu projeto do Google Cloud.
-
Ative as APIs Batch, Cloud Storage, Compute Engine, and Logging:
gcloud services enable batch.googleapis.com
compute.googleapis.com logging.googleapis.com storage.googleapis.com -
Verifique se o projeto tem pelo menos uma conta de serviço com as permissões necessárias para este tutorial.
Cada job requer uma conta de serviço que permite que o agente de serviço do Batch crie e acesse os recursos necessários para executar o job. Neste tutorial, a conta de serviço do job é a conta de serviço padrão do Compute Engine.
Para garantir que a conta de serviço padrão do Compute Engine tenha as permissões necessárias para permitir que o agente de serviço do Batch crie e acesse recursos para jobs do Batch, peça ao administrador que conceda à conta de serviço padrão do Compute Engine os seguintes papéis do IAM:
-
Relatório do agente em lote (
roles/batch.agentReporter
) no projeto -
Administrador de armazenamento (
roles/storage.admin
) no projeto -
(Recomendado) Permita que os jobs gerem registros no Cloud Logging:
Gravador de registros (
roles/logging.logWriter
) no projeto
Para mais informações sobre como conceder papéis, consulte Gerenciar acesso.
O administrador também pode conceder à conta de serviço padrão do Compute Engine as permissões necessárias por meio de papéis personalizados ou outros papéis predefinidos.
-
Relatório do agente em lote (
-
Verifique se você tem as permissões necessárias para este tutorial.
Para ter as permissões necessárias para concluir este tutorial, peça ao administrador para conceder a você os seguintes papéis do IAM:
-
Editor de jobs em lote (
roles/batch.jobsEditor
) no projeto -
Usuário da conta de serviço (
roles/iam.serviceAccountUser
) na conta de serviço do job, que, neste tutorial, é a conta de serviço padrão do Compute Engine. -
Administrador de objetos do Storage (
roles/storage.objectAdmin
) no projeto
-
Editor de jobs em lote (
-
Instale o
dsub
e as dependências dele. Para mais informações, consulte a documentação de instalação dodsub
.Confira se você tem versões instaladas do Python e do pip (links em inglês) compatíveis com a versão mais recente do
dsub
. Para conferir as versões atualmente instaladas, execute o seguinte comando:pip --version
Se você precisar instalar ou atualizar o
pip
ou o Python, siga as etapas de instalação do Python.Recomendado: para evitar erros de conflito de dependência ao instalar o
dsub
, crie e ative um ambiente virtual do Python:python -m venv dsub_libs && source dsub_libs/bin/activate
Clone o repositório
dsub
do GitHub usandogit
e abra-o:git clone https://github.com/databiosphere/dsub.git && cd dsub
Instale o
dsub
e as dependências dele:python -m pip install .
O resultado será assim:
... 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
Crie um bucket do Cloud Storage
Para criar um bucket do Cloud Storage para armazenar os arquivos de saída do
pipeline dsub
de amostra usando a CLI gcloud, execute o
comando gcloud storage buckets create
:
gcloud storage buckets create gs://BUCKET_NAME \
--project PROJECT_ID
Substitua:
BUCKET_NAME
: um nome globalmente exclusivo para o bucket.PROJECT_ID
: o ID do projeto do Google Cloud.
O resultado será assim:
Creating gs://BUCKET_NAME/...
Executar o pipeline dsub
O pipeline de amostra dsub
indexa um arquivo BAM do 1.000 Genomes Project e gera os resultados em um bucket do Cloud Storage.
Para executar o pipeline dsub
de exemplo, execute o seguinte 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
Substitua:
PROJECT_ID
: o ID do projeto do Google Cloud.BUCKET_NAME
: o nome do bucket do Cloud Storage que você criou.WORK_DIRECTORY
: o nome de um novo diretório que o pipeline pode usar para armazenar registros e saídas. Por exemplo, insiraworkDir
.
O pipeline dsub
executa um
job em lote que grava o arquivo BAI
e os registros no diretório especificado no bucket do Cloud Storage.
Especificamente, o repositório dsub
contém uma imagem do Docker
pré-criada que usa samtools
para indexar o
arquivo BAM que você especificou na sinalização --input
.
O comando não termina até que o pipeline dsub
termine a execução,
o que pode variar com base no momento em que o job em lote está programado.
Geralmente, isso leva cerca de 10 minutos: o lote geralmente começa
a executar o job em alguns minutos, e o ambiente de execução do job é de cerca de 8 minutos.
Inicialmente, o comando ainda está em execução e a saída é semelhante a esta:
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.
Após a conclusão bem-sucedida do job, o comando termina e a saída é semelhante a esta:
JOB_NAME: SUCCESS
JOB_NAME
Esta saída inclui os seguintes valores:
JOB_NAME
: o nome do job.USERNAME
: seu nome de usuário do Google Cloud.PROJECT_ID
: o ID do projeto do Google Cloud.
Conferir os arquivos de saída
Para visualizar os arquivos de saída criados pelo pipeline dsub
de amostra usando a
CLI gcloud, execute o
comando gcloud storage ls
:
gcloud storage ls gs://BUCKET_NAME/WORK_DIRECTORY \
--project PROJECT_ID
Substitua:
BUCKET_NAME
: o nome do bucket do Cloud Storage que você criou.WORK_DIRECTORY
: o diretório especificado no comandodsub
.PROJECT_ID
: o ID do projeto do Google Cloud.
O resultado será assim:
gs://BUCKET_NAME/WORK_DIRECTORY/HG00114.mapped.ILLUMINA.bwa.GBR.low_coverage.20120522.bam.bai
gs://BUCKET_NAME/WORK_DIRECTORY/logs/
Essa saída inclui o arquivo BAI e um diretório que contém os registros do job.
Limpar
Para evitar cobranças na sua conta do Google Cloud pelos recursos usados no tutorial, exclua o projeto que os contém ou mantenha o projeto e exclua os recursos individuais.
Excluir o projeto
A maneira mais fácil de evitar cobranças é excluindo o projeto atual.
Exclua um projeto do Google Cloud:
gcloud projects delete PROJECT_ID
Excluir recursos individuais
Se você quiser continuar usando o projeto atual, exclua os recursos individuais usados neste tutorial.
Excluir o bucket
Depois que o pipeline termina de ser executado, ele cria e armazena arquivos de saída no diretório WORK_DIRECTORY
do bucket do Cloud Storage.
Para reduzir as cobranças do Cloud Storage na conta atual do Google Cloud, siga um destes procedimentos:
Se você não precisar mais do bucket usado neste tutorial, use o comando
gcloud storage rm
com a sinalização--recursive
para excluir o bucket e todo o conteúdo dele:gcloud storage rm gs://BUCKET_NAME \ --recursive \ --project PROJECT_ID
Substitua:
BUCKET_NAME
: o nome do bucket do Cloud Storage que você criou.PROJECT_ID
: o ID do projeto do Google Cloud.
Caso contrário, se você ainda precisar do bucket, use o comando
gcloud storage rm
com a sinalização--recursive
para excluir apenas o diretórioWORK_DIRECTORY
e todo o conteúdo dele:gcloud storage rm gs://BUCKET_NAME/WORK_DIRECTORY \ --recursive \ --project PROJECT_ID
Substitua:
BUCKET_NAME
: o nome do bucket do Cloud Storage que você criou.WORK_DIRECTORY
: o diretório que você especifica no comandodsub
.PROJECT_ID
: o ID do projeto do Google Cloud.
Excluir o job
Para excluir um job usando a CLI gcloud, execute o
comando gcloud batch jobs delete
.
gcloud batch jobs delete JOB_NAME \
--location us-central1 \
--project PROJECT_ID
Substitua:
JOB_NAME
: o nome do job.PROJECT_ID
: o ID do projeto do Google Cloud.
A seguir
- Saiba mais sobre
dsub
edsub
para o Batch. - Saiba mais sobre como usar volumes de armazenamento com o Batch.