Reversões, implementações graduais e migração de tráfego

O Cloud Run permite especificar quais revisões receberão tráfego e especificar porcentagens de tráfego recebidas por uma revisão. Esse recurso permite que você faça reversão para uma revisão anterior, distribua gradualmente uma revisão e divida o tráfego entre várias revisões. Nesta página, descrevemos como usar esse recurso para gerenciar o tráfego das suas revisões do Cloud Run.

Os ajustes de roteamento de tráfego não são instantâneos. Quando você altera o tráfego para revisões, todas as solicitações em processamento atualmente continuam sendo concluídas. As solicitações em andamento não serão descartadas e poderão ser direcionadas para uma nova revisão ou uma revisão anterior durante o período de transição.

Se você estiver dividindo o tráfego entre várias revisões com a afinidade de sessão ativada, consulte Afinidade da sessão e divisão de tráfego para ver detalhes sobre o efeito da afinidade de sessão na divisão de tráfego.

Reverter para uma revisão anterior

Para reverter para uma revisão anterior:

Console

1. Acessar o Cloud Run

2. Na lista, localize e clique no serviço.

3. Clique na guia Revisões para mostrar a lista de revisões atuais desse serviço.

4. Na lista de revisões, clique no ícone de elipse à direita da revisão que você está revertendo:

   

5. Clique em Gerenciar tráfego para exibir o formulário de gerenciamento de tráfego:

   1. Selecione a revisão anterior que você quer reverter na lista suspensa.
   2. Defina a porcentagem de tráfego da revisão anterior como 100.
   3. Defina a porcentagem da revisão de processamento atual como 0.
   4. Clique em Salvar.

Linha de comando

Use o comando a seguir:

gcloud run services update-traffic SERVICE --to-revisions REVISION=100

• Substitua SERVICE pelo nome do serviço.
• Substitua REVISION pelo nome da revisão para a qual você está revertendo.

YAML

É possível fazer o download e conferir as configurações de serviço usando o comando gcloud run services describe --format export, que produz resultados limpos no formato YAML. Em seguida, modifique os campos descritos abaixo e faça upload do YAML modificado usando o comando gcloud run services replace. Modifique os campos somente conforme documentado.

1. Para visualizar e fazer o download da configuração:

   gcloud run services describe SERVICE --format export > service.yaml

2. Abaixo do atributo spec, localize e atualize o atributo traffic para o seguinte:

   apiVersion: serving.knative.dev/v1
   kind: Service
   metadata:
    name: SERVICE
   spec:
   ...
     traffic:
     - revisionName: REVISION
       percent: 100
   

   Substituir

   • REVISION pelo nome da revisão para a qual você está revertendo.

3. Substitua o serviço pela nova configuração usando o seguinte comando:

   gcloud run services replace service.yaml

4. Aguarde a conclusão da atualização. Você verá uma mensagem informando que a revisão da qual você está revertendo foi implantada e está exibindo 0% do tráfego.

Terraform

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

Adicione a instrução a seguir ao seu arquivo .tf:

run/traffic_rollback/main.tf

Acessar no GitHub Feedback

resource "google_cloud_run_v2_service" "default" {
  name     = "cloudrun-srv"
  location = "us-central1"

  template {}

  traffic {
    percent = 100
    # This revision needs to already exist
    revision = "cloudrun-srv-green"
    type     = "TRAFFIC_TARGET_ALLOCATION_TYPE_REVISION"

  }
}

Observação: se a revisão não existir, você receberá o erro: Error creating Service: googleapi: Error 400: spec.template.spec: Revision template was empty.

Lançamento gradual para revisões

Para implantar uma nova revisão gradualmente:

Console

1. Acessar o Cloud Run

2. Na lista, localize e clique no serviço.

3. Clique em Implantar uma revisão nova.

4. Preencha o formulário de implantação conforme necessário, mas verifique se a caixa de seleção Veicular esta revisão imediatamente está DESMARCADA.

5. Clique em Implantar.

6. Clique em Gerenciar tráfego.

