Configura la scalabilità automatica della CPU per i pool di worker

La scalabilità automatica della CPU nei pool di worker di Cloud Run consente di scalare le istanze in base all'utilizzo medio della CPU per ottimizzare prestazioni e costi. Puoi configurare la scalabilità automatica con il target di utilizzo della CPU predefinito o specificare target di utilizzo della CPU e limiti delle istanze personalizzati. Per saperne di più su come Cloud Run calcola i conteggi delle istanze e scala i pool di worker, consulta Informazioni sulla scalabilità automatica della CPU.

Quando esegui il deployment di un pool di worker senza abilitare la scalabilità automatica della CPU, Cloud Run utilizza la scalabilità manuale con 1 istanza per impostazione predefinita.

Se utilizzi la scalabilità automatica delle metriche esterne di Cloud Run (CREMA) per scalare i tuoi workload, passa alla scalabilità manuale.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per configurare ed eseguire il deployment dei pool di worker Cloud Run, chiedi all'amministratore di concederti i seguenti ruoli IAM:

Per un elenco di ruoli e autorizzazioni IAM associati a Cloud Run, consulta Ruoli IAM di Cloud Run e Autorizzazioni IAM di Cloud Run. Se il tuo pool di worker Cloud Run interagisce con le APIGoogle Cloud , come le librerie client Cloud, consulta la guida alla configurazione dell'identità del servizio. Per saperne di più sulla concessione dei ruoli, consulta Autorizzazioni di deployment e Gestisci l'accesso.

Configura il target CPU predefinito

Quando attivi la scalabilità automatica della CPU predefinita, Cloud Run punta a un utilizzo della CPU del 60% e scala il pool di worker tra 1 e 100 istanze. Pur mantenendo il target di utilizzo della CPU predefinito del 60%, puoi facoltativamente personalizzare i limiti minimi e massimi delle istanze in base alle tue esigenze.

L'aggiornamento della modalità di scalabilità o dei limiti delle istanze in un pool di worker esistente non crea una nuova revisione.

Puoi attivare la scalabilità automatica della CPU predefinita per un pool di worker Cloud Run utilizzando Google Cloud CLI, YAML o l'API REST:

gcloud

  • Per eseguire il deployment di un nuovo pool di worker con la CPU target predefinita, esegui questo comando con il flag --scaling=auto:

    gcloud beta run worker-pools deploy WORKER_POOL \
      --image=IMAGE_URL \
      --scaling=auto

    Sostituisci quanto segue:

    • WORKER_POOL: il nome del tuo pool di worker.
    • IMAGE_URL: un riferimento all'immagine container che contiene il pool di worker, ad esempio us-docker.pkg.dev/cloudrun/container/worker-pool:latest.
  • Per aggiornare un pool di worker esistente in modo che utilizzi il target della CPU predefinito, esegui il seguente comando con il flag --scaling=auto:

    gcloud beta run worker-pools update WORKER_POOL \
      --scaling=auto

    Sostituisci WORKER_POOL con il nome del tuo pool di worker.

  • Per aggiornare un pool di worker esistente con il target CPU predefinito e i limiti di istanze personalizzati, esegui questo comando con i flag --scaling=auto, --min e --max:

    gcloud beta run worker-pools update WORKER_POOL \
      --scaling=auto \
      --min=MIN_INSTANCES \
      --max=MAX_INSTANCES

    Sostituisci quanto segue:

    • WORKER_POOL: il nome del tuo pool di worker.
    • (Facoltativo) MIN_INSTANCES: il numero minimo di istanze di container da eseguire per il pool di worker. Deve essere pari o superiore a 1. Se ometti questo valore, Cloud Run imposta il numero minimo su 1 istanza.
    • (Facoltativo) MAX_INSTANCES: il numero massimo di istanze di container da eseguire per il pool di worker. Se ometti questo valore, Cloud Run imposta il numero massimo su 100 istanze.

