Configura le variabili di ambiente

Puoi eseguire il deployment di coppie chiave/valore arbitrarie insieme a una funzione Cloud Run. Queste coppie vengono rese disponibili alla funzione come variabili di ambiente letterali, accessibili dal codice in fase di esecuzione o come informazioni di configurazione per i buildpack di Google Cloud.

Le variabili di ambiente sono associate a una singola funzione e non sono visibili alle altre funzioni del progetto Google Cloud. Ogni variabile viene archiviata nel backend delle funzioni Cloud Run ed esiste nello stesso ciclo di vita della funzione a cui è associata.

Puoi aggiungere o rimuovere le variabili di ambiente di runtime utilizzando Google Cloud CLI o la console Google Cloud.

Impostazione delle variabili di ambiente di runtime

Utilizza questi metodi per stabilire nuove variabili o sostituire completamente quelle esistenti. Per apportare modifiche additive, utilizza la procedura di aggiornamento descritta nella sezione successiva.

gcloud

Per impostare una variabile di ambiente di runtime utilizzando Google Cloud CLI, utilizza il flag --set-env-vars al momento del deployment:

gcloud functions deploy FUNCTION_NAME --set-env-vars FOO=bar FLAGS ...

Puoi anche impostare più variabili d'ambiente di runtime utilizzando un elenco separato da virgole:

gcloud functions deploy FUNCTION_NAME --set-env-vars FOO=bar,BAZ=boo FLAGS...

Se vuoi memorizzare la configurazione in un file (ad es. in un controllo delle versioni), puoi utilizzare un file YAML insieme al flag --env-vars-file:

gcloud functions deploy FUNCTION_NAME --env-vars-file .env.yaml FLAGS...

dove i contenuti del file .env.yaml sono:

 FOO: bar
 BAZ: boo

Negli esempi precedenti, FLAGS... fa riferimento ad altre opzioni che passi durante il deployment della funzione. Per un riferimento completo al comando deploy, consulta gcloud functions deploy.

UI di Google Cloud Console

Puoi impostare le variabili di ambiente di runtime durante la creazione della funzione nella console Google Cloud:

1. Apri la pagina Panoramica di Functions nella console Google Cloud:

   Vai alla pagina Panoramica delle funzioni Cloud Run.

2. Fai clic su Crea funzione.

3. Compila i campi obbligatori per la funzione.

4. Apri la sezione Impostazioni di runtime, build e connessioni.

5. Seleziona la scheda Runtime.

6. Nella sezione Variabili di ambiente runtime, fai clic su Aggiungi variabile e aggiungi il nome e il valore.

   Per istruzioni su come aggiungere variabili di ambiente a una funzione esistente, consulta Aggiornare le variabili di ambiente runtime.

Aggiornamento delle variabili di ambiente runtime

Puoi anche aggiornare le variabili di ambiente di runtime per le funzioni esistenti. Si tratta di un approccio non distruttivo che modifica o aggiunge le variabili di ambiente di runtime, ma non le elimina.

gcloud

Per aggiornare una variabile utilizzando Google Cloud CLI, utilizza il --update-env-vars flag al momento del deployment:

gcloud functions deploy FUNCTION_NAME --update-env-vars FOO=bar

Puoi anche aggiornare più variabili d'ambiente di runtime utilizzando un elenco separato da virgole:

gcloud functions deploy FUNCTION_NAME --update-env-vars FOO=bar,BAZ=boo

UI di Google Cloud Console

Per aggiornare le variabili di ambiente di runtime utilizzando la console Google Cloud:

1. Apri la pagina Panoramica di Functions nella console Google Cloud:

   Vai alla pagina Panoramica delle funzioni Cloud Run.

2. Fai clic su una funzione esistente per aprire la relativa pagina dei dettagli.

3. Fai clic su Modifica.

4. Apri la sezione Impostazioni di runtime, build e connessioni.

5. Seleziona la scheda Runtime.