7. A nova revisão está listada, mas com uma porcentagem 0 definida: ela não está veiculando tráfego no momento. No formulário, siga estas etapas:

   1. Defina a porcentagem pretendida, por exemplo, 5. Observe que a porcentagem da versão em exibição no momento é reduzida automaticamente na mesma quantidade.
   2. Clique em Salvar.
   3. Repita essas etapas Gerenciar tráfego, mas com porcentagens alteradas, aumentando a porcentagem conforme necessário para a nova revisão. Você não precisa reimplantar para alterar as porcentagens de tráfego.

Linha de comando

1. Implante a revisão que você quer implantar gradualmente, inicialmente a definindo para não receber tráfego:

   gcloud run deploy --image IMAGE --no-traffic

   Substitua IMAGE pela imagem que você está implantando.

2. Especifique a porcentagem de tráfego que você quer que a nova revisão processe, por exemplo, 5%:

   gcloud run services update-traffic SERVICE --to-revisions REVISION=PERCENTAGE

   • Substitua SERVICE pelo nome do serviço.
   • Substitua REVISION pelo nome da revisão que você está implementando gradualmente. Para especificar a revisão mais recente, use LATEST, por exemplo, LATEST=5.
   • Substitua PERCENTAGE pela porcentagem de tráfego que você quer enviar para a nova revisão, por exemplo, 5 para enviar 5% do tráfego.

3. Depois que o desempenho da revisão for satisfatório, repita a etapa update-traffic anterior, mas aumente o valor percentual conforme desejado.

YAML

É possível fazer o download e conferir as configurações de serviço usando o comando gcloud run services describe --format export, que produz resultados limpos no formato YAML. Em seguida, modifique os campos descritos abaixo e faça upload do YAML modificado usando o comando gcloud run services replace. Modifique os campos somente conforme documentado.

1. Para ver e fazer o download da configuração:

   gcloud run services describe SERVICE --format export > service.yaml

2. Faça as alterações de configuração desejadas no serviço e especifique o nome da nova revisão que você quer:

   apiVersion: serving.knative.dev/v1
   kind: Service
   metadata:
    name: SERVICE
   template:
     metadata:
       annotations:
         ...
       name: REVISION-NAME
   

   Substituir

   • REVISION-NAME pelo nome que você quer para a nova revisão.

3. Abaixo do atributo spec, localize e atualize o atributo traffic para que a nova revisão exiba apenas uma pequena quantidade de tráfego:

   apiVersion: serving.knative.dev/v1
   kind: Service
   metadata:
    name: SERVICE
   spec:
   ...
     traffic:
     - revisionName: REVISION-NEW
       percent: PERCENT-NEW
     - revisionName: REVISION-FORMER
       percent: PERCENT-FORMER
   

   As porcentagens precisam totalizar até 100. Substituir

   • REVISION-NEW pelo nome da revisão que você está lançando gradualmente.
   • REVISION-FORMER pelo nome da revisão que está sendo exibida no momento.
   • PERCENT-NEW pela porcentagem de tráfego que você quer enviar para a nova revisão. Por exemplo, use 10 para enviar 10% do tráfego para essa revisão.
   • PERCENT-FORMER pela porcentagem de tráfego que você quer enviar para a revisão antiga.

4. Aguarde a conclusão da atualização. Você verá uma mensagem informando que a nova revisão que está sendo lançada gradualmente foi implantada e está exibindo o valor de porcentagem de tráfego usado.

Terraform

Adicione o seguinte ao seu arquivo .tf e atualize gradualmente a porcentagem de tráfego da revisão anterior para a revisão mais recente. Lembre-se de que cada mudança de tráfego exigirá outra terraform apply para ser executada.

run/traffic_gradual_rollout/main.tf

Acessar no GitHub Feedback

resource "google_cloud_run_v2_service" "default" {
  name     = "cloudrun-srv"
  location = "us-central1"

  template {
    containers {
      # Image or image tag must be different from previous revision
      image = "us-docker.pkg.dev/cloudrun/container/hello"
    }
  }

  # Define the traffic split for each revision
  # https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/cloud_run_v2_service#traffic
  traffic {
    percent = 100
    # This revision needs to already exist
    revision = "cloudrun-srv-green"
    type     = "TRAFFIC_TARGET_ALLOCATION_TYPE_REVISION"
  }

  traffic {
    # Deploy new revision with 0% traffic
    percent = 0
    type    = "TRAFFIC_TARGET_ALLOCATION_TYPE_LATEST"
  }
}

