Usar uma estratégia de implantação canário

Neste documento, descrevemos como configurar e usar uma estratégia de implantação canário.

O que é uma implantação canário?

Uma implantação canário é um lançamento progressivo de um aplicativo que divide o tráfego entre uma versão já implantada e uma nova versão, lançando-a para um subconjunto de usuários antes do lançamento completo.

Tipos de segmentação compatíveis

A implantação canário no Cloud Deploy é compatível com todos os tipos de destino, incluindo:

O Canary também funciona com vários destinos.

Por que usar uma estratégia de implantação canário?

Com uma implantação canário, você tem a chance de liberar parcialmente o aplicativo. Dessa forma, você pode garantir que a nova versão do aplicativo seja confiável antes de enviá-la a todos os usuários.

Se você estiver implantando no GKE ou no GKE Enterprise, por exemplo, você implantará a nova versão do aplicativo em um número limitado de pods. A versão antiga continuaria em execução, mas com mais tráfego sendo enviado para os novos pods.

Se você estiver implantando no Cloud Run, o Cloud Run dividirá o tráfego entre as revisões antigas e novas, de acordo com as porcentagens configuradas.

Tipos de canário

O Cloud Deploy permite configurar os seguintes tipos de implantação canário:

  • Automatizado

    Com uma implantação canário automatizada, você configura o Cloud Deploy com uma série de porcentagens que expressam uma implantação progressiva. O Cloud Deploy executa operações adicionais em seu nome para dividir porcentagens de tráfego entre as versões antiga e nova.

  • Personalizado (automatizado)

    Para um canário automatizado personalizado, forneça o seguinte:

    • O nome da fase
    • A porcentagem da meta
    • O perfil do Skaffold a ser usado para a fase
    • Incluir ou não uma vaga de verificação

    Você não precisa fornecer informações sobre balanceamento de tráfego, já que o Cloud Deploy cria os recursos necessários, conforme descrito aqui.

  • Personalizado

    Com um canário personalizado, você configura cada fase canário separadamente, incluindo o seguinte:

    • O nome da fase
    • A porcentagem da meta
    • O perfil do Skaffold a ser usado para a fase
    • Incluir ou não uma vaga de verificação

    Além disso, para um canário totalmente personalizado, forneça toda a configuração de balanceamento de tráfego, conforme descrito aqui.

Fases de uma implantação canário

Quando você cria uma versão para uma implantação canário, o lançamento é criado com uma fase para cada incremento canário, além de uma fase stable final para 100%.

Por exemplo, se você configurar um canário para incrementos de 25%, 50% e 75%, o lançamento terá as seguintes fases:

  • canary-25
  • canary-50
  • canary-75
  • stable

Leia mais sobre fases de lançamento, jobs e execuções de jobs em Gerenciar implantações.

O que acontece durante um teste canário automatizado ou personalizado

Para dar suporte à implantação canário, o Cloud Deploy inclui etapas de processamento especiais ao renderizar o manifesto do Kubernetes ou a configuração do serviço do Cloud Run:

GKE/GKE Enterprise (rede)

Confira como o Cloud Deploy executa uma implantação canário no GKE baseado em rede e no GKE Enterprise:

  1. Forneça o nome dos recursos de implantação e de serviço.

  2. O Cloud Deploy cria um recurso de implantação adicional, com o nome da sua implantação atual mais -canary.

  3. O Cloud Deploy modifica o serviço para ajustar o seletor e selecionar os pods na implantação atual e nos pods canário.

    O Cloud Deploy calcula o número de pods a serem usados para o canário com base no cálculo descrito aqui. Esse cálculo varia dependendo da ativação ou desativação do superprovisionamento de pods.

    Se estivermos pulando para a fase stable, o Cloud Deploy adicionará os rótulos a serem usados para corresponder aos pods. Assim, eles estarão disponíveis para as próximas execuções canário.

    O Cloud Deploy cria uma implantação que inclui a porcentagem de pods específica da fase, atualizando-a para cada fase. Isso é feito calculando o número de pods como uma porcentagem do número original de pods. Isso pode resultar em uma divisão de tráfego imprecisa. Se você precisar de uma divisão de tráfego exata, faça isso usando a API Gateway.

    Além disso, Secrets e ConfigMaps também são copiados e renomeados com -canary.

  4. Durante a fase stable, a implantação -canary é reduzida para zero e a implantação original é substituída pela nova implantação.

    O Cloud Deploy não modifica a implantação original até a fase stable.

O Cloud Deploy provisiona pods para atingir a porcentagem canário solicitada o mais próximo possível. Isso é baseado no número de pods, não no tráfego para eles. Se você quiser que o canário seja baseado no tráfego, será necessário usar a API Gateway.

Para o canário baseado em rede do GKE, é possível ativar ou desativar o superprovisionamento de pods. Nas seções a seguir, descrevemos como o Cloud Deploy calcula o número de pods a serem provisionados para a implantação canário em cada fase desse tipo.

Provisionamento de pod com o superprovisionamento ativado

Ativar o superprovisionamento (disablePodOverprovisioning: false) permite que o Cloud Deploy crie pods adicionais suficientes para executar a porcentagem de canário que você quiser, com base no número de pods que executam sua implantação atual. A fórmula a seguir mostra como o Cloud Deploy calcula o número de pods a serem provisionados para a implantação canário em cada fase canário, quando o superprovisionamento de pods está ativado:

math.Ceil( percentage * ReplicaCountOfDeploymentOnCluster / (100-percentage))

Com essa fórmula, a contagem de réplicas atual (o número de pods que você já tem, antes deste canário) é multiplicada pela porcentagem de canários da fase, e o resultado é dividido por (100 menos a porcentagem).

Por exemplo, se você tiver quatro pods alead e a fase canário for 50%, o número de pods canário será 4. O resultado de 100-percentage é usado como uma porcentagem: 100-50=50, tratado como .50.

O superprovisionamento de pods é o comportamento padrão.

Provisionamento de pod com o superprovisionamento desativado

É possível desativar o superprovisionamento (disablePodOverprovisioning: true) para garantir que o Cloud Deploy não aumente a contagem de réplicas.

A fórmula a seguir mostra como o Cloud Deploy calcula o provisionamento de pods para a implantação canário em cada fase canário, quando o superprovisionamento de pods está desativado:

math.Ceil( (ReplicaCountOfDeploymentOnCluster + ReplicaCountOfCanaryDeploymentOnCluster) * percentage)

Nessa fórmula, ReplicaCountOfCanaryDeploymentOnCluster só existirá se já houvesse uma fase canário. Se essa for a primeira fase canário, não haverá ReplicaCountOfCanaryDeploymentOnCluster.

Se você começar com quatro pods, esse número será multiplicado pela porcentagem dos canários (por exemplo, 50% ou .5) para conseguir 2. Portanto, a implantação original agora é reduzida para dois, e dois novos pods são criados para a implantação canário. Se você tiver um estágio canário de 75%, terá 2 (implantação original) +2 (primeiro estágio canário), *.75, para receber 3 pods canário e 1 pod executando a implantação original.

GKE/GKE Enterprise (gateway)

Veja como o Cloud Deploy executa uma implantação canário no GKE e no GKE Enterprise usando a API Gateway:

  1. Além das referências de implantação e serviço, você fornece um recurso HTTPRoute, com uma regra backendRefs que faz referência ao serviço.

  2. O Cloud Deploy cria uma nova implantação, com o nome da sua implantação original, mais -canary, e um novo serviço com o nome do serviço original mais -canary.

    Além disso, Secrets, ConfigMaps e escalonadores automáticos horizontais de pods também são copiados e renomeados com -canary.

  3. Para cada fase canário, o Cloud Deploy modifica o HTTPRoute para atualizar a ponderação entre os pods da implantação original e os da implantação canário, com base na porcentagem dessa fase.

    Como pode haver um atraso na propagação de alterações para recursos HTTPRoute, inclua a propriedade routeUpdateWaitTime em sua configuração. Assim, o sistema aguarda um período especificado para essa propagação.

  4. Durante a fase stable, a implantação -canary é reduzida a zero, e a implantação original é atualizada para usar a implantação da nova versão.

    Além disso, o HTTPRoute agora é revertido para o original que você forneceu.

    O Cloud Deploy não modifica a implantação ou o serviço original até a fase stable.

Cloud Run

Veja como o Cloud Deploy executa uma implantação canário para o Cloud Run:

  • Para uma implantação canário no Cloud Run, não forneça uma estrofe traffic no YAML de serviço.

  • Ao criar um novo lançamento para a versão canário, o Cloud Deploy divide o tráfego entre a revisão anterior que foi implantada com sucesso pelo Cloud Deploy e uma nova revisão.

Se você quiser ver as diferenças entre as fases de uma implantação canário, confira as alterações no manifesto renderizado por fase disponível no Inspetor de versão. É possível fazer isso antes mesmo do início do lançamento. Além disso, se você estiver usando a implantação paralela, também vai ser possível inspecionar o manifesto renderizado de cada filho.

Configurar uma implantação canário

Nesta seção, descrevemos como configurar o pipeline de entrega e os destinos para uma implantação canário.

As instruções aqui incluem apenas o que é específico para a configuração canário. O documento Implantar seu aplicativo tem as instruções gerais para configurar e executar o pipeline de implantação.

Verifique se você tem as permissões necessárias

Além das outras permissões do Identity and Access Management necessárias para usar o Cloud Deploy, você precisa das seguintes permissões para executar outras ações que podem ser necessárias para uma implantação canário:

  • clouddeploy.rollouts.advance
  • clouddeploy.rollouts.ignoreJob
  • clouddeploy.rollouts.cancel
  • clouddeploy.rollouts.retryJob
  • clouddeploy.jobRuns.get
  • clouddeploy.jobRuns.list
  • clouddeploy.jobRuns.terminate

Consulte Papéis e permissões do IAM para mais informações sobre quais papéis disponíveis incluem essas permissões.

Prepare seu dispositivo skaffold.yaml

Assim como em uma implantação padrão, seu canário precisa de um arquivo skaffold.yaml, que define como os manifestos e as definições de serviço são renderizados e implantados.

O skaffold.yaml criado para uma implantação canário não tem nenhum requisito especial além do que é necessário para a implantação padrão.

Preparar o manifesto ou a definição do serviço

Assim como em uma implantação padrão, o canário precisa de um manifesto do Kubernetes ou de uma definição de serviço do Cloud Run.

GKE e GKE Enterprise

Para o canário, seu manifesto precisa ter o seguinte:

  • Uma implantação e um serviço.

  • O serviço precisa definir um seletor app e selecionar os pods da implantação especificada.

  • Se você estiver usando um canário baseado na API Gateway, o manifesto também precisará ter um HTTPRoute.

Cloud Run

Para a versão canário no Cloud Run, o arquivo normal de definição do serviço do Cloud Run é suficiente, mas sem uma estrofe traffic. O Cloud Deploy gerencia a divisão do tráfego entre a última revisão bem-sucedida e a nova.

Configurar um canário automatizado

As instruções a seguir são para destinos de rede com base em serviço do Cloud Run e GKE e GKE Enterprise. Se você estiver usando a API Kubernetes Gateway com o GKE ou o GKE Enterprise, consulte esta documentação.

Você configura o canário automatizado na definição do pipeline de entrega:

GKE e GKE Enterprise

No estágio do pipeline, inclua uma propriedade strategy da seguinte maneira:

serialPipeline:
  stages:
  - targetId: prod
    profiles: []
    strategy:
      canary:
        runtimeConfig:
          kubernetes:
            serviceNetworking:
              service: "SERVICE_NAME"
              deployment: "DEPLOYMENT_NAME"
        canaryDeployment:
          percentages: [PERCENTAGES]
          verify: true|false

Nesta configuração...

  • SERVICE_NAME é o nome do serviço do Kubernetes, definido no manifesto.

  • DEPLOYMENT_NAME é o nome da implantação do Kubernetes, definida no manifesto.

  • PERCENTAGES é uma lista separada por vírgulas de valores percentuais que representam os incrementos canário, por exemplo, [5, 25, 50].

    O canário automatizado oferece suporte a porcentagens de até 50, mas não mais que isso. Se você precisar de uma fase canário com uma porcentagem maior que 50%, use a API Gateway ou use um canário personalizado.

    Além disso, isso não inclui 100, porque 100% da implantação é considerada na versão canário e é processada pela fase stable.

  • É possível ativar a verificação de implantação (verify: true). Se você fizer isso, um job verify será ativado em cada fase.

Cloud Run

No estágio do pipeline, inclua uma propriedade strategy da seguinte maneira:

serialPipeline:
  stages:
  - targetId: prod
    profiles: []
    strategy:
      canary:
        runtimeConfig:
          cloudRun:
            automaticTrafficControl: true
        canaryDeployment:
          percentages: [PERCENTAGES]
          verify: true|false

Nesta configuração...

  • PERCENTAGES é uma lista separada por vírgulas de valores percentuais que representam os incrementos canário, por exemplo, [25, 50, 75]. Isso não inclui 100, porque 100% da implantação é considerada no canário e é processada pela fase stable.
  • É possível ativar a verificação de implantação (verify: true). Nesse caso, um job verify é adicionado a cada fase canário.

Configurar um canário personalizado

É possível configurar o canário manualmente em vez de depender totalmente da automação fornecida pelo Cloud Deploy. Com a configuração canário personalizada, você especifica o seguinte na definição do pipeline de entrega:

  • Nomes das fases de lançamento

    Em um canário totalmente automatizado, o Cloud Deploy nomeia as fases para você (canary-25, canary-75, stable, por exemplo). No entanto, com um canário personalizado, você pode dar qualquer nome a cada fase, desde que ele seja único entre todas as fases desse estágio e que respeite as restrições de nome de recurso. Mas o nome da fase final (100%) precisa ser stable.

  • Metas percentuais para cada fase

    Especifique os percentuais separadamente, por fase.

  • Perfis do Skaffold a serem usados para a fase

    É possível usar um perfil do Skaffold separado para cada fase, o mesmo perfil ou qualquer combinação. E cada perfil pode usar um manifesto diferente do Kubernetes ou uma definição de serviço do Cloud Run. Você também pode usar mais de um perfil em uma determinada fase. O Cloud Deploy as combina.

  • Se há um trabalho de verificação para a fase

    Se você estiver ativando a verificação, também será necessário configure skaffold.yaml para verificação.

Todos os tipos de destino são compatíveis com a versão canário personalizada.

Elementos personalizados de configuração canário

O YAML a seguir mostra a configuração das fases da implantação canário totalmente personalizada:

strategy:
  canary:
    # Custom configuration for each canary phase
    ​customCanaryDeployment:
      phaseConfigs:
      - phaseId: "PHASE1_NAME"
        percentage: PERCENTAGE1
        profiles: [ "PROFILE_NAME" ]
        verify: true | false
      - …
      - phaseId: "stable"
        percentage: 100
        profiles: [ "LAST_PROFILE_NAME" ]
        verify: true|false

Neste YAML

  • PHASE1_NAME

    É o nome da fase. Cada nome de fase precisa ser único.

  • [ "PROFILE_NAME" ]

    É o nome do perfil a ser usado para a fase. É possível usar o mesmo perfil para cada fase, um diferente para cada uma ou qualquer combinação. Além disso, é possível especificar mais de um perfil. O Cloud Deploy usa todos os perfis que você especificar, além do perfil ou manifesto usado pelo cenário geral.

  • PERCENTAGE1

    É a porcentagem a ser implantada para a primeira fase. Cada fase precisa ter um valor de porcentagem exclusivo, que é uma porcentagem inteira (não 10.5, por exemplo), e as fases precisam estar em ordem crescente.

  • verify: true|false

    Informa ao Cloud Deploy se precisa incluir um job de verificação para a fase. Observe que, para cada fase, o Skaffold usa o mesmo perfil especificado para renderização e implantação para essa fase.

  • stable

    A fase final precisa ser nomeada como stable.

A porcentagem da última fase precisa ser 100. As fases são executadas de acordo na ordem que você as configurou nesta estrofe ​customCanaryDeployment, mas se os valores percentuais não estiverem em ordem crescente, o comando para registrar o pipeline de entrega falhará com um erro.

Observe que a configuração de um canário personalizado não inclui uma estrofe runtimeConfig. Se você incluir runtimeConfig, ele será considerado um canário automatizado personalizado.

Configurar um canário automatizado e personalizado

Um canário automatizado personalizado é semelhante a um canário personalizado porque você especifica as fases separadas, com nomes de fase personalizados, valores percentuais e perfis do Skaffold, além de jobs de verificação. No entanto, com um canário personalizado, você não fornece as configurações que definem a distribuição de tráfego. O Cloud Deploy faz isso por você, mas você ainda fornece os perfis do Skaffold a serem usados para cada etapa.

Para configurar um canário automatizado personalizado, inclua uma estrofe runtimeConfig, conforme mostrado aqui, e inclua a estrofe customCanaryDeployment, conforme mostrado aqui.

Configurar uma implantação canário usando a malha de serviço da API Kubernetes Gateway

É possível usar uma implantação canário do Cloud Deploy para implantar seu aplicativo em uma rede baseada em serviços do Kubernetes, mas uma alternativa é usar a malha de serviço da API Gateway do Kubernetes. Veja nesta seção como fazer isso.

É possível usar a API Gateway com o Istio ou qualquer implementação compatível.

  1. Configure os recursos da API Gateway:

    Estes são apenas exemplos.

  2. No manifesto do Kubernetes, fornecido ao Cloud Deploy quando você criou a versão, inclua o seguinte:

    • Um HTTPRoute que faça referência ao recurso de gateway

    • Uma implantação

    • Um serviço

  3. Configure o pipeline de entrega e o destino em que a implantação canário será feita:

    • A configuração para o destino é a mesma para qualquer destino.

    • A configuração do pipeline de entrega, na sequência de progressão do destino específico, inclui uma estrofe gatewayServiceMesh para fazer referência à configuração HTTPRoute da API Kubernetes Gateway, bem como à implantação e ao serviço.

      strategy:
 canary:
   runtimeConfig:
     kubernetes:
       gatewayServiceMesh:
         httpRoute: "ROUTE"
         service: "SERVICE"
         deployment: "DEPLOYMENT"
         routeUpdateWaitTime: "WAIT_TIME"
   canaryDeployment:
     percentages:
     - 50

      Em que…

      • ROUTE é a configuração do httpRoute que define o comportamento de roteamento que você quer.

      • SERVICE é a configuração de serviço exigida pelo Cloud Deploy para implantações canário no GKE e no GKE Enterprise.

      • DEPLOYMENT é a configuração de implantação, que o Cloud Deploy exige para implantações canário no GKE e no GKE Enterprise.

      • WAIT_TIME é um período de tempo para o Cloud Deploy aguardar as alterações no recurso HTTPRoute para concluir a propagação, para evitar solicitações descartadas. Por exemplo: routeUpdateWaitTime: 60s.

        Se você estiver executando o Canary usando a API Gateway sem o Istio e a API Gateway estiver conectada a um balanceador de carga do Google Cloud, uma pequena quantidade de tráfego poderá ser perdida quando a instância do Canary for reduzida. Se você observar esse comportamento, defina essa configuração.

Usar a implantação paralela com uma estratégia de implantação canário

É possível executar uma implantação canário usando a implantação paralela. Isso significa que o destino que você está implantando progressivamente pode incluir dois ou mais destinos filhos. Por exemplo, é possível implantar progressivamente em clusters em regiões separadas, ao mesmo tempo.

Como um canário paralelo é diferente dos canários de destino único

  • Assim como na implantação canário de destino único, se você estiver implantando em destinos do GKE, precisará de uma configuração de implantação do Kubernetes e uma configuração de serviço do Kubernetes no manifesto.

  • Assim como na implantação canário de destino único, a configuração do pipeline de entrega precisa incluir uma estrofe strategy.canary dentro da definição do estágio aplicável.

  • Além disso, é necessário configurar um destino múltiplo e configurar os destinos filhos aos quais vários destinos fazem referência.

  • Ao criar uma versão, são gerados um lançamento do controlador e um lançamento filho.

    Os dois tipos de lançamento (controlador e filho) têm fases separadas para todas as porcentagens de canário configuradas e uma fase stable para os 100% canário.

  • Não é possível avançar um lançamento filho.

    Só é possível avançar os lançamentos do controlador. Quando você avança o lançamento do controlador para o próximo estágio, os lançamentos filhos também são avançados pelo Cloud Deploy.

  • Não é possível tentar novamente jobs com falha no lançamento do controlador.

    Só é possível repetir um job em lançamentos filhos.

  • Não é possível ignore jobs com falha no lançamento do controlador.

    Só é possível ignorar jobs com falha em lançamentos filhos.

  • É possível cancelar um lançamento de controlador, mas não é possível cancelar lançamentos filhos.

  • É possível encerrar execuções de jobs somente em um lançamento filho, não em uma implementação de controlador.

O que fazer se um lançamento paralelo falhar na versão canário

Quando um lançamento filho falha, o lançamento do controlador pode fazer a transição para estados diferentes, dependendo do que acontece com os lançamentos filhos:

  • Se um ou mais lançamentos filhos falharem, mas pelo menos um lançamento filho ainda for IN_PROGRESS, o lançamento do controlador permanecerá IN_PROGRESS.

  • Se um ou mais lançamentos filhos falhar, mas pelo menos um lançamento filho for bem-sucedido, o lançamento do controlador será HALTED se houver mais fases após a atual.

    Se esta for a fase stable, o lançamento do controlador será FAILED.

    HALTED oferece a chance de ignore, tentar novamente os jobs com falha no lançamento filho com falha ou cancelar o lançamento do controlador e impedir outras ações nos lançamentos filhos.

  • Se o lançamento do controlador estiver em um estado HALTED devido a uma falha no lançamento filho e você ignorar o job com falha no lançamento filho, o lançamento do controlador será revertido para um estado IN_PROGRESS.

Executar o canário configurado

Para executar a implantação canário:

  1. Registrar o pipeline de entrega e os destinos configurados.

    gcloud deploy apply --file=PIPELINE

    O pipeline de entrega inclui a configuração canário automatizada ou personalizada para o ambiente de execução escolhido.

    Esse comando presume que os destinos estejam definidos no mesmo arquivo ou já tenham sido registrados. Caso contrário, registre também seus destinos.

  2. Criar uma versão:

    gcloud deploy releases create RELEASE_NAME \
                              --delivery-pipeline=PIPELINE_NAME \
                              --region=REGION

    O pipeline de entrega identificado por PIPELINE_NAME contém a configuração canário automatizada ou personalizada descrita neste documento.

  3. Avance o canário:

    CLI da gcloud 

    gcloud deploy rollouts advance ROLLOUT_NAME \
                            --release=RELEASE_NAME \
                            --delivery-pipeline=PIPELINE_NAME \
                            --region=REGION

    Em que:

    ROLLOUT_NAME é o nome do lançamento atual que você está avançando para a próxima fase.

    RELEASE_NAME é o nome da versão da qual o lançamento faz parte.

    PIPELINE_NAME é o nome do pipeline de entrega usado para gerenciar a implantação dessa versão.

    REGION é o nome da região em que a versão foi criada, por exemplo, us-central1. Obrigatório.

    Consulte a referência do SDK Google Cloud para mais informações sobre o comando gcloud deploy rollouts advance.

    Console do Google Cloud

    1. Abra a página "Pipelines de entrega".

    2. Clique no pipeline mostrado na lista de pipelines de entrega.

      A página de detalhes do pipeline de entrega mostra uma representação gráfica do progresso do pipeline de entrega.

    3. Na guia Lançamentos, em Detalhes do pipeline de entrega, clique no nome do seu lançamento.

      A página de detalhes desse lançamento será exibida.

      detalhes do lançamento no console do Google Cloud

      Observe que, neste exemplo, o lançamento tem uma fase canary-50 e uma stable. O lançamento pode ter mais fases ou fases diferentes.

    4. Clique em Lançamento avançado.

      O lançamento é avançado para a próxima fase.

Fases ignoradas

Se você implantar um canário e o aplicativo ainda não tiver sido implantado nesse ambiente de execução, o Cloud Deploy ignorará a fase de canário e executará a fase estável. Consulte Como ignorar fases na primeira vez para descobrir por que isso acontece.

A seguir