Implantações canário no Cloud Run

Neste documento, descrevemos como configurar e usar implantações canário para implantar aplicativos no Cloud Run (somente serviços, não jobs) usando o Cloud Deploy.

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 Cloud Run

Ao implantar no Cloud Run usando uma estratégia de implantação canário, o Cloud Deploy atualiza seu serviço atual com uma nova revisão. A nova revisão recebe uma porcentagem especificada de tráfego, e a revisão antiga continua recebendo o restante. Você aumenta gradualmente a divisão de tráfego para a nova revisão ao longo do tempo.

Com o Cloud Deploy, é possível configurar implantações canário no Cloud Run em uma ou várias etapas.

As instruções aqui incluem apenas o que é específico da configuração de canary. O documento Implantar um serviço ou job do Cloud Run 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 as definições de serviço do Cloud Run são renderizadas e implantadas. Para uma implantação canário no Cloud Run, verifique se ela aponta corretamente para os arquivos de definição de serviço e define os artefatos de build necessários, como imagens de contêiner. 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 definição de serviço em fases canário personalizadas.

Preparar a definição de serviço

O arquivo de definição de serviço normal 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.

Exemplo service.yaml (sem estrofe traffic):

apiVersion: serving.knative.dev/v1
kind: Service
metadata:
  name: my-cloudrun-service
spec:
  template:
    spec:
      containers:
      - image: gcr.io/my-project/my-cloudrun-app
        ports:
        - containerPort: 8080

Configurar um teste canário automatizado

Configure um canário automático diretamente na definição do pipeline de entrega para uma etapa específica do Cloud Run. O Cloud Deploy instrui automaticamente o Cloud Run a dividir o tráfego entre a última revisão estável e a nova revisão de acordo com as porcentagens especificadas.

serialPipeline:
  stages:
  - targetId: prod
    profiles: []
    strategy:
      canary:
        runtimeConfig:
          cloudRun:
            automaticTrafficControl: true
        canaryDeployment:
          percentages: [PERCENTAGES]
          verify: true|false
          predeploy:
            actions: "PREDEPLOY_ACTION"
          postdeploy:
            actions: "POSTDEPLOY_ACTION"

Nesta configuração:

• PERCENTAGES é uma lista separada por vírgulas de valores percentuais que representam seus incrementos de canário, por exemplo, [25, 50, 75]. Isso não inclui 100, porque a implantação de 100% é presumida no canary e é processada pela fase stable.

• Você pode ativar a verificação de implantação (verify: true). Se fizer isso, um job verify será adicionado a cada fase de canário.

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

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 uma definição de serviço do Cloud Run diferente. 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 não inclui uma seção runtimeConfig. Se você incluir runtimeConfig, ele será considerado um canário automatizado personalizado.

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 o Cloud Run. Você define as fases, mas o Cloud Deploy instrui o Cloud Run a mudar o tráfego com base nas porcentagens.

Para configurar isso, inclua a configuração runtimeConfig.cloudRun.automaticTrafficControl: true e a seção customCanaryDeployment (definindo phaseConfigs) no bloco strategy.canary. O Cloud Deploy vai usar os perfis do Skaffold especificados para renderizar a definição de serviço (que ainda não deve ter uma estrofe traffic), mas vai gerenciar automaticamente o tráfego de acordo com as porcentagens de fase.

serialPipeline:
  stages:
  - targetId: cloudrun-prod
    profiles: []
    strategy:
      canary:
        # Include runtimeConfig for automatic traffic management
        runtimeConfig:
          cloudRun:
            automaticTrafficControl: true
        # Include customCanaryDeployment for phase customization
        customCanaryDeployment:
          phaseConfigs:
          - phaseId: "warmup-cr"
            percentage: 10
            profiles: ["base-config"] # Profile rendering service def (no traffic stanza)
            verify: true
          - phaseId: "scaling-cr"
            percentage: 50
            profiles: ["base-config"] # Can use the same profile
            verify: true
          - phaseId: "stable"
            percentage: 100
            profiles: ["base-config"]
            verify: true

Executar o canário do Cloud Run

1. Registre o pipeline e os destinos: aplique os arquivos de configuração do pipeline de entrega e do destino do Cloud Run.

   
   gcloud deploy apply --file=delivery-pipeline.yaml --region=REGION
   gcloud deploy apply --file=cloudrun-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
   

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

      

      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

• Confira o guia de início rápido de implantação canário.

• Saiba como gerenciar o ciclo de vida dos rollouts do seu canary.

• Saiba mais sobre a implantação paralela.

• Saiba mais sobre as estratégias de implantação do Cloud Deploy.

• Saiba mais sobre o Cloud Run.