Para aplicar as mudanças, insira terraform apply.

Dividir o tráfego entre várias revisões

Para dividir o tráfego entre duas ou mais revisões:

Console

1. Acessar o Cloud Run

2. Na lista, localize e clique no serviço.

3. Clique em Gerenciar tráfego.

4. A nova revisão em exibição no momento é listada. No formulário, siga estas etapas:

   1. Defina a porcentagem de revisão em exibição no momento para a divisão pretendida.
   2. Selecione uma das revisões anteriores usando a lista suspensa e defina-a como a porcentagem pretendida.
   3. Para dividir o tráfego entre mais revisões, clique em Adicionar revisão, selecione a revisão pretendida e defina a porcentagem para a divisão pretendida.
   4. Clique em Salvar.

Linha de comando

Especifique as revisões e a porcentagem de tráfego de cada revisão em uma lista delimitada por vírgulas:

gcloud run services update-traffic SERVICE --to-revisions LIST

• Substitua SERVICE pelo nome do serviço.
• Substitua LIST por uma lista delimitada por vírgulas de revisões e porcentagens:
  REVISION1=PERCENTAGE1, REVISION2=PERCENTAGE2, REVISIONn=PERCENTAGEx
  , por exemplo, hello2-00005-red=25,hello2-00001-bod=25,hello2-00002-nan=50.

YAML

É possível fazer o download e conferir as configurações de serviço usando o comando gcloud run services describe --format export, que produz resultados limpos no formato YAML. Em seguida, modifique os campos descritos abaixo e faça upload do YAML modificado usando o comando gcloud run services replace. Modifique os campos somente conforme documentado.

1. Para visualizar e fazer o download da configuração:

   gcloud run services describe SERVICE --format export > service.yaml

2. Abaixo do atributo spec, localize e atualize o atributo traffic para que a nova revisão exiba apenas uma pequena quantidade de tráfego:

   apiVersion: serving.knative.dev/v1
   kind: Service
   metadata:
    name: SERVICE
   spec:
   ...
     traffic:
     - revisionName: REVISION-A
       percent: PERCENT-A
     - revisionName: REVISION-B
       percent: PERCENT-B
     - revisionName: REVISION-C
       percent: PERCENT-C
   

   As porcentagens precisam totalizar até 100. Substituir

   • REVISION-A, REVISION-B e REVISION-C pelas revisões para as quais você está alocando tráfego.
   • PERCENT-A, PERCENT-B, PERCENT-C pela porcentagem da revisão correspondente.

3. Substitua o serviço pela nova configuração usando o seguinte comando:

   gcloud run services replace service.yaml

4. Aguarde a conclusão da atualização. Você verá uma mensagem informando que a nova revisão que está sendo lançada gradualmente foi implantada e está exibindo 5% (ou o valor gradual usado) do tráfego.

Terraform

Adicione a instrução a seguir ao seu arquivo .tf:

run/traffic_split/main.tf

Acessar no GitHub Feedback

resource "google_cloud_run_v2_service" "default" {
  name     = "cloudrun-srv"
  location = "us-central1"

  template {
    containers {
      image = "us-docker.pkg.dev/cloudrun/container/hello"
    }
    revision = "cloudrun-srv-green"
  }

  # Define the traffic split for each revision
  # https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/cloud_run_v2_service#traffic
  traffic {
    percent  = 25
    revision = "cloudrun-srv-green"
    type     = "TRAFFIC_TARGET_ALLOCATION_TYPE_REVISION"
  }

  traffic {
    percent = 75
    # This revision needs to already exist
    revision = "cloudrun-srv-blue"
    type     = "TRAFFIC_TARGET_ALLOCATION_TYPE_REVISION"
  }
}

Para aplicar as mudanças, insira terraform apply.

Enviar todo o tráfego para a revisão mais recente

