Divisões de instâncias e rollbacks para pools de workers do Cloud Run

Os pools de workers processam cargas de trabalho sem solicitação. Para casos de uso que precisam dividir o trabalho entre várias revisões, como a implantação de uma nova revisão, os pools de workers usam divisão de instâncias.

O Cloud Run permite especificar quais revisões recebem instâncias e porcentagens de alocação de instâncias para cada revisão. Com esse recurso, é possível reverter para uma revisão anterior, dividir instâncias entre várias revisões e alocar instâncias para a revisão mais recente. Esta página descreve como usar esse recurso para gerenciar a alocação de instâncias nas revisões do Cloud Run.

Os ajustes na alocação de instâncias não são instantâneos. Quando você muda a alocação de instâncias para revisões, todas as solicitações em processamento continuam até a conclusão. As solicitações em andamento não são descartadas, e o Cloud Run pode direcionar essas solicitações para uma revisão nova ou anterior durante o período de transição.

Ciclo de vida das divisões de instâncias

Se você dividir instâncias entre várias revisões ou atribuir instâncias a uma revisão anterior, todos os implantes subsequentes usarão esse padrão de divisão de instâncias daí em diante. Para voltar a usar apenas a revisão mais recente sem divisão de instâncias, envie todas as instâncias para a revisão mais recente.

Funções exigidas

Para ter as permissões necessárias para gerenciar pools de trabalhadores e revisões de pool de trabalhadores do Cloud Run, peça ao administrador para conceder a você o papel do IAM de Desenvolvedor do Cloud Run (roles/run.developer) no pool de trabalhadores do Cloud Run.

Para uma lista de papéis e permissões do IAM associados ao Cloud Run, consulte Papéis do IAM do Cloud Run e Permissões do IAM do Cloud Run. Se o pool de trabalhadores do Cloud Run interagir com APIsGoogle Cloud , como as bibliotecas de cliente do Cloud, consulte o guia de configuração de identidade de serviço. Para mais informações sobre como conceder papéis, consulte permissões de implantação e gerenciar acesso.

Reverter para uma revisão anterior

Para reverter para uma revisão anterior, use o console Google Cloud ou a Google Cloud CLI:

Console

  1. No console do Google Cloud , acesse os pools de trabalhadores do Cloud Run:

    Acessar o Cloud Run

  2. Localize o pool de worker na lista e clique nele.

  3. Clique na guia Revisões para mostrar a lista de revisões atuais desse pool de trabalhadores.

  4. Clique em Gerenciar divisões de instâncias para mostrar o formulário de gerenciamento de instâncias. O Cloud Run lista a revisão de exibição mais recente. No formulário, configure os seguintes detalhes:

    1. Adicionar revisão e use a lista suspensa para selecionar uma revisão anterior.
    2. Defina a porcentagem de instâncias da revisão anterior como 100.
    3. Defina a porcentagem da revisão de exibição mais recente como 0.
    4. Clique em Salvar.

gcloud

Especifique as revisões para as quais fazer o rollback executando o seguinte comando.

   gcloud run worker-pools update-instance-split WORKER_POOL --to-revisions=REVISION=100

Substitua:

  • WORKER_POOL: o nome do pool de workers.
  • REVISION: o nome da revisão para a qual você está revertendo.

YAML

  1. Se você estiver criando um novo pool de workers, pule esta etapa. Se você estiver atualizando um pool de trabalhadores, faça o download da configuração YAML correspondente:

    gcloud run worker-pools describe WORKER_POOL --format export > workerpool.yaml

  2. O exemplo a seguir contém a configuração YAML:

    apiVersion: run.googleapis.com/v1
kind: WorkerPool
metadata:
  name: WORKER_POOL
  labels:
    cloud.googleapis.com/location: REGION
spec:
  template:
    spec:
      containers:
      - image: IMAGE_URL
  instanceSplits:
  - revisionName: REVISION
    percent: 100

    Substitua:

    • WORKER_POOL: o nome do pool de workers.
    • REGION: a região Google Cloud , por exemplo, us-central1.
    • IMAGE_URL: uma referência à imagem de contêiner que contém o pool de workers, como us-docker.pkg.dev/cloudrun/container/worker-pool:latest
    • REVISION: o nome da revisão para a qual você está revertendo.

  3. Crie ou atualize o pool de workers usando o seguinte comando:

    gcloud run worker-pools replace workerpool.yaml

Terraform

