Orquestre trabalhos executando pipelines dsub no Batch

---

Este tutorial explica como executar um pipeline de dsub no Batch. Especificamente, o pipeline de exemplo dsub processa dados de sequenciação de ADN num ficheiro de mapa de alinhamento binário (BAM) para criar um ficheiro de índice BAM (BAI).

Este tutorial destina-se a utilizadores do Batch que querem usar o dsub com o Batch. dsub é um agendador de tarefas de código aberto para orquestrar fluxos de trabalho de processamento em lote no Google Cloud. Para saber como usar o comando Batch com dsub, consulte a documentação do comando Batch.dsub

Objetivos

• Execute um pipeline dsub no Batch que lê e escreve ficheiros em contentores do Cloud Storage.
• Ver os ficheiros de saída num contentor do Cloud Storage.

Custos

Neste documento, usa os seguintes componentes faturáveis do Google Cloud:

• Batch
• Cloud Storage

Para gerar uma estimativa de custos com base na sua utilização projetada, use a calculadora de preços.

Os novos Google Cloud utilizadores podem ser elegíveis para uma avaliação gratuita.

Normalmente, os recursos criados neste tutorial custam menos de 1 €, se concluir todos os passos, incluindo a limpeza, de forma atempada.

Antes de começar

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.

Install the Google Cloud CLI.

Se estiver a usar um fornecedor de identidade (IdP) externo, tem primeiro de iniciar sessão na CLI gcloud com a sua identidade federada.

Para inicializar a CLI gcloud, execute o seguinte comando:

gcloud init

Create or select a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

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.

Verify that billing is enabled for your Google Cloud project.

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

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

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

Install the Google Cloud CLI.

Se estiver a usar um fornecedor de identidade (IdP) externo, tem primeiro de iniciar sessão na CLI gcloud com a sua identidade federada.

Para inicializar a CLI gcloud, execute o seguinte comando:

gcloud init

Create or select a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

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.

Verify that billing is enabled for your Google Cloud project.

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

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

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

1. Certifique-se de que o seu projeto tem, pelo menos, uma conta de serviço com as autorizações necessárias para este tutorial.

   Nota: se estiver a usar um novo projeto, este passo não é necessário a menos que a sua organização impeça a concessão automática de funções para contas de serviço predefinidas. Por predefinição, à conta de serviço predefinida do Compute Engine é concedido automaticamente o papel de Editor (roles/editor) do IAM, que já tem todas as autorizações necessárias para este tutorial.

   Cada tarefa requer uma conta de serviço que permita ao agente do serviço Batch criar e aceder aos recursos necessários para executar a tarefa. Para este tutorial, a conta de serviço da tarefa é a conta de serviço predefinida do Compute Engine.

   Para garantir que a conta de serviço predefinida do Compute Engine tem as autorizações necessárias para permitir que o agente do serviço Batch crie e aceda a recursos para tarefas do Batch, peça ao seu administrador para conceder à conta de serviço predefinida do Compute Engine as seguintes funções do IAM:

   Importante: tem de conceder estas funções à conta de serviço predefinida do Compute Engine e não à sua conta de utilizador. Se não conceder as funções ao principal correto, podem ocorrer erros de autorização.
   • Batch Agent Reporter (roles/batch.agentReporter) no projeto
   • Administrador de armazenamento (roles/storage.admin) no projeto
   • (Recomendado) Permitir que os trabalhos gerem registos no Cloud Logging: Logs Writer (roles/logging.logWriter) no projeto

   Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

   O administrador também pode conceder à conta de serviço predefinida do Compute Engine as autorizações necessárias através de funções personalizadas ou outras funções predefinidas.

2. Certifique-se de que tem as autorizações necessárias para este tutorial.

   Nota: se criou este projeto, este passo não é necessário. Como criador do projeto, tem automaticamente a função de proprietário (roles/owner) do IAM, que já tem todas as autorizações necessárias para este tutorial.

   Para receber as autorizações de que precisa para concluir este tutorial, peça ao seu administrador que lhe conceda as seguintes funções do IAM:

   • Editor de tarefas em lote (roles/batch.jobsEditor) no projeto
   • Utilizador da conta de serviço (roles/iam.serviceAccountUser) na conta de serviço da tarefa, que, para este tutorial, é a conta de serviço predefinida do Compute Engine
   • Administrador de objetos de armazenamento (roles/storage.objectAdmin) no projeto

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

   1. Certifique-se de que tem instaladas versões do Python e do pip que são suportadas pela versão mais recente do dsub. Para ver as versões instaladas atualmente, execute o seguinte comando:

      pip --version
      

      Se precisar de instalar ou atualizar o pip ou o Python, siga os passos para instalar o Python.

   2. Recomendado: para evitar erros de conflitos de dependências 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 dsubrepositório do GitHub usando git e abra-o:

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

   4. Instale o dsub e as respetivas dependências:

      python -m pip install .
      

      O resultado é semelhante ao 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
      

Crie um contentor do Cloud Storage

Para criar um contentor do Cloud Storage para armazenar os ficheiros de saída do pipeline de exemplo dsub através da CLI gcloud, execute o comando gcloud storage buckets create:

gcloud storage buckets create gs://BUCKET_NAME \
    --project PROJECT_ID

Substitua o seguinte:

• BUCKET_NAME: um nome globalmente exclusivo para o seu contentor.

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

