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.

Como 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:

    gerenciar-tráfego

  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 ver a configuração do serviço atual 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
    

    Replace

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

Como implementar gradualmente uma revisão

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 ver a configuração do serviço atual 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 que quiser no serviço, conforme descrito nas várias páginas de configuração, e especifique o nome da revisão que você quer para a nova revisão:

    apiVersion: serving.knative.dev/v1
    kind: Service
    metadata:
     name: SERVICE
    template:
      metadata:
        annotations:
          ...
        name: REVISION-NAME
     ```
    
    Replace
    
    • 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. Replace

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

Como 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 ver a configuração do serviço atual 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. Replace

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

Como 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 ver a configuração do serviço atual 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.

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

Como implantar uma nova revisão com tag

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

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

Substitua:

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

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 Cloud, a linha de comando gcloud 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:

    manage-traffic

  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

Substitua:

  • 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 ver a configuração do serviço atual 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 que você quiser no serviço, conforme descrito nas várias páginas de configuraçã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. Substitua:

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