Rollback, rilasci graduali, migrazione del traffico

Cloud Run consente di specificare quali revisioni devono ricevere traffico e di specificare le percentuali di traffico ricevute da una revisione. Questa funzionalità consente di eseguire il rollback a una revisione precedente, implementare gradualmente una revisione e suddividere il traffico tra più revisioni. Questa pagina descrive come utilizzare questa funzionalità per gestire il traffico verso le revisioni di Cloud Run.

Tieni presente che gli aggiustamenti del routing del traffico non sono istantanei. Quando modifichi il traffico per le revisioni, tutte le richieste attualmente in fase di elaborazione continueranno a essere completate. Le richieste in fase di pubblicazione non verranno ignorate e potrebbero essere indirizzate a una nuova revisione o a una precedente durante il periodo di transizione.

Se suddividi il traffico tra più revisioni con l'affinità sessione abilitata, consulta Affinità delle sessioni e suddivisione del traffico per maggiori dettagli sull'effetto dell'affinità sessione sulla suddivisione del traffico.

Esegui il rollback a una revisione precedente

Per eseguire il rollback a una revisione precedente:

Console

Vai a Cloud Run
Individua il servizio nell'elenco e fai clic su di esso.
Fai clic sulla scheda Revisioni per visualizzare l'elenco delle revisioni correnti per quel servizio.
Nell'elenco delle revisioni, fai clic sull'icona con i puntini di sospensione a destra della revisione di cui stai eseguendo il rollback:
Fai clic su Gestisci traffico per visualizzare il modulo di gestione del traffico:
1. Seleziona dall'elenco a discesa la revisione precedente di cui vuoi eseguire il rollback.
2. Impostare la percentuale di traffico della revisione precedente su 100.
3. Imposta la percentuale della revisione attualmente pubblicata su 0.
4. Fai clic su Salva.

Riga di comando

Utilizza il seguente comando:

gcloud run services update-traffic SERVICE --to-revisions REVISION=100

Sostituisci SERVICE con il nome del servizio.
Sostituisci REVISION con il nome della revisione a cui stai eseguendo il rollback.

YAML

Puoi scaricare e visualizzare le configurazioni di servizio esistenti utilizzando il comando gcloud run services describe --format export, che restituisce risultati puliti in formato YAML. Puoi quindi modificare i campi descritti di seguito e caricare il file YAML modificato utilizzando il comando gcloud run services replace. Assicurati di modificare i campi solo come documentato.

Per visualizzare e scaricare la configurazione:

gcloud run services describe SERVICE --format export > service.yaml

Sotto l'attributo spec, individua e aggiorna l'attributo traffic nel seguente modo:
```
apiVersion: serving.knative.dev/v1
kind: Service
metadata:
 name: SERVICE
spec:
...
  traffic:
  - revisionName: REVISION
    percent: 100
```
Sostituisci
- REVISION con il nome della revisione a cui stai eseguendo il rollback.
Sostituisci il servizio con la nuova configurazione utilizzando il seguente comando:
```
gcloud run services replace service.yaml
```
Attendi il completamento dell'aggiornamento: dovresti visualizzare un messaggio che ti informa che è stato eseguito il deployment della revisione da cui stai eseguendo il rollback e che gestisce il 0% di traffico.

Terraform

Per scoprire come applicare o rimuovere una configurazione Terraform, consulta Comandi Terraform di base.

Aggiungi quanto segue al tuo file .tf:

resource "google_cloud_run_v2_service" "default" {
  name     = "cloudrun-srv"
  location = "us-central1"

  template {}

  traffic {
    percent = 100
    # This revision needs to already exist
    revision = "cloudrun-srv-green"
    type     = "TRAFFIC_TARGET_ALLOCATION_TYPE_REVISION"

  }
}

Implementazione graduale per revisioni

Per implementare gradualmente una nuova revisione:

Console

Vai a Cloud Run
Individua il servizio nell'elenco e fai clic su di esso.
Fai clic su Esegui il deployment di nuova revisione.
Compila il modulo di deployment se necessario, ma assicurati che la casella di controllo Pubblica immediatamente questa revisione sia NON CONTROLLATA.
Fai clic su Esegui il deployment.
Fai clic su Gestisci traffico.
La nuova revisione è elencata ma con una percentuale impostata su 0: al momento non gestisce alcun traffico. Nel modulo:
1. Impostala sulla percentuale desiderata, ad esempio 5. Tieni presente che la percentuale della versione attualmente pubblicata viene ridotta automaticamente dello stesso importo.
2. Fai clic su Salva.
3. Ripeti questi passaggi in Gestione del traffico, ma con percentuali modificate, aumentando la percentuale secondo necessità per la nuova revisione. Non è necessario eseguire nuovamente il deployment per modificare le percentuali di traffico.