Ao implantar uma nova revisão, é possível fazer essa revisão e todas as futuras processarem todo o tráfego o mais rápido possível, modificando qualquer divisão de tráfego estabelecida:

Console

1. Acessar o Cloud Run

2. Na lista, localize e clique no serviço.

3. Clique em Implantar uma revisão nova.

4. Preencha o formulário de implantação conforme necessário, marcando a caixa de seleção Veicular esta revisão imediatamente. Isso substituirá qualquer divisão de tráfego existente, com a nova revisão veiculando todo o tráfego.

5. Clique em Implantar.

Linha de comando

Para enviar todo o tráfego para a revisão implantada mais recentemente:

gcloud run services update-traffic SERVICE --to-latest

Substitua SERVICE pelo nome do serviço.

YAML

É possível fazer o download e conferir as configurações de serviço usando o comando gcloud run services describe --format export, que produz resultados limpos no formato YAML. Em seguida, modifique os campos descritos abaixo e faça upload do YAML modificado usando o comando gcloud run services replace. Modifique os campos somente conforme documentado.

1. Para visualizar e fazer o download da configuração:

   gcloud run services describe SERVICE --format export > service.yaml

2. Abaixo do atributo spec, localize e atualize o atributo traffic para o seguinte:

   apiVersion: serving.knative.dev/v1
   kind: Service
   metadata:
    name: SERVICE
   spec:
   ...
     traffic:
     - latestRevision: true
       percent: 100
   

3. Substitua o serviço pela nova configuração usando o seguinte comando:

   gcloud run services replace service.yaml

4. Aguarde a conclusão da atualização. Você verá uma mensagem informando que a revisão (mais recente) foi implantada e está exibindo 100% do tráfego.

Terraform

Adicione a instrução a seguir ao seu arquivo .tf:

run/traffic_latest_revision/main.tf

Acessar no GitHub Feedback

resource "google_cloud_run_v2_service" "default" {
  name     = "cloudrun-srv"
  location = "us-central1"

  template {}

  traffic {
    percent = 100
    type    = "TRAFFIC_TARGET_ALLOCATION_TYPE_LATEST"
  }
}

Para aplicar as mudanças, insira terraform apply.

Usar tags para teste, migração de tráfego e reversões

Depois de implantar um serviço, é possível criar uma nova revisão e atribuir uma tag que permita acessar a revisão em um URL específico sem veicular o tráfego. Em seguida, use essa tag para migrar gradualmente o tráfego para a revisão marcada com a tag e para reverter uma revisão com tags.

Um caso de uso comum desse recurso é usá-lo para testar e verificar uma nova revisão de serviço antes de disponibilizar qualquer tráfego, nesta sequência típica:

1. Executar testes de integração em um contêiner durante o desenvolvimento.
2. Implantar o contêiner em um projeto do Google Cloud que você usa apenas para preparo, sem tráfego e testar em uma revisão marcada com tag.
3. Implantá-lo na produção, sem exibir tráfego, e testar em uma revisão marcada com tag na produção.
4. Migrar o tráfego para a revisão marcada.

Implantar uma nova revisão com tag

Para implantar uma nova revisão de um serviço em produção:

Linha de comando

gcloud run deploy myservice --image IMAGE_URL  --no-traffic --tag TAG_NAME

Substituir

• IMAGE_URL pelo URL da imagem;
• TAG_NAME pelo nome da tag em letras minúsculas.

A tag permite testar diretamente a nova revisão em um URL específico, sem veicular o tráfego. O URL começa com o nome da tag fornecido. Por exemplo, se você usou o nome de tag green no serviço myservice, teste a revisão marcada com tag no URL https://green---myservice-abcdef.a.run.app.

Terraform

Adicione o seguinte ao seu arquivo .tf e atualize gradualmente a porcentagem de tráfego da revisão antiga para a mais recente com a nova tag. Lembre-se de que cada mudança de tráfego exigirá outra terraform apply para ser executada.

run/deploy_tag/main.tf

Acessar no GitHub Feedback

