App-Hosting-Backends konfigurieren und verwalten

App Hosting ist benutzerfreundlich und wartungsarm. Die Standardeinstellungen sind für die meisten Anwendungsfälle optimiert. Gleichzeitig bietet App Hosting Tools, mit denen Sie Back-Ends nach Ihren spezifischen Anforderungen verwalten und konfigurieren können. In diesem Leitfaden werden diese Tools und Prozesse beschrieben.

Umgebungsvariablen festlegen und aktualisieren

Manchmal ist für den Build-Prozess eine zusätzliche Konfiguration erforderlich. App Hosting bietet eine Umgebungskonfiguration zum Speichern und Abrufen dieser Art von Daten für Ihr Projekt über die Firebase-Konsole und alternativ in apphosting.yaml.

Das Festlegen von Umgebungsvariablen in der Console ist der schnellste Weg, um loszulegen. Verwenden Sie apphosting.yaml, wenn Sie vertrauliche Parameter speichern und darauf zugreifen, Variablen festlegen müssen, die nur zur Build- oder Laufzeit verfügbar sind, oder Umgebungsvariablen für mehrere Umgebungen freigeben möchten. Sowohl in der Konsole als auch mit apphosting.<env>.yaml können Sie unterschiedliche Werte für verschiedene Umgebungen festlegen.

Firebase Console

Screenshot des Firebase Console-Dialogfelds zum Hinzufügen von Umgebungsvariablen

`apphosting.yaml`

env:
-   variable: STORAGE_BUCKET
    value: mybucket.firebasestorage.app

Variablen aktualisieren

Sie können Umgebungsvariablen in der Firebase-Konsole auf dem Tab Einstellungen für ein Backend hinzufügen und bearbeiten. Rufen Sie Backend ansehen >> Einstellungen >> Umgebung auf und fügen Sie Umgebungsvariablen hinzu, bearbeiten oder löschen Sie sie.

Wenn Sie Umgebungsvariablen in apphosting.yaml, hinzufügen und bearbeiten möchten, erstellen und bearbeiten Sie die Datei manuell.

Ihre Änderungen werden erst beim nächsten Roll-out wirksam und wirken sich nicht auf den aktuellen Roll-out aus. Sie können die Variablen entweder speichern und einen neuen Roll-out erstellen oder die Variablen speichern und später bereitstellen.

Variablenverfügbarkeit festlegen

Umgebungsvariablen, die in der Firebase Console erstellt wurden, sind sowohl zur Build- als auch zur Laufzeit verfügbar. Dies ist auch die Standardbedingung für Variablen, die in apphosting.yaml definiert sind, sofern Sie den Bereich nicht mit der Property availability eingeschränkt haben. In apphosting.yaml (aber nicht in der Console) können Sie eine Umgebungsvariable so einschränken, dass sie nur in der Build-Umgebung oder nur in der Laufzeitumgebung verfügbar ist.

env:
-   variable: STORAGE_BUCKET
    value: mybucket.firebasestorage.app
    availability:
    -   BUILD
    -   RUNTIME

Bei Next.js-Apps können Sie auch das Präfix NEXT_PUBLIC_ auf dieselbe Weise wie in Ihrer dotenv-Datei verwenden, um eine Variable im Browser zugänglich zu machen.

env:
-   variable: NEXT_PUBLIC_STORAGE_BUCKET
    value: mybucket.firebasestorage.app
    availability:
    -   BUILD
    -   RUNTIME

dotenv-Dateien für Next.js

Für Next.js-Apps funktionieren dotenv-Dateien mit Umgebungsvariablen mit App Hosting.

Wenn Sie ein Backend erstellen oder aktualisieren, können Sie Umgebungsvariablen aus Ihrer dotenv-Datei in die Firebase-Konsole übertragen, indem Sie den gesamten Inhalt der dotenv-Datei in das erste Feld „Schlüssel“ im Formular „Neu hinzufügen“ in den Einstellungen für Umgebungsvariablen kopieren und einfügen.

Alle so kopierten Umgebungsvariablen sollten ordentlich in das Formular formatiert werden, ohne dass jede einzeln eingegeben werden muss, sofern die Eingabe ein Format wie das folgende hat:

KEY1=value1
KEY2=value2
KEY3=value3

Für eine komplexe oder detaillierte Steuerung von Umgebungsvariablen mit einem beliebigen Framework empfehlen wir die Verwendung von apphosting.yaml.

Variablenhierarchie

Bei Firebase App Hosting werden Ihre Variablen in einer Reihenfolge angewendet, die auf ihrer Quelle basiert. Beispielsweise werden in der Console festgelegte Werte immer durch Werte in apphosting.yaml- und dotenv-Dateien überschrieben oder haben Vorrang vor diesen.

Hier ist die vollständige Reihenfolge:

Firebase Console → in der Console festgelegte Variablen
apphosting.<env>.yaml: Variablen, die in einer umgebungsspezifischen YAML-Datei wie apphosting.staging.yaml angegeben sind (siehe Mehrere Umgebungen bereitstellen)
apphosting.yaml → in der Datei apphosting.yaml angegebene Variablen
Firebase-System: Von Firebase festgelegte Variablen, die Werte für firebase_config json oder firebase_webapp_config enthalten, sowie Umgebungsvariablen, mit denen die Hostnamen und Ports für SSR-Apps festgelegt werden (von App Hosting-Adaptern in bundle.yaml festgelegt).

Reservierte Namen und Einschränkungen

Gültige Variablenschlüssel müssen mit einem Großbuchstaben beginnen und dürfen nur Großbuchstaben, Ziffern und Unterstriche enthalten. Einige Umgebungsvariablenschlüssel sind für die interne Verwendung reserviert. Verwenden Sie keinen dieser Schlüssel in Ihren Konfigurationsdateien:

Leere Strings („“)
Variablen, die „=“ enthalten
Alle Variablen, die mit X_FIREBASE_ beginnen
PORT
K_SERVICE
K_REVISION
K_CONFIGURATION
Schlüsselduplikate

`apphosting.yaml` erstellen und bearbeiten

Für erweiterte Konfigurationen wie Secrets oder Laufzeiteinstellungen wie Parallelität, CPU- und Speicherlimits müssen Sie die Datei apphosting.yaml im Stammverzeichnis Ihrer App erstellen und bearbeiten. Diese Datei unterstützt Verweise auf Secrets, die mit Cloud Secret Manager verwaltet werden. Sie kann also sicher in die Versionsverwaltung eingecheckt werden.

Führen Sie den folgenden Befehl aus, um apphosting.yaml zu erstellen:

firebase init apphosting

Dadurch wird eine einfache apphosting.yaml-Datei mit Beispielkonfigurationen (auskommentiert) erstellt. Nach der Bearbeitung könnte eine typische apphosting.yaml-Datei so aussehen, mit Einstellungen für den Cloud Run-Dienst des Back-Ends, einigen Umgebungsvariablen und einigen Verweisen auf Secrets, die von Cloud Secret Manager verwaltet werden:

# Settings for Cloud Run
runConfig:
  minInstances: 2
  maxInstances: 100
  concurrency: 100
  cpu: 2
  memoryMiB: 1024

# Environment variables and secrets
env:
  - variable: STORAGE_BUCKET
    value: mybucket.firebasestorage.app
    availability:
      - BUILD
      - RUNTIME

  - variable: API_KEY
    secret: myApiKeySecret

    # Same as API_KEY above but with a pinned version.
  - variable: PINNED_API_KEY
    secret: myApiKeySecret@5

    # Same as API_KEY above but with the long form secret reference as defined by Cloud Secret Manager.
  - variable: VERBOSE_API_KEY
    secret: projects/test-project/secrets/secretID

    # Same as API_KEY above but with the long form secret reference with pinned version.
  - variable: PINNED_VERBOSE_API_KEY
    secret: projects/test-project/secrets/secretID/versions/5

Im weiteren Verlauf dieser Anleitung finden Sie weitere Informationen und Kontext zu diesen Beispielkonfigurationen.

Cloud Run-Diensteinstellungen konfigurieren

Mit den apphosting.yaml-Einstellungen können Sie konfigurieren, wie Ihr Cloud Run-Dienst bereitgestellt wird. Die verfügbaren Einstellungen für den Cloud Run-Dienst werden im Objekt runConfig bereitgestellt:

cpu: Anzahl der CPUs, die für jede Bereitstellungsinstanz verwendet werden (Standardwert: 0).
memoryMiB – Menge des Arbeitsspeichers, der jeder Serving-Instanz in MiB zugewiesen wird (Standardwert: 512)
maxInstances – Maximale Anzahl von Containern, die gleichzeitig ausgeführt werden können (Standardwert: 100, wird durch das Kontingent verwaltet)
minInstances: Anzahl der Container, die immer aktiv bleiben sollen (Standardwert: 0).
concurrency: Maximale Anzahl von Anfragen, die jede Serving-Instanz empfangen kann (Standardwert: 80).

Beachten Sie die wichtige Beziehung zwischen cpu und memoryMiB. Der Arbeitsspeicher kann auf einen beliebigen Ganzzahlwert zwischen 128 und 32.768 festgelegt werden. Wenn Sie das Arbeitsspeicherlimit erhöhen, müssen Sie möglicherweise auch die CPU-Limits erhöhen:

Für mehr als 4 GiB sind mindestens 2 CPUs erforderlich.
Für mehr als 8 GiB sind mindestens 4 CPUs erforderlich.
Für mehr als 16 GiB sind mindestens 6 CPUs erforderlich.
Für mehr als 24 GiB sind mindestens 8 CPUs erforderlich.

Ebenso wirkt sich der Wert von cpu auf die Einstellungen für die gleichzeitige Ausführung aus. Wenn Sie einen Wert von weniger als 1 CPU festlegen, müssen Sie die Gleichzeitigkeit auf 1 festlegen. Die CPU wird dann nur während der Anfrageverarbeitung zugewiesen.

Build- und Ausführungsskripts überschreiben

App Hosting leitet den Build- und Startbefehl Ihrer App aus dem erkannten Framework ab. Wenn Sie einen benutzerdefinierten Build- oder Startbefehl verwenden möchten, können Sie die Standardwerte von App Hosting in apphosting.yaml überschreiben.

scripts:
  buildCommand: next build --no-lint
  runCommand: node dist/index.js

Die Überschreibung des Build-Befehls hat Vorrang vor allen anderen Build-Befehlen. Dadurch wird die Verwendung von Framework-Adaptern für Ihre App deaktiviert und alle Framework-spezifischen Optimierungen, die App Hosting bietet, werden deaktiviert. Sie eignet sich am besten, wenn die Funktionen Ihrer App von den Adaptern nicht gut unterstützt werden. Wenn Sie den Build-Befehl ändern, aber weiterhin die von uns bereitgestellten Adapter verwenden möchten, legen Sie das Build-Script stattdessen in package.json fest, wie unter App Hosting-Framework-Adapter beschrieben.

Verwenden Sie die Überschreibung des Ausführungsbefehls, wenn Sie einen bestimmten Befehl zum Starten Ihrer App verwenden möchten, der sich vom abgeleiteten App Hosting-Befehl unterscheidet.

Build-Ausgabe konfigurieren

App Hosting optimiert Ihre App-Bereitstellungen standardmäßig, indem nicht verwendete Ausgabedateien gelöscht werden, wie vom Framework angegeben. Wenn Sie die Bereitstellungsgröße Ihrer App weiter optimieren oder die Standardoptimierungen ignorieren möchten, können Sie dies in apphosting.yaml überschreiben.

outputFiles:
  serverApp:
    include: [dist, server.js]

Der Parameter include akzeptiert eine Liste von Verzeichnissen und Dateien relativ zum Stammverzeichnis der App, die für die Bereitstellung der App erforderlich sind. Wenn Sie sicherstellen möchten, dass alle Dateien beibehalten werden, setzen Sie „include“ auf [.]. In diesem Fall werden alle Dateien bereitgestellt.

Geheime Parameter speichern und darauf zugreifen

Vertrauliche Informationen wie API-Schlüssel sollten als Secrets gespeichert werden. Sie können in apphosting.yaml auf Secrets verweisen, um zu vermeiden, dass vertrauliche Informationen in die Quellcodeverwaltung eingecheckt werden.

Parameter vom Typ secret stellen Stringparameter dar, deren Wert in Cloud Secret Manager gespeichert ist. Anstatt den Wert direkt abzuleiten, wird bei geheimen Parametern geprüft, ob sie in Cloud Secret Manager vorhanden sind, und die Werte werden während der Einführung geladen.

  -   variable: API_KEY
      secret: myApiKeySecret

Secrets in Cloud Secret Manager können mehrere Versionen haben. Standardmäßig ist der Wert eines geheimen Parameters, der für Ihr Live-Backend verfügbar ist, an die neueste verfügbare Version des Secrets gebunden, die zum Zeitpunkt der Erstellung des Backends verfügbar war. Wenn Sie Anforderungen an die Versionsverwaltung und die Verwaltung des Lebenszyklus von Parametern haben, können Sie mit Cloud Secret Manager bestimmte Versionen verwenden. So heften Sie beispielsweise Version 5 an:

  - variable: PINNED_API_KEY
    secret: myApiKeySecret@5

Sie können Secrets mit dem CLI-Befehl firebase apphosting:secrets:set erstellen. Sie werden dann aufgefordert, die erforderlichen Berechtigungen hinzuzufügen. In diesem Ablauf haben Sie die Möglichkeit, den Secret-Verweis automatisch zu apphosting.yaml hinzuzufügen.

Wenn Sie alle Funktionen von Cloud Secret Manager nutzen möchten, können Sie stattdessen die Cloud Secret Manager-Konsole verwenden. In diesem Fall müssen Sie Ihrem App Hosting-Backend mit dem CLI-Befehl firebase apphosting:secrets:grantaccess Berechtigungen erteilen.

VPC-Zugriff konfigurieren

Ihr App Hosting-Backend kann eine Verbindung zu einem VPC-Netzwerk (Virtual Private Cloud) herstellen. Weitere Informationen und ein Beispiel finden Sie unter Firebase App Hosting mit einem VPC-Netzwerk verbinden.

Verwenden Sie die vpcAccess-Zuweisung in Ihrer apphosting.yaml-Datei, um den Zugriff zu konfigurieren. Verwenden Sie entweder einen vollqualifizierten Netzwerk-/Connector-Namen oder eine ID. Durch die Verwendung von IDs ist die Übertragbarkeit zwischen Staging- und Produktionsumgebungen mit unterschiedlichen Connectors/Netzwerken möglich.

Konfiguration für ausgehenden Direct VPC-Traffic (`apphosting.yaml`):

runConfig:
  vpcAccess:
    egress: PRIVATE_RANGES_ONLY # Default value
    networkInterfaces:
      # Specify at least one of network and/or subnetwork
      - network: my-network-id
        subnetwork: my-subnetwork-id

Konfiguration des serverlosen Connectors (`apphosting.yaml`):

runConfig:
  vpcAccess:
    egress: ALL_TRAFFIC
    connector: connector-id

Back-Ends verwalten

Befehle für die grundlegende Verwaltung von App Hosting-Back-Ends sind in der Firebase-Befehlszeile und der Firebase-Konsole verfügbar. In diesem Abschnitt werden einige der häufigsten Verwaltungsaufgaben beschrieben, z. B. das Erstellen und Löschen von Back-Ends.

Backend erstellen

Ein App Hosting-Backend ist die Sammlung verwalteter Ressourcen, die von App Hosting zum Erstellen und Ausführen Ihrer Web-App erstellt werden.

Firebase Console: Wählen Sie im Menü Build die Option App Hosting und dann Backend erstellen aus. Wenn dies das erste Backend in Ihrem Firebase-Projekt ist, wählen Sie Jetzt starten aus.

CLI (Version 13.15.4 oder höher): Führen Sie den folgenden Befehl im Stammverzeichnis Ihres lokalen Projektverzeichnisses aus und geben Sie Ihre projectID als Argument an, um ein Backend zu erstellen:

firebase apphosting:backends:create --project PROJECT_ID

Folgen Sie in der Konsole oder CLI der Anleitung, um eine Region auszuwählen, eine GitHub-Verbindung einzurichten und die folgenden grundlegenden Bereitstellungseinstellungen zu konfigurieren:

Stammverzeichnis Ihrer App festlegen (Standardwert ist /)

Hier befindet sich üblicherweise die Datei package.json.

Live-Branch festlegen

Dies ist der Zweig Ihres GitHub-Repositorys, der unter Ihrer Live-URL bereitgestellt wird. Häufig ist es der Branch, in den Feature- oder Entwicklungs-Branches zusammengeführt werden.
Automatische Roll-outs akzeptieren oder ablehnen

Automatische Roll-outs sind standardmäßig aktiviert. Nachdem das Backend erstellt wurde, können Sie festlegen, dass Ihre App sofort in App Hosting bereitgestellt wird.
Weisen Sie Ihrem Backend einen Namen zu.

Backend löschen

Wenn Sie ein Backend vollständig entfernen möchten, löschen Sie es zuerst mit der Firebase-CLI oder der Firebase-Konsole und entfernen Sie dann die zugehörigen Assets manuell. Achten Sie dabei darauf, keine Ressourcen zu löschen, die von anderen Backends oder anderen Aspekten Ihres Firebase-Projekts verwendet werden.

Firebase Console: Wählen Sie im Menü Einstellungen die Option Backend löschen aus.

CLI:Version 13.15.4 oder höher

Führen Sie den folgenden Befehl aus, um das App Hosting-Backend zu löschen. Dadurch werden alle Domains für Ihr Backend deaktiviert und der zugehörige Cloud Run-Dienst wird gelöscht:
```
firebase apphosting:backends:delete BACKEND_ID --project PROJECT_ID
```
Optional: Löschen Sie auf dem Google Cloud Console-Tab für Artifact Registry das Image für Ihr Backend in „firebaseapphosting-images“.
Löschen Sie in Cloud Secret Manager alle Secrets, die „apphosting“ im Secret-Namen enthalten. Achten Sie dabei besonders darauf, dass diese Secrets nicht von anderen Back-Ends oder anderen Aspekten Ihres Firebase-Projekts verwendet werden.