Configura le variabili di ambiente per i servizi

Questa pagina descrive come configurare le variabili di ambiente per il servizio Cloud Run.

Puoi utilizzare le variabili di ambiente per la configurazione del servizio, ma non le consigliamo come metodo per archiviare secret come le credenziali del database o le chiavi API. I valori sensibili devono essere archiviati al di fuori del codice sorgente e delle variabili di ambiente. Per l'archiviazione dei secret, ti consigliamo di utilizzare Secret Manager. Per configurare i servizi per l'accesso ai secret archiviati in Secret Manager, vedi Configurare i secret.

Qualsiasi modifica alla configurazione comporta la creazione di una nuova revisione. Anche le revisioni successive riceveranno automaticamente questa impostazione di configurazione, a meno che tu non apporti aggiornamenti espliciti per modificarla.

Ruoli obbligatori

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

• Cloud Run Developer (roles/run.developer) sul servizio Cloud Run
• Utente service account (roles/iam.serviceAccountUser) sull'identità di servizio

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

Numero massimo di variabili di ambiente e limiti

Puoi impostare un massimo di 1000 variabili di ambiente per un servizio Cloud Run.

La lunghezza variabile massima è 32 kB.

Imposta le variabili di ambiente

Puoi impostare le variabili di ambiente per i servizi nuovi ed esistenti. Tieni presente che il flag --set-env-vars è un'azione distruttiva che elimina le variabili di ambiente impostate in precedenza non incluse nel nuovo elenco di variabili di ambiente.

Le variabili di ambiente sono associate a una revisione specifica del servizio e non sono visibili ad altri servizi nel tuo progetto Google Cloud .

Puoi impostare le variabili di ambiente utilizzando la console Google Cloud , gcloud CLI o un file YAML quando crei un nuovo servizio o deploy una nuova revisione:

gcloud run deploy SERVICE --image IMAGE_URL --set-env-vars KEY1=VALUE1,KEY2=VALUE2

gcloud run services update SERVICE --image IMAGE_URL --set-env-vars KEY1=VALUE1,KEY2=VALUE2

   [...]
   --set-env-vars "KEY1=VALUE1" \
   --set-env-vars "KEY2=VALUE2" \
   --set-env-vars "KEY3=VALUE3"

--set-env-vars "^@^KEY1=value1,value2,value3@KEY2=..."

resource "google_cloud_run_v2_service" "default" {
  name     = "cloudrun-service-env-var"
  location = "us-central1"

  deletion_protection = false # set to "true" in production

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

      # Environment variables
      env {
        name  = "foo"
        value = "bar"
      }
      env {
        name  = "baz"
        value = "quux"
      }
    }
  }
}

Imposta le variabili di ambiente predefinite nel container

Puoi utilizzare l'istruzione ENV in un Dockerfile per impostare i valori predefiniti per le variabili di ambiente:

ENV KEY1=VALUE1,KEY2=VALUE2

Ordine di precedenza: variabili del container e del servizio

Se imposti una variabile di ambiente predefinita nel container e imposti una variabile di ambiente con lo stesso nome nel servizio Cloud Run, il valore impostato nel servizio ha la precedenza.

Aggiorna le variabili di ambiente

Puoi aggiornare le variabili di ambiente per i servizi esistenti. Si tratta di un approccio non distruttivo che modifica o aggiunge variabili di ambiente, ma non elimina le variabili di ambiente impostate in precedenza.

gcloud run services update SERVICE --update-env-vars KEY1=VALUE1,KEY2=VALUE2

Visualizza le impostazioni delle variabili di ambiente

Per visualizzare le impostazioni correnti delle variabili di ambiente per il servizio Cloud Run:

Elimina le variabili di ambiente

Puoi eliminare le variabili di ambiente per i servizi esistenti.

gcloud run services update SERVICE --remove-env-vars KEY1,KEY2

gcloud run services update SERVICE --clear-env-vars

Best practice

La sezione seguente mette in evidenza alcune delle best practice per la configurazione delle variabili di ambiente.

Variabili di ambiente riservate per i servizi

Le variabili di ambiente definite nel contratto di runtime del container sono riservate e non possono essere impostate. In particolare, la variabile di ambiente PORT viene inserita nel container da Cloud Run. Non devi impostarlo manualmente.

Variabili di ambiente riservate aggiuntive durante il deployment delle funzioni

Cloud Run imposta automaticamente le seguenti variabili di ambiente di runtime quando esegui il deployment delle funzioni:

• FUNCTION_TARGET: la funzione da eseguire.
• FUNCTION_SIGNATURE_TYPE: il tipo di funzione: http per le funzioni HTTP e event per le funzioni basate su eventi.

Alcune variabili di ambiente aggiuntive vengono impostate automaticamente a seconda del runtime utilizzato dalla funzione. Questi si basano sul sistema operativo del runtime, ad esempio DEBIAN_FRONTEND, SHLVL o PATH e sul runtime del linguaggio, ad esempio NODE_ENV, VIRTUAL_ENV o GOPATH.

Le variabili di ambiente fornite dall'ambiente, diverse da quelle impostate automaticamente, potrebbero cambiare nelle versioni future del runtime. Come best practice, ti consigliamo di non fare affidamento su variabili di ambiente che non hai impostato in modo esplicito e di non modificarle.

La modifica delle variabili di ambiente fornite dall'ambiente potrebbe portare a risultati imprevedibili. I tentativi di modificare queste variabili di ambiente potrebbero essere bloccati o, peggio ancora, portare a conseguenze indesiderate, ad esempio funzioni che non possono essere avviate. Come best practice, valuta la possibilità di aggiungere un prefisso a qualsiasi variabile di ambiente con una chiave univoca per evitare conflitti.

Variabili di ambiente non valide

Non puoi utilizzare le seguenti variabili di ambiente:

Codice di esempio

Per un esempio di codice che mostra come accedere alle variabili di ambiente nel codice, fai riferimento a Gestione della configurazione sensibile con Secret Manager nel tutorial sull'autenticazione dell'utente finale.

Passaggi successivi

Puoi utilizzare le variabili di ambiente per impostare la configurazione dei buildpack. Per i dettagli specifici della lingua, consulta la documentazione dei buildpack per:

• Node.js
• Python
• Go
• Ruby
• PHP
• Java

Se esegui il deployment dal codice sorgente e devi personalizzare le variabili in fase di compilazione, consulta Impostare le variabili di ambiente di compilazione.