Implantações canário no GKE e no GKE Enterprise usando a rede da API Gateway

Este documento descreve como configurar e usar implantações canário para implantar seus aplicativos no GKE ou no GKE Enterprise usando o Cloud Deploy com a malha de serviço da API Gateway do Kubernetes.

Uma implantação canário é um lançamento progressivo de uma nova versão do aplicativo, em que você aumenta gradualmente a porcentagem de tráfego enviado para a nova versão, enquanto monitora o desempenho do aplicativo. Isso ajuda a detectar possíveis problemas antecipadamente e minimizar o impacto nos usuários.

Como as implantações canário funcionam 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 do serviço original mais -canary.

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

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

    Como pode haver um atraso na propagação de mudanças nos recursos do HTTPRoute, inclua a propriedade routeUpdateWaitTime na sua configuração para que o sistema aguarde um período especificado por 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, a HTTPRoute foi revertida para a original que você forneceu.

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

Com o Cloud Deploy, é possível configurar implantações canário no GKE e no GKE Enterprise em uma única etapa ou em várias etapas.

As instruções aqui incluem apenas o que é específico da configuração de canary. O documento Implantar em um cluster do Google Kubernetes Engine tem as instruções gerais para configurar e executar seu 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, você precisa das seguintes permissões para realizar 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

O arquivo skaffold.yaml define como os manifestos do Kubernetes são renderizados e implantados. Para uma implantação canário no GKE/GKE Enterprise, verifique se ela aponta corretamente para seus manifestos e define os artefatos de build necessários. Não é necessária nenhuma configuração específica do canary no skaffold.yaml além do que é necessário para uma implantação padrão. Você pode usar perfis do Skaffold para gerenciar diferentes variações de manifesto em fases canário personalizadas.

Preparar manifestos do Kubernetes

Os manifestos do Kubernetes precisam incluir um recurso Deployment e um recurso Service. O Service precisa definir um selector que corresponda aos rótulos dos pods gerenciados pelo Deployment. O rótulo padrão que o Cloud Deploy procura é app, mas isso pode ser configurado no pipeline.

Além de Deployment e Service, seus manifestos precisam incluir um recurso HTTPRoute configurado para divisão de tráfego, fazendo referência ao Service e ao gateway associado.

Configurar um teste canário automatizado

Use a API Kubernetes Gateway (com Istio ou qualquer implementação compatível) para divisão de tráfego precisa e baseada em porcentagem gerenciada pela malha/gateway e orquestrada pelo Cloud Deploy.

  1. Configure os recursos da API Gateway: verifique se o gateway e a malha de serviço subjacente (por exemplo, Istio) ou o controlador de gateway estão configurados corretamente nos clusters.

  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 você vai fazer a implantação canário:

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

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

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

      Em que…

      • ROUTE é a configuração httpRoute que define o comportamento de roteamento desejado.

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

      • DEPLOYMENT é sua 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 para o Cloud Deploy aguardar a conclusão da propagação das mudanças no recurso HTTPRoute, evitando 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 Google Cloud , uma pequena quantidade de tráfego poderá ser perdida quando a instância canary for reduzida. É possível configurar essa opção se você observar esse comportamento.

      • LABEL é um rótulo de seletor de pod. Ele precisa corresponder ao seletor de rótulos no serviço e na implantação do Kubernetes definidos no manifesto. Isso é opcional. O padrão é app.

Configurar um canário personalizado

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

  • Nomes das fases de lançamento

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

  • Metas de porcentagem para cada fase

    Especifique as porcentagens separadamente, por fase.

  • Perfis do Skaffold a serem usados na 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 diferente do Kubernetes. Também é possível usar mais de um perfil para uma determinada fase. O Cloud Deploy combina os dois.

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

    Se você estiver ativando a verificação, configure seu skaffold.yaml para verificação também.

  • Se há jobs de pré-implantação ou pós-implantação para a fase

    Se você estiver ativando jobs de pré ou pós-implantação, precisará configurar seu skaffold.yaml para esses jobs.

Todos os tipos de destino são compatíveis com o canary personalizado.

Elementos de configuração canário personalizados

O YAML a seguir mostra a configuração das fases de 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
        predeploy:
          actions: "PREDEPLOY_ACTION"
        postdeploy:
          actions: "POSTDEPLOY_ACTION"
      - …
      - phaseId: "stable"
        percentage: 100
        profiles: [ "LAST_PROFILE_NAME" ]
        verify: true|false
        predeploy:
          actions: "PREDEPLOY_ACTION"
        postdeploy:
          actions: "POSTDEPLOY_ACTION"

Neste YAML

  • PHASE1_NAME

    É o nome da fase. Cada nome de fase precisa ser exclusivo.

  • [ "PROFILE_NAME" ]

    É o nome do perfil a ser usado na fase. Você pode 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 especificados, além do perfil ou manifesto usado pela etapa geral.

  • stable

    A fase final precisa ser chamada de stable.

  • PERCENTAGE1

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

  • verify: true|false

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

  • PREDEPLOY_ACTION

    É o mesmo que o ACTION_NAME usado no skaffold.yaml para definir a ação personalizada que você quer executar antes da implantação.

  • POSTDEPLOY_ACTION

    É o mesmo que o ACTION_NAME usado no skaffold.yaml para definir a ação personalizada que você quer executar após a implantação.

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