resource "google_cloud_run_v2_service" "default" {
  name     = "cloudrun-srv"
  location = "us-central1"

  template {
    containers {
      # image or tag must be different from previous revision
      image = "us-docker.pkg.dev/cloudrun/container/hello"
    }
    revision = "cloudrun-srv-blue"
  }

  # Define the traffic split for each revision
  # https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/cloud_run_v2_service#traffic
  traffic {
    percent = 100
    # This revision needs to already exist
    revision = "cloudrun-srv-green"
    type     = "TRAFFIC_TARGET_ALLOCATION_TYPE_REVISION"
  }

  traffic {
    # Deploy new revision with 0% traffic
    percent  = 0
    revision = "cloudrun-srv-blue"
    tag      = "tag-name"
    type     = "TRAFFIC_TARGET_ALLOCATION_TYPE_REVISION"
  }
}

Para aplicar as mudanças, insira terraform apply.

Remover uma tag

Para remover uma tag de uma revisão:

Console

1. Acessar o Cloud Run

2. Na lista, localize e clique no serviço.

3. Navegue até a seção Revisões no serviço desejado e selecione a revisão com a tag que você quer remover.

4. Passe o cursor sobre a coluna URLs de revisão (tags) e clique no ícone do lápis, como mostrado abaixo.

   

5. No menu pop-up URLs de revisão, clique no ícone da lata de lixo para remover a tag atual usada na revisão.

6. Clique em Save.

Linha de comando

Para remover uma tag de revisão:

gcloud run services update-traffic SERVICE --remove-tags TAG_NAME

Substituir

• TAG_NAME pelo nome da tag para onde você está migrando o tráfego;
• SERVICE pelo nome do serviço do qual você está removendo a tag.

YAML

É possível fazer o download e conferir as configurações de serviço usando o comando gcloud run services describe --format export, que produz resultados limpos no formato YAML. Em seguida, modifique os campos descritos abaixo e faça upload do YAML modificado usando o comando gcloud run services replace. Modifique os campos somente conforme documentado.

1. Para ver e fazer o download da configuração:

   gcloud run services describe SERVICE --format export > service.yaml

2. Faça as alterações de configuração desejadas no serviço.

3. Abaixo do atributo spec, localize e remova o atributo tag da revisão com tag:

   apiVersion: serving.knative.dev/v1
   kind: Service
   metadata:
    name: SERVICE
   spec:
   ...
     traffic:
     - revisionName: REVISION
       tag: TAG_NAME
       percent: PERCENT-NEW
   

4. Substitua o serviço pela nova configuração usando o seguinte comando:

   gcloud run services replace service.yaml

5. Aguarde a conclusão da atualização. Você verá uma mensagem informando que a nova revisão que está sendo lançada gradualmente foi implantada e está exibindo o valor de porcentagem de tráfego usado.

Terraform

Adicione a instrução a seguir ao seu arquivo .tf:

run/remove_tag/main.tf

Acessar no GitHub Feedback

resource "google_cloud_run_v2_service" "default" {
  name     = "cloudrun-srv"
  location = "us-central1"

  template {}

  # Define the traffic split for each revision
  # https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/cloud_run_v2_service#traffic
  traffic {
    percent = 100
    # This revision needs to already exist
    revision = "cloudrun-srv-green"
    type     = "TRAFFIC_TARGET_ALLOCATION_TYPE_REVISION"
  }

  traffic {
    # No tags for this revision
    # Keep revision at 0% traffic
    percent = 0
    # This revision needs to already exist
    revision = "cloudrun-srv-blue"
    type     = "TRAFFIC_TARGET_ALLOCATION_TYPE_REVISION"
  }
}

Para aplicar as mudanças, insira terraform apply.

Observação: se a revisão não existir, você receberá o erro: Error creating Service: googleapi: Error 400: spec.template.spec: Revision template was empty.

Como migrar tráfego para uma revisão com tags

Depois de confirmar que a nova revisão funciona corretamente, é possível começar a migrar o tráfego para ela usando o Console do Google Cloud, a linha de comando gcloud, o Terraform ou um arquivo YAML:

Console

1. Acessar o Cloud Run

2. Na lista, localize e clique no serviço.

3. Selecione a revisão marcada com tag que receberá o tráfego:

   

4. Clique em Gerenciar tráfego.

