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 zum Verwalten und Konfigurieren von Back-Ends für Ihre spezifischen Anforderungen. In diesem Leitfaden werden diese Tools und Prozesse beschrieben.

apphosting.yaml erstellen und bearbeiten

Für erweiterte Konfigurationen wie Umgebungsvariablen oder Laufzeiteinstellungen wie Gleichzeitigkeit, CPU- und Arbeitsspeicherlimits müssen Sie die Datei apphosting.yaml im Stammverzeichnis Ihrer App erstellen und bearbeiten. Diese Datei unterstützt auch Verweise auf Secrets, die mit Cloud Secret Manager verwaltet werden. Daher kann sie sicher in die Quellcodeverwaltung 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 (Standard: 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 ganzzahligen Wert 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 Nutzung 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.

Umgebung konfigurieren

Manchmal ist für den Build-Prozess eine zusätzliche Konfiguration erforderlich, z. B. API-Schlüssel von Drittanbietern oder anpassbare Einstellungen. App Hosting bietet die Umgebungskonfiguration in apphosting.yaml, um diese Art von Daten für Ihr Projekt zu speichern und abzurufen.

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

Für Next.js-Apps funktionieren auch dotenv-Dateien mit Umgebungsvariablen mit App Hosting. Wir empfehlen, apphosting.yaml für die detaillierte Steuerung von Umgebungsvariablen mit einem beliebigen Framework zu verwenden.

In apphosting.yaml können Sie mit der Property availability angeben, welche Prozesse Zugriff auf Ihre Umgebungsvariable haben. Sie können eine Umgebungsvariable so einschränken, dass sie nur in der Build-Umgebung oder nur in der Laufzeitumgebung verfügbar ist. Standardmäßig ist sie für beide verfügbar.

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

Gültige Variablenschlüssel bestehen aus den Buchstaben A–Z oder Unterstrichen. Einige Umgebungsvariablenschlüssel sind für die interne Verwendung reserviert. Verwenden Sie keinen dieser Schlüssel in Ihren Konfigurationsdateien:

• Alle Variablen, die mit X_FIREBASE_ beginnen
• PORT
• K_SERVICE
• K_REVISION
• K_CONFIGURATION

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 unsere 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 App Hosting-abgeleiteten Befehl unterscheidet.

Build-Ausgabe konfigurieren

App Hosting optimiert die Bereitstellung Ihrer App 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 [.]. Dann 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 das Lebenszyklusmanagement 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 die gesamte Cloud Secret Manager-Funktionalität nutzen möchten, können Sie stattdessen die Cloud Secret Manager-Konsole verwenden. Wenn Sie dies tun, 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-Zuordnung in Ihrer apphosting.yaml-Datei, um den Zugriff zu konfigurieren. Verwenden Sie entweder einen voll qualifizierten Netzwerknamen oder eine ID. Durch die Verwendung von IDs ist die Übertragbarkeit zwischen Staging- und Produktionsumgebungen mit unterschiedlichen Connectors/Netzwerken möglich.

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

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 erstellt werden, um Ihre Web-App zu erstellen und auszuführen.

Ein Projektinhaber muss das erste App Hosting-Backend für ein Projekt erstellen. Nach dieser Ersteinrichtung können App Hosting-Administratoren auch zusätzliche Back-Ends erstellen und verwalten. Weitere Informationen finden Sie unter Firebase App Hosting IAM-Rollen.

Firebase Console: Wählen Sie im Menü Build die Option App Hosting und dann 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 Projekt-ID als Argument an, um ein Backend zu erstellen:

firebase apphosting:backends:create --project PROJECT_ID

Folgen Sie in der Console 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: /)

  Hier befindet sich üblicherweise die Datei package.json.

• Live-Zweig festlegen

  Dies ist der Branch 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. 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)

1. 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
   

2. Optional: Löschen Sie auf dem Google Cloud Console-Tab für Artifact Registry das Image für Ihr Backend in „firebaseapphosting-images“.

3. Löschen Sie in Cloud Secret Manager alle Secrets, deren Name „apphosting“ enthält. Achten Sie dabei besonders darauf, dass diese Secrets nicht von anderen Back-Ends oder anderen Aspekten Ihres Firebase-Projekts verwendet werden.