YAML

  1. Se stai creando un nuovo pool di worker, salta questo passaggio. Se stai aggiornando un pool di worker esistente, scarica la relativa configurazione YAML:

    gcloud run worker-pools describe WORKER_POOL --format export > worker-pool.yaml
  2. Aggiungi o aggiorna le annotazioni launch-stage e scalingMode in metadata.annotations e rimuovi l'annotazione run.googleapis.com/manualInstanceCount, se presente. Per impostare limiti di istanze personalizzati, aggiungi facoltativamente le annotazioni minScale e maxScale:

    apiVersion: run.googleapis.com/v1
    kind: WorkerPool
    metadata:
     name: WORKER_POOL
     annotations:
       run.googleapis.com/launch-stage: BETA
       run.googleapis.com/scalingMode: automatic
       run.googleapis.com/minScale: 'MIN_INSTANCES'
       run.googleapis.com/maxScale: 'MAX_INSTANCES'

    Sostituisci quanto segue:

    • WORKER_POOL: il nome del tuo pool di worker.
    • (Facoltativo) MIN_INSTANCES: il numero minimo di istanze di container da eseguire per il pool di worker. Deve essere pari o superiore a 1. Se ometti questo valore, Cloud Run imposta il numero minimo su 1 istanza.
    • (Facoltativo) MAX_INSTANCES: il numero massimo di istanze di container da eseguire per il pool di worker. Se ometti questo valore, Cloud Run imposta il numero massimo su 100 istanze.
  3. Crea o aggiorna il pool di worker utilizzando il seguente comando:

    gcloud run worker-pools replace worker-pool.yaml

    Per impostazione predefinita, il comando gcloud run worker-pools replace utilizza il file worker-pool.yaml, se presente.

API REST

Per configurare il target CPU predefinito su un pool di worker esistente, invia la seguente richiesta HTTP PATCH all'workerPools.patchendpoint dell'API Cloud Run Admin . Per impostare limiti di istanze personalizzati, includi facoltativamente i campi minInstanceCount e maxInstanceCount e i relativi percorsi update_mask:

curl -H "Content-Type: application/json" \
    -H "Authorization: Bearer ACCESS_TOKEN" \
    -X PATCH \
    -d '{"launchStage":"BETA","scaling":{"scalingMode":"AUTOMATIC","minInstanceCount":MIN_INSTANCES,"maxInstanceCount":MAX_INSTANCES}}' \
    https://run.googleapis.com/v2/projects/PROJECT_ID/locations/REGION/workerPools/WORKER_POOL?update_mask=launchStage,scaling.scalingMode,scaling.manualInstanceCount,scaling.minInstanceCount,scaling.maxInstanceCount

Sostituisci quanto segue:

  • ACCESS_TOKEN: un token di accesso valido per un account che dispone delle autorizzazioni di Identity and Access Management per aggiornare un pool di worker. Ad esempio, se hai eseguito l'accesso a Google Cloud CLI, puoi recuperare un token di accesso eseguendo gcloud auth print-access-token.
  • (Facoltativo) MIN_INSTANCES: il numero minimo di istanze di container da eseguire per il pool di worker. Deve essere 1 o un numero superiore. Se ometti questo valore, Cloud Run imposta il numero minimo su 1 istanza.
  • (Facoltativo) MAX_INSTANCES: il numero massimo di istanze di container da eseguire per il pool di worker. Se ometti questo valore, Cloud Run imposta il numero massimo su 100 istanze.
  • PROJECT_ID: il tuo ID progetto Google Cloud .
  • REGION: la regione Google Cloud in cui è stato eseguito il deployment del pool di worker, ad esempio europe-west1.
  • WORKER_POOL: il nome del tuo pool di worker.

Configura i target della CPU e i limiti delle istanze personalizzati

Puoi personalizzare il target di utilizzo della CPU, i limiti minimi e massimi delle istanze o entrambi. Qualsiasi impostazione omessa utilizza il valore predefinito (target CPU del 60%, 1 istanza minima e 100 istanze massime). L'aggiornamento del target di utilizzo della CPU o dei limiti delle istanze in un pool di worker esistente non crea una nuova revisione.

Puoi configurare target di CPU personalizzati e limiti di istanze utilizzando Google Cloud CLI, YAML o l'API REST:

gcloud

  • Per eseguire il deployment di un nuovo pool di worker con un target CPU personalizzato, esegui questo comando con il flag --scaling-cpu-target:

    gcloud beta run worker-pools deploy WORKER_POOL \
      --image=IMAGE_URL \
      --scaling-cpu-target=CPU_TARGET

    Sostituisci quanto segue:

    • WORKER_POOL: il nome del tuo pool di worker.
    • IMAGE_URL: un riferimento all'immagine container che contiene il pool di worker, ad esempio us-docker.pkg.dev/cloudrun/container/worker-pool:latest.
    • CPU_TARGET: il target per l'utilizzo della CPU. Specifica un valore compreso tra 0.1 e 0.90.
  • Per aggiornare un pool di worker esistente con un target della CPU personalizzato, esegui il seguente comando con il flag --scaling-cpu-target:

    gcloud beta run worker-pools update WORKER_POOL \
      --scaling-cpu-target=CPU_TARGET

    Sostituisci quanto segue:

    • WORKER_POOL: il nome del tuo pool di worker.
    • CPU_TARGET: il target per l'utilizzo della CPU. Specifica un valore compreso tra 0.1 e 0.90.
  • Per aggiornare un pool di worker esistente con un target della CPU personalizzato e limiti di istanze, esegui questo comando con i flag --scaling-cpu-target, --min e --max:

    gcloud beta run worker-pools update WORKER_POOL \
      --scaling-cpu-target=CPU_TARGET \
      --min=MIN_INSTANCES \
      --max=MAX_INSTANCES

    Sostituisci quanto segue:

    • WORKER_POOL: il nome del tuo pool di worker.
    • CPU_TARGET: il target per l'utilizzo della CPU. Specifica un valore compreso tra 0.1 e 0.90.
    • (Facoltativo) MIN_INSTANCES: il numero minimo di istanze di container da eseguire per il pool di worker. Deve essere pari o superiore a 1. Se ometti questo valore, Cloud Run imposta il numero minimo su 1 istanza.
    • (Facoltativo) MAX_INSTANCES: il numero massimo di istanze di container da eseguire per il pool di worker. Se ometti questo valore, Cloud Run imposta il numero massimo su 100 istanze.

YAML

  1. Se stai creando un nuovo pool di worker, salta questo passaggio. Se stai aggiornando un pool di worker esistente, scarica la relativa configurazione YAML:

    gcloud run worker-pools describe WORKER_POOL --format export > worker-pool.yaml
  2. Aggiungi o aggiorna le annotazioni launch-stage, scalingMode, scaling-cpu-target, minScale e maxScale in metadata.annotations e rimuovi l'annotazione run.googleapis.com/manualInstanceCount se presente. Puoi omettere qualsiasi annotazione personalizzata (scaling-cpu-target, minScale o maxScale) che vuoi mantenere al valore predefinito:

    apiVersion: run.googleapis.com/v1
    kind: WorkerPool
    metadata:
     name: WORKER_POOL
     annotations:
       run.googleapis.com/launch-stage: BETA
       run.googleapis.com/scalingMode: automatic
       run.googleapis.com/scaling-cpu-target: 'CPU_TARGET'
       run.googleapis.com/minScale: 'MIN_INSTANCES'
       run.googleapis.com/maxScale: 'MAX_INSTANCES'

    Sostituisci quanto segue:

    • WORKER_POOL: il nome del tuo pool di worker.
    • CPU_TARGET: il target per l'utilizzo della CPU. Specifica un valore compreso tra 0.1 e 0.90.
    • (Facoltativo) MIN_INSTANCES: il numero minimo di istanze di container da eseguire per il pool di worker. Deve essere pari o superiore a 1. Se ometti questo valore, Cloud Run imposta il numero minimo su 1 istanza.
    • (Facoltativo) MAX_INSTANCES: il numero massimo di istanze di container da eseguire per il pool di worker. Se ometti questo valore, Cloud Run imposta il numero massimo su 100 istanze.
  3. Crea o aggiorna il pool di worker utilizzando il seguente comando:

    gcloud run worker-pools replace worker-pool.yaml

    Per impostazione predefinita, il comando gcloud run worker-pools replace utilizza il file worker-pool.yaml, se presente.

API REST

Per configurare un target CPU personalizzato e limiti di istanze personalizzati su un pool di worker esistente, invia la seguente richiesta HTTP PATCH all'endpoint workerPools.patch dell'API Cloud Run Admin:

curl -H "Content-Type: application/json" \
    -H "Authorization: Bearer ACCESS_TOKEN" \
    -X PATCH \
    -d '{"launchStage":"BETA","scaling":{"scalingMode":"AUTOMATIC","cpuScaling":{"cpuUtilization":CPU_TARGET},"minInstanceCount":MIN_INSTANCES,"maxInstanceCount":MAX_INSTANCES}}' \
    https://run.googleapis.com/v2/projects/PROJECT_ID/locations/REGION/workerPools/WORKER_POOL?update_mask=launchStage,scaling.scalingMode,scaling.manualInstanceCount,scaling.cpuScaling.cpuUtilization,scaling.minInstanceCount,scaling.maxInstanceCount

Sostituisci quanto segue:

  • ACCESS_TOKEN: un token di accesso valido per un account con le autorizzazioni IAM per aggiornare un pool di worker. Ad esempio, se hai eseguito l'accesso a Google Cloud CLI, puoi recuperare un token di accesso eseguendo gcloud auth print-access-token.
  • CPU_TARGET: il target per l'utilizzo della CPU. Specifica un valore compreso tra 0.1 e 0.90.
  • (Facoltativo) MIN_INSTANCES: il numero minimo di istanze di container da eseguire per il pool di worker. Deve essere pari o superiore a 1. Se ometti questo valore, Cloud Run imposta il numero minimo su 1 istanza.
  • (Facoltativo) MAX_INSTANCES: il numero massimo di istanze di container da eseguire per il pool di worker. Se ometti questo valore, Cloud Run imposta il numero massimo su 100 istanze.
  • PROJECT_ID: il tuo ID progetto Google Cloud .
  • REGION: la regione Google Cloud in cui è stato eseguito il deployment del pool di worker, ad esempio europe-west1.
  • WORKER_POOL: il nome del tuo pool di worker.

Ripristina le impostazioni di scalabilità automatica predefinite

Quando ripristini i valori predefiniti di un target di utilizzo della CPU personalizzato o dei limiti delle istanze personalizzati, Cloud Run torna al target predefinito del 60% di utilizzo della CPU, 1 istanza minima e 100 istanze massime, mantenendo attiva la scalabilità automatica della CPU.

Puoi ripristinare le impostazioni di scalabilità automatica predefinite utilizzando Google Cloud CLI, YAML o l'API REST:

gcloud

  • Per ripristinare la CPU di destinazione predefinita, esegui questo comando con il flag --scaling-cpu-target=default:

    gcloud beta run worker-pools update WORKER_POOL \
      --scaling-cpu-target=default

    Sostituisci WORKER_POOL con il nome del tuo pool di worker.

  • Per ripristinare i limiti predefiniti delle istanze, esegui questo comando con i flag --min=default e --max=default:

    gcloud beta run worker-pools update WORKER_POOL \
      --min=default \
      --max=default

    Sostituisci WORKER_POOL con il nome del tuo pool di worker.

YAML

  1. Se stai creando un nuovo pool di worker, salta questo passaggio. Se stai aggiornando un pool di worker esistente, scarica la relativa configurazione YAML:

    gcloud run worker-pools describe WORKER_POOL --format export > worker-pool.yaml
  2. Rimuovi le annotazioni scaling-cpu-target, minScale e maxScale da metadata.annotations. Aggiorna l'annotazione scalingMode: automatic:

    apiVersion: run.googleapis.com/v1
    kind: WorkerPool
    metadata:
     name: WORKER_POOL
     annotations:
       run.googleapis.com/launch-stage: BETA
       run.googleapis.com/scalingMode: automatic

    Sostituisci WORKER_POOL con il nome del tuo pool di worker.

  3. Crea o aggiorna il pool di worker utilizzando il seguente comando:

    gcloud run worker-pools replace worker-pool.yaml

    Per impostazione predefinita, il comando gcloud run worker-pools replace utilizza il file worker-pool.yaml, se presente.

API REST

Per ripristinare i limiti predefiniti di CPU target e istanze in un pool di worker esistente, invia la seguente richiesta HTTP PATCH all'endpoint workerPools.patch dell'API Cloud Run Admin:

curl -H "Content-Type: application/json" \
    -H "Authorization: Bearer ACCESS_TOKEN" \
    -X PATCH \
    -d '{"launchStage":"BETA","scaling":{"scalingMode":"AUTOMATIC","cpuScaling":{}}}' \
    https://run.googleapis.com/v2/projects/PROJECT_ID/locations/REGION/workerPools/WORKER_POOL?update_mask=launchStage,scaling.scalingMode,scaling.cpuScaling.cpuUtilization,scaling.minInstanceCount,scaling.maxInstanceCount

Sostituisci quanto segue:

  • ACCESS_TOKEN: un token di accesso valido per un account con le autorizzazioni IAM per aggiornare un pool di worker. Ad esempio, se hai eseguito l'accesso a Google Cloud CLI, puoi recuperare un token di accesso eseguendo gcloud auth print-access-token.
  • PROJECT_ID: il tuo ID progetto Google Cloud .
  • REGION: la regione Google Cloud in cui è stato eseguito il deployment del pool di worker, ad esempio europe-west1.
  • WORKER_POOL: il nome del tuo pool di worker.

Disabilita la scalabilità automatica della CPU

Per disattivare la scalabilità automatica della CPU e tornare alla scalabilità manuale del pool di worker, specifica un numero fisso di istanze utilizzando Google Cloud CLI, YAML o l'API REST:

gcloud

Per disattivare la scalabilità automatica della CPU su un pool di worker esistente, esegui questo comando con il flag --scaling impostato sul numero di istanze fisse:

gcloud beta run worker-pools update WORKER_POOL \
    --scaling=INSTANCE_COUNT

Sostituisci quanto segue:

  • WORKER_POOL: il nome del tuo pool di worker.
  • INSTANCE_COUNT: il numero fisso di istanze da eseguire in modalità di scalabilità manuale.

YAML

  1. Se stai creando un nuovo pool di worker, salta questo passaggio. Se stai aggiornando un pool di worker esistente, scarica la relativa configurazione YAML:

    gcloud run worker-pools describe WORKER_POOL --format export > worker-pool.yaml
  2. Imposta scalingMode su manual, specifica manualInstanceCount e rimuovi scaling-cpu-target, minScale e maxScale se presenti:

    apiVersion: run.googleapis.com/v1
    kind: WorkerPool
    metadata:
     name: WORKER_POOL
     annotations:
       run.googleapis.com/scalingMode: manual
       run.googleapis.com/manualInstanceCount: "INSTANCE_COUNT"

    Sostituisci quanto segue:

    • WORKER_POOL: il nome del tuo pool di worker.
    • INSTANCE_COUNT: il numero fisso di istanze da eseguire in modalità di scalabilità manuale.
  3. Crea o aggiorna il pool di worker utilizzando il seguente comando:

    gcloud run worker-pools replace worker-pool.yaml

    Per impostazione predefinita, il comando gcloud run worker-pools replace utilizza il file worker-pool.yaml, se presente.

API REST

Per disabilitare la scalabilità automatica della CPU su un pool di worker esistente, invia la seguente richiesta HTTP PATCH all'endpoint workerPools.patch dell'API Cloud Run Admin:

curl -H "Content-Type: application/json" \
    -H "Authorization: Bearer ACCESS_TOKEN" \
    -X PATCH \
    -d '{"scaling":{"scalingMode":"MANUAL","manualInstanceCount":INSTANCE_COUNT}}' \
    https://run.googleapis.com/v2/projects/PROJECT_ID/locations/REGION/workerPools/WORKER_POOL?update_mask=scaling.scalingMode,scaling.manualInstanceCount,scaling.cpuScaling,scaling.minInstanceCount,scaling.maxInstanceCount

Sostituisci quanto segue:

  • ACCESS_TOKEN: un token di accesso valido per un account con le autorizzazioni IAM per aggiornare un pool di worker. Ad esempio, se hai eseguito l'accesso a Google Cloud CLI, puoi recuperare un token di accesso eseguendo gcloud auth print-access-token.
  • INSTANCE_COUNT: il numero fisso di istanze da eseguire in modalità di scalabilità manuale.
  • PROJECT_ID: il tuo ID progetto Google Cloud .
  • REGION: la regione Google Cloud in cui è stato eseguito il deployment del pool di worker, ad esempio europe-west1.
  • WORKER_POOL: il nome del tuo pool di worker.

Visualizza le impostazioni di scalabilità automatica della CPU

Per visualizzare la configurazione della scalabilità automatica della CPU per il tuo pool di worker, esegui il comando gcloud beta run worker-pools describe:

gcloud beta run worker-pools describe WORKER_POOL

Sostituisci WORKER_POOL con il nome del tuo pool di worker.

Informazioni sulla scalabilità automatica della CPU

Per impostazione predefinita, la scalabilità automatica della CPU ha come target un utilizzo medio della CPU del 60% (run.googleapis.com/container/cpu/utilizations) e scala il pool di worker tra 1 e 100 istanze.

Quando attivi la scalabilità automatica della CPU, Cloud Run calcola il numero di istanze richieste per il pool di worker calcolando la media dell'utilizzo della CPU al secondo nell'ultimo minuto in tutte le istanze in esecuzione e divide questo valore per il numero di CPU per istanza. Il risultato viene poi ulteriormente diviso per il target della CPU:

\[ \text{Instances} = \left\lceil \dfrac{\left( \frac{\text{Average CPU usage per second over the past minute}}{\text{Number of CPUs per instance}} \right)}{\text{CPU target}} \right\rceil \]

Cloud Run regola il numero di istanze del pool di worker utilizzando i seguenti comportamenti:

  • Arrotondamento per eccesso: Cloud Run calcola il numero di istanze richieste in base all'utilizzo della CPU misurato e al target, non in base al numero di istanze in esecuzione, e arrotonda il risultato per eccesso all'istanza intera successiva. A causa di questo arrotondamento, il pool di worker può fare lo scale up anche se l'utilizzo è ancora inferiore al target. Ad esempio, un pool di worker che richiede 4,1 istanze esegue 5 istanze.
  • Scalabilità a livello di pool e suddivisioni delle istanze: Cloud Run calcola il numero totale di istanze per l'intero pool di worker e poi le distribuisce tra le revisioni attive in base alle suddivisioni delle istanze configurate.
  • Stabilizzazione dello scale down di 5 minuti: Cloud Run utilizza una finestra di stabilizzazione di 5 minuti (300 secondi) durante lo scale down. Per evitare frequenti fluttuazioni delle istanze, Cloud Run mantiene il numero di istanze al livello più alto consigliato nei 5 minuti precedenti.

Scegli un target di utilizzo della CPU

Puoi utilizzare il target di utilizzo della CPU predefinito del 60% o configurare un target personalizzato compreso tra il 10% e il 90% in base al profilo del workload e alla tolleranza alla latenza utilizzando le seguenti linee guida:

  • Target di CPU più elevato (85%-90%): utilizza un target più elevato per workload in background costanti e prevedibili o attività di elaborazione batch che non sono sensibili alla latenza. Un target più elevato massimizza l'utilizzo delle risorse e riduce i costi dell'infrastruttura, ma lascia meno spazio per picchi di lavoro improvvisi, il che può portare alla limitazione della CPU o a una maggiore latenza di elaborazione durante l'avvio di nuove istanze.
  • Target di CPU inferiore (dal 20% al 40%): utilizza un target inferiore per i workload con una domanda di CPU instabile o imprevedibile, requisiti di latenza di elaborazione rigorosi o tempi di avvio dei container più lunghi. Un target più basso fornisce un buffer per assorbire picchi di attività improvvisi eseguendo il provisioning di più istanze in anticipo, contribuendo a prevenire il peggioramento delle prestazioni. Il compromesso è un costo più elevato, perché in condizioni di carico normali vengono eseguite più istanze.

Ti consigliamo di iniziare con il target predefinito, monitorare la metrica run.googleapis.com/container/instance_count in Cloud Monitoring e modificare il target in base ai test di carico e alle osservazioni sulle prestazioni.

Passaggi successivi