Orquestre jobs executando pipelines dsub no Batch

---

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. Novos usuários do Google Cloud podem estar qualificados para uma avaliação gratuita.

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

1. 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.
2. Instale a CLI do Google Cloud.

3. Para inicializar a CLI gcloud, execute o seguinte comando:

   gcloud init

4. Crie ou selecione um projeto do Google Cloud.

   Observação: se você não pretende manter os recursos criados neste procedimento, crie um projeto novo em vez de selecionar um que já existe. Depois de concluir essas etapas, é possível excluir o projeto. Para fazer isso, basta remover todos os recursos associados a ele.

   • 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.

5. Verifique se a cobrança está ativada para o seu projeto do Google Cloud.

6. 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

7. Instale a CLI do Google Cloud.

8. Para inicializar a CLI gcloud, execute o seguinte comando:

   gcloud init

9. Crie ou selecione um projeto do Google Cloud.

   Observação: se você não pretende manter os recursos criados neste procedimento, crie um projeto novo em vez de selecionar um que já existe. Depois de concluir essas etapas, é possível excluir o projeto. Para fazer isso, basta remover todos os recursos associados a ele.

   • 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.

10. Verifique se a cobrança está ativada para o seu projeto do Google Cloud.

11. 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

12. Verifique se o projeto tem pelo menos uma conta de serviço com as permissões necessárias para este tutorial.

    Observação: se você estiver usando um novo projeto, esta etapa não será necessária, a menos que sua organização impeça concessões automáticas de papéis para contas de serviço padrão. Por padrão, a conta de serviço padrão do Compute Engine recebe automaticamente o papel de Editor (roles/editor) do IAM, que já tem todas 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.

13. Verifique se você tem as permissões necessárias para este tutorial.

    Observação:se você criou o projeto, esta etapa não é necessária. Como criador do projeto, você recebe automaticamente o papel do IAM de Proprietário (roles/owner), que já tem todas 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

14. Instale o dsub e as dependências dele. Para mais informações, consulte a documentação de instalação do dsub.

    1. 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.

    2. 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
       

    3. Clone o repositório dsub do GitHub usando git e abra-o:

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

    4. 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, insira workDir.

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 comando dsub.

• 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.

Cuidado: excluir um projeto tem os seguintes efeitos:

• Tudo no projeto é excluído. Se você tiver usado um projeto existente para as tarefas neste documento, a exclusão dele incluirá a exclusão de quaisquer outros trabalhos feitos no projeto.
• Os IDs do projeto personalizados são perdidos. Ao criar o projeto, você pode ter criado um código do projeto personalizado para ser usado no futuro. Para preservar os URLs que usam o ID do projeto, como um URL appspot.com, exclua recursos específicos do projeto, em vez de excluir o projeto inteiro.

Se você planeja passar por várias arquiteturas, tutoriais ou guias de início rápido, a reutilização de projetos pode evitar que você exceda os limites da cota do projeto.

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ório WORK_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 comando dsub.

  • 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 e dsub para o Batch.
• Saiba mais sobre como usar volumes de armazenamento com o Batch.