Orquestrar jobs executando pipelines dsub no Batch

---

Neste tutorial, explicamos como executar um pipeline dsub no Batch. Especificamente, o exemplo de pipeline dsub 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).

Este tutorial é destinado a usuários do Batch que querem usar dsub com o Batch. O dsub é um agendador 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.
• Acesse 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. 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, essa etapa não será necessária a menos que sua organização impeça as 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 que o agente de serviço de lote 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 trabalhos do Batch, peça ao administrador para conceder à conta de serviço padrão do Compute Engine os seguintes papéis do IAM:

    • Relator do agente em lote (roles/batch.agentReporter) no projeto
    • Administrador do Storage (roles/storage.admin) no projeto
    • (Recomendado) Permitir 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.

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

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. 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 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 conferir as versões instaladas, 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 dsub, crie e ative um 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:

       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 do pipeline de amostra 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 nome globalmente exclusivo para o bucket.

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

O resultado será assim:

Creating gs://BUCKET_NAME/...

Executar o pipeline dsub

O pipeline de amostra dsub indexa um arquivo BAM do Projeto 1.000 Genomas e gera os resultados em um bucket do Cloud Storage.

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

• BUCKET_NAME: o nome do bucket do Cloud Storage criado.

• 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 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 de ser executado, o que pode variar com base no momento em que o job em lote é programado. Isso geralmente leva cerca de 10 minutos: o lote geralmente começa a executar o job em alguns minutos, e o tempo de execução do job é de cerca de 8 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 Google Cloud nome de usuário.

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

• PROJECT_ID: o ID do projeto do projeto 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 com 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 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 para a contaGoogle Cloud atual, 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 projeto 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 especificado no comando dsub.

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

A seguir

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