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) para criar um arquivo de índice BAM (BAI).

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

Objetivos

• Execute 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ê vai 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 um teste sem custo financeiro.

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

Faça login na sua conta do Google Cloud . Se você começou a usar o Google Cloud, 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.

Instale a CLI do Google Cloud.

Ao usar um provedor de identidade (IdP) externo, primeiro faça login na gcloud CLI com sua identidade federada.

Para inicializar a gcloud CLI, execute o seguinte comando:

gcloud init

Crie ou selecione um Google Cloud projeto.

Funções necessárias para selecionar ou criar um projeto

• Selecionar um projeto: não é necessário um papel específico do IAM para selecionar um projeto. Você pode escolher qualquer projeto em que tenha recebido um papel.
• Criar um projeto: para criar um projeto, é necessário ter o papel de Criador de projetos (roles/resourcemanager.projectCreator), que contém a permissão resourcemanager.projects.create. Saiba como conceder papéis.

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 Google Cloud que você está criando.

• Selecione o projeto Google Cloud que você criou:

  gcloud config set project PROJECT_ID

  Substitua PROJECT_ID pelo nome do projeto do Google Cloud .

Verifique se o faturamento está ativado para o projeto do Google Cloud .

Ative as APIs Batch, Cloud Storage, Compute Engine e Logging:

Funções necessárias para ativar APIs

Para ativar as APIs, é necessário ter o papel do IAM de administrador do Service Usage (roles/serviceusage.serviceUsageAdmin), que contém a permissão serviceusage.services.enable. Saiba como conceder papéis.

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

Instale a CLI do Google Cloud.

Ao usar um provedor de identidade (IdP) externo, primeiro faça login na gcloud CLI com sua identidade federada.

Para inicializar a gcloud CLI, execute o seguinte comando:

gcloud init

Crie ou selecione um Google Cloud projeto.

Funções necessárias para selecionar ou criar um projeto

• Selecionar um projeto: não é necessário um papel específico do IAM para selecionar um projeto. Você pode escolher qualquer projeto em que tenha recebido um papel.
• Criar um projeto: para criar um projeto, é necessário ter o papel de Criador de projetos (roles/resourcemanager.projectCreator), que contém a permissão resourcemanager.projects.create. Saiba como conceder papéis.

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 Google Cloud que você está criando.

• Selecione o projeto Google Cloud que você criou:

  gcloud config set project PROJECT_ID

  Substitua PROJECT_ID pelo nome do projeto do Google Cloud .

Verifique se o faturamento está ativado para o projeto do Google Cloud .

Ative as APIs Batch, Cloud Storage, Compute Engine e Logging:

Funções necessárias para ativar APIs

Para ativar as APIs, é necessário ter o papel do IAM de administrador do Service Usage (roles/serviceusage.serviceUsageAdmin), que contém a permissão serviceusage.services.enable. Saiba como conceder papéis.

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

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

   Importante:conceda esses papéis à conta de serviço padrão do Compute Engine, não à sua conta de usuário. Se o papel não for concedido ao principal correto, poderão ocorrer erros de permissão.
   • Relator do agente em lote (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.

   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.

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

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

   Para conseguir as permissões necessárias a fim de 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

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

   1. Verifique se você instalou versões do Python e do pip compatíveis com a 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 o dsub, crie e ative um ambiente virtual do Python:

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

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

      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á o seguinte:

      ...
      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 seu projeto Google Cloud .

O resultado será o seguinte:

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 seu 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 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 especificado na flag --input.

O comando não será concluído até que o pipeline dsub termine de ser executado, o que pode variar de acordo com o momento em que o job em lote é programado. Normalmente, isso leva cerca de 10 minutos: o Batch 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 for concluído, o comando será encerrado e a saída será 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 seu projeto Google Cloud .

Ver 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 seu projeto Google Cloud .

O resultado será o seguinte:

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 atual para as tarefas neste documento, a exclusão dele incluirá a exclusão de quaisquer outros trabalhos feitos nele.
• Os IDs do projeto personalizados são perdidos. Ao criar o projeto, você pode ter criado um ID 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 explorar várias arquiteturas, tutoriais e guias de início rápido, a reutilização de projetos pode evitar que você exceda limites da cota.

Excluir 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 terminar de ser executado, ele vai criar e armazenar arquivos de saída no diretório WORK_DIRECTORY do bucket do Cloud Storage.

Para reduzir as cobranças do Cloud Storage na conta Google Cloud atual, faça o seguinte:

• 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 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ê especificou no comando dsub.

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