Migrar do Cloud Life Sciences para lote

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

Em 17 de julho de 2023, o Google Cloud anunciou que o Cloud Life Sciences, que estava na versão Beta, foi descontinuado. O serviço não estará mais disponível no Google Cloud após 8 de julho de 2025. No entanto, o Batch geralmente está disponível e é um sucessor abrangente compatível com todos os casos de uso do Cloud Life Sciences.

Saiba mais sobre Batch, Cloud Life Sciences e fases de lançamento de produtos.

Cloud Life Sciences vs. Batch

A migração do Cloud Life Sciences para o Batch envolve principalmente a compreensão de como é possível usar o Batch para as cargas de trabalho que você executa atualmente, executando pipelines do Cloud Life Sciences.

Para entender como executar as cargas de trabalho do Cloud Life Sciences em lote, consulte estas seções:

Informações gerais

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

Um job em lote descreve uma matriz de uma ou mais tarefas e o ambiente em que 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 em lote de tarefa única.

Por exemplo, os exemplos 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 de 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. Indique o número de vezes que você quer executar a sequência de executáveis para um job definindo o número de tarefas. Quando um job tem várias tarefas, especifique como você quer que cada execução varie referenciando o índice da tarefa nos executáveis. Além disso, é possível configurar as programações relativas para as tarefas de um job. Por exemplo, se você quer permitir que várias tarefas sejam executadas em paralelo ou exigir que as tarefas sejam executadas em ordem sequencial e uma de cada vez. O Batch gerencia a programação das tarefas do job: quando uma tarefa termina, o job inicia automaticamente a próxima, se houver.

Por exemplo, consulte o job em lote a seguir. Este job de exemplo tem 100 tarefas executadas em 10 instâncias de máquina virtual (VM) do Compute Engine. Portanto, há aproximadamente 10 tarefas em execução paralelamente a qualquer momento. Cada tarefa neste job de exemplo executa apenas um executável: um script que mostra 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
  }]
}

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

Operações básicas

Nesta seção, descrevemos 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 do Cloud Life Sciences e do Batch.

Operação básica Opções do Cloud Life Sciences Opções de lote
executar uma carga de trabalho;
  • Executar um pipeline.
  • Crie e execute um job.
Veja todas as suas cargas de trabalho.
  • Listar operações de longa duração.
  • Veja uma lista dos seus jobs.
Visualizar os detalhes e o status de uma carga de trabalho.
  • Veja detalhes de uma operação de longa duração.
  • Pesquise uma operação de longa duração.
  • Ver os detalhes de uma tarefa.
  • Veja uma lista das tarefas de uma tarefa.
  • 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.
  • Verificar 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.

Em primeiro lugar, os recursos operação de longa duração não desempenham em lote o mesmo papel que no Cloud Life Sciences. Os recursos de operação de longa duração (LROs, na sigla em inglês) no Cloud Life Sciences são o principal recurso usado para listar e visualizar seus pipelines. No entanto, recursos de operação de longa duração em lote e outras APIs do 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 de operação de longa duração para Lote, consulte a documentação de referência da API em lote 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 podem ser visualizados e excluídos das cargas de trabalho.

Em segundo lugar, a visualização dos detalhes de uma carga de trabalho em lote envolve operações diferentes do Cloud Life Sciences. Você pode ver um job para ver os detalhes e o status dele. No entanto, cada tarefa de um job também tem os próprios detalhes e status, que podem ser conferidos em uma lista de tarefas e 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 do Google Cloud CLI e caminhos de solicitações de 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 em lote começam com gcloud batch. Por exemplo, consulte os seguintes comandos da CLI gcloud.

  • Comandos da CLI gcloud de exemplo do Cloud Life Sciences:

    • Execute um pipeline:

      gcloud beta lifesciences pipelines run \
        --project=PROJECT_ID \
        --regions=LOCATION \
        --pipeline-file=JSON_CONFIGURATION_FILE
      
    • Veja detalhes de uma operação de longa duração:

      gcloud beta lifesciences operations describe OPERATION_ID
      

    Substitua:

    • PROJECT_ID: o ID do 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 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
      
    • Visualizar os detalhes de uma tarefa:

      gcloud batch jobs describe JOB_NAME \
        --project=PROJECT_ID \
        --location=LOCATION \
      
    • Veja a lista de tarefas de uma tarefa:

      ​​gcloud batch tasks list \
        --project=PROJECT_ID \
        --location=LOCATION \
        --job=JOB_NAME
      
    • 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.
    • LOCATION: o local do job.
    • JSON_CONFIGURATION_FILE: o caminho de um arquivo JSON com os detalhes de configuração do job.
    • TASK_INDEX: o índice da tarefa com os detalhes que você quer ver. Os índices da tarefa em um grupo de tarefas começam em 0 e aumentam em um para cada tarefa. Por exemplo, os índices de um grupo com quatro tarefas são 0, 1, 2 e 3.
    • TASK_GROUP_NAME: o nome do grupo de tarefas com os detalhes que você quer ver. O valor precisa ser definido como group0.