6. Apporta le modifiche nella sezione Variabili di ambiente runtime.

Eliminazione delle variabili di ambiente runtime

gcloud

Se vuoi rimuovere in modo selettivo le variabili di ambiente di runtime, puoi utilizzare il flag --remove-env-vars al momento del deployment:

gcloud functions deploy FUNCTION_NAME --remove-env-vars FOO,BAZ

In alternativa, puoi cancellare tutte le variabili di ambiente di runtime impostate in precedenza con il flag --clear-env-vars:

gcloud functions deploy FUNCTION_NAME --clear-env-vars

UI di Google Cloud Console

Per eliminare le variabili di ambiente di runtime utilizzando la console Google Cloud:

1. Apri la pagina Panoramica di Functions nella console Google Cloud:

   Vai alla pagina Panoramica delle funzioni Cloud Run.

2. Fai clic su una funzione esistente per aprire la relativa pagina dei dettagli.

3. Fai clic su Modifica.

4. Apri la sezione Impostazioni di runtime, build e connessioni.

5. Seleziona la scheda Runtime.

6. Nella sezione Variabili di ambiente runtime, fai clic sull'icona del cestino accanto alla coppia chiave/valore per eliminarla.

Variabili di ambiente runtime impostate automaticamente

Questa sezione elenca le variabili di ambiente runtime impostate automaticamente.

Chiave	Descrizione
FUNCTION_TARGET	Riservato: la funzione da eseguire.
FUNCTION_SIGNATURE_TYPE	Riservato: il tipo di funzione: http per le funzioni HTTP e event per le funzioni basate sugli eventi.
K_SERVICE	Riservato: il nome della risorsa funzione.
K_REVISION	Riservato: l'identificatore della versione della funzione.
PORT	Riservato: la porta su cui viene richiamata la funzione.

Nota: se la funzione richiede una delle variabili di ambiente di un runtime precedente, puoi impostarla durante il deployment della funzione. Ad esempio:

gcloud functions deploy envVarMemory \
--runtime nodejs10 \
--set-env-vars FUNCTION_MEMORY_MB=2Gi \
--memory 2Gi \
--trigger-http

Impostazione e recupero delle variabili di ambiente di runtime: un esempio

Imposta la variabile di ambiente di runtime:

Node.js

gcloud functions deploy envVar \
--runtime nodejs22 \
--set-env-vars FOO=bar \
--trigger-http

Utilizza il flag --runtime per specificare l'ID runtime di una versione di Node.js supportata per eseguire la funzione.

Python

gcloud functions deploy env_vars \
--runtime python312 \
--set-env-vars FOO=bar \
--trigger-http

Utilizza il flag --runtime per specificare l'ID runtime di una versione di Python supportata per eseguire la funzione.

Vai

gcloud functions deploy EnvVar \
--runtime go122 \
--set-env-vars FOO=bar \
--trigger-http

Utilizza il flag --runtime per specificare l'ID runtime di una versione Go supportata per eseguire la funzione.

Java

gcloud functions deploy java-envVar-function \
--entry-point functions.EnvVars \
--runtime java21 \
--memory 512MB \
--set-env-vars FOO=bar \
--trigger-http

Utilizza il flag --runtime per specificare l'ID runtime di una versione Java supportata per eseguire la funzione.

C#

gcloud functions deploy csharp-envVar-function \
--entry-point EnvironmentVariables.Function \
--runtime dotnet8 \
--set-env-vars FOO=bar \
--trigger-http

Utilizza il flag --runtime per specificare l'ID runtime di una versione .NET supportata per eseguire la funzione.

Ruby

gcloud functions deploy env_vars --runtime ruby33 \
--set-env-vars FOO=bar \
--trigger-http

Utilizza il flag --runtime per specificare l'ID runtime di una versione di Ruby supportata per eseguire la funzione.

PHP

 gcloud functions deploy envVar --runtime php83 \
--set-env-vars FOO=bar \
--trigger-http

Utilizza il flag --runtime per specificare l'ID runtime di una versione PHP supportata per eseguire la funzione.

In fase di esecuzione, accedi alle variabili in modo programmatico:

Node.js

In Node.js, utilizza la proprietà process.env per accedere alle variabili di ambiente di runtime:

exports.envVar = (req, res) => {
  // Sends 'bar' as response
  res.send(process.env.FOO);
};

Python

In Python, utilizza os.environ per accedere alle variabili di ambiente runtime:

import os


def env_vars(request):
    return os.environ.get("FOO", "Specified environment variable is not set.")

Vai

In Go, utilizza os.Getenv() per accedere alle variabili di ambiente runtime:

// Package tips contains tips for writing Cloud Functions in Go.
package tips

import (
	"fmt"
	"net/http"
	"os"
)

// EnvVar is an example of getting an environment variable in a Go function.
func EnvVar(w http.ResponseWriter, r *http.Request) {
	fmt.Fprintf(w, "FOO: %q", os.Getenv("FOO"))
}

Java

In Java, utilizza System.getenv per accedere alle variabili di ambiente di runtime:

import com.google.cloud.functions.HttpFunction;
import com.google.cloud.functions.HttpRequest;
import com.google.cloud.functions.HttpResponse;
import java.io.BufferedWriter;
import java.io.IOException;

public class EnvVars implements HttpFunction {

  // Returns the environment variable "foo" set during function deployment.
  @Override
  public void service(HttpRequest request, HttpResponse response)
      throws IOException {
    BufferedWriter writer = response.getWriter();
    String foo = System.getenv("FOO");
    if (foo == null) {
      foo = "Specified environment variable is not set.";
    }
    writer.write(foo);
  }
}

C#

In fase di runtime, le variabili di ambiente sono accessibili utilizzando Environment.GetEnvironmentVariable in C#:

using Google.Cloud.Functions.Framework;
using Microsoft.AspNetCore.Http;
using System;
using System.Threading.Tasks;

namespace EnvironmentVariables;

public class Function : IHttpFunction
{
    public async Task HandleAsync(HttpContext context)
    {
        string foo = Environment.GetEnvironmentVariable("FOO")
            ?? "Specified environment variable is not set.";
        await context.Response.WriteAsync(foo, context.RequestAborted);
    }
}

Ruby

In fase di runtime, le variabili di ambiente sono accessibili utilizzando ENV in Ruby:

require "functions_framework"

FunctionsFramework.http "env_vars" do |_request|
  ENV["FOO"] || "Specified environment variable is not set."
end

PHP

In fase di runtime, le variabili di ambiente sono accessibili utilizzando la funzione getenv di PHP:

use Psr\Http\Message\ServerRequestInterface;

function envVar(ServerRequestInterface $request): string
{
    return getenv('FOO') . PHP_EOL;
}

Utilizzo delle variabili di ambiente di compilazione

Puoi anche impostare le variabili di ambiente di compilazione per i runtime che supportano i buildpacks.

Le variabili di ambiente di build sono coppie chiave/valore di cui viene eseguito il deployment insieme a una funzione che ti consente di passare le informazioni di configurazione ai buildpack. Ad esempio, potresti voler personalizzare le opzioni del compilatore. Puoi aggiungere o rimuovere queste variabili di ambiente di compilazione utilizzando Google Cloud CLI o l'interfaccia utente della console Google Cloud.

Nota: le chiavi devono iniziare con una lettera ASCII maiuscola e essere costituite da lettere ASCII maiuscole, cifre e trattini bassi. Evita di creare chiavi di variabili con un prefisso GOOGLE_*. Visualizza tutte le variabili di ambiente dei buildpack supportate.

Impostazione delle variabili di ambiente di compilazione

Utilizza questi metodi per stabilire nuove variabili o sostituire completamente quelle esistenti. Per apportare modifiche additive, utilizza la procedura di aggiornamento (--update-build-env-vars in gcloud) descritta nella sezione successiva.

gcloud

Per impostare una variabile utilizzando Google Cloud CLI, utilizza il --set-build-env-vars flag al momento del deployment:

gcloud beta functions deploy FUNCTION_NAME --set-build-env-vars FOO=bar FLAGS...

Puoi anche impostare più variabili d'ambiente di compilazione utilizzando un elenco separato da virgole:

gcloud functions deploy FUNCTION_NAME --set-build-env-vars FOO=bar,BAZ=boo FLAGS...

Se vuoi memorizzare la configurazione in un file (ad es. sotto il controllo del codice sorgente), puoi utilizzare un file YAML insieme al flag --build-env-vars-file:

gcloud functions deploy FUNCTION_NAME --build-env-vars-file FILE_NAME.yaml FLAGS...

dove i contenuti del file *.yaml sono:

 FOO: bar
 BAZ: boo

Negli esempi precedenti, FLAGS... si riferisce ad altre opzioni che passi durante il deployment della funzione. Per una documentazione completa del comando deploy, consulta gcloud beta functions deploy.

UI di Google Cloud Console

Puoi anche impostare le variabili di ambiente di compilazione durante la creazione della funzione nella console Google Cloud:

1. Apri la pagina Panoramica di Functions nella console Google Cloud:

   Vai alla pagina Panoramica delle funzioni Cloud Run.

2. Fai clic su Crea funzione.

3. Compila i campi obbligatori per la funzione.

4. Apri la sezione Impostazioni di runtime, build e connessioni.

5. Seleziona la scheda Crea.

6. Nella sezione Variabili di ambiente di compilazione, fai clic su Aggiungi variabile e aggiungi il nome e il valore.

Aggiornamento delle variabili di ambiente di build

Puoi anche aggiornare le variabili di ambiente di compilazione per le funzioni esistenti. Si tratta di un approccio non distruttivo che modifica o aggiunge le variabili dell'ambiente di compilazione, ma non le elimina.

gcloud

Per impostare una variabile utilizzando Google Cloud CLI, utilizza il --update-build-env-vars flag al momento del deployment:

gcloud functions deploy FUNCTION_NAME --update-build-env-vars FOO=bar

Puoi anche aggiornare più variabili d'ambiente di compilazione utilizzando un elenco separato da virgole:

gcloud functions deploy FUNCTION_NAME --update-build-env-vars FOO=bar,BAZ=boo

UI di Google Cloud Console

Per aggiornare le variabili di ambiente di compilazione utilizzando la console Google Cloud:

1. Apri la pagina Panoramica di Functions nella console Google Cloud:

   Vai alla pagina Panoramica delle funzioni Cloud Run.

2. Fai clic su una funzione esistente per aprire la relativa pagina dei dettagli.

3. Fai clic su Modifica.

4. Apri la sezione Impostazioni di runtime, build e connessioni.

5. Seleziona la scheda Crea.

6. Apporta le modifiche nella sezione Variabili di ambiente di build.

Eliminazione delle variabili di ambiente di build

gcloud

Se vuoi rimuovere in modo selettivo le variabili di ambiente di compilazione, puoi utilizzare il --remove-build-env-vars flag al momento del deployment:

gcloud functions deploy FUNCTION_NAME --remove-build-env-vars FOO,BAZ

In alternativa, puoi cancellare tutte le variabili di ambiente di compilazione impostate in precedenza con il --clear-build-env-vars flag:

gcloud functions deploy FUNCTION_NAME --clear-build-env-vars

UI di Google Cloud Console

Per eliminare le variabili di ambiente di compilazione utilizzando la console Google Cloud:

1. Apri la pagina Panoramica di Functions nella console Google Cloud:

   Vai alla pagina Panoramica delle funzioni Cloud Run.

2. Fai clic su una funzione esistente per aprire la relativa pagina dei dettagli.

3. Fai clic su Modifica.

4. Apri la sezione Impostazioni di runtime, build e connessioni.

5. Seleziona la scheda Crea.

6. Nella sezione Variabili di ambiente di compilazione, fai clic sull'icona del cestino accanto alla coppia chiave/valore per eliminarla.

Ciclo di vita delle variabili

Tutte le variabili di ambiente sono associate a un deployment di una funzione Cloud Run e possono essere impostate o modificate solo con un deployment. Se un deployment non va a buon fine per qualsiasi motivo, le modifiche alle variabili di ambiente non verranno applicate. Le modifiche alle variabili di ambiente richiedono un deployment riuscito.

Best practice e variabili di ambiente riservate

Alcune variabili di ambiente aggiuntive vengono impostate automaticamente in base al runtime utilizzato dalla funzione. Questi valori 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 elencate in VARIABILI DI AMBIENTE IMPOSTE AUTOMATICAMENTE) potrebbero cambiare nelle versioni future del runtime. Come best practice, ti consigliamo di non fare affidamento su o modificare le variabili di ambiente che non hai impostato esplicitamente.

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, portare a conseguenze indesiderate come funzioni che non possono essere avviate. Come best practice, ti consigliamo di anteporre un prefisso a tutte le variabili di ambiente con una chiave univoca per evitare conflitti.

Infine, non puoi utilizzare le seguenti variabili di ambiente:

Chiave	Descrizione
Vuoto ("'")	Le chiavi non possono essere una stringa vuota.
=	Le chiavi non possono contenere il carattere "=".
X_GOOGLE_	Le chiavi non possono contenere il prefisso X_GOOGLE_.

Nota: le variabili di ambiente visualizzate nell'ambiente di esecuzione, ma non documentate nella tabella precedente, devono essere considerate obsolete e potrebbero scomparire in qualsiasi momento senza preavviso.

Limiti di dimensioni

Il numero totale di byte utilizzati dai nomi e dai valori delle variabile di ambiente di runtime per una singola funzione è limitato a 32 KB. Non sono previsti limiti specifici per singole chiavi o valori all'interno di questa capacità complessiva.

Per le variabili di ambiente di compilazione, è possibile definire fino a 100 variabili, con la stringa di definizione foo=bar limitata a 64 KB.

Gestione dei secret

Le variabili di ambiente possono essere utilizzate per la configurazione delle funzioni, ma non sono consigliate come metodo per archiviare secret come credenziali di database o chiavi API. Questi valori più sensibili devono essere archiviati al di fuori del codice sorgente e al di fuori delle variabili di ambiente. Alcuni ambienti di esecuzione o l'utilizzo di alcuni framework possono comportare l'invio dei contenuti delle variabili di ambiente ai log e non è consigliabile memorizzare le credenziali sensibili in file YAML, script di deployment o sotto il controllo del codice sorgente.

Per archiviare i segreti, ti consigliamo di utilizzare Secret Manager. Per configurare le funzioni Cloud Run in modo che accedano ai secret archiviati in Secret Manager, consulta Configurare i secret. Tieni presente che non esiste un'integrazione specifica per le funzioni Cloud Run con Cloud KMS.

Portabilità

È possibile che le variabili di ambiente che attualmente funzionano con la funzione Cloud Run non funzionino con un ambiente di runtime diverso, ad esempio in un linguaggio diverso o con determinati strumenti o librerie. È anche possibile che non vengano accettati da un'altra piattaforma.

Puoi evitare questi problemi seguendo lo standard POSIX per le variabili di ambiente. Se utilizzi la console Google Cloud per modificare le variabili, la console Google Cloud ti avvisa ogni volta che definisci una variabile che potrebbe avere problemi di portabilità (ma non impedirà il deployment). Come regola generale, consigliamo di usare per le chiavi delle variabile di ambiente solo lettere maiuscole, cifre e <underscore> (_), come definito nel set di caratteri portatile, e di non iniziare con un numero.