Migrar do Cloud Life Sciences para o Batch

Nesta página, descrevemos como migrar do Cloud Life Sciences para o Batch.

Google Cloud anunciou que o Cloud Life Sciences foi descontinuado em 17 de julho de 2023 e será encerrado em 8 de julho de 2025. No entanto, o Batch está disponível de maneira geral e é um sucessor abrangente que oferece suporte a todos os casos de uso do Cloud Life Sciences.

Saiba mais sobre o Batch, o Cloud Life Sciences e as etapas de lançamento de produtos.

Cloud Life Sciences x Batch

A migração do Cloud Life Sciences para o Batch envolve principalmente entender como usar o Batch para as cargas de trabalho que você executa atualmente com a execução de pipelines do Cloud Life Sciences.

Para entender como executar suas cargas de trabalho do Cloud Life Sciences no Batch, consulte todas as seções a seguir:

Visão geral

Um pipeline do Cloud Life Sciences descreve uma sequência de ações (contêineres) a serem executadas e o ambiente em que os contêineres serão executados.

Um job do Batch descreve uma matriz de uma ou mais tarefas e o ambiente em que elas serão executadas. Você define a carga de trabalho de um job como uma sequência de um ou mais executáveis (contêineres e/ou scripts) a serem executados. Cada tarefa de um job representa uma execução da sequência de executáveis.

Os pipelines do Cloud Life Sciences podem ser expressos como jobs do Batch de tarefa única.

Por exemplo, as amostras a seguir descrevem um pipeline simples do Cloud Life Sciences e o job em lote equivalente:

Pipeline do Cloud Life Sciences Job em lote 
  {
    "actions": [
      {
        "imageUri": "bash",
        "commands": [
          "-c",
          "echo Hello, world!"
        ]
      }
    ]
  }
  
    {
      "taskGroups" : [{
        "taskSpec" : {
          "runnables" : [{
            "container":{
              "imageUri": "bash",
              "commands": [
                "-c",
                "echo Hello, world!"
              ]
            }
          }]
        }
      }]
    }

Os jobs em lote com várias tarefas são semelhantes aos pipelines copiados do Cloud Life Sciences.

Ao contrário do Cloud Life Sciences, o Batch permite programar automaticamente várias execuções da sua carga de trabalho. Você indica o número de vezes que quer executar a sequência de executáveis para um job definindo o número de tarefas. Quando um job tem várias tarefas, você especifica como quer que cada execução varie referenciando o índice da tarefa nos executáveis. Além disso, é possível configurar os cronogramas relativos das tarefas de um job. Por exemplo, se permitir que várias tarefas sejam executadas em paralelo ou exigir que elas sejam executadas em ordem sequencial e uma de cada vez. O Batch gerencia o agendamento das tarefas do job: quando uma tarefa termina, o job inicia automaticamente a próxima, se houver.

Por exemplo, confira o seguinte job em lote. Este exemplo tem 100 tarefas que são executadas em 10 instâncias de máquina virtual (VM) do Compute Engine. Portanto, há aproximadamente 10 tarefas em execução em paralelo a qualquer momento. Cada tarefa neste exemplo de job executa apenas um executável: um script que imprime uma mensagem e o índice da tarefa, que é definido pela variável de ambiente predefinida BATCH_TASK_INDEX.

{
  "taskGroups" : [{
    "taskSpec" : {
      "runnables" : [{
        "script":{
          "text": "echo Hello world! This is task ${BATCH_TASK_INDEX}."
        }
      }]
    },
    "taskCount": 100,
    "parallelism": 10
  }]
}

Workflows que envolvem a criação e o monitoramento de vários pipelines semelhantes do Cloud Life Sciences às vezes podem ser simplificados aproveitando o agendamento integrado do Batch.

Operações básicas

Esta seção descreve as operações básicas no Cloud Life Sciences e no Batch.

A tabela a seguir resume as opções básicas de operações para o Cloud Life Sciences e o Batch.

Operação básica Opções do Cloud Life Sciences Opções de lote
Execute uma carga de trabalho.
  • Execute um pipeline.
  • Crie e execute um job.
Confira todas as suas cargas de trabalho.
  • Listar operações de longa duração.
  • Confira uma lista dos seus jobs.
Confira os detalhes e o status de uma carga de trabalho.
  • Recebe detalhes de uma operação de longa duração.
  • Pesquise uma operação de longa duração.
  • Veja os detalhes de um job.
  • Confira uma lista das tarefas de um job.
  • Ver os detalhes de uma tarefa.
Interrompa e remova uma carga de trabalho.
  • Cancelar uma operação de longa duração.
  • Excluir (e cancelar) um job.
  • Verifique o status de uma solicitação de exclusão de job.

As operações básicas do Cloud Life Sciences e do Batch têm algumas diferenças importantes.

Primeiro, os recursos de operação de longa duração não têm a mesma função no Batch que no Cloud Life Sciences. Recursos de operações de longa duração (LROs, na sigla em inglês) no Cloud Life Sciences são o recurso principal usado para listar e visualizar seus pipelines. No entanto, os recursos de operação de longa duração no Batch e em outras APIs Google Cloud são usados apenas para monitorar o status de uma solicitação que leva muito tempo para ser concluída. Especificamente, no Batch, a única solicitação que retorna um recurso de operação de longa duração é a exclusão de um job. Para mais informações sobre recursos operação de longa duração do Batch, consulte a documentação de referência da API Batch para o recurso REST projects.locations.operations. Em vez de usar recursos de operação de longa duração, o Batch tem recursos de job que você pode visualizar e excluir para suas cargas de trabalho.

Em segundo lugar, a visualização dos detalhes de uma carga de trabalho no Batch envolve operações diferentes do Cloud Life Sciences. É possível ver um job para conferir os detalhes e o status dele. No entanto, cada uma das tarefas de um job também tem detalhes e status próprios que podem ser vistos em uma lista de tarefas de um job e nos detalhes de uma tarefa.

Para ajudar você a entender melhor as operações básicas do Cloud Life Sciences e do Batch, as seções a seguir fornecem exemplos de comandos da Google Cloud CLI e caminhos de solicitações da API para algumas dessas operações básicas.

Exemplos de comandos da CLI gcloud

Para a CLI gcloud, os comandos do Cloud Life Sciences começam com gcloud beta lifesciences e os comandos do Batch começam com gcloud batch. Por exemplo, consulte os seguintes comandos da CLI gcloud.

  • Exemplos de comandos da CLI gcloud do Cloud Life Sciences:

    • Execute um pipeline:

      gcloud beta lifesciences pipelines run \
  --project=PROJECT_ID \
  --regions=LOCATION \
  --pipeline-file=JSON_CONFIGURATION_FILE

    • Acessar detalhes de uma operação de longa duração:

      gcloud beta lifesciences operations describe OPERATION_ID

    Substitua:

    • PROJECT_ID: o ID do projeto do seu projeto.
    • LOCATION: o local do pipeline.
    • JSON_CONFIGURATION_FILE: o arquivo de configuração JSON do pipeline.
    • OPERATION_ID: o identificador da operação de longa duração, que foi retornado pela solicitação para executar o pipeline.

  • Exemplos de comandos da CLI gcloud em lote:

    • Crie e execute um job:

      gcloud batch jobs submit JOB_NAME \
  --project=PROJECT_ID \
  --location=LOCATION \
  --config=JSON_CONFIGURATION_FILE

    • Ver os detalhes de um job:

      gcloud batch jobs describe JOB_NAME \
  --project=PROJECT_ID \
  --location=LOCATION \

    • Para ver a lista de tarefas de um job:

      ​​gcloud batch tasks list \
  --project=PROJECT_ID \
  --location=LOCATION \
  --job=JOB_NAME

    • Para ver os detalhes de uma tarefa:

      gcloud batch tasks describe TASK_INDEX \
  --project=PROJECT_ID \
  --location=LOCATION \
  --job=JOB_NAME \
  --task_group=TASK_GROUP

    • Excluir (e cancelar) um job:

      gcloud batch jobs delete JOB_NAME \
  --project=PROJECT_ID \
  --location=LOCATION

    Substitua:

    • JOB_NAME: o nome do job.
    • PROJECT_ID: o ID do projeto do seu projeto.
    • LOCATION: o local do job.
    • JSON_CONFIGURATION_FILE: o caminho para um arquivo JSON com os detalhes de configuração do job.
    • TASK_INDEX: o índice da tarefa que você quer ver os detalhes. Em um grupo de tarefas, o índice começa em 0 para a primeira tarefa e aumenta em 1 a cada tarefa adicional. Por exemplo, um grupo de tarefas com quatro tarefas tem os índices 0, 1, 2 e 3.
    • TASK_GROUP_NAME: o nome do grupo de tarefas cujos detalhes você quer conferir. O valor precisa ser definido como group0.

Exemplos de caminhos de solicitação da API

Para APIs, o Cloud Life Sciences usa caminhos de solicitação lifesciences.googleapis.com, e o Batch usa caminhos de solicitação batch.googleapis.com. Por exemplo, confira os caminhos de solicitação de API a seguir. Ao contrário do Cloud Life Sciences, o Batch não tem uma API RPC, apenas uma API REST.

  • Exemplos de caminhos de solicitação da API Cloud Life Sciences:

    • Execute um pipeline:

      POST https://lifesciences.googleapis.com/v2beta/projects/PROJECT_ID/locations/LOCATION/pipelines:run

    • Acessar detalhes de uma operação de longa duração:

      GET https://lifesciences.googleapis.com/v2beta/projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID

    Substitua:

    • PROJECT_ID: o ID do projeto do seu projeto.
    • LOCATION: o local do pipeline.
    • OPERATION_ID: o identificador da operação de longa duração, que foi retornado pela solicitação para executar o pipeline.

  • Exemplos de caminhos de solicitação da API em lote:

    • Crie e execute um job:

      POST https://batch.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/jobs?job_id=JOB_NAME

    • Ver os detalhes de um job:

      GET https://batch.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/jobs/JOB_NAME

    • Para ver a lista de tarefas de um job:

      GET https://batch.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/jobs/JOB_NAME/taskGroups/TASK_GROUP/tasks

    • Excluir um job

      DELETE https://batch.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/jobs/JOB_NAME

    • Verifique o status da solicitação de exclusão do job:

      GET https://batch.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID

    Substitua:

    • PROJECT_ID: o ID do projeto do seu projeto.
    • LOCATION: o local do job.
    • JOB_NAME: o nome do job.
    • TASK_GROUP_NAME: o nome do grupo de tarefas cujos detalhes você quer conferir. O valor precisa ser definido como group0.
    • OPERATION_ID: o identificador da operação de longa duração, que foi retornado pela solicitação para excluir o job.

Permissões e papéis do IAM

Esta seção resume as diferenças nas funções e permissões do Identity and Access Management para o Cloud Life Sciences e o Batch. Para mais informações sobre papéis e permissões, consulte a Referência de papéis básicos e predefinidos do IAM.

A tabela a seguir descreve os papéis predefinidos e as permissões necessárias para usuários do Cloud Life Sciences.

Papéis do Cloud Life Sciences Permissões

Qualquer um dos seguintes:

  • Administrador do Cloud Life Sciences (roles/lifesciences.admin) no projeto
  • Editor do Cloud Life Sciences (roles/lifesciences.editor) no projeto
  • Executor de fluxos de trabalho do Cloud Life Sciences (roles/lifesciences.workflowsRunner) no projeto
  • lifesciences.workflows.run
  • lifesciences.operations.cancel
  • lifesciences.operations.get
  • lifesciences.operations.list
Leitor do Cloud Life Sciences (roles/lifesciences.viewer) no projeto
  • lifesciences.operations.get
  • lifesciences.operations.list
  • resourcemanager.projects.get
  • resourcemanager.projects.list

A tabela a seguir descreve alguns dos papéis predefinidos e as permissões deles para o Batch. Ao contrário do Cloud Life Sciences, o Batch exige que você conceda permissões aos usuários e à conta de serviço para um job. Para mais informações sobre os requisitos do IAM, consulte Pré-requisitos do Batch.

Atribuir funções em lote para usuários Permissões
Editor de jobs em lote (roles/batch.jobsEditor) no projeto
  • batch.jobs.create
  • batch.jobs.delete
  • batch.jobs.get
  • batch.jobs.list
  • batch.locations.get
  • batch.locations.list
  • batch.operations.get
  • batch.operations.list
  • batch.tasks.get
  • batch.tasks.list
  • resourcemanager.projects.get
  • resourcemanager.projects.list
Leitor de job em lote (roles/batch.jobsViewer) no projeto
  • batch.jobs.get
  • batch.jobs.list
  • batch.locations.get
  • batch.locations.list
  • batch.operations.get
  • batch.operations.list
  • batch.tasks.get
  • batch.tasks.list
  • resourcemanager.projects.get
  • resourcemanager.projects.list
Usuário da conta de serviço (roles/iam.serviceAccountUser) na conta de serviço do job
  • iam.serviceAccounts.actAs
  • iam.serviceAccounts.get
  • iam.serviceAccounts.list
  • resourcemanager.projects.get
  • resourcemanager.projects.list
Papéis em lote para contas de serviço Permissões
Relator do agente em lote (roles/batch.agentReporter) no projeto
  • batch.states.report

Recursos correspondentes

A tabela a seguir descreve os recursos do Cloud Life Sciences, os recursos equivalentes do Batch e detalhes sobre as diferenças entre eles.

Cada recurso é representado por uma descrição e sua sintaxe JSON. É possível usar a sintaxe JSON ao acessar o Batch pela API ou ao especificar um arquivo de configuração JSON pela Google Cloud CLI. No entanto, é possível usar os recursos do Batch por outros métodos, como campos do console Google Cloud , flags da CLI gcloud e bibliotecas de cliente, que são descritos na documentação do Batch.

Para mais informações sobre cada recurso e a sintaxe JSON dele, consulte o seguinte:

Recursos do Cloud Life Sciences Recursos em lote Detalhes
pipeline (pipeline) job (job) e as tarefas dele (taskGroups[])

Um job em lote consiste em uma matriz de uma ou mais tarefas que executam todos os mesmos executáveis. Um pipeline do Cloud Life Sciences é semelhante a um job do Batch com uma tarefa. No entanto, o Cloud Life Sciences não tem um conceito equivalente para tarefas (jobs com várias tarefas), que são um pouco como repetições de um pipeline.

Para mais informações sobre jobs e tarefas, consulte Visão geral do Batch.

ações (actions[]) para um pipeline executáveis (runnables[]) para as tarefas de um job

Uma ação do Cloud Life Sciences descreve um contêiner, mas um executável do Batch pode conter um contêiner ou um script.

credenciais (credentials) para uma ação

para um contêiner executável:

No Cloud Life Sciences, as credenciais de uma ação precisam ser um dicionário criptografado do Cloud Key Management Service com pares de chave-valor de nome de usuário e senha.

No Batch, o nome de usuário e a senha de um executável de contêiner estão em campos separados. Qualquer um dos campos pode ser especificado com texto simples ou com o nome de um secret do Secret Manager.

para uma ação:

para um ambiente:

ambientes possíveis:

Com o Cloud Life Sciences, é possível especificar as variáveis de ambiente de uma ação formatadas como texto simples ou como um dicionário criptografado. No Batch, isso é semelhante a ter o ambiente para um executável (campo environment em runnables[]) incluir variáveis formatadas como texto simples (variables) ou um dicionário criptografado (encryptedVariables).

No entanto, o Batch também tem mais opções para especificar variáveis de ambiente:

  • Como alternativa a especificar variáveis como texto simples ou um dicionário criptografado, é possível especificar variáveis usando secrets do Secret Manager com uma variável de secret (secretVariables).
  • Como alternativa a especificar uma variável de ambiente para um executável, você pode especificar uma variável de ambiente para todos os executáveis usando o campo environment em taskSpec.
  • Como alternativa a especificar uma variável de ambiente que tenha o mesmo valor para cada tarefa, você pode especificar uma variável de ambiente que tenha um valor diferente para cada tarefa usando o campo taskEnvironments[] em taskGroups[].

Para mais informações, consulte Usar variáveis de ambiente.
rótulos para uma solicitação de execução de um pipeline (labels no corpo da solicitação) rótulos de um job (labels no recurso de job)

Ao contrário do Cloud Life Sciences, o Batch não inclui um campo de rótulos na solicitação para criar um job. A opção mais próxima para o Batch é usar rótulos associados apenas ao job.

O Batch tem vários tipos de rótulos (campos labels) que podem ser usados ao criar um job. Para mais informações, consulte Organizar recursos usando rótulos.
regiões (regions[]) e zonas (zones[]) para os recursos de um pipeline (resources) locais permitidos (allowedLocations) para uma política de local do recurso de um job (locationPolicy)

No Cloud Life Sciences, um pipeline é executado em uma única VM, para a qual você pode especificar as regiões e/ou zonas desejadas.

No Batch, a opção equivalente são os locais permitidos para um job, que podem ser definidos como uma ou mais regiões ou zonas e especificam onde as VMs de um job podem ser criadas. Todas as VMs de um único job em lote pertencem a um único grupo gerenciado de instâncias (MIG), que existe em uma região específica. No entanto, as VMs individuais podem estar em zonas diferentes dessa região.

Especificar o campo de locais permitidos para um job é opcional porque ele é separado do local do job. Ao contrário do local do job, o local permitido não afeta o local usado para criar um job em lote e armazenar metadados do job. Para mais informações, consulte Locais de lote.

para os recursos de um pipeline (resources):

para uma política de recursos de um job (allocationPolicy):

No Cloud Life Sciences, é possível configurar a VM em que um pipeline é executado.

No Batch, as mesmas opções para VMs estão disponíveis nos campos de uma política de alocação de recursos de um job (allocationPolicy):

  • A conta de serviço, os rótulos e a configuração de rede das VMs são definidos nos campos dedicados.
  • O campo de VM (instances), que pode ser definido diretamente ou usando um modelo de instância, inclui as opções de configuração para o tipo de máquina, plataforma mínima de CPU permitida, disco de inicialização e outros discos conectados, além de GPUs e drivers de GPU.

para uma ação:

para um executável:

Esses vários flags de conveniência do Cloud Life Sciences são equivalentes no Batch, exceto que são especificados para cada executável (que pode conter um script ou contêiner) em vez de cada ação (contêiner).

para uma ação:

  • opção para publicar portas expostas (publishExposedPorts)
  • opção para especificar o namespace do ID do processo (PID) (pidNamespace)
  • e a opção de especificar mapeamentos de porta do contêiner para o host (portMappings).
 opções (options) para um contêiner executável

Essas opções do Cloud Life Sciences (e outras) são compatíveis com o Batch pelo campo de opções (options) para um executável de contêiner. Defina o campo de opções como qualquer flag que você queira que o Batch adicione ao comando docker run, por exemplo, -P --pid mynamespace -p 22:22.

para uma ação:

 sem equivalente

O pré-busca em lote imagens e processa as saídas de todos os executáveis de maneira idêntica, de acordo com a política de registros do job (logsPolicy).

opção para bloquear redes externas (blockExternalNetwork) em uma ação opção para bloquear redes externas (blockExternalNetwork) para um executável de contêiner

A opção do Cloud Life Sciences para bloquear redes externas em uma ação é semelhante à opção do Batch para bloquear redes externas em um contêiner.

O Batch também tem muitas outras opções de rede, como bloquear redes externas para todas as VMs de um job. Para mais informações, consulte Visão geral da rede em lote.
montagens (mounts[]) para uma ação volumes para todos os executáveis (volumes[] em taskSpec) e opções de volume para um contêiner (volumes[] em container)

No Batch, é possível usar o campo volumes[] em taskSpec para definir os volumes de um job e os caminhos de montagem deles. O Batch monta volumes de armazenamento nas VMs do job e eles ficam acessíveis a todos os executáveis do job (scripts ou contêineres). Essa montagem é feita antes que a VM execute tarefas ou executáveis.

Além disso, o Batch aceita opções de volume explícitas em executáveis de contêiner usando o campo volumes[] em container. Essas opções de montagem são transmitidas ao contêiner como opções para a flag --volume do comando docker run. Por exemplo, o valor [ "/etc:/etc", "/foo:/bar" ] é traduzido para o comando docker run --volume /etc:/etc --volume /foo:/bar no contêiner.

Para mais informações sobre como usar volumes de armazenamento com o Batch, consulte Criar e executar um job que usa volumes de armazenamento.

opção para ativar o Cloud Storage FUSE (enableFuse) em uma ação sem equivalente

O Batch processa a montagem de todos os volumes de armazenamento, como um bucket do Cloud Storage, que você especifica para um job. Como resultado, você não ativa nenhuma ferramenta de montagem, como o Cloud Storage FUSE para o Batch. No entanto, é possível especificar opções de montagem para seus volumes de armazenamento usando o campo mountOptions[].

Para mais informações sobre como usar buckets do Cloud Storage com o Batch, consulte Criar e executar um job que usa volumes de armazenamento.

Tópico do Pub/Sub (pubSubTopic) para uma solicitação de execução de um pipeline

para as configurações de notificação de um job (notifications[]):

O Batch permite uma personalização maior das atualizações de status do que o Cloud Life Sciences. Por exemplo, os usuários do Batch podem receber uma notificação em um tópico do Pub/Sub quando tarefas individuais mudam de estado ou apenas quando o job geral muda de estado.

Serviços de fluxo de trabalho

Se você usa um serviço de fluxo de trabalho com o Cloud Life Sciences, seu processo de migração também envolve a configuração de um serviço de fluxo de trabalho para trabalhar com o Batch. Esta seção resume os serviços de fluxo de trabalho que podem ser usados com o Lote.

O Batch é compatível com o Workflows, um serviço de fluxo de trabalho do Google Cloud. Se quiser usar o Workflows com o Batch, consulte Executar um job do Batch usando o Workflows. Caso contrário, a tabela a seguir descreve outros serviços de fluxos de trabalho que podem ser usados com o Cloud Life Sciences e também com o Batch. Esta tabela lista as principais diferenças entre usar cada serviço de fluxo de trabalho com o Batch em vez do Cloud Life Sciences e detalhes sobre onde saber mais sobre o uso de cada serviço com o Batch.

Serviço de fluxo de trabalho Principais diferenças Detalhes
Cromwell

Para usar um arquivo de configuração do Cromwell com a API Cloud Life Sciences v2beta e a API Batch, faça as seguintes mudanças:

  1. Para o campo actor-factory, substitua cromwell.backend.google.pipelines.v2beta.PipelinesApiLifecycleActorFactory por cromwell.backend.google.batch.GcpBatchLifecycleActorFactory.
  2. Remova o campo genomics.endpoint-url.
  3. Gere um novo arquivo de configuração.
 Para saber mais sobre como usar o Batch com o Cromwell, consulte a documentação do Cromwell para o Batch e o tutorial do Cromwell para o Batch.
dsub

Para usar um pipeline dsub para o Cloud Life Sciences com o Batch, faça as seguintes mudanças:

  • Para o campo provider, substitua google-cls-v2 por google-batch.
 Para saber mais sobre como usar o Batch com dsub, consulte a documentação do dsub para o Batch.
Nextflow

Para usar um arquivo de configuração do Nextflow para o Cloud Life Sciences com o Batch, em vez disso, faça as seguintes mudanças:

  1. Para o campo executor, substitua google-lifesciences por google-batch.
  2. Para todos os prefixos config, substitua google.lifeScience por google.batch.
 Para saber mais sobre como usar o Batch com o Nextflow, consulte um tutorial do Batch ou tutorial do Nextflow. Para mais informações sobre opções de configuração, consulte a documentação do Nextflow.
Snakemake

Para usar um pipeline do Snakemake com a API Cloud Life Sciences v2beta e a API Batch, faça as seguintes mudanças:

  1. Verifique se você está usando a versão 8 ou mais recente do Snakemake. Para mais informações, consulte Migração entre versões do Snakemake.

  2. Faça as seguintes mudanças no comando snakemake:

    • Substitua a flag --google-lifesciences pela flag --executor googlebatch.
    • Substitua todas as flags adicionais que tenham o prefixo --google-lifesciences- pelo prefixo --googlebatch-.
 Para saber mais sobre como usar o Batch com o Snakemake, consulte a documentação do Snakemake para o Batch.

A seguir

  • Para configurar o Batch para novos usuários e projetos, consulte Começar a usar.
  • Para saber como executar cargas de trabalho usando o Batch, consulte Criar um job.