Riga di comando

Esegui il deployment della revisione da implementare gradualmente, impostando inizialmente la revisione in modo che non riceva traffico:
```
gcloud run deploy --image IMAGE --no-traffic
```
Sostituisci IMAGE con l'immagine di cui stai eseguendo il deployment.
Specifica la percentuale di traffico da gestire con la nuova revisione, ad esempio 5%:
```
gcloud run services update-traffic SERVICE --to-revisions REVISION=PERCENTAGE
```
- Sostituisci SERVICE con il nome del servizio.
- Sostituisci REVISION con il nome della revisione che stai implementando gradualmente. Per specificare la revisione più recente, puoi utilizzare LATEST, ad esempio LATEST=5.
- Sostituisci PERCENTAGE con la percentuale di traffico che vuoi inviare alla nuova revisione, ad esempio 5 per inviarle il 5% del traffico.
Quando le prestazioni della revisione sono soddisfacenti, ripeti il passaggio update-traffic precedente, ma aumenta il valore percentuale in base alle tue esigenze.

YAML

Per visualizzare e scaricare la configurazione:

gcloud run services describe SERVICE --format export > service.yaml

Apporta le modifiche alla configurazione al servizio e specifica il nome della revisione che preferisci per la nuova revisione:
```
apiVersion: serving.knative.dev/v1
kind: Service
metadata:
 name: SERVICE
template:
  metadata:
    annotations:
      ...
    name: REVISION-NAME
```
Sostituisci
- REVISION-NAME con il nome che vuoi che abbia la nuova revisione.
Sotto l'attributo spec, individua e aggiorna l'attributo traffic in modo che la nuova revisione pubblichi solo una piccola quantità di traffico:
```
apiVersion: serving.knative.dev/v1
kind: Service
metadata:
 name: SERVICE
spec:
...
  traffic:
  - revisionName: REVISION-NEW
    percent: PERCENT-NEW
  - revisionName: REVISION-FORMER
    percent: PERCENT-FORMER
```
Tieni presente che la somma delle percentuali deve essere 100. Sostituisci
- REVISION-NEW con il nome della revisione che stai implementando gradualmente.
- REVISION-FORMER con il nome della revisione attualmente pubblicata.
- PERCENT-NEW con la percentuale di traffico da inviare alla nuova revisione, ad esempio utilizza 10 per inviare il 10% del traffico a quella revisione.
- PERCENT-FORMER con la percentuale di traffico che vuoi inviare alla vecchia revisione
Attendi il completamento dell'aggiornamento: dovresti vedere un messaggio che indica che è stato eseguito il deployment della nuova revisione che stai implementando gradualmente e che pubblica il valore percentuale di traffico utilizzato.

Terraform

Aggiungi quanto segue al file .tf e aggiorna gradualmente la percentuale di traffico dalla revisione precedente all'ultima revisione. Tieni presente che ogni modifica al traffico richiederà l'esecuzione di un altro terraform apply.

resource "google_cloud_run_v2_service" "default" {
  name     = "cloudrun-srv"
  location = "us-central1"

  template {
    containers {
      # Image or image tag must be different from previous revision
      image = "us-docker.pkg.dev/cloudrun/container/hello"
    }
  }

  # Define the traffic split for each revision
  # https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/cloud_run_v2_service#traffic
  traffic {
    percent = 100
    # This revision needs to already exist
    revision = "cloudrun-srv-green"
    type     = "TRAFFIC_TARGET_ALLOCATION_TYPE_REVISION"
  }

  traffic {
    # Deploy new revision with 0% traffic
    percent = 0
    type    = "TRAFFIC_TARGET_ALLOCATION_TYPE_LATEST"
  }
}

Applica le modifiche inserendo terraform apply.

Suddividi il traffico tra più revisioni

Per suddividere il traffico tra due o più revisioni:

Console

Vai a Cloud Run
Individua il servizio nell'elenco e fai clic su di esso.
Fai clic su Gestisci traffico.
È elencata la nuova revisione attualmente in fase di pubblicazione. Nel modulo:
1. Imposta la percentuale di revisione attualmente pubblicata sulla suddivisione desiderata.
2. Seleziona una delle revisioni precedenti utilizzando l'elenco a discesa e impostala sulla suddivisione percentuale desiderata.
3. Per suddividere il traffico tra più revisioni, fai clic su Aggiungi revisione, seleziona la revisione desiderata e imposta la percentuale sulla suddivisione desiderata.
4. Fai clic su Salva.