A configuração de um canary personalizado da API Gateway não inclui uma cláusula runtimeConfig. Se você incluir runtimeConfig, ele será considerado um canário personalizado baseado em serviço.

Configurar um teste canário automatizado personalizado

Isso combina a definição de fase personalizada (nomes, porcentagens, perfis, verificação, hooks) com o gerenciamento automático de tráfego do Cloud Deploy para GKE ou GKE Enterprise. Você define as fases, mas o Cloud Deploy processa a manipulação de recursos subjacentes com base nas porcentagens e no runtimeConfig escolhido.

Para configurar isso, inclua uma seção runtimeConfig com serviceNetworking e a seção customCanaryDeployment (que define phaseConfigs) no bloco strategy.canary. O Cloud Deploy vai usar os perfis do Skaffold especificados para renderização, mas vai ajustar automaticamente o tráfego de acordo com as porcentagens de runtimeConfig e fase.

serialPipeline:
  stages:
  - targetId: gke-prod
    profiles: []
    strategy:
      canary:
        # Include runtimeConfig for automatic traffic management
        runtimeConfig:
          kubernetes:
            gatewayServiceMesh:
              httpRoute: "my-route"
              service: "my-app"
              deployment: "my-deployment"  
        # Include customCanaryDeployment for phase customization
        customCanaryDeployment:
          phaseConfigs:
          - phaseId: "warmup"
            percentage: 10
            profiles: ["profile-a"] # Profile used for rendering this phase
            verify: true
          - phaseId: "scaling"
            percentage: 50
            profiles: ["profile-b"] # Different profile for this phase
            verify: true
          - phaseId: "stable"
            percentage: 100
            profiles: ["profile-b"] # Can reuse profiles
            verify: true

Implantar um HTTPRoute em um cluster diferente

Quando você tem um canary configurado usando a malha de serviço da API Gateway, é possível especificar um cluster alternativo que não seja o de destino para implantar a HTTPRoute.

Para isso, use uma estrofe routeDestinations na configuração da estratégia de canário para identificar o cluster ou os clusters de destino da HTTPRoute e uma configuração booleana para propagar o serviço para o mesmo cluster não de destino. E você cria uma seção associatedEntities na configuração de destino para identificar os clusters.

  1. Configure associatedEntities no destino.

    Cada entidade é um cluster em que o Cloud Deploy implanta a HTTPRoute e, opcionalmente, o serviço do Kubernetes. Na definição de destino, inclua uma seção associatedEntities:

    associatedEntities:
  [KEY]:
    gkeClusters:
    - cluster: [PATH]
      dnsEndpoint: [true|false]
      internalIp: [true|false]
      proxyUrl:

    Em que:

    • KEY é um nome arbitrário para esse grupo de entidades associadas. Você vai usar esse nome para se referir às entidades do routeDestinations na sua configuração de canário.

    • PATH é o caminho do recurso que identifica o cluster do GKE em que o HTTPRoute (e, opcionalmente, o serviço) será implantado.

    • dnsEndpoint indica se o endpoint DNS do cluster deve ser usado se vários endpoints estiverem configurados. O padrão é false.

    • internalIp indica se o IP interno (IP particular) do cluster deve ser usado ou não se vários endpoints estiverem configurados. O padrão é false.

    É possível incluir qualquer número de clusters, com ou sem internalIp.

  2. Configure routeDestinations na configuração canário.

    Cada destino de rota faz referência a uma estrofe associatedEntities e indica se o serviço também precisa ser implantado no cluster alternativo. Adicione o seguinte à estrofe gatewayServiceMesh na configuração do canary:

    routeDestinations:
  destinationIds: ["KEY"]
  propagateService: [true|false]

    Em que:

    • KEY é o nome configurado no destino, em associatedEntities. Use esse nome para fazer referência às entidades do routeDestinations na sua configuração canary.

      Você também pode fornecer o valor @self para implantar o HTTPRoute no cluster de destino, além do destino associado.

    • propagateService indica se você quer implantar o serviço no cluster associado, além do HTTPRoute. O padrão é false.

Executar o canary do GKE ou do GKE Enterprise

  1. Registrar pipeline e destinos: aplique o pipeline de entrega e os arquivos de configuração de destino do GKE ou do GKE Enterprise.

    
gcloud deploy apply --file=delivery-pipeline.yaml --region=REGION
gcloud deploy apply --file=gke-targets.yaml --region=REGION

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

  2. Crie um lançamento: inicie a implantação fornecendo o nome da imagem.

    
gcloud deploy releases create RELEASE_NAME \
                                --delivery-pipeline=PIPELINE_NAME \
                                --region=REGION
  # e.g., --images=my-cloudrun-service=gcr.io/my-project/my-app:v1.1
  # Add --skaffold-file or --source if not using default Skaffold config discovery

    O pipeline de entrega identificado por PIPELINE_NAME contém a configuração de teste 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 de que este lançamento faz parte.

    PIPELINE_NAME é o nome do pipeline de entrega que você está usando 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.

    Google Cloud console

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

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

      A página "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 lançamento.

      A página de detalhes da implementação é mostrada.

      detalhes do lançamento no console Google Cloud

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

    4. Clique em Continuar lançamento.

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

Fases ignoradas

Se você implantar um canary e o aplicativo ainda não tiver sido implantado nesse ambiente de execução, o Cloud Deploy vai pular a fase canary e executar a fase estável. Consulte Pular fases na primeira vez para saber por que isso acontece.

A seguir