O resultado é semelhante ao seguinte:

Creating gs://BUCKET_NAME/...

Execute o pipeline dsub

O pipeline de amostra dsub indexa um ficheiro BAM do 1000 Genomes Project e envia os resultados para um contentor do Cloud Storage.

Para executar o exemplo de pipeline 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 o seguinte:

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

• BUCKET_NAME: o nome do contentor do Cloud Storage que criou.

• WORK_DIRECTORY: o nome de um novo diretório que o pipeline pode usar para armazenar registos e resultados. Por exemplo, introduza workDir.

O pipeline dsub executa uma tarefa em lote que escreve o ficheiro BAI e regista-se no diretório especificado no seu contentor do Cloud Storage. Especificamente, o repositório dsub contém uma imagem Docker pré-criada que usa o samtools para indexar o ficheiro BAM que especificou na flag --input.

O comando não termina até que o pipeline dsub termine a execução, o que pode variar consoante a data de agendamento da tarefa em lote. Normalmente, este processo demora cerca de 10 minutos: o Batch começa normalmente a executar a tarefa em poucos minutos e o tempo de execução da tarefa é de cerca de 8 minutos.

Inicialmente, o comando continua a ser executado e o resultado é semelhante ao seguinte:

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.

Em seguida, após a conclusão bem-sucedida da tarefa, o comando termina e o resultado é semelhante ao seguinte:

  JOB_NAME: SUCCESS
JOB_NAME

Esta saída inclui os seguintes valores:

• JOB_NAME: o nome da tarefa.

• USERNAME: o seu nome de utilizador Google Cloud .

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

Veja os ficheiros de saída

Para ver os ficheiros de saída criados pela pipeline dsub de amostra através da CLI gcloud, execute o comando gcloud storage ls:

gcloud storage ls gs://BUCKET_NAME/WORK_DIRECTORY \
    --project PROJECT_ID

Substitua o seguinte:

• BUCKET_NAME: o nome do contentor do Cloud Storage que criou.

• WORK_DIRECTORY: o diretório que especificou no comando dsub.

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

O resultado é semelhante ao seguinte:

gs://BUCKET_NAME/WORK_DIRECTORY/HG00114.mapped.ILLUMINA.bwa.GBR.low_coverage.20120522.bam.bai
gs://BUCKET_NAME/WORK_DIRECTORY/logs/

Esta saída inclui o ficheiro BAI e um diretório que contém os registos da tarefa.

Limpar

Para evitar incorrer em custos na sua conta do Google Cloud pelos recursos usados neste tutorial, elimine o projeto que contém os recursos ou mantenha o projeto e elimine os recursos individuais.

Elimine o projeto

A forma mais fácil de eliminar a faturação é eliminar o projeto atual.

Atenção: a eliminação de um projeto tem os seguintes efeitos:

• Tudo no projeto é eliminado. Se usou um projeto existente para as tarefas neste documento, quando o elimina, também elimina qualquer outro trabalho que tenha feito no projeto.
• Os IDs dos projetos personalizados são perdidos. Quando criou este projeto, pode ter criado um ID do projeto personalizado que quer usar no futuro. Para preservar os URLs que usam o ID do projeto, como um URL appspot.com, elimine os recursos selecionados no projeto em vez de eliminar o projeto inteiro.

Se planeia explorar várias arquiteturas, tutoriais ou inícios rápidos, a reutilização de projetos pode ajudar a evitar exceder os limites de quota de projetos.

Delete a Google Cloud project:

gcloud projects delete PROJECT_ID

Elimine recursos individuais

Se quiser continuar a usar o projeto atual, elimine os recursos individuais usados neste tutorial.

Elimine o contentor

Depois de a pipeline terminar a execução, cria e armazena ficheiros de saída no diretório WORK_DIRECTORY do seu contentor do Cloud Storage.

Para reduzir as cobranças do Cloud Storage na conta atual, faça uma das seguintes ações:Google Cloud

• Se já não precisar do contentor que usou neste tutorial, use o comando gcloud storage rm com a flag --recursive para eliminar o contentor e todo o respetivo conteúdo:

  gcloud storage rm gs://BUCKET_NAME \
      --recursive \
      --project PROJECT_ID
  

  Substitua o seguinte:

  • BUCKET_NAME: o nome do contentor do Cloud Storage que criou.

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

• Caso contrário, se ainda precisar do contentor, use o comando gcloud storage rm com a flag --recursive para eliminar apenas o diretório WORK_DIRECTORY e todo o respetivo conteúdo:

  gcloud storage rm gs://BUCKET_NAME/WORK_DIRECTORY \
      --recursive \
      --project PROJECT_ID
  

  Substitua o seguinte:

  • BUCKET_NAME: o nome do contentor do Cloud Storage que criou.

  • WORK_DIRECTORY: o diretório que especificou no comando dsub.

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

Elimine a tarefa

Para eliminar uma tarefa através da CLI gcloud, execute o comando gcloud batch jobs delete.

gcloud batch jobs delete JOB_NAME \
    --location us-central1 \
    --project PROJECT_ID

Substitua o seguinte:

• JOB_NAME: o nome da tarefa.
• PROJECT_ID: o ID do projeto do seu Google Cloud projeto.

O que se segue?

• Saiba mais acerca da dsub e da dsub para o processamento em lote.
• Saiba mais sobre a utilização de volumes de armazenamento com o Batch.