App-Hosting-Backends konfigurieren und verwalten

App Hosting wurde für eine einfache Verwendung und geringen Wartungsaufwand entwickelt, 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.

Umgebungsvariablen festlegen und aktualisieren

Manchmal ist für Ihren Build-Prozess eine zusätzliche Konfiguration erforderlich. App Hosting bietet eine Umgebungskonfiguration, um diese Art von Daten für Ihr Projekt über die Firebase Console und alternativ in apphosting.yaml zu speichern und abzurufen.

Das Festlegen von Umgebungsvariablen in der Firebase Console ist der schnellste Weg, um loszulegen. Verwenden Sie apphosting.yaml, wenn Sie geheime 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 mit der Console als auch mit apphosting.<env>.yaml können Sie unterschiedliche Werte für verschiedene Umgebungen festlegen.

Firebase console

apphosting.yaml

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

Achtung: Die konsolenbasierte und die dateibasierte Konfiguration unterscheiden sich in einigen wichtigen Punkten. Lesen Sie diesen Abschnitt daher sorgfältig durch. Wichtig: In der Console festgelegte Werte überschreiben immer die in festgelegten Werte oder haben Vorrang vor ihnen. apphosting.yaml. Weitere Informationen finden Sie unter Variablenhierarchie.

Variablen aktualisieren

Sie können Umgebungsvariablen in der Firebase Konsole oder mit apphosting.yaml hinzufügen, bearbeiten oder löschen:

• Firebase console:

  1. Rufen Sie in der Firebase Console Hosting & Serverless > App Hosting auf.

  2. Rufen Sie Backend ansehen > Einstellungen > Umgebung auf.

  3. Fügen Sie Umgebungsvariablen hinzu, bearbeiten oder löschen Sie sie.

• apphosting.yaml:

  Informationen zum manuellen Erstellen und Bearbeiten der Datei

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

Verfügbarkeit von Variablen festlegen

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

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

Bei Next.js-Anwendungen 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-Anwendungen funktionieren dotenv Dateien mit Umgebung Variablen mit App Hosting.

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

Alle auf diese Weise kopierten Umgebungsvariablen sollten ordnungsgemäß im Formular formatiert sein, ohne dass Sie sie einzeln eingeben müssen, 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.

Automatisch ausgefüllte Umgebungsvariablen

Es gibt Umgebungsvariablen, die automatisch von App Hosting ausgefüllt werden. Dazu gehören die von Google Cloud, sowie Firebase-spezifische Umgebungsvariablen, wenn appId bei der Einrichtung im Backend festgelegt ist:

• FIREBASE_CONFIG: (verfügbar in der Build- und Laufzeitumgebung) Enthält die folgenden Konfigurationsinformationen für das Firebase-Projekt:

  {
    "databaseURL": 'https://DATABASE_NAME.firebaseio.com',
    "storageBucket": 'PROJECT_ID.firebasestorage.app',
    "projectId": 'PROJECT_ID'
  }
  

  Diese Konfiguration wird automatisch angewendet, wenn Sie das Firebase Admin SDK ohne Argumente initialisieren.

• FIREBASE_WEBAPP_CONFIG: (nur in der Build-Umgebung verfügbar) Enthält die folgenden Konfigurationsinformationen für das Firebase-Projekt:

  {
    "apiKey": 'API_KEY',
    "appId": 'APP_ID',
    "authDomain": 'AUTH_DOMAIN.firebaseapp.com',
    "databaseURL": 'https://DATABASE_NAME.firebaseio.com',
    "messagingSenderId": 'PROJECT_NUMBER',
    "projectId": 'PROJECT_ID',
    "storageBucket": 'PROJECT_ID.firebasestorage.app',
  }
  

  Das Firebase JS SDK sucht während des Builds automatisch in einem Postinstall-Script nach dieser FIREBASE_WEBAPP_CONFIG Umgebungsvariable. So können Sie das Client SDK auch ohne Argumente initialisieren.

Weitere Informationen zum Initialisieren der SDKs mit diesen Umgebungsvariablen finden Sie unter Firebase Admin SDK und Web-SDKs automatisch initialisieren.

Die Werte in Ihrer tatsächlichen Firebase-Konfiguration entsprechen den jeweiligen Ressourcen, die Sie in Ihrem Projekt bereitgestellt haben.

Variablenhierarchie

Firebase App Hosting wendet Ihre Variablen in einer Reihenfolge der Priorität an, die auf ihrer Quelle basiert. In der Firebase Console festgelegte Werte überschreiben beispielsweise immer die in apphosting.yaml und dotenv Dateien festgelegten Werte oder haben Vorrang vor ihnen.

Tipp: In der Firebase Console können Sie einen bestimmten Roll-out auswählen, um die Details des Roll-outs aufzurufen. Rufen Sie unten im Detailbereich des Roll-outs Umgebungsvariablen in diesem Build auf, um die Liste der während des Roll-outs verwendeten Umgebungsvariablen und ihre Quellen zu sehen.

Hier ist die vollständige Reihenfolge der Priorität:

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

Reservierte Namen und Einschränkungen

Die im Cloud Run Containerlaufzeitvertrag definierten Umgebungsvariablen sind reserviert. Sie können nicht festgelegt werden.

Umgebungsvariablen, die von der Umgebung bereitgestellt werden (außer den automatisch festgelegten), könnten sich in zukünftigen Laufzeitversionen ändern. Als Best Practice empfehlen wir, sich nicht auf Umgebungsvariablen zu verlassen und keine Umgebungsvariablen zu ändern, die Sie nicht explizit festgelegt haben. Außerdem sollten Sie vor alle Umgebungsvariablen einen eindeutigen Schlüssel setzen, um Konflikte zu vermeiden.

Einige Umgebungsvariablenschlüssel sind für die interne Verwendung reserviert. Verwenden Sie keine dieser Schlüssel in Ihren Konfigurationsdateien:

• Leere Strings ("")
• Schlüssel, die „=“ enthalten
• Schlüssel, die mit X_FIREBASE_, X_GOOGLE_ oder CLOUD_RUN_ beginnen
• PORT
• K_SERVICE
• K_REVISION
• K_CONFIGURATION
• Doppelte Schlüssel

apphosting.yaml erstellen und bearbeiten

Für erweiterte Konfigurationen wie Secrets oder Laufzeiteinstellungen wie Limits für Nebenläufigkeit, CPU und Arbeitsspeicher müssen Sie die Datei apphosting.yaml im Stammverzeichnis Ihrer Anwendung erstellen und bearbeiten. Diese Datei unterstützt 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-Startdatei mit einer Beispielkonfiguration (auskommentiert) erstellt. Nach der Bearbeitung kann eine typische apphosting.yaml-Datei so aussehen. Sie enthält Einstellungen für den Cloud Run-Dienst des Back-Ends, einige Umgebungsvariablen und einige Verweise 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 Rest dieses Leitfadens finden Sie weitere Informationen und Kontext zu diesen Beispielkonfigurationen.

Einstellungen für den Cloud Run Dienst konfigurieren

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

• cpu: Anzahl der CPUs, die für jede Serving-Instanz verwendet werden (Standardwert: 0).
• memoryMiB : Menge des Arbeitsspeichers, der für jede 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 ganzzahligen Wert zwischen 128 und 32768 festgelegt werden. Wenn Sie das Arbeitsspeicherlimit erhöhen, müssen Sie jedoch möglicherweise auch die CPU-Limits erhöhen:

• Über 4 GiB sind mindestens 2 CPUs erforderlich.
• Über 8 GiB sind mindestens 4 CPUs erforderlich.
• Über 16 GiB sind mindestens 6 CPUs erforderlich.
• Über 24 GiB sind mindestens 8 CPUs erforderlich.

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

Build- und Ausführungsscripts überschreiben

App Hosting leitet den Build- und Startbefehl Ihrer Anwendung basierend auf dem erkannten Framework ab. Wenn Sie einen benutzerdefinierten Build- oder Startbefehl verwenden möchten, können Sie App Hosting's Standardwerte 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 und Ihre Anwendung wird dann nicht mehr von den Framework-Adaptern unterstützt und alle frameworkspezifischen Optimierungen, die App Hosting bietet, werden deaktiviert. Diese Option ist am besten geeignet, wenn die Funktionen Ihrer Anwendung 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 Anwendung verwenden möchten, der sich vom App Hosting-abgeleiteten Befehl unterscheidet.

Build-Ausgabe konfigurieren

App Hosting optimiert Ihre Anwendungsbereitstellungen standardmäßig, indem nicht verwendete Ausgabedateien gemäß den Angaben des Frameworks gelöscht werden. Wenn Sie die Größe der Anwendungsbereitstellung 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 enthält eine Liste von Verzeichnissen und Dateien relativ zum Stammverzeichnis der Anwendung, die für die Bereitstellung Ihrer Anwendung erforderlich sind. Wenn Sie sicherstellen möchten, dass alle Dateien beibehalten werden, legen Sie „include“ auf [.] fest. 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 des Roll-outs 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 des Erstellens des Back-Ends verfügbar war. Wenn Sie Anforderungen an die Versionsverwaltung und den Lebenszyklus von Parametern haben, können Sie mit Cloud Secret Manager bestimmte Versionen verwenden. Beispiel: So verwenden Sie Version 5:

  - variable: PINNED_API_KEY
    secret: myApiKeySecret@5

Sie können Secrets mit dem Firebase CLI-Befehl firebase apphosting:secrets:set erstellen. Sie werden dann aufgefordert, die erforderlichen Berechtigungen hinzuzufügen. Bei diesem Vorgang können Sie den Secret-Verweis automatisch zu apphosting.yaml hinzufügen.

Wenn Sie alle Funktionen von Cloud Secret Manager nutzen möchten, können Sie stattdessen die Cloud Secret Manager Console verwenden. In diesem Fall müssen Sie Ihrem App Hosting Backend mit dem Firebase Befehlszeilenbefehl firebase apphosting:secrets:grantaccess Berechtigungen gewähren.

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 Verbinden Sie Firebase App Hosting mit einem VPC-Netzwerk.

Verwenden Sie die Zuordnung vpcAccess in Ihrer apphosting.yaml-Datei, um den Zugriff zu konfigurieren. Verwenden Sie entweder einen voll qualifizierten Netzwerk-/Connector-Namen oder eine ID. Mit IDs können Sie die Portabilität zwischen Staging- und Produktionsumgebungen mit unterschiedlichen Connectors/Netzwerken ermöglichen.

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 für serverlose 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 Console und der Firebase CLI verfügbar. In diesem Abschnitt werden einige der häufigsten Verwaltungsaufgaben beschrieben, darunter das Erstellen und Löschen von Back-Ends.

Backend erstellen

Ein App Hosting Backend ist die Sammlung verwalteter Ressourcen, die App Hosting erstellt, um Ihre Webanwendung zu erstellen und auszuführen.

Ein Projektinhaber muss das erste App Hosting Backend erstellen. Nach dieser Ersteinrichtung, App Hosting Administratoren können auch zusätzliche Back-Ends erstellen und verwalten. Wenn Sie alle Repositories Ihrer Organisation sehen möchten, benötigen Sie die Organisationsadministrator Rolle in GitHub. Mit einer Standardmitgliedsrolle werden nur Repositories angezeigt, die Sie selbst erstellt haben. Weitere Informationen finden Sie unter Firebase App Hosting IAM-Rollen.

Firebase Konsole: Navigieren Sie zu Hosting & Serverless > App Hosting, und klicken Sie dann auf Backend erstellen. Wenn dies das erste Backend in Ihrem Firebase Projekt ist, klicken Sie auf Jetzt starten.

Firebase 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 sowohl in der Console als auch in der CLI der Anleitung, um eine Regionauszuwählen, eine GitHub-Verbindungeinzurichten und diese grundlegenden Bereitstellungseinstellungen zu konfigurieren:

• Legen Sie das Stammverzeichnis Ihrer Anwendung fest (Standardwert: /)

  Hier befindet sich normalerweise Ihre package.json-Datei.

• Legen Sie den Live-Zweig fest.

  Dies ist der Zweig Ihres GitHub-Repositorys, der unter Ihrer Live-URL bereitgestellt wird. Oft ist es der Zweig, in den Feature- oder Entwicklungszweige zusammengeführt werden.

• Automatische Roll-outs akzeptieren oder ablehnen

  Automatische Roll-outs sind standardmäßig aktiviert. Nach Abschluss der Backend-Erstellung, können Sie festlegen, dass Ihre Anwendung 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 in der Firebase Console oder mit der Firebase CLI. Entfernen Sie dann manuell die zugehörigen Assets. Achten Sie dabei darauf, keine Ressourcen zu löschen, die von anderen Back-Ends oder anderen Aspekten Ihres Firebase-Projekts verwendet werden.

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

Firebase 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 gelöscht:

   firebase apphosting:backends:delete BACKEND_ID --project PROJECT_ID
   

2. Optional: Löschen Sie auf dem Google Cloud Tab „Artifact Registry“ für die Konsole 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.