Para saber como aplicar ou remover uma configuração do Terraform, consulte Comandos básicos do Terraform.

import {
  id = "projects/PROJECT_ID/locations/REGION/workerPools/WORKER_POOL"
  to = google_cloud_run_v2_worker_pool.default
}

resource "google_cloud_run_v2_worker_pool" "default" {
  name     = "WORKER_POOL"
  location = "REGION"

  template {
    containers {
      image = "IMAGE_URL"
    }
  }

  instance_splits {
    type     = "INSTANCE_SPLIT_ALLOCATION_TYPE_REVISION"
    revision = "REVISION"
    percent  = 100
  }
}

Substitua:

  • PROJECT_ID: o ID do seu projeto do Google Cloud .
  • REGION: a região Google Cloud , por exemplo, us-central1.
  • WORKER_POOL: o nome do pool de workers.
  • IMAGE_URL: uma referência à imagem de contêiner que contém o pool de workers, como us-docker.pkg.dev/cloudrun/container/worker-pool:latest
  • REVISION: o nome da revisão para a qual você está revertendo.

Dividir instâncias entre várias revisões

Para dividir instâncias entre duas ou mais revisões, use o console Google Cloud ou a Google Cloud CLI:

Ao dividir instâncias entre várias revisões, verifique se a porcentagem total em todas as revisões é igual a 100% e se o número de instâncias manuais é maior que o número de divisões de instâncias que atendem à carga de trabalho.

Console

  1. No console do Google Cloud , acesse os pools de trabalhadores do Cloud Run:

    Acessar o Cloud Run

  2. Localize o pool de worker na lista e clique nele.

  3. Clique na guia Revisões para mostrar a lista de revisões atuais desse pool de worker.

  4. Clique em Gerenciar divisões de instâncias para mostrar o formulário de gerenciamento de instâncias. O Cloud Run lista a revisão de exibição mais recente. No formulário, configure os seguintes detalhes:

    1. Defina a porcentagem da revisão mais recente para a divisão necessária. Por exemplo, reduza de 100%.

    2. Clique em Adicionar revisão e use a lista suspensa para selecionar uma revisão anterior e definir a porcentagem correspondente.

    3. Para dividir instâncias com mais revisões, clique em Adicionar revisão, selecione outra revisão e defina a porcentagem dela.

    4. Clique em Salvar.

gcloud

Especifique as revisões e a porcentagem de instâncias executando o seguinte comando. Alocar instâncias para cada revisão em uma lista delimitada por vírgulas:

   gcloud run worker-pools update-instance-split WORKER_POOL --to-revisions=LIST

Substitua:

  • WORKER_POOL: o nome do pool de workers.

  • LIST: lista delimitada por vírgulas de revisões e porcentagens:

    REVISION1=PERCENTAGE1,REVISION2=PERCENTAGE2,REVISIONn=PERCENTAGEx.

    Por exemplo, my-worker-pool-s5sxn=10,my-worker-pool-cp9kw=90

YAML

  1. Se você estiver criando um novo pool de workers, pule esta etapa. Se você estiver atualizando um pool de trabalhadores, faça o download da configuração YAML correspondente:

    gcloud run worker-pools describe WORKER_POOL --format export > workerpool.yaml

  2. O exemplo a seguir contém a configuração YAML:

    apiVersion: run.googleapis.com/v1
kind: WorkerPool
metadata:
  name: WORKER_POOL
  labels:
    cloud.googleapis.com/location: REGION
  annotations:
    run.googleapis.com/scalingMode: manual
spec:
  template:
    spec:
      containers:
      - image: IMAGE_URL
  instanceSplits:
  - revisionName: REVISION1
    percent: PERCENTAGE1
  - revisionName: REVISION2
    percent: PERCENTAGE2

    Substitua:

    • WORKER_POOL: o nome do pool de workers.
    • REGION: a região Google Cloud , por exemplo, us-central1.
    • INSTANCE_COUNT: o número de instâncias.
    • IMAGE_URL: uma referência à imagem de contêiner que contém o pool de workers, como us-docker.pkg.dev/cloudrun/container/worker-pool:latest
    • REVISION1 e REVISION2: o nome das revisões.
    • PERCENTAGE1 e PERCENTAGE2: a porcentagem de instâncias a serem alocadas para cada uma dessas revisões. Esses valores precisam totalizar 100.

  3. Crie ou atualize o pool de workers usando o seguinte comando:

    gcloud run worker-pools replace workerpool.yaml

