Deployment canary in Cloud Run

Questo documento descrive come configurare e utilizzare i deployment canary per eseguire il deployment delle applicazioni in Cloud Run (solo servizi, non job) utilizzando Cloud Deploy.

Un deployment canary è un'implementazione progressiva di una nuova versione dell'applicazione, in cui aumenti gradualmente la percentuale di traffico inviato alla nuova versione, monitorando al contempo le prestazioni dell'applicazione. In questo modo, puoi rilevare potenziali problemi in anticipo e ridurre al minimo l'impatto sugli utenti.

Come funzionano i deployment canary per Cloud Run

Quando esegui il deployment in Cloud Run utilizzando una strategia di deployment canary, Cloud Deploy aggiorna il servizio esistente con una nuova revisione. La nuova revisione riceve una percentuale specificata di traffico, mentre la vecchia revisione continua a ricevere il resto. Aumenti gradualmente la suddivisione del traffico alla nuova revisione nel tempo.

Utilizzando Cloud Deploy, puoi configurare i deployment canary in Cloud Run in una o più fasi.

Le istruzioni riportate di seguito includono solo ciò che è specifico della configurazione canary. Il documento Eseguire il deployment di un servizio o di un job Cloud Run contiene le istruzioni generali per configurare ed eseguire la pipeline di deployment.

Assicurati di disporre delle autorizzazioni necessarie

Oltre alle altre autorizzazioni Identity and Access Management necessarie per utilizzare Cloud Deploy, devi disporre delle seguenti autorizzazioni per eseguire azioni aggiuntive che potrebbero essere necessarie per un deployment canary:

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

Per ulteriori informazioni sui ruoli disponibili che includono queste autorizzazioni, consulta Ruoli e autorizzazioni IAM.

Prepara il tuo skaffold.yaml

Il file skaffold.yaml definisce il rendering e il deployment delle definizioni del servizio Cloud Run. Per un deployment canary su Cloud Run, assicurati che punti correttamente ai file di definizione del servizio e definisca gli artefatti di build necessari (come le immagini container). All'interno di skaffold.yaml non è richiesta alcuna configurazione specifica per la versione canary, oltre a quella necessaria per un deployment standard. Puoi utilizzare i profili Skaffold per gestire diverse varianti della definizione del servizio per le fasi canary personalizzate.

Prepara la definizione del servizio

Il normale file di definizione del servizio Cloud Run è sufficiente, ma senza una sezione traffic. Cloud Deploy gestisce la suddivisione del traffico tra l'ultima revisione riuscita e la nuova revisione.

Esempio service.yaml (senza traffic stanza):

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

Configurare un canary automatico

Configura un canary automatico direttamente nella definizione della pipeline di distribuzione per una fase Cloud Run specifica. Cloud Deploy indica automaticamente a Cloud Run di dividere il traffico tra l'ultima revisione stabile e la nuova revisione in base alle percentuali specificate.

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"

In questa configurazione:

  • PERCENTAGES è un elenco separato da virgole di valori percentuali che rappresentano gli incrementi canary, ad esempio [25, 50, 75]. Tieni presente che non è incluso 100, perché l'implementazione al 100% è presunta nel canary ed è gestita dalla fase stable.

  • Puoi attivare la verifica del deployment (verify: true). In questo caso, a ogni fase canary viene aggiunto un job verify.

  • PREDEPLOY_ACTION

    È uguale a ACTION_NAME che hai utilizzato in skaffold.yaml per definire l'azione personalizzata che vuoi eseguire prima del deployment.

  • POSTDEPLOY_ACTION

    È uguale a ACTION_NAME che hai utilizzato in skaffold.yaml per definire l'azione personalizzata che vuoi eseguire dopo il deployment.

Configurare un canary personalizzato automatizzato

In questo modo, la definizione personalizzata delle fasi (nomi, percentuali, profili, verifica, hook) viene combinata con la gestione automatica del traffico di Cloud Deploy per Cloud Run. Definisci le fasi, ma Cloud Deploy gestisce l'istruzione di Cloud Run per spostare il traffico in base alle percentuali.

Per configurare questa impostazione, includi sia l'impostazione runtimeConfig.cloudRun.automaticTrafficControl: true sia la sezione customCanaryDeployment (che definisce phaseConfigs) all'interno del blocco strategy.canary. Cloud Deploy utilizzerà i profili Skaffold specificati per il rendering della definizione del servizio (che non deve ancora avere una sezione traffic), ma gestirà automaticamente il traffico in base alle percentuali di 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

Esegui il canary Cloud Run

  1. Registra pipeline e destinazioni: applica i file di configurazione della pipeline di distribuzione e della destinazione Cloud Run.

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

    La pipeline di distribuzione include la configurazione canary automatica o personalizzata per il runtime scelto.

  2. Crea una release: avvia il deployment fornendo il nome dell'immagine.

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

    La pipeline di distribuzione identificata da PIPELINE_NAME contiene la configurazione canary automatica o personalizzata descritta in questo documento.

  3. Avanza alla fase canary:

    Interfaccia a riga di comando gcloud 

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

    Dove:

    ROLLOUT_NAME è il nome dell'implementazione attuale che stai facendo avanzare alla fase successiva.

    RELEASE_NAME è il nome della release di cui fa parte questo rollout.

    PIPELINE_NAME è il nome della pipeline di distribuzione che utilizzi per gestire il deployment di questa release.

    REGION è il nome della regione in cui è stata creata la release, ad esempio us-central1. Campo obbligatorio.

    Per ulteriori informazioni sul comando gcloud deploy rollouts advance, consulta il riferimento per Google Cloud SDK.

    Console Google Cloud

    1. Apri la pagina Pipeline di pubblicazione.

    2. Fai clic sulla pipeline visualizzata nell'elenco delle pipeline di pubblicazione.

      La pagina Dettagli pipeline di distribuzione mostra una rappresentazione grafica dell'avanzamento della pipeline di distribuzione.

    3. Nella scheda Implementazioni, in Dettagli della pipeline di pubblicazione, fai clic sul nome dell'implementazione.

      Viene visualizzata la pagina dei dettagli dell'implementazione.

      Dettagli dell'implementazione nella console Google Cloud

      Nota che in questo esempio l'implementazione ha una fase canary-50 e una fase stable. L'implementazione potrebbe avere più fasi o fasi diverse.

    4. Fai clic su Prosegui con implementazione.

      L'implementazione passa alla fase successiva.

Fasi saltate

Se esegui il deployment di una versione canary e la tua applicazione non è ancora stata sottoposta a deployment in quel runtime, Cloud Deploy salta la fase canary ed esegue la fase stabile. Consulta la sezione Saltare le fasi la prima volta per scoprire perché ciò accade.

Passaggi successivi