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

O Cloud Run permite especificar quais revisões receberão tráfego, além de 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 conferir detalhes sobre o efeito da afinidade de sessão na divisão de tráfego.

Funções exigidas

Para ter as permissões necessárias para gerenciar os serviços e as revisões do Cloud Run, peça ao administrador para conceder a você os seguintes papéis do IAM:

• Desenvolvedor do Cloud Run (roles/run.developer) no serviço do Cloud Run
• Usuário da conta de serviço (roles/iam.serviceAccountUser) na conta de serviço

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 serviço do Cloud Run interage com as APIs do Google 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:

Console

1. No console do Google Cloud, acesse o Cloud Run:

   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.

gcloud

Use este comando:

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

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

   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:

resource "google_cloud_run_v2_service" "default" {
  name     = "my-service"
  location = "us-central1"

  deletion_protection = false # set to true to prevent destruction of the resource

  template {}

  traffic {
    percent = 100
    # This revision needs to already exist
    revision = "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. No console do Google Cloud, acesse o Cloud Run:

   Acessar o Cloud Run

2. Selecione seu serviço na lista.

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.

gcloud

Observação: se você estiver implantando uma função ao executar gcloud run deploy, é preciso usar gcloud beta run deploy, especifique as flags necessárias e tenha os papéis necessários concedidas a você.

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

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

   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
   spec:
    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.

resource "google_cloud_run_v2_service" "default" {
  name     = "my-service"
  location = "us-central1"

  deletion_protection = false # set to true to prevent destruction of the resource

  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 = "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. No console do Google Cloud, acesse o Cloud Run:

   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.

gcloud

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

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

   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:

resource "google_cloud_run_v2_service" "default" {
  name     = "my-service"
  location = "us-central1"

  deletion_protection = false # set to true to prevent destruction of the resource

  template {
    containers {
      image = "us-docker.pkg.dev/cloudrun/container/hello"
    }
    revision = "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 = "green"
    type     = "TRAFFIC_TARGET_ALLOCATION_TYPE_REVISION"
  }

  traffic {
    percent = 75
    # This revision needs to already exist
    revision = "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. No console do Google Cloud, acesse o Cloud Run:

   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.

gcloud

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

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

   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:

resource "google_cloud_run_v2_service" "default" {
  name     = "my-service"
  location = "us-central1"

  deletion_protection = false # set to true to prevent destruction of the resource

  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

Importante: se você tiver um número mínimo de instâncias configuradas no nível de serviço, as tags de tráfego não alocarão instâncias mínimas para revisões com tags. Se você tiver um número mínimo de instâncias configuradas no nível de revisão, as tags de tráfego vão alocar instâncias mínimas para revisões com tags.

Para evitar custos de faturamento para revisões com tags, use instâncias mínimas de nível de serviço ou remova tags em revisões quando não precisar mais delas.

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 atual em produção:

gcloud

Observação: se você estiver implantando uma função ao executar gcloud run deploy, use gcloud beta run deploy, especifique as flags necessárias e tenha as funções necessárias concedidas a você.

Implantar uma nova revisão com tag:

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.

resource "google_cloud_run_v2_service" "default" {
  name     = "my-service"
  location = "us-central1"

  deletion_protection = false # set to "true" in production

  template {
    containers {
      # image or tag must be different from previous revision
      image = "us-docker.pkg.dev/cloudrun/container/hello"
    }
    revision = "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 = "green"
    type     = "TRAFFIC_TARGET_ALLOCATION_TYPE_REVISION"
  }

  traffic {
    # Deploy new revision with 0% traffic
    percent  = 0
    revision = "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. No console do Google Cloud, acesse o Cloud Run:

   Acessar o Cloud Run

2. Selecione seu serviço na lista.

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 Salvar.

gcloud

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

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

   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

Terraform

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

resource "google_cloud_run_v2_service" "default" {
  name     = "my-service"
  location = "us-central1"

  deletion_protection = false # set to true to prevent destruction of the resource

  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 = "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 = "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. No console do Google Cloud, acesse o Cloud Run:

   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.

gcloud

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

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

   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:

resource "google_cloud_run_v2_service" "default" {
  name     = "my-service"
  location = "us-central1"

  deletion_protection = false # set to true to prevent destruction of the resource

  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 = "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 implantação no Cloud Run..