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, implementando-o em um subconjunto de usuários antes do lançamento completo.

Tipos de segmentação compatíveis

A implantação canário no Cloud Deploy oferece suporte a todos os tipos de destino, incluindo os seguintes:

O canário também funciona com destinos múltiplos.

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

Uma implantação canário oferece a chance de lançar parcialmente seu aplicativo. Dessa forma, você pode garantir que a nova versão do aplicativo seja confiável antes de entregá-lo a todos os usuários.

Se você estiver implantando no GKE ou no GKE Enterprise, por exemplo, implante 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 aos novos pods.

Se você estiver implantando no Cloud Run, o próprio Cloud Run dividirá o tráfego entre a revisão antiga e a nova, 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 realiza mais operações em seu nome para distribuir porcentagens de tráfego entre a versão antiga e a nova.

  • Personalizado e automatizado

    Para um canário automatizado de modo personalizado, é possível fornecer o seguinte:

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

    No entanto, não é necessário fornecer informações de balanceamento de tráfego. 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 nome da fase
    • A meta de porcentagem
    • O perfil do Skaffold a ser usado para a fase
    • Incluir ou não um job de verificação

    Além disso, para um canário totalmente personalizado, você fornece 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 lançamentos.

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

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

Gateway GKE/Enterprise

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

  1. Você fornece o nome dos recursos de implantação e de serviço.

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

  3. O Cloud Deploy modifica o serviço para ajustar o seletor para 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 será diferente dependendo se você ativar ou desativar o provisionamento excessivo de pods.

    Se pular 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, use 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 a 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 se baseia no número de pods, não no tráfego para os pods. Se você quiser que o canário seja baseado no tráfego, use a API Gateway.

Para o canário com base em rede do GKE, é possível ativar ou desativar o provisionamento excessivo de pods. As seções a seguir descrevem como o Cloud Deploy calcula o número de pods a serem provisionados para a implantação canário em cada fase canário.

Provisionamento de pods com superprovisionamento ativado

A ativação do superprovisionamento (disablePodOverprovisioning: false) permite que o Cloud Deploy crie pods extras suficientes para executar a porcentagem canário que você quer, 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 provisionamento excessivo de pods está ativado:

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

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

Por exemplo, se você tiver 4 pods e a fase canário for 50%, então 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 pods com 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)

Nesta fórmula, ReplicaCountOfCanaryDeploymentOnCluster só existe se já havia uma fase canário. Se esta for a primeira fase canário, não haverá ReplicaCountOfCanaryDeploymentOnCluster.

Se você começar com quatro pods, esse número será multiplicado pela porcentagem de canários (por exemplo, 50% ou .5) para chegar a 2. Portanto, a implantação original é 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 ter os pods canário 3 e o pod 1 que executa a implantação original.

Gateway GKE/Enterprise

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 implantação original mais -canary e um novo serviço com o nome original de serviço 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 pods da implantação canário, com base na porcentagem dessa fase.

    Como pode haver um atraso na propagação de mudanças nos recursos HTTPRoute, inclua a propriedade routeUpdateWaitTime na configuração para que o sistema aguarde um período especificado pela 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 foi 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 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, consulte as alterações no manifesto renderizado por fase, disponível no Inspetor de versões. É possível fazer isso antes do início do lançamento. Além disso, se você estiver usando implantação paralela, também vai poder inspecionar cada manifesto renderizado 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 o 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 de outras permissões do Identity and Access Management necessárias para usar o Cloud Deploy, as permissões a seguir são necessárias 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 skaffold.yaml

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

O skaffold.yaml criado para uma implantação canário não tem requisitos especiais 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 canário, o 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 canário no Cloud Run, seu arquivo normal de definição de 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 o Cloud Run, o GKE e o GKE Enterprise para destinos de rede baseados em serviços. Se você estiver usando a API Kubernetes Gateway com o GKE ou o GKE Enterprise, consulte esta documentação.

Configure 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, definido no manifesto.

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

    Além disso, isso não inclui 100, porque a implantação de 100% por cento é suposta no 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 de porcentagem que representam os incrementos canário, por exemplo [25, 50, 75]. Observe que isso não inclui 100, porque a implantação de 100% por cento é suposta no 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á adicionado a cada fase canário.

Configurar um canário personalizado