5. Localize o nome da revisão marcada com tag: ele está listado, mas com uma porcentagem definida em zero. No momento, ela não está veiculando tráfego. No formulário Gerenciar tráfego*:

   1. Defina a porcentagem pretendida. Por exemplo, 5. Observe que a porcentagem da versão em exibição no momento é reduzida automaticamente na mesma quantidade.
   2. Clique em Salvar.
   3. Durante um período de horas ou dias, conforme necessário, repita essas etapas em Gerenciar tráfego, mas com porcentagens alteradas, aumentando a porcentagem conforme necessário para a revisão marcada. Você não precisa reimplantar para alterar as porcentagens de tráfego.

Linha de comando

Para migrar o tráfego para uma tag de revisão específica:

gcloud run services update-traffic myservice --to-tags TAG_NAME=TRAFFIC_PERCENT

Substituir

• TAG_NAME pelo nome da tag para onde você está migrando o tráfego;
• TRAFFIC_PERCENT pela porcentagem de tráfego que você quer que a revisão marcada com tag veicule, por exemplo, 1.

YAML

É possível fazer o download e conferir as configurações de serviço usando o comando gcloud run services describe --format export, que produz resultados limpos no formato YAML. Em seguida, modifique os campos descritos abaixo e faça upload do YAML modificado usando o comando gcloud run services replace. Modifique os campos somente conforme documentado.

1. Para ver e fazer o download da configuração:

   gcloud run services describe SERVICE --format export > service.yaml

2. Faça as alterações de configuração desejadas no serviço.

3. Abaixo do atributo spec, localize e atualize o atributo traffic para a revisão marcada com tag para que a revisão veicule apenas uma pequena quantidade de tráfego:

   apiVersion: serving.knative.dev/v1
   kind: Service
   metadata:
    name: SERVICE
   spec:
   ...
     traffic:
     - revisionName: REVISION
       tag: TAG_NAME
       percent: PERCENT-NEW
     - revisionName: REVISION-FORMER
       percent: PERCENT-FORMER
   

   As porcentagens precisam totalizar até 100. Substituir

   • REVISION pelo nome da revisão marcada com tag.
   • TAG_NAME pelo nome da tag que você está lançando gradualmente.
   • PERCENT-NEW pela porcentagem de tráfego que você quer enviar para a revisão marcada com tag. Por exemplo, use 10 para enviar 10% do tráfego a essa revisão.
   • REVISION-FORMER pelo nome da revisão que está sendo exibida no momento.
   • PERCENT-FORMER pela porcentagem de tráfego que você quer enviar para a revisão antiga.

4. Substitua o serviço pela nova configuração usando o seguinte comando:

   gcloud run services replace service.yaml

5. Aguarde a conclusão da atualização. Você verá uma mensagem informando que a nova revisão que está sendo lançada gradualmente foi implantada e está exibindo o valor de porcentagem de tráfego usado.

Terraform

Adicione a instrução a seguir ao seu arquivo .tf:

run/traffic_split_tag/main.tf

Acessar no GitHub Feedback

resource "google_cloud_run_v2_service" "default" {
  name     = "cloudrun-srv"
  location = "us-central1"

  template {}

  # Define the traffic split for each revision
  # https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/cloud_run_v2_service#traffic
  traffic {
    # Update revision to 50% traffic
    percent = 50
    # This revision needs to already exist
    revision = "cloudrun-srv-green"
    type     = "TRAFFIC_TARGET_ALLOCATION_TYPE_REVISION"
  }

  traffic {
    # Update tag to 50% traffic
    percent = 50
    # This tag needs to already exist
    tag = "tag-name"
  }
}

Durante um período de horas ou dias, conforme necessário, atualize gradualmente uma tag para outra, aumentando a porcentagem necessária para a revisão marcada.

Faça a aplicação inserindo terraform apply depois de cada mudança.

Observação: se a revisão não existir, você receberá o erro: Error creating Service: googleapi: Error 400: spec.template.spec: Revision template was empty.

A seguir

• Saiba como usar o Cloud Deploy para configurar um pipeline de entrega contínua para implantar no Cloud Run.