Riga di comando

Specifica le revisioni e la percentuale di traffico per ogni revisione in un elenco delimitato da virgole:

gcloud run services update-traffic SERVICE --to-revisions LIST

Sostituisci SERVICE con il nome del servizio.
Sostituisci LIST con un elenco di revisioni e percentuali delimitato da virgole:
REVISION1=PERCENTAGE1,REVISION2=PERCENTAGE2,REVISIONn=PERCENTAGEx
ad esempio hello2-00005-red=25,hello2-00001-bod=25,hello2-00002-nan=50.

YAML

Per visualizzare e scaricare la configurazione:

gcloud run services describe SERVICE --format export > service.yaml

Sotto l'attributo spec, individua e aggiorna l'attributo traffic in modo che la nuova revisione pubblichi solo una piccola quantità di traffico:
```
apiVersion: serving.knative.dev/v1
kind: Service
metadata:
 name: SERVICE
spec:
...
  traffic:
  - revisionName: REVISION-A
    percent: PERCENT-A
  - revisionName: REVISION-B
    percent: PERCENT-B
  - revisionName: REVISION-C
    percent: PERCENT-C
```
Tieni presente che la somma delle percentuali deve essere 100. Sostituisci
- REVISION-A, REVISION-B, REVISION-C con le revisioni a cui stai assegnando il traffico.
- PERCENT-A, PERCENT-B, PERCENT-C con la percentuale per la revisione corrispondente.
Sostituisci il servizio con la nuova configurazione utilizzando il seguente comando:
```
gcloud run services replace service.yaml
```
Attendi il completamento dell'aggiornamento: dovresti visualizzare un messaggio che indica che è stato eseguito il deployment della nuova revisione che stai implementando gradualmente e che gestisce il traffico pari a 5% (o qualsiasi valore graduale utilizzato).

Terraform

Aggiungi quanto segue al tuo file .tf:

resource "google_cloud_run_v2_service" "default" {
  name     = "cloudrun-srv"
  location = "us-central1"

  template {
    containers {
      image = "us-docker.pkg.dev/cloudrun/container/hello"
    }
    revision = "cloudrun-srv-green"
  }

  # Define the traffic split for each revision
  # https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/cloud_run_v2_service#traffic
  traffic {
    percent  = 25
    revision = "cloudrun-srv-green"
    type     = "TRAFFIC_TARGET_ALLOCATION_TYPE_REVISION"
  }

  traffic {
    percent = 75
    # This revision needs to already exist
    revision = "cloudrun-srv-blue"
    type     = "TRAFFIC_TARGET_ALLOCATION_TYPE_REVISION"
  }
}

Applica le modifiche inserendo terraform apply.

Invia tutto il traffico all'ultima revisione

Quando esegui il deployment di una nuova revisione, puoi fare in modo che questa revisione, insieme a tutte quelle future, coprano il 100% del traffico il prima possibile, sostituendo qualsiasi suddivisione del traffico stabilita:

Console

Vai a Cloud Run
Individua il servizio nell'elenco e fai clic su di esso.
Fai clic su Esegui il deployment di nuova revisione.
Compila il modulo di deployment in base alle esigenze, assicurandoti di selezionare la casella di controllo con l'etichetta Pubblica immediatamente questa revisione. Questa operazione sostituirà qualsiasi suddivisione del traffico esistente, in quanto la nuova revisione gestisce il 100% del traffico.
Fai clic su Esegui il deployment.

Riga di comando

Per inviare tutto il traffico alla revisione di cui è stato eseguito il deployment più di recente:

gcloud run services update-traffic SERVICE --to-latest

Sostituisci SERVICE con il nome del servizio.

YAML

Per visualizzare e scaricare la configurazione:

gcloud run services describe SERVICE --format export > service.yaml

Sotto l'attributo spec, individua e aggiorna l'attributo traffic nel seguente modo

apiVersion: serving.knative.dev/v1
kind: Service
metadata:
 name: SERVICE
spec:
...
  traffic:
  - latestRevision: true
    percent: 100

Sostituisci il servizio con la nuova configurazione utilizzando il seguente comando:
```
gcloud run services replace service.yaml
```
Attendi il completamento dell'aggiornamento: dovresti visualizzare un messaggio che indica che è stato eseguito il deployment della revisione (più recente) che gestisce il 100% del traffico.

Terraform

Aggiungi quanto segue al tuo file .tf:

resource "google_cloud_run_v2_service" "default" {
  name     = "cloudrun-srv"
  location = "us-central1"

  template {}

  traffic {
    percent = 100
    type    = "TRAFFIC_TARGET_ALLOCATION_TYPE_LATEST"
  }
}

