O Cloud Run permite especificar quais revisões devem receber tráfego e especificar porcentagens de tráfego recebidas por uma revisão. Esse recurso permite reverter para uma revisão anterior, implantar gradualmente uma revisão e dividir 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ê muda o tráfego para revisões, todas as solicitações em processamento 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.
Divisão de tráfego e afinidade de sessã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.
Ciclo de vida das divisões de tráfego
Se você dividir o tráfego entre várias revisões ou atribuir o tráfego a uma revisão anterior, todas as implantações subsequentes vão usar esse padrão de divisão de tráfego. Para voltar a usar apenas a revisão mais recente sem a divisão de tráfego, envie todo o tráfego para a revisão mais recente.
Funções exigidas
Para receber as permissões necessárias para gerenciar serviços e revisões do Cloud Run, peça ao administrador para conceder a você os seguintes papéis do IAM:
- Se você estiver gerenciando um serviço implantado a partir de uma imagem de contêiner:
- Desenvolvedor do Cloud Run
(
roles/run.developer
) no serviço do Cloud Run - Usuário da conta de serviço
(
roles/iam.serviceAccountUser
) na identidade do serviço - Leitor do Artifact Registry
(
roles/artifactregistry.reader
) no repositório do Artifact Registry das imagens do contêiner do serviço (se aplicável)
- Desenvolvedor do Cloud Run
(
- Se você estiver gerenciando um serviço implantado a partir do código-fonte:
- Desenvolvedor de origem do Cloud Run
(
roles/run.sourceDeveloper
) no seu projeto - Usuário da conta de serviço
(
roles/iam.serviceAccountUser
) na identidade do serviço - Além disso, conceda o papel de
construtor do Cloud Run
(
roles/run.builder
) à conta de serviço do Cloud Build no projeto. A conta de serviço de build é responsável por criar seu serviço e é definida como a conta de serviço padrão do Compute Engine.
- Desenvolvedor de origem 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 serviço 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:
No Google Cloud console, acesse o Cloud Run:
Na lista, localize e clique no serviço.
Clique na guia Revisões para mostrar a lista de revisões atuais desse serviço.
Na lista de revisões, clique no ícone de elipse à direita da revisão que você está revertendo:
Clique em Gerenciar tráfego para exibir o formulário de gerenciamento de tráfego:
- Selecione a revisão anterior que você quer reverter na lista suspensa.
- Defina a porcentagem de tráfego da revisão anterior como 100.
- Defina a porcentagem da revisão de processamento atual como 0.
- Clique em Salvar.
Use este comando:
gcloud run services update-trafficSERVICE --to-revisionsREVISION =100
- Substitua SERVICE pelo nome do serviço.
- Substitua REVISION pelo nome da revisão para a qual você está revertendo.
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.yamlAbaixo do atributo
spec
, localize e atualize o atributotraffic
para o seguinte:apiVersion: serving.knative.dev/v1 kind: Service metadata: name: SERVICE spec: ... traffic: - revisionName:
REVISION percent: 100Substituir
- REVISION pelo nome da revisão para a qual você está revertendo.
Substitua o serviço pela nova configuração usando o seguinte comando:
gcloud run services replace service.yaml
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.
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
:
Lançamento gradual para revisões
Para implantar uma nova revisão gradualmente:
No Google Cloud console, acesse o Cloud Run:
Selecione seu serviço na lista.
Clique em Implantar uma revisão nova.
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.
Clique em Implantar.
Clique em Gerenciar tráfego.
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:
- Defina a porcentagem pretendida, por exemplo, 5. Observe que a porcentagem da versão em exibição no momento é reduzida automaticamente na mesma quantidade.
- Clique em Salvar.
- 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.
Para implantar um serviço usando uma imagem de contêiner:
Implante a revisão que você quer implantar gradualmente, inicialmente a definindo para não receber tráfego:
Para implantar um serviço usando o código-fonte:
gcloud run deploy --image
IMAGE --no-trafficSubstitua IMAGE pela imagem que você está implantando.
Para implantar um serviço usando o código-fonte:
gcloud run deploy
SERVICE --source . --no-trafficSERVICE pelo nome do serviço;
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-revisionsREVISION =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.
Depois que o desempenho da revisão for satisfatório, repita a etapa
update-traffic
anterior, mas aumente o valor percentual conforme desejado.
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.yamlFaç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.
Abaixo do atributo
spec
, localize e atualize o atributotraffic
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.
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.
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.
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:
No Google Cloud console, acesse o Cloud Run:
Localize o serviço na lista e clique nele.
Clique em Gerenciar tráfego.
A nova revisão em exibição no momento é listada. No formulário, siga estas etapas:
- Defina a porcentagem de revisão em exibição no momento para a divisão pretendida.
- Selecione uma das revisões anteriores usando a lista suspensa e defina-a como a porcentagem pretendida.
- 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.
- Clique em Salvar.
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-trafficSERVICE --to-revisionsLIST
- 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
.
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.yamlAbaixo do atributo
spec
, localize e atualize o atributotraffic
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.
Substitua o serviço pela nova configuração usando o seguinte comando:
gcloud run services replace service.yaml
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.
Adicione a instrução a seguir ao seu arquivo .tf
:
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:
No Google Cloud console, acesse o Cloud Run:
Na lista, localize e clique no serviço.
Clique em Implantar uma revisão nova.
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.
Clique em Implantar.
Para enviar todo o tráfego para a revisão implantada mais recentemente:
gcloud run services update-trafficSERVICE --to-latest
Substitua SERVICE pelo nome do serviço.
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.yamlAbaixo do atributo
spec
, localize e atualize o atributotraffic
para o seguinte:apiVersion: serving.knative.dev/v1 kind: Service metadata: name: SERVICE spec: ... traffic: - latestRevision: true percent: 100
Substitua o serviço pela nova configuração usando o seguinte comando:
gcloud run services replace service.yaml
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.
Adicione a instrução a seguir ao seu arquivo .tf
:
Para aplicar as mudanças, insira terraform apply
.
Usar tags para teste, migração de tráfego e reversões
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:
- Executar testes de integração em um contêiner durante o desenvolvimento.
- Implante o contêiner em um projeto Google Cloud que você usa apenas para preparo, sem tráfego e teste em uma revisão marcada com tag.
- Implantá-lo na produção, sem exibir tráfego, e testar em uma revisão marcada com tag na produção.
- 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:
Para implantar uma nova revisão com tag de uma imagem de contêiner:
gcloud run deploy myservice --image
IMAGE_URL --no-traffic --tagTAG_NAME Substitua:
- IMAGE_URL pelo URL da imagem.
- TAG_NAME com o nome da tag em letras minúsculas.
Para implantar um serviço usando o código-fonte:
gcloud run deploy myservice --source . --no-traffic --tag
TAG_NAME Substitua 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
.
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.
Para aplicar as mudanças, insira terraform apply
.
Remover uma tag
Para remover uma tag de uma revisão:
No Google Cloud console, acesse o Cloud Run:
Selecione seu serviço na lista.
Navegue até a seção Revisões no serviço desejado e selecione a revisão com a tag que você quer remover.
Mantenha o cursor sobre a coluna URLs de revisão (tags) e clique no ícone de lápis:
No menu de diálogo URLs de revisão, clique no ícone da lata de lixo para remover a tag atual usada na revisão.
Clique em Salvar.
Para remover uma tag de revisão:
gcloud run services update-trafficSERVICE --remove-tagsTAG_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.
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.yamlFaça as alterações de configuração desejadas no serviço.
Abaixo do atributo
spec
, localize e remova o atributotag
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 Substitua o serviço pela nova configuração usando o seguinte comando:
gcloud run services replace service.yaml
Adicione a instrução a seguir ao seu arquivo .tf
:
Para aplicar as mudanças, insira terraform apply
.
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:
No Google Cloud console, acesse o Cloud Run:
Localize o serviço na lista e clique nele:
Selecione a revisão marcada com tag que receberá o tráfego:
Clique em Gerenciar tráfego.
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*:
- Defina a porcentagem pretendida, por exemplo, 5. Observe que a porcentagem da versão em exibição no momento é reduzida automaticamente na mesma quantidade.
- Clique em Salvar.
- 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.
Para migrar o tráfego para uma tag de revisão específica:
gcloud run services update-traffic myservice --to-tagsTAG_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
.
Se você estiver criando um novo serviço, pule esta etapa. Se você estiver atualizando um serviço existente, faça o download da configuração YAML correspondente:
gcloud run services describe
SERVICE --format export > service.yamlFaça as mudanças de configuração escolhidas no serviço.
Abaixo do atributo
spec
, localize e atualize o atributotraffic
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.
Substitua o serviço pela nova configuração usando o seguinte comando:
gcloud run services replace service.yaml
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.
Adicione a instrução a seguir ao seu arquivo .tf
:
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.