Orquestrar jobs executando pipelines dsub no Batch

---

Neste tutorial, explicamos como executar um pipeline dsub no Batch. Especificamente, o pipeline de exemplo dsub processa dados de sequenciamento de DNA em uma Arquivo de mapa de alinhamento binário (BAM, na sigla em inglês) para criar um arquivo de índice BAM (BAI).

Este tutorial é destinado a usuários do Batch que querem usar dsub com o Batch. 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 do dsub para o Batch.

Objetivos

• Execute um pipeline dsub no Batch que le e grava arquivos em buckets do Cloud Storage.
• Visualize os arquivos de saída em um bucket do Cloud Storage.

Custos

Neste documento, você usará os seguintes componentes faturáveis do Google Cloud:

• Batch
• 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 normalmente custam menos de um dólar, supondo que você conclua todas as etapas, incluindo a limpeza, em tempo hábil.

Antes de começar

1. 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.
2. Install the Google Cloud CLI.

3. To initialize the gcloud CLI, run the following command:

   gcloud init

4. Create or select a Google Cloud project.

   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.

5. Make sure that billing is enabled for your Google Cloud project.

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

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

7. Install the Google Cloud CLI.

8. To initialize the gcloud CLI, run the following command:

   gcloud init

9. Create or select a Google Cloud project.

   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.

10. Make sure that billing is enabled for your Google Cloud project.

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

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

12. Certifique-se de que o projeto tenha pelo menos conta de serviço com o as permissões necessárias para este tutorial.

    Observação: se você estiver usando um novo projeto, essa 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 do IAM de Editor (roles/editor), que já tem todas as permissões necessárias para este tutorial.

    Cada job exige uma conta de serviço que permita ao agente de serviço de lote criar e acessar 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 trabalhos do Batch, peça ao administrador para conceder à conta de serviço padrão do Compute Engine os seguintes papéis do IAM:

    • Batch Agent Reporter (roles/batch.agentReporter) no projeto
    • Administrador do Storage (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 a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

    Talvez o administrador também possa conceder à conta de serviço padrão do Compute Engine as permissões necessárias por meio de tags personalizadas ou outras funções predefinidas papéis.

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

    Observação: se você criou este projeto, esta etapa não é necessária. Conforme o criador de projeto, você recebe automaticamente o papel de Proprietário (roles/owner) papel do IAM, que já tem todos os as permissões necessárias para este tutorial.

    Para conseguir 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 dsub e as dependências dele. Para mais informações, consulte a Documentação de instalação do dsub.

    1. Verifique se você tem versões instaladas do Python e do pip com suporte à versão mais recente do dsub. Para ver as versões instaladas atualmente, execute o seguinte comando:

       pip --version
       

       Se você precisar instalar ou atualizar o pip ou o Python, siga as etapas para instalar o Python.

    2. Recomendado: para evitar erros de conflito de dependência ao instalar o dsub, crie e ative uma Ambiente virtual do Python:

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

    3. Clone o repositório do GitHub dsub 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
       

Criar um bucket do Cloud Storage

Para criar um bucket do Cloud Storage para armazenar os arquivos de saída da exemplo de pipeline dsub 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 um nome exclusivo globalmente para seu bucket.

• PROJECT_ID: o ID do projeto do seu projeto do Google Cloud.

O resultado será assim:

Creating gs://BUCKET_NAME/...

Executar o pipeline dsub

O pipeline dsub de exemplo indexa um arquivo BAM da Projeto 1,000 Genomes e gera os resultados em um bucket do Cloud Storage.

Para executar o pipeline dsub de amostra, 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 seu projeto do Google Cloud.

• BUCKET_NAME: o nome do Cloud Storage. que você criou.

• WORK_DIRECTORY: o nome de um novo 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 registra no diretório especificado no bucket do Cloud Storage. Especificamente, o repositório dsub contém uma imagem do Docker predefinida que usa samtools para indexar o arquivo BAM especificado na flag --input.

O comando não é concluído até que o pipeline dsub termine a execução, o que pode variar com base no momento em que o job em lote é programado. Geralmente, isso leva cerca de 10 minutos. O lote geralmente começa executar o job em alguns minutos e o tempo de execução do job é de cerca de oito minutos.

No início, 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.

Depois que o job é concluído, o comando é encerrado 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 seu projeto do Google Cloud.

Conferir os arquivos de saída

Para conferir os arquivos de saída criados pelo pipeline de amostra dsub 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 criado.

• WORK_DIRECTORY: o diretório especificado em o comando dsub.

• PROJECT_ID: o ID do projeto do seu 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.

Exclua o projeto

A maneira mais fácil de evitar o faturamento é excluir 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.

Delete a Google Cloud project:

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 flag --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 criado.

  • PROJECT_ID: o ID do projeto do seu projeto do Google Cloud.

• Caso contrário, se você ainda precisar do bucket, use o comando gcloud storage rm com a flag --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 criado.

  • WORK_DIRECTORY: o diretório que você especificado no comando dsub.

  • PROJECT_ID: o ID do projeto do seu 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 seu projeto do Google Cloud.

A seguir

• Saiba mais sobre dsub e dsub para Batch.
• Saiba mais sobre como usar volumes de armazenamento com o Batch.