Umgebungsvariablen konfigurieren

Sie können zusammen mit einer Cloud Run-Funktion beliebige Schlüssel/Wert-Paare bereitstellen. Diese Paare werden Ihrer Funktion entweder als literale Umgebungsvariablenzur Verfügung gestellt, zugänglich durch Ihren Code zur Laufzeit, oder als Konfigurationsinformationen für die Buildpacks von Google Cloud.

Umgebungsvariablen sind an eine einzelne Funktion gebunden und sind für andere Funktionen in Ihrem Google Cloud-Projekt nicht sichtbar. Jede Variable wird im Cloud Run-Backend gespeichert und befindet sich im selben Lebenszyklus wie die Funktion, an die sie gebunden sind.

Sie können Laufzeit-Umgebungsvariablen über die Google Cloud CLI oder die Google Cloud Console hinzufügen oder entfernen.

Laufzeit-Umgebungsvariablen festlegen

Mit den folgenden Methoden können Sie neue Variablen einrichten oder vorhandene Variablen komplett ersetzen. Wenn Sie additive Änderungen vornehmen möchten, verwenden Sie den Aktualisierungsprozess im nächsten Abschnitt.

gcloud

Verwenden Sie zum Festlegen einer Laufzeit-Umgebungsvariablen über die Google Cloud CLI das Flag --set-env-vars zum Zeitpunkt der Bereitstellung:

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

Sie können auch mehrere Laufzeit-Umgebungsvariablen mithilfe einer durch Kommas getrennten Liste festlegen:

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

Wenn Sie Ihre Konfiguration in einer Datei speichern möchten (z. B. unter der Versionsverwaltung), können Sie eine YAML-Datei zusammen mit dem Flag --env-vars-file verwenden:

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

Der Inhalt der Datei .env.yaml ist:

 FOO: bar
 BAZ: boo

In den obigen Beispielen bezieht sich FLAGS... auf weitere Optionen, die Sie bei der Bereitstellung der Funktion übergeben. Eine vollständige Referenz zum deploy-Befehl finden Sie unter gcloud functions deploy.

Google Cloud Console-UI

Sie können Laufzeit-Umgebungsvariablen festlegen, während Sie die Funktion in der Google Cloud Console erstellen:

1. Rufen Sie in der Google Cloud Console die Übersichtsseite von Cloud Functions auf:

   Zur Cloud Run-Übersicht

2. Klicken Sie auf Funktion erstellen.

3. Füllen Sie die erforderlichen Felder für die Funktion aus.

4. Öffnen Sie den Bereich Laufzeit-, Build- und Verbindungseinstellungen.

5. Wählen Sie den Tab Laufzeit aus.

6. Klicken Sie im Bereich Laufzeit-Umgebungsvariablen auf Variable hinzufügen und fügen Sie den Namen und den Wert hinzu.

   Eine Anleitung zum Hinzufügen von Umgebungsvariablen zu einer vorhandenen Funktion finden Sie unter Laufzeit-Umgebungsvariablen aktualisieren.

Laufzeit-Umgebungsvariablen aktualisieren

Sie können Laufzeit-Umgebungsvariablen auch für vorhandene Funktionen aktualisieren. Bei diesem nicht destruktiven Ansatz werden Laufzeit-Umgebungsvariablen geändert oder hinzugefügt, jedoch nicht gelöscht.

gcloud

Verwenden Sie zum Aktualisieren einer Variablen mit der Google Cloud CLI das Flag --update-env-vars bei der Bereitstellung:

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

Sie können auch mehrere Laufzeit-Umgebungsvariablen mithilfe einer durch Kommas getrennten Liste aktualisieren:

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

Google Cloud Console-UI

So aktualisieren Sie Laufzeit-Umgebungsvariablen mithilfe der Google Cloud Console:

1. Rufen Sie in der Google Cloud Console die Übersichtsseite von Cloud Functions auf:

   Zur Cloud Run-Übersicht

2. Klicken Sie auf eine vorhandene Funktion, um die zugehörige Detailseite zu öffnen.

3. Klicken Sie auf Bearbeiten.

4. Öffnen Sie den Bereich Laufzeit-, Build- und Verbindungseinstellungen.

5. Wählen Sie den Tab Laufzeit aus.

6. Nehmen Sie die Änderungen im Bereich Laufzeit-Umgebungsvariablen vor.

Laufzeit-Umgebungsvariablen löschen

gcloud

Wenn Sie Laufzeit-Umgebungsvariablen selektiv entfernen möchten, können Sie das Flag --remove-env-vars bei der Bereitstellung verwenden:

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

Alternativ können Sie alle zuvor festgelegten Laufzeit-Umgebungsvariablen mit dem Flag --clear-env-vars löschen:

gcloud functions deploy FUNCTION_NAME --clear-env-vars

Google Cloud Console-UI

So löschen Sie Laufzeit-Umgebungsvariablen mithilfe der Google Cloud Console:

1. Rufen Sie in der Google Cloud Console die Übersichtsseite von Cloud Functions auf:

   Zur Cloud Run-Übersicht

2. Klicken Sie auf eine vorhandene Funktion, um die zugehörige Detailseite zu öffnen.

3. Klicken Sie auf Bearbeiten.

4. Öffnen Sie den Bereich Laufzeit-, Build- und Verbindungseinstellungen.

5. Wählen Sie den Tab Laufzeit aus.

6. Klicken Sie im Bereich Laufzeit-Umgebungsvariablen neben dem Schlüssel/Wert-Paar auf das Papierkorbsymbol, um das Paar zu löschen.

Automatisch festgelegte Laufzeit-Umgebungsvariablen

In diesem Abschnitt werden automatisch festgelegte Laufzeit-Umgebungsvariablen aufgeführt.

Schlüssel	Beschreibung
FUNCTION_TARGET	Reserviert: Die auszuführende Funktion.
FUNCTION_SIGNATURE_TYPE	Reserviert: Der Typ der Funktion: http für HTTP-Funktionen und event für ereignisgesteuerte Funktionen.
K_SERVICE	Reserviert: Der Name der Funktionsressource.
K_REVISION	Reserviert: Die Versionskennung der Funktion.
PORT	Reserviert: Der Port, über den die Funktion aufgerufen wird.

Hinweis: Wenn Ihre Funktion eine der Umgebungsvariablen aus einer älteren Laufzeit benötigt, können Sie die Variable beim Bereitstellen der Funktion festlegen. Beispiel:

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

Laufzeit-Umgebungsvariablen festlegen und abrufen: Beispiel

Legen Sie die Laufzeit-Umgebungsvariable fest:

Node.js

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

Verwenden Sie das Flag --runtime, um die Laufzeit-ID einer unterstützten Node.js-Version anzugeben und die Funktion auszuführen.

Python

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

Verwenden Sie das Flag --runtime, um die Laufzeit-ID einer unterstützten Python-Version anzugeben und die Funktion auszuführen.

Go

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

Verwenden Sie das Flag --runtime, um die Laufzeit-ID einer unterstützten Go-Version anzugeben und die Funktion auszuführen.

Java

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

Verwenden Sie das Flag --runtime, um die Laufzeit-ID einer unterstützten Java-Version anzugeben und die Funktion auszuführen.

C#

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

Verwenden Sie das Flag --runtime, um die Laufzeit-ID einer unterstützten .NET-Version anzugeben, um Ihre Funktion auszuführen.

Ruby

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

Verwenden Sie das Flag --runtime, um die Laufzeit-ID einer unterstützten Ruby-Version anzugeben, um die Funktion auszuführen.

PHP

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

Verwenden Sie das Flag --runtime, um die Laufzeit-ID einer unterstützten PHP-Version anzugeben und die Funktion auszuführen.

Greifen Sie zur Laufzeit programmatisch auf die Variablen zu:

Node.js

Verwenden Sie in Node.js das Attribut process.env, um auf Laufzeit-Umgebungsvariablen zuzugreifen:

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

Python

Verwenden Sie in Python os.environ, um auf Laufzeit-Umgebungsvariablen zuzugreifen:

import os


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

Go

Verwenden Sie in Go os.Getenv(), um auf Laufzeit-Umgebungsvariablen zuzugreifen:

// 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

Verwenden Sie in Java System.getenv, um auf Laufzeit-Umgebungsvariablen zuzugreifen:

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#

Zur Laufzeit ist der Zugriff auf Umgebungsvariablen mit Environment.GetEnvironmentVariable in C# möglich:

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

Zur Laufzeit ist der Zugriff auf Umgebungsvariablen mit ENV in Ruby möglich:

require "functions_framework"

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

PHP

Zur Laufzeit können Sie über die Funktion getenv von PHP auf Umgebungsvariablen zugreifen:

use Psr\Http\Message\ServerRequestInterface;

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

Build-Umgebungsvariablen verwenden

Sie können auch Build-Umgebungsvariablen für Laufzeiten festlegen, die Buildpacks unterstützen.

Build-Umgebungsvariablen sind Schlüssel/Wert-Paare, die zusammen mit einer Funktion bereitgestellt werden und Ihnen ermöglichen, Konfigurationsinformationen an Buildpacks zu übergeben. Sie können damit beispielsweise Compiler-Optionen anpassen. Diese Build-Umgebungsvariablen lassen sich entweder über die Google Cloud CLI oder die Google Cloud Console-Benutzeroberfläche hinzufügen oder entfernen.

Hinweis: Schlüssel müssen mit einem ASCII-Großbuchstaben beginnen und dürfen nur aus ASCII-Großbuchstaben, Ziffern und Unterstrichen bestehen. Sie sollten keine Variablenschlüssel mit dem Präfix GOOGLE_* erstellen. Alle unterstützten Buildpacks-Umgebungsvariablen ansehen

Build-Umgebungsvariablen festlegen

Mit den folgenden Methoden können Sie neue Variablen einrichten oder vorhandene Variablen komplett ersetzen. Für additive Änderungen verwenden Sie den Aktualisierungsvorgang (das Flag --update-build-env-vars in gcloud), der im nächsten Abschnitt beschrieben wird.

gcloud

Verwenden Sie zum Festlegen einer Variablen mit der Google Cloud-Befehlszeile das Flag --set-build-env-vars bei der Bereitstellung:

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

Sie können auch mehrere Build-Umgebungsvariablen mithilfe einer durch Kommas getrennten Liste festlegen:

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

Wenn Sie Ihre Konfiguration in einer Datei speichern möchten (z. B. unter der Versionsverwaltung), können Sie eine YAML-Datei zusammen mit dem Flag --build-env-vars-file verwenden:

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

Der Inhalt der Datei *.yaml ist:

 FOO: bar
 BAZ: boo

In den obigen Beispielen bezieht sich FLAGS... auf weitere Optionen, die Sie bei der Bereitstellung der Funktion übergeben. Eine vollständige Referenz zum deploy-Befehl finden Sie unter gcloud beta functions deploy.

Google Cloud Console-UI

Sie können Build-Umgebungsvariablen auch festlegen, während Sie die Funktion in der Google Cloud Console erstellen:

1. Rufen Sie in der Google Cloud Console die Übersichtsseite von Cloud Functions auf:

   Zur Cloud Run-Übersicht

2. Klicken Sie auf Funktion erstellen.

3. Füllen Sie die erforderlichen Felder für die Funktion aus.

4. Öffnen Sie den Bereich Laufzeit-, Build- und Verbindungseinstellungen.

5. Wählen Sie den Tab Erstellen aus.

6. Klicken Sie im Bereich Build-Umgebungsvariablen auf Variable hinzufügen und fügen Sie den Namen und den Wert hinzu.

Build-Umgebungsvariablen aktualisieren

Sie können Build-Umgebungsvariablen auch für vorhandene Funktionen aktualisieren. Bei diesem nicht destruktiven Ansatz werden Build-Umgebungsvariablen geändert oder hinzugefügt, jedoch nicht gelöscht.

gcloud

Verwenden Sie zum Festlegen einer Variablen mit der Google Cloud-Befehlszeile das Flag --update-build-env-vars bei der Bereitstellung:

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

Sie können auch mehrere Build-Umgebungsvariablen mithilfe einer durch Kommas getrennten Liste aktualisieren:

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

Google Cloud Console-UI

So aktualisieren Sie Build-Umgebungsvariablen mithilfe der Google Cloud Console:

1. Rufen Sie in der Google Cloud Console die Übersichtsseite von Cloud Functions auf:

   Zur Cloud Run-Übersicht

2. Klicken Sie auf eine vorhandene Funktion, um die zugehörige Detailseite zu öffnen.

3. Klicken Sie auf Bearbeiten.

4. Öffnen Sie den Bereich Laufzeit-, Build- und Verbindungseinstellungen.

5. Wählen Sie den Tab Erstellen aus.

6. Nehmen Sie die Änderungen im Bereich Build-Umgebungsvariablen vor.

Build-Umgebungsvariablen löschen

gcloud

Wenn Sie Build-Umgebungsvariablen selektiv entfernen möchten, können Sie das Flag --remove-build-env-vars bei der Bereitstellung verwenden:

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

Alternativ können Sie alle zuvor festgelegten Build-Umgebungsvariablen mit dem Flag --clear-build-env-vars löschen:

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

Google Cloud Console-UI

So löschen Sie Build-Umgebungsvariablen mithilfe der Google Cloud Console:

1. Rufen Sie in der Google Cloud Console die Übersichtsseite von Cloud Functions auf:

   Zur Cloud Run-Übersicht

2. Klicken Sie auf eine vorhandene Funktion, um die zugehörige Detailseite zu öffnen.

3. Klicken Sie auf Bearbeiten.

4. Öffnen Sie den Bereich Laufzeit-, Build- und Verbindungseinstellungen.

5. Wählen Sie den Tab Erstellen aus.

6. Klicken Sie im Bereich Build-Umgebungsvariablen neben dem Schlüssel/Wert-Paar auf das Papierkorbsymbol, um das Paar zu löschen.

Lebenszyklus von Variablen

Alle Umgebungsvariablen sind an eine Bereitstellung einer Cloud Run-Funktion gebunden und können nur mit einer Bereitstellung festgelegt oder geändert werden. Wenn eine Bereitstellung fehlschlägt, werden Änderungen an Umgebungsvariablen nicht angewendet. Änderungen erfordern eine erfolgreiche Bereitstellung.

Best Practices und reservierte Umgebungsvariablen

Je nachdem, welche Laufzeit die Funktion verwendet, werden einige zusätzliche Umgebungsvariablen automatisch festgelegt. Diese basieren auf dem Betriebssystem der Laufzeit (z. B. DEBIAN_FRONTEND, SHLVL oder PATH) und der Sprachlaufzeit (z. B. NODE_ENV, VIRTUAL_ENV oder GOPATH).

Umgebungsvariablen, die von der Umgebung bereitgestellt werden (außer den in automatisch festgelegten Umgebungsvariablen aufgelisteten), könnten sich in zukünftigen Laufzeitversionen ändern. Als Best Practice empfehlen wir Ihnen, sich nur auf Umgebungsvariablen zu verlassen oder Umgebungsvariablen zu ändern, die Sie explizit festgelegt haben.

Das Ändern von Umgebungsvariablen, die von der Umgebung bereitgestellt werden, kann zu unvorhersehbaren Ergebnissen führen. Versuche, solche Umgebungsvariablen zu ändern, könnten blockiert werden oder sogar unbeabsichtigte Auswirkungen haben, wie beispielsweise Funktionen, die nicht gestartet werden können. Als Best Practice empfehlen wir, vor alle Umgebungsvariablen einen eindeutigen Schlüssel zu setzen, um Konflikte zu vermeiden.

Die folgenden Umgebungsvariablen können Sie nicht verwenden:

Schlüssel	Beschreibung
Leer ('')	Schlüssel dürfen keine leeren Strings sein.
=	Schlüssel dürfen nicht das Gleichheitszeichen (=) enthalten.
X_GOOGLE_	Schlüssel dürfen nicht das Präfix X_GOOGLE_ enthalten.

Hinweis: Umgebungsvariablen, die in der Ausführungsumgebung angezeigt, aber in nicht der obigen Tabelle aufgeführt werden, gelten als verworfen und können jederzeit ohne vorherige Benachrichtigung entfernt werden.

Größenbeschränkungen

Die Gesamtzahl der Byte, die von Namen und Werten von Laufzeit-Umgebungsvariablen für eine einzelne Funktion belegt werden, ist auf 32 KiB begrenzt. Es gibt keine spezifischen Limits für einzelne Schlüssel oder Werte innerhalb dieser Gesamtkapazität.

Für Build-Umgebungsvariablen können bis zu 100 Variablen definiert werden, wobei der Definitionsstring foo=bar auf 64 KiB begrenzt ist.

Secrets verwalten

Umgebungsvariablen können zur Funktionskonfiguration verwendet werden. Zum Speichern von Secrets wie Datenbankanmeldedaten oder API-Schlüsseln werden sie jedoch nicht empfohlen. Diese vertraulicheren Informationen sollten weder im Quellcode noch in Umgebungsvariablen gespeichert werden. Einige Ausführungsumgebungen oder die Verwendung einiger Frameworks können dazu führen, dass die Inhalte von Umgebungsvariablen an Logs gesendet werden. Vertrauliche Anmeldedaten sollten außerdem nicht in YAML-Dateien, Bereitstellungsskripts oder in der Versionsverwaltung gespeichert werden.

Wir empfehlen die Verwendung von Secret Manager zum Speichern von Secrets. Informationen zum Konfigurieren von Cloud Run-Funktionen für den Zugriff auf in Secret Manager gespeicherte Secrets finden Sie unter Secrets konfigurieren. Beachten Sie, dass Cloud KMS über keine für Cloud Run-Funktionen spezifische Integration verfügt.

Portabilität

Umgebungsvariablen, die Sie derzeit in einer Cloud Run-Funktion verwenden, funktionieren möglicherweise nicht in anderen Laufzeitumgebungen wie in einer anderen Sprache oder in Kombination mit bestimmten Tools oder Bibliotheken. Außerdem kann es vorkommen, dass sie von einer anderen Plattform nicht akzeptiert werden.

Probleme dieser Art können Sie vermeiden, wenn Sie sich am POSIX-Standard für Umgebungsvariablen orientieren. Wenn Sie die Google Cloud Console zum Bearbeiten von Variablen verwenden, warnt die Google Cloud Console Sie, wenn Sie eine Variable definieren, die möglicherweise Portabilitätsprobleme hat (was aber die Bereitstellung nicht verhindert). Als allgemeine Regel empfehlen wir, dass Schlüssel von Umgebungsvariablen ausschließlich aus Großbuchstaben, Ziffern und <underscore> (_) bestehen (wie in der Tabelle Portable Character Set definiert) und nicht mit einer Ziffer beginnen.