Applica le modifiche inserendo terraform apply.

Usa i tag per test, migrazione del traffico e rollback

Per evitare costi di fatturazione per le revisioni con tag, utilizza le istanze minime del livello di servizio o rimuovi i tag nelle revisioni quando non sono più necessarie.

Un caso d'uso comune per questa funzionalità consiste nell'utilizzare la funzionalità per i test e il controllo di una nuova revisione del servizio prima di gestire tutto il traffico, in questa sequenza tipica:

Esegui test di integrazione su un container durante lo sviluppo.
Esegui il deployment del container in un progetto Google Cloud che utilizzi solo per la gestione temporanea e senza traffico e il test rispetto a una revisione con tag.
Esegui il deployment in produzione, senza gestire il traffico, ed esegui il test con una revisione con tag in produzione.
Esegui la migrazione del traffico alla revisione con tag.

Esegui il deployment di una nuova revisione con tag

Per eseguire il deployment in produzione di una nuova revisione di un servizio esistente:

Riga di comando

gcloud run deploy myservice --image IMAGE_URL  --no-traffic --tag TAG_NAME

Sostituisci

IMAGE_URL con l'URL della tua immagine
TAG_NAME con il nome del tuo tag in minuscolo

Il tag consente di testare direttamente la nuova revisione in un URL specifico, senza gestire il traffico. L'URL inizia con il nome del tag fornito: ad esempio, se hai utilizzato il nome del tag green nel servizio myservice, dovrai verificare la revisione del tag in corrispondenza dell'URL https://green---myservice-abcdef.a.run.app

Terraform

Aggiungi quanto segue al file .tf e aggiorna gradualmente la percentuale di traffico dalla vecchia revisione a quella più recente con il nuovo tag. Tieni presente che ogni modifica al traffico richiederà l'esecuzione di un altro terraform apply.

resource "google_cloud_run_v2_service" "default" {
  name     = "cloudrun-srv"
  location = "us-central1"

  template {
    containers {
      # image or tag must be different from previous revision
      image = "us-docker.pkg.dev/cloudrun/container/hello"
    }
    revision = "cloudrun-srv-blue"
  }

  # Define the traffic split for each revision
  # https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/cloud_run_v2_service#traffic
  traffic {
    percent = 100
    # This revision needs to already exist
    revision = "cloudrun-srv-green"
    type     = "TRAFFIC_TARGET_ALLOCATION_TYPE_REVISION"
  }

  traffic {
    # Deploy new revision with 0% traffic
    percent  = 0
    revision = "cloudrun-srv-blue"
    tag      = "tag-name"
    type     = "TRAFFIC_TARGET_ALLOCATION_TYPE_REVISION"
  }
}

Applica le modifiche inserendo terraform apply.

Rimuovere un tag

Per rimuovere un tag da una revisione:

Console

Vai a Cloud Run
Individua il servizio nell'elenco e fai clic su di esso.
Vai alla sezione Revisioni del servizio desiderato e seleziona la revisione per la quale vuoi rimuovere il tag esistente.
Passa il mouse sopra la colonna URL revisioni (tag) e fai clic sull'icona a forma di matita, come mostrato di seguito.
Nel menu popup URL revisioni, fai clic sull'icona Bin per rimuovere il tag corrente utilizzato nella revisione.
Fai clic su Salva.

Riga di comando

Per rimuovere un tag di revisione:

gcloud run services update-traffic SERVICE --remove-tags TAG_NAME

Sostituisci

TAG_NAME con il nome del tag a cui stai eseguendo la migrazione del traffico
SERVICE con il nome del servizio da cui stai rimuovendo il tag

YAML

Per visualizzare e scaricare la configurazione:

gcloud run services describe SERVICE --format export > service.yaml

Apporta le modifiche desiderate alla configurazione al servizio.

Sotto l'attributo spec, individua e rimuovi l'attributo tag per la revisione con tag:

apiVersion: serving.knative.dev/v1
kind: Service
metadata:
 name: SERVICE
spec:
...
  traffic:
  - revisionName: REVISION
    tag: TAG_NAME
    percent: PERCENT-NEW

Sostituisci il servizio con la nuova configurazione utilizzando il seguente comando:
```
gcloud run services replace service.yaml
```

Terraform

Aggiungi quanto segue al tuo file .tf:

resource "google_cloud_run_v2_service" "default" {
  name     = "cloudrun-srv"
  location = "us-central1"

  template {}

  # Define the traffic split for each revision
  # https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/cloud_run_v2_service#traffic
  traffic {
    percent = 100
    # This revision needs to already exist
    revision = "cloudrun-srv-green"
    type     = "TRAFFIC_TARGET_ALLOCATION_TYPE_REVISION"
  }

  traffic {
    # No tags for this revision
    # Keep revision at 0% traffic
    percent = 0
    # This revision needs to already exist
    revision = "cloudrun-srv-blue"
    type     = "TRAFFIC_TARGET_ALLOCATION_TYPE_REVISION"
  }
}

Applica le modifiche inserendo terraform apply.

Migrazione del traffico a una revisione con tag

Dopo aver verificato che la nuova revisione funzioni correttamente, puoi avviare la migrazione del traffico alla nuova revisione utilizzando la console Google Cloud, la riga di comando gcloud, Terraform o un file YAML:

Console

Vai a Cloud Run
Individua il servizio nell'elenco dei servizi e fai clic su di esso:
Seleziona la revisione codificata a cui vuoi inviare il traffico:
Fai clic su Gestisci traffico.
Individua il nome della revisione codificata: è elencata ma con una percentuale impostata su 0: al momento non gestisce traffico. Nel modulo Gestisci traffico*:
1. Impostala sulla percentuale desiderata, ad esempio 5. Tieni presente che la percentuale della versione attualmente pubblicata viene ridotta automaticamente dello stesso importo.
2. Fai clic su Salva.
3. Per un periodo di ore o giorni, a seconda delle esigenze, ripeti questi passaggi di Gestione del traffico, ma con percentuali modificate, aumentando la percentuale secondo necessità per la revisione codificata. Non è necessario eseguire nuovamente il deployment per modificare le percentuali di traffico.

Riga di comando

Per eseguire la migrazione del traffico a un tag di revisione specifico:

gcloud run services update-traffic myservice --to-tags TAG_NAME=TRAFFIC_PERCENT

Sostituisci

TAG_NAME con il nome del tag a cui stai eseguendo la migrazione del traffico
TRAFFIC_PERCENT con la percentuale di traffico che deve essere pubblicata dalla revisione codificata, ad esempio 1.

YAML

Per visualizzare e scaricare la configurazione:

gcloud run services describe SERVICE --format export > service.yaml

Apporta le modifiche desiderate alla configurazione al servizio.
Sotto l'attributo spec, individua e aggiorna l'attributo traffic per la revisione con tag in modo che la revisione con tag pubblichi solo una piccola quantità di traffico:
```
apiVersion: serving.knative.dev/v1
kind: Service
metadata:
 name: SERVICE
spec:
...
  traffic:
  - revisionName: REVISION
    tag: TAG_NAME
    percent: PERCENT-NEW
  - revisionName: REVISION-FORMER
    percent: PERCENT-FORMER
```
Tieni presente che la somma delle percentuali deve essere 100. Sostituisci
- REVISION con il nome della revisione codificata.
- TAG_NAME con il nome del tag che stai implementando gradualmente.
- PERCENT-NEW con la percentuale di traffico che vuoi inviare alla revisione codificata; ad esempio, utilizza 10 per inviare il 10% del traffico a quella revisione.
- REVISION-FORMER con il nome della revisione attualmente pubblicata.
- PERCENT-FORMER con la percentuale di traffico che vuoi inviare alla vecchia revisione
Sostituisci il servizio con la nuova configurazione utilizzando il seguente comando:
```
gcloud run services replace service.yaml
```
Attendi il completamento dell'aggiornamento: dovresti vedere un messaggio che indica che è stato eseguito il deployment della nuova revisione che stai implementando gradualmente e che pubblica il valore percentuale di traffico utilizzato.

Terraform

Aggiungi quanto segue al tuo file .tf:

resource "google_cloud_run_v2_service" "default" {
  name     = "cloudrun-srv"
  location = "us-central1"

  template {}

  # Define the traffic split for each revision
  # https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/cloud_run_v2_service#traffic
  traffic {
    # Update revision to 50% traffic
    percent = 50
    # This revision needs to already exist
    revision = "cloudrun-srv-green"
    type     = "TRAFFIC_TARGET_ALLOCATION_TYPE_REVISION"
  }

  traffic {
    # Update tag to 50% traffic
    percent = 50
    # This tag needs to already exist
    tag = "tag-name"
  }
}

Nel corso di un periodo di ore o giorni, se necessario, aggiorna gradualmente da un tag all'altro, aumentando la percentuale in base alle esigenze della revisione con tag.

Applica inserendo terraform apply dopo ogni modifica.

Passaggi successivi

Scopri come utilizzare Cloud Deploy per configurare una pipeline di distribuzione continua di cui eseguire il deployment in Cloud Run.