Terraform

Para saber como aplicar ou remover uma configuração do Terraform, consulte Comandos básicos do Terraform.

import {
  id = "projects/PROJECT_ID/locations/REGION/workerPools/WORKER_POOL"
  to = google_cloud_run_v2_worker_pool.default
}

resource "google_cloud_run_v2_worker_pool" "default" {
  name     = "WORKER_POOL"
  location = "REGION"

  template {
    containers {
      image = "IMAGE_URL"
    }
  }

  instance_splits {
    type     = "INSTANCE_SPLIT_ALLOCATION_TYPE_REVISION"
    revision = "REVISION1"
    percent  = PERCENTAGE1
  }
  instance_splits {
    type     = "INSTANCE_SPLIT_ALLOCATION_TYPE_REVISION"
    revision = "REVISION2"
    percent  = PERCENTAGE2
  }
}

Substitua:

  • PROJECT_ID: o ID do seu projeto do Google Cloud .
  • REGION: a região Google Cloud , por exemplo, us-central1.
  • WORKER_POOL: o nome do pool de workers.
  • IMAGE_URL: uma referência à imagem de contêiner que contém o pool de workers, como us-docker.pkg.dev/cloudrun/container/worker-pool:latest
  • REVISION1 e REVISION2: o nome das revisões.
  • PERCENTAGE1 e PERCENTAGE2: a porcentagem de instâncias a serem alocadas para cada uma dessas revisões. Esses valores precisam totalizar 100.

Alocar instâncias para a revisão mais recente

Ao implantar uma nova revisão, é possível alocar 100% das instâncias para essa revisão e todas as futuras, modificando qualquer divisão de instâncias estabelecida.

gcloud

Para alocar 100% das instâncias para a revisão mais recente, execute os seguintes comandos:

  • Use a flag --to-latest para direcionar 100% das instâncias à revisão mais recente e alocar automaticamente todas as instâncias a qualquer nova revisão implantada:

    gcloud run worker-pools update-instance-split WORKER_POOL --to-latest

  • Se quiser, use a flag --to-revisions com a palavra-chave LATEST para sempre alocar uma porcentagem flutuante de instâncias para a revisão mais recente ao implantar uma. Para definir uma porcentagem de instâncias que sempre flutuam para a revisão mais recente, execute o seguinte comando:

    gcloud run worker-pools update-instance-split WORKER_POOL --to-revisions=LATEST=PERCENTAGE

    Substitua:

    • WORKER_POOL: o nome do pool de workers.
    • PERCENTAGE: a porcentagem de instâncias a serem alocadas para as revisões mais recentes e futuras.

YAML

  1. Se você estiver criando um novo pool de workers, pule esta etapa. Se você estiver atualizando um pool de trabalhadores, faça o download da configuração YAML correspondente:

    gcloud run worker-pools describe WORKER_POOL --format export > workerpool.yaml

  2. O exemplo a seguir contém a configuração YAML:

    apiVersion: run.googleapis.com/v1
kind: WorkerPool
metadata:
  name: WORKER_POOL
  labels:
    cloud.googleapis.com/location: REGION
spec:
  template:
    spec:
      containers:
      - image: IMAGE_URL
  instanceSplits:
  - latestRevision: true
    percent: 100

    Substitua:

    • WORKER_POOL: o nome do pool de workers.
    • REGION: a região Google Cloud , por exemplo, us-central1.
    • IMAGE_URL: uma referência à imagem de contêiner que contém o pool de workers, como us-docker.pkg.dev/cloudrun/container/worker-pool:latest

  3. Crie ou atualize o pool de workers usando o seguinte comando:

    gcloud run worker-pools replace workerpool.yaml

Terraform

Para saber como aplicar ou remover uma configuração do Terraform, consulte Comandos básicos do Terraform.

resource "google_cloud_run_v2_worker_pool" "default" {
  name     = "WORKER_POOL"
  location = "REGION"

  template {
    containers {
      image = "IMAGE_URL"
    }
  }

  instance_splits {
    type = "INSTANCE_SPLIT_ALLOCATION_TYPE_LATEST"
    percent  = 100
  }
}

Substitua:

  • WORKER_POOL: o nome do pool de workers.
  • REGION: a região Google Cloud , por exemplo, us-central1.
  • IMAGE_URL: uma referência à imagem de contêiner que contém o pool de workers, como us-docker.pkg.dev/cloudrun/container/worker-pool:latest

A seguir