Exemplos de caminhos de solicitação de 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 do Cloud Life Sciences:

    • Execute um pipeline:

      POST https://lifesciences.googleapis.com/v2beta/projects/PROJECT_ID/locations/LOCATION/pipelines:run
      
    • Veja 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.
    • LOCATION: o local do pipeline.
    • OPERATION_ID: o identificador da operação de longa duração retornado pela solicitação para executar o pipeline.
  • Exemplos de caminhos de solicitação de API em lote:

    • Crie e execute um job:

      POST https://batch.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/jobs?job_id=JOB_NAME
      
    • Visualizar os detalhes de uma tarefa:

      GET https://batch.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/jobs/JOB_NAME
      
    • Veja a lista de tarefas de uma tarefa:

      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.
    • LOCATION: o local do job.
    • JOB_NAME: o nome do job.
    • TASK_GROUP_NAME: o nome do grupo de tarefas com os detalhes que você quer ver. O valor precisa ser definido como group0.
    • OPERATION_ID: o identificador da operação de longa duração retornado pela solicitação para excluir o job.

Permissões e papéis do IAM

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

Na tabela a seguir, descrevemos os papéis predefinidos e as permissões necessárias para os 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 para o Batch.

Papéis 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 jobs 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
Relatório do agente de lote (roles/batch.agentReporter) no projeto
  • batch.states.report

Recursos correspondentes

Na tabela a seguir, descrevemos os recursos do Cloud Life Sciences, os recursos equivalentes para o Batch e os detalhes sobre as diferenças entre eles.

Cada recurso é representado por uma descrição e sua sintaxe JSON. Use a sintaxe JSON ao acessar o Batch por meio da API ou ao especificar um arquivo de configuração JSON pela Google Cloud CLI. No entanto, observe que também é possível usar os recursos do Batch com outros métodos, como campos do console do Google Cloud, sinalizações 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 deles, consulte:

Recursos do Cloud Life Sciences Atributos 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, cada uma executando os mesmos executáveis. Um pipeline do Cloud Life Sciences é semelhante a um job em lote com uma tarefa. No entanto, o Cloud Life Sciences não tem um conceito equivalente para tarefas (jobs com várias), que são parecidas com as repetições de um pipeline.

Para mais informações sobre jobs e tarefas, consulte a 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 lote executável 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 contêiner executável 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:

O Cloud Life Sciences permite especificar as variáveis de ambiente para uma ação formatada como texto simples ou como um dicionário criptografado. No Batch, isso é semelhante a ter o ambiente de um executável (campo environment em runnables[]) que inclui 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:

  • Em vez de especificar variáveis como texto simples ou dicionário criptografado, especifique variáveis usando os secrets do Secret Manager com uma variável secreta (secretVariables).
  • Em vez de especificar uma variável de ambiente para um executável, é possível especificar uma variável de ambiente para todos os executáveis usando o campo environment em taskSpec.
  • Em vez de especificar uma variável de ambiente que tenha o mesmo valor para cada tarefa, especifique 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 de uma solicitação para executar um pipeline (labels no corpo da solicitação). rótulos de um job (labels no recurso do job)

Ao contrário do Cloud Life Sciences, o Batch não inclui um campo de rótulos na solicitação para criar um novo 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 identificadores.

regiões (regions[]) e zonas (zones[]) dos recursos de um pipeline (resources) locais permitidos (allowedLocations) para a política de local de recursos de um job (locationPolicy)

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

No Batch, a opção equivalente são os locais permitidos para um job, que você pode definir como uma ou mais regiões ou zonas e especifica 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, VMs individuais podem estar em zonas diferentes dessa região.

A especificação do campo de locais permitidos para uma vaga é opcional, porque é separada do local da vaga. 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 em lote.

para os recursos de um pipeline (resources):

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

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

No Batch, as mesmas opções para VMs estão disponíveis nos campos da 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, a plataforma de CPU mínima permitida, o disco de inicialização e outros discos anexados, além de todas as GPUs e drivers de GPU.

para uma ação:

de um executável:

Essas diversas sinalizações de conveniência do Cloud Life Sciences são equivalentes em lote, mas são especificadas 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 de processo (PID, na sigla em inglês) (pidNamespace).
  • e uma opção para especificar mapeamentos de portas de contêiner para host (portMappings).
(options) para um contêiner executável

Essas opções do Cloud Life Sciences e outras são aceitas em lote por meio do campo de opções (options) para um contêiner executável. Defina o campo de opções para qualquer sinalização que você quer que o Batch anexe ao comando docker run, por exemplo, -P --pid mynamespace -p 22:22.

para uma ação:

nenhum equivalente

Faz pré-busca de imagens em lote 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) para uma ação opção para bloquear redes externas (blockExternalNetwork) em um contêiner executável

A opção do Cloud Life Sciences para bloquear redes externas para uma ação é semelhante à opção de lote para bloquear redes externas de 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 para as VMs do job e os volumes de armazenamento são acessíveis a todos os executáveis do job (scripts ou contêineres). Essa montagem é feita antes que a VM execute qualquer tarefa ou executável.

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

Para mais informações sobre o uso de volumes de armazenamento com Lote, consulte Criar e executar um job que use volumes de armazenamento.

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

O Batch processa a montagem de todos os volumes de armazenamento que você especifica para um job, como um bucket do Cloud Storage. Como resultado, você não ativa nenhuma ferramenta de montagem, como o Cloud Storage FUSE para Batch. No entanto, também é 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 lote, consulte Criar e executar um job que usa volumes de armazenamento.

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

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

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

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. Nesta seção, resumimos os serviços de fluxo de trabalho que podem ser usados com o Batch. Além dos serviços de fluxo de trabalho listados nesta seção, o Batch também planeja oferecer suporte a mais serviços de fluxo de trabalho ao longo do tempo.

O Batch é compatível com o Workflows, que é um serviço de fluxo de trabalho do Google Cloud. Se você quiser usar Workflows com lotes, consulte Executar um job em lote usando fluxos de trabalho. Caso contrário, a tabela a seguir descreve outros serviços de fluxos de trabalho que podem ser usados no Cloud Life Sciences e que você também pode usar com o Batch. Nesta tabela, listamos as principais diferenças para usar cada serviço de fluxo de trabalho com o Batch em vez do Cloud Life Sciences e detalhamos onde saber mais sobre como usar cada lote de trabalho.

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

Para usar um arquivo de configuração do Nextflow para o Cloud Life Sciences com Batch, faça as seguintes alterações:

  1. No campo executor, substitua google-lifesciences por google-batch.
  2. Para os prefixos config, substitua google.lifeScience por google.batch.
Para saber mais sobre como usar lotes com o Nextflow, consulte um tutorial em lote ou um tutorial do Nextflow Para mais informações sobre as opções de configuração, consulte a documentação do Nextflow (em inglês).
Cromwell

Para usar um arquivo de configuração do Cromwell para a API Cloud Life Sciences v2beta com a API em lote, faça as seguintes alterações:

  1. No 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 lotes com o Cromwell, consulte a documentação do Cromwell sobre lotes e o tutorial do Cromwell para lotes (links em inglês).
dsub

Para usar um pipeline dsub da API Cloud Life Sciences com Batch, faça as seguintes alterações:

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

A seguir

  • Para configurar o Batch para novos usuários e projetos, consulte os Primeiros passos.
  • Para aprender a executar cargas de trabalho usando Batch, consulte Criar um job.