É possível configurar o canário manualmente, em vez de confiar totalmente na 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, é possível dar a cada fase qualquer nome, desde que ele seja único entre todas as fases desse estágio canário e respeite as restrições de nome de recurso. No entanto, o nome da fase final (100%) precisa ser stable.

  • Metas percentuais para cada fase

    Especifique as porcentagens 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. Cada perfil pode usar um manifesto 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 combina esses recursos.

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

    Lembre-se de que, se você ativar a verificação, também vai precisar configure o skaffold.yaml para verificação.

Todos os tipos de destino são compatíveis com canários personalizados.

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. O nome de cada 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, você pode especificar mais de um perfil. O Cloud Deploy usa todos os perfis especificados, além do perfil ou manifesto usado pelo estágio geral.

  • PERCENTAGE1

    É a porcentagem de implantação para a primeira fase. Cada fase precisa ter um valor de porcentagem exclusivo, que precisa ser 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 em que a verificação é usada, o Skaffold usa o mesmo perfil para verificar que está especificado para renderização e implantação nessa 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 em que você as configura nesta estrofe de ​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 personalizado

Um canário personalizado e automatizado é semelhante a um canário personalizado porque você especifica as fases de canário separadas, com nomes de fase personalizados, valores percentuais, perfis do Skaffold e 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 para você, mas você ainda fornece os perfis do Skaffold a serem usados para cada estágio.

Para configurar um canário automatizado personalizado, inclua uma estrofe runtimeConfig, conforme mostrado aqui, e inclua a estrofe customCanaryDeployment, como mostrado aqui (link em inglês).

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 redes baseadas em serviços do Kubernetes, mas uma alternativa é usar a malha de serviço da API Gateway do Kubernetes. Esta seção descreve 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:

    Esses 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 faz 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 de httpRoute que define o comportamento de roteamento desejado.

      • 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, exigida pelo Cloud Deploy para implantações canário no GKE e no GKE Enterprise.

      • WAIT_TIME é um tempo para que o Cloud Deploy aguarde a conclusão da propagação das alterações no recurso HTTPRoute para evitar o descarte de solicitações. Por exemplo: routeUpdateWaitTime: 60s.

        Se você estiver executando o canário usando a API Gateway sem o Istio e ela estiver conectada a um balanceador de carga do Google Cloud, uma pequena quantidade de tráfego poderá ser perdida quando a instância canário 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 em que você está implantando progressivamente pode abranger dois ou mais destinos filhos. Por exemplo, é possível implantar progressivamente em clusters em regiões separadas, ao mesmo tempo.

Qual é a diferença entre um canário paralelo e um canário de destino único

  • Assim como na implantação canário de destino único, se você estiver implantando em destinos do GKE, você 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, você precisa configurar um destino múltiplo e configurar os destinos filhos referenciados por vários destinos.

  • Ao criar uma versão, um lançamento do controlador e os lançamentos filhos são criados.

    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 100% do canário.

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

    Só é possível avançar os lançamentos dos controladores. Quando você avança a implementação do controlador para a próxima etapa, os lançamentos filhos também são avançados pelo Cloud Deploy.

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

    Só é possível executar um job novamente 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 um lançamento filho.

  • Só é possível encerrar execuções de jobs em um lançamento filho, e não em um lançamento do controlador.

O que fazer se um lançamento paralelo falhar no canário

Quando um lançamento filho falha, o lançamento do controlador pode mudar para estados diferentes, dependendo do que acontece com eles:

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

  • Se um ou mais lançamentos filhos falharem, mas pelo menos um 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, repetir 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 no estado HALTED devido a uma falha na implementação do filho e você ignorar o job com falha no lançamento filho, a implementação do controlador será revertida para o estado IN_PROGRESS.

Executar o canário configurado

Para executar a implantação canário:

  1. Registre 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 pressupõe que seus destinos estão definidos no mesmo arquivo ou já já foram registrados. Caso contrário, registre seus destinos também.

  2. Crie 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. Avançar 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 este lançamento faz parte.

    PIPELINE_NAME é o nome do pipeline de entrega que você está usando para gerenciar a implantação desta 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 do lançamento é exibida.

      detalhes do lançamento no console do Google Cloud

      Neste exemplo, o lançamento tem uma fase canary-50 e uma stable. Seu lançamento pode ter mais fases ou fases diferentes.

    4. Clique em Avançar o lançamento.

      O lançamento avança 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 pulará a fase canário e executará a fase estável. Consulte Como pular fases na primeira vez para descobrir por que isso acontece.

A seguir