Funktionen der 1. Generation auf Cloud Run-Funktionen upgraden

In dieser Anleitung wird beschrieben, wie Sie Ihre HTTP- und Pub/Sub-Funktionen der 1. Generation auf Cloud Run-Funktionen aktualisieren, die in Cloud Run ausgeführt werden. Dieser Leitfaden gilt nur für Funktionen der 1. Generation, die mit der Cloud Functions v1 API erstellt wurden. Die Anleitung in diesem Dokument gilt nicht für Funktionen der 2. Generation, die mit der Cloud Functions v2 API oder Cloud Functions for Firebase erstellt wurden. Cloud Functions for Firebase ist ein separates Produkt.

Nach Abschluss des Upgrades können Sie nur noch über die Cloud Run Admin API und Cloud Run-Tools mit der aktualisierten Funktion interagieren.

Beschränkungen

Das Upgrade-Tool unterstützt derzeit nur das Upgrade von HTTP- und Pub/Sub-ausgelösten Funktionen.

Übersicht über den Upgradevorgang

Hier finden Sie eine allgemeine Übersicht über den Upgradeprozess:

Übersicht über das Upgrade einer Funktion der 1. Generation auf Cloud Run.
Abbildung 1. Übersicht über die Schritte, mit denen eine Funktion der 1. Generation auf Cloud Run aktualisiert wird.

Die Details dieses Vorgangs werden in den folgenden Abschnitten beschrieben.

Übersicht zum Starten des Upgrades

  • Wenn Sie das Upgrade starten (entweder mit der Google Cloud CLI oder der Google Cloud Console), erstellt das Upgrade-Tool eine temporäre Funktion der 2. Generation, die eine Kopie Ihrer ursprünglichen Funktion der 1. Generation ist. Diese Funktion der 2. Generation:
    • Fungiert als Brücke zwischen der ursprünglichen Funktion der 1. Generation und der endgültigen, vollständig aktualisierten Funktion.
    • Sie hat denselben Namen, Code und dieselbe Konfiguration wie die ursprüngliche Funktion der 1. Generation.
      • Wenn Sie eine HTTP-Funktion aktualisieren, hat sie dieselbe cloudfunctions.net-URL wie die ursprüngliche Funktion der 1. Generation und auch eine run.app-Cloud Run-URL.
        • Nach dem Start des Upgrades werden sowohl Ihrer Funktion der 1. Generation als auch Ihrer Funktionskopie der 2. Generation dieselbe cloudfunctions.net-URL zugewiesen. Wenn Anfragen an die URL cloudfunctions.net gesendet werden, wird der Traffic weiterhin an die Funktion der 1. Generation weitergeleitet. Die Kopie der Funktion der 2. Generation hat auch eine Cloud Runrun.app-URL. Die Funktions-URLs der 2. Generation erhalten erst Traffic, wenn Sie den Traffic im nächsten Schritt weiterleiten.
      • Wenn Sie eine Pub/Sub-Funktion aktualisieren, wird dasselbe Pub/Sub-Thema wie für die Funktion der 1. Generation verwendet, aber es ist noch kein Abo vorhanden.
    • Wenn Sie Ihre Abhängigkeiten nicht an eine bestimmte Version angeheftet haben, kann es sein, dass die neu erstellte Kopie der Funktion der 2. Generation eine neuere Abhängigkeitsversion verwendet.
  • Die Funktion der 1. Generation wird weiterhin in der Google Cloud -Konsole der 1. Generation aufgeführt und die temporäre Kopie der 2. Generation wird zum ersten Mal in der Cloud Run-Konsole angezeigt.

Beispiel: Diese Tabelle zeigt den Status von HTTP-Funktionen während des ersten Upgradeschritts.

Funktionen Traffic bereitstellen? In der Konsole sichtbar?
Originalfunktion der 1. Generation Ja, von der URL cloudfunctions.net Ja, Konsole der 1. Generation.
Neue Kopie der 2. Generation Nein. Diese Funktion hat sowohl cloudfunctions.net- als auch run.app-URLs, aber sie stellen erst nach dem Weiterleitungsschritt Traffic bereit. Ja, die Cloud Run-Konsole.

Traffic weiterleiten – Übersicht

  • Wenn Sie Traffic weiterleiten, hängt das Ergebnis davon ab, ob die Funktion, die Sie aktualisieren, eine HTTP-Funktion oder eine Pub/Sub-Funktion ist:
    • Wenn Sie eine HTTP-Funktion aktualisieren, wird der Traffic, der an die URL cloudfunctions.net gerichtet ist, an die Funktion der 2. Generation weitergeleitet. Ihre Funktion der 1. Generation ist weiterhin vorhanden, erhält aber keinen Traffic.
    • Wenn Sie eine Pub/Sub-Funktion aktualisieren, verwendet der Trigger der 2. Generation dasselbe Pub/Sub-Thema, erstellt aber ein neues Abo, das eine Nachricht an die Cloud Run-Funktion sendet. Das alte Abo wird gelöscht.
  • Die Funktion der 1. Generation wird aus der Console der 1. Generation entfernt.
  • Wenn Sie den Befehl gcloud functions describe ausführen, sehen Sie, dass die Umgebung der Funktion jetzt der 2. Generation entspricht.
  • Beachten Sie, dass in dieser Übergangsphase Risiken bestehen, insbesondere für Pub/Sub-Funktionen:
    • Doppelte Nachrichten: Ein neues Abo wird erstellt, bevor das alte Abo gelöscht wird. Dieselbe Pub/Sub-Nachricht kann während dieser Übergangszeit sowohl an Ihre alte als auch an die neue Funktion gesendet werden.
    • Verlust von Nachrichten: Wenn Sie eine Pub/Sub-Funktion aktualisieren und die neue Funktion Nachrichten nach der Umleitung des Traffics nicht verarbeiten kann, riskieren Sie den Verlust von Pub/Sub-Nachrichten. Das gilt insbesondere, wenn für die Funktion Wiederholungen deaktiviert sind. Weitere Informationen finden Sie unter Pub/Sub upgraden.

Beispiel: In dieser Tabelle wird der Status von HTTP-Funktionen während der Umleitung des Traffics dargestellt.

Funktionen Traffic bereitstellen? In der Konsole sichtbar?
Originalfunktion der 1. Generation Nein. In der Console der 1. Generation nicht mehr sichtbar, aber weiterhin vorhanden.
Neue Kopie der 2. Generation Ja, sowohl über die cloudfunctions.net-URL als auch über die run.app-Cloud Run-URL. Ja, die Cloud Run-Konsole.

Rollback für Traffic – Übersicht

  • Wenn Sie den Traffic zurücksetzen, wird mit dem Upgrade-Tool der gesamte Traffic von der Kopie der Funktion der 2. Generation zur ursprünglichen Funktion der 1. Generation zurückgesetzt, die jetzt den gesamten Traffic bereitstellt. Die Funktion der 2. Generation ist weiterhin für Tests verfügbar.
  • Wenn Sie eine Pub/Sub-Funktion zurücksetzen, wird das Abo für die Funktion der 1. Generation wieder erstellt und das Abo für die Funktion der 2. Generation wird gelöscht.
  • Wenn Sie das Upgrade nach dem Rollback des Traffics fortsetzen möchten, müssen Sie den Traffic zuerst wieder an die neue Funktion der 2. Generation weiterleiten.

Beispiel: In dieser Tabelle sehen Sie den Status von HTTP-Funktionen, wenn Sie den Traffic zurücksetzen.

Funktionen Traffic bereitstellen? In der Konsole sichtbar?
Originalfunktion der 1. Generation Ja. Ja, Konsole der 1. Generation.
Neue Kopie der 2. Generation Nein. Nicht mehr in der Cloud Run Console sichtbar, aber weiterhin vorhanden.

Übersicht zum Abbrechen

Sie können das Upgrade jederzeit abbrechen, bevor Sie es ausführen. Sobald Sie die Umstellung bestätigen, ist sie nicht mehr rückgängig zu machen.

Beispiel: In dieser Tabelle sehen Sie den Status von HTTP-Funktionen, wenn Sie das Upgrade abbrechen.

Funktionen Traffic bereitstellen? In der Konsole sichtbar?
Originalfunktion der 1. Generation Ja. Ja, Konsole der 1. Generation.
Text der 2. Generation Nein. Nicht mehr in der Cloud Run-Konsole sichtbar, nicht mehr vorhanden.

Commit-Übersicht (nicht rückgängig zu machen)

  • Durch das Übertragen des Upgrades wird der Upgradeprozess für die Funktion der 1. Generation abgeschlossen. Diese Aktion kann nicht rückgängig gemacht werden.
  • Die temporäre Funktion der 2. Generation wird in eine vollwertige Cloud Run-Funktion auf Grundlage der Cloud Run Admin API umgewandelt.
    • Dies entspricht dem Ausführen des Befehls detach für eine Funktion der 2. Generation. Mit dem Befehl detach wird eine Cloud Functions v2-Funktion von ihrer vorhandenen API-Umgebung getrennt.
    • Künftig können Sie nur noch über die Cloud Run Admin API und Cloud Run-Tools mit der aktualisierten Funktion interagieren.
  • Die Funktion der 1. Generation wird gelöscht und der gesamte Traffic wird an die aktualisierte Cloud Run-Funktion weitergeleitet.

Beispiel: In dieser Tabelle sehen Sie den Status von HTTP-Funktionen nach dem Commit des Upgrades:

Funktionen Traffic bereitstellen? In der Konsole sichtbar?
Neue Cloud Run-Funktion basierend auf der Cloud Run Admin API. Ja, sowohl über die cloudfunctions.net-URL als auch über die run.app-Cloud Run-URL. Ja, die Cloud Run-Konsole.
Originalfunktion der 1. Generation Nein. Nein, sie ist nicht mehr vorhanden.
Text der 2. Generation Nein. Nein, sie ist nicht mehr vorhanden.

Tipps zum Testen

Tests sind ein wesentlicher Bestandteil des Upgrade-Prozesses.

Wir empfehlen, sich mit dem Upgrade-Tool vertraut zu machen, indem Sie es mit Funktionen testen, die nicht in der Produktion verwendet werden. Wenn Sie den Prozess beherrschen und regelmäßig Erfolge erzielen, können Sie mit dem Upgrade von Produktionsfunktionen beginnen.

Hier sind einige der Tools und Techniken, mit denen Sie Ihre Funktionen während eines Upgrades testen können:

  • Wenn sich der Status Ihrer Funktionen ändert, verwenden Sie die Google Cloud CLI-Befehle describe, um zu prüfen, ob die Funktion vorhanden ist und ob ihre Umgebung und Version wie erwartet sind. Je nach aktuellem Status der Funktion, die aktualisiert wird, können Sie eine der folgenden Optionen verwenden.

    • Cloud Run:

      gcloud run services describe FUNCTION_NAME --format yaml

    • Cloud Functions:

      gcloud functions describe --region REGION_NAME FUNCTION_NAME

  • Auf der Seite „Logging“ in der Konsole der 1. Generation und in der Cloud Run-Konsole können Sie die Details des Funktions-Traffics einsehen.

  • Verwenden Sie die Cloud Run-Konsole, um die Kopie der Funktion der 2. Generation während des Upgrades anzusehen und zu testen:

    • Verwenden Sie den Tab Trigger, um die Kopie der Funktion der 2. Generation nach dem Start der Umstellung zu testen.
    • Auf dem Tab YAML finden Sie Details zur Funktion, einschließlich der Cloud Run-run.app-URL.

Hinweise

Bevor Sie mit dem Upgrade beginnen, sollten Sie prüfen, ob die folgenden Voraussetzungen erfüllt sind:

  • Sie haben die Cloud Run API aktiviert:

    gcloud services enable run.googleapis.com

  • Sie haben eine vorhandene HTTP- oder Pub/Sub-Funktion der 1. Generation.

  • Sie haben die erforderlichen IAM-Rollen:

    • Sie müssen roles/iam.serviceAccountUser für das Dienstkonto der Funktion festlegen.
    • Sie benötigen die Rolle roles/cloudfunctions.admin oder eine entsprechende Rolle für das Projekt, um das Upgrade durchzuführen.
    • Für eine Pub/Sub-Funktion mit der Einstellung no-retry haben Sie die Rolle roles/serviceusage.consumer oder eine benutzerdefinierte Rolle mit der Berechtigung serviceusage.services.user.
    • Zum Übertragen eines Pub/Sub-Funktionsupgrades benötigen Sie die Rolle roles/pubsub.admin. Die Rolle roles/pubsub.admin ist eine Rolle auf Projektebene, die administrativen Zugriff auf alle Pub/Sub-Ressourcen innerhalb eines Projekts gewährt.

    So rufen Sie die IAM-Richtlinien Ihrer Funktion auf:

    gcloud functions get-iam-policy FUNCTION_NAME

  • Sie benötigen die Berechtigung roles/cloudfunctions.admin für das Dienstkonto der Funktion. Verwenden Sie den Befehl gcloud functions add-iam-policy-binding, um die Rolle roles/cloudfunctions.admin zu erteilen, z. B.:

    gcloud functions add-iam-policy-binding FUNCTION_NAME \
   --region=REGION \
   --member=serviceAccount:SERVICE_ACCOUNT \
   --role="roles/cloudfunctions.admin"

    Wenn beim Ausführen dieses Befehls Fehler auftreten, prüfen Sie, ob Ihre Funktion den Richtlinien Ihrer Organisation entspricht. Beispielsweise lässt Ihre Organisation möglicherweise keine nicht authentifizierten HTTP-Funktionen zu.

Weitere Informationen zu Mitgliedern und Rollen finden Sie unter Hauptkonten hinzufügen und Rollen zuweisen.

HTTP-Funktionen aktualisieren

In diesem Abschnitt wird beschrieben, wie Sie eine HTTP-Funktion der 1. Generation auf eine Cloud Run Function aktualisieren. Informationen zum Aktualisieren einer Pub/Sub-Funktion der 1. Generation finden Sie unten.

Nachdem Sie den Traffic weitergeleitet und das Upgrade durchgeführt haben, wie in den folgenden Abschnitten beschrieben, funktioniert die cloudfunctions.net-URL, die mit der ursprünglichen HTTP-Funktion der 1. Generation verknüpft ist, weiterhin und leitet Traffic an die neue Cloud Run-Funktion weiter.

HTTP-Funktionsupgrade starten

In diesem Schritt wird eine Kopie Ihrer Funktion der 1. Generation in der 2. Generation erstellt.

Console

  1. Wechseln Sie in der Google Cloud Console zur Seite „Functions (1st gen)“:

    Zu Cloud Functions (1. Generation)

  2. Suchen Sie die Funktion der 1. Generation, die Sie aktualisieren möchten, und prüfen Sie, ob ihr Status in der Spalte Upgradestatus Bereit für Upgrade ist.

  3. Klicken Sie auf den Funktionsnamen, um die zugehörige Detailseite aufzurufen.

  4. Klicken Sie auf der Seite „Funktionsdetails“ unter Für Upgrade verfügbar auf Upgrade.

  5. Folgen Sie der Anleitung, um das Upgrade zu starten.

Nachdem Sie diesen Schritt abgeschlossen haben, wird das Feld Upgrade wird ausgeführt angezeigt. Klicken Sie auf den Link Zu Cloud Run, um mit dem Upgrade fortzufahren.

gcloud

Führen Sie den Befehl gcloud beta functions upgrade mit dem Flag --setup-config aus.

gcloud beta functions upgrade FUNCTION_NAME --setup-config

Ersetzen Sie FUNCTION_NAME durch den Namen Ihrer Funktion der 1. Generation.

Nach dem Start des Upgrades:

  • Die Funktion der 1. Generation stellt weiterhin Traffic über ihre ursprüngliche URL bereit. Sie können diese URL auf der Detailseite der Funktion in der Console für Functions (1. Generation) aufrufen und den Tab Trigger öffnen.

  • Es wird eine temporäre Funktion der 2. Generation erstellt, die eine Kopie der Funktion der 1. Generation ist. Sie hat dieselbe cloudfunctions.net-URL wie die Funktion der 1. Generation sowie eine neue Cloud Run-run.app-URL. Sie können beide URLs auf der Detailseite der Funktion in der Cloud Run Console auf dem Tab „YAML“ aufrufen. Alternativ können Sie diesen Befehl verwenden:

    gcloud run services describe YOUR_SERVICE_NAME \
    --region YOUR_REGION \
    --format="value(status.url)"

  • So können Sie prüfen, ob die Kopie der 2. Generation Ihrer Funktion der 1. Generation vorhanden ist:

    gcloud run services describe FUNCTION_NAME --format yaml

  • Sie können die Umgebung der 1st gen-Funktion überprüfen. In der Ausgabe sollte die Funktionsumgebung als 1st gen angezeigt werden:

    gcloud functions describe --region REGION_NAME FUNCTION_NAME

Fehlerbehebung beim Schritt „Upgrade starten“

Das Upgrade schlägt unter den folgenden Bedingungen fehl:

  • Eine Funktion mit demselben Namen ist in derselben Region und demselben Projekt bereits vorhanden.
  • Die Funktion der 1. Generation verwendet eine eingestellte Laufzeit und kann daher erst aktualisiert werden, wenn Sie sie mit einer unterstützten Laufzeit noch einmal bereitstellen.
  • Dem Aufrufer fehlt die Berechtigung cloudfunctions.functions.generationUpgrade. Der Aufrufer benötigt die Rolle roles/cloudfunctions.admin oder eine entsprechende Rolle für das Projekt.

Traffic für HTTP-Funktion weiterleiten

An diesem Punkt sollten Sie die URL sowohl für die ursprüngliche Funktion als auch für die Kopie testen. Prüfen Sie, ob sie wie erwartet funktionieren, bevor Sie fortfahren. Wenn Probleme auftreten, brechen Sie das Upgrade ab, um zu einem sauberen Zustand zurückzukehren, in dem Sie alle zugrunde liegenden Probleme in der Funktion der 1. Generation beheben können.

Im Weiterleitungsschritt wird der Traffic von der Cloud Functions-URL der 1. Generation zur Kopie der Funktion der 2. Generation weitergeleitet.

Console

  1. Klicken Sie auf der Seite mit den Details zu Cloud Run-Funktionen im Bereich Upgrade wird ausgeführt auf Zu Cloud Run.
  2. Klicken Sie auf Funktion testen, um die Funktion zu testen (optional, aber dringend empfohlen).
  3. Wenn Sie bereit sind, klicken Sie auf Traffic umleiten.

gcloud

Führen Sie den Befehl gcloud beta functions upgrade mit dem Flag --redirect-traffic aus.

gcloud beta functions upgrade FUNCTION_NAME --redirect-traffic

Nach der Weiterleitung des Traffics wird der Traffic von der Kopie der Funktion der 2. Generation sowohl an die Funktions-URL (cloudfunctions.net) als auch an die Cloud Run-URL (run.app) gesendet.

HTTP-Funktion nach der Weiterleitung testen

  • Funktionsumgebung prüfen:

    gcloud functions describe --region REGION_NAME FUNCTION_NAME

    Die Ausgabe zeigt die Umgebung als 2nd gen.

  • Verwenden Sie das Tool für die Konsolenprotokollierung, um Ihre Kopie der Funktion der 2. Generation mit der ursprünglichen Funktion der 1. Generation zu vergleichen.

Fehlerbehebung bei der Weiterleitung

Die Weiterleitung schlägt unter den folgenden Bedingungen fehl:

  • Sie haben den vorherigen Schritt (--setup-config) nicht ausgeführt.

Rollback des Traffics für HTTP-Funktion durchführen

Wenn Sie das Upgrade noch nicht bestätigen möchten, können Sie den Traffic auf die Funktion der 1. Generation zurücksetzen.

Console

Klicken Sie in der Cloud Run Console auf der Detailseite für Cloud Run-Funktionen im Bereich Upgrade in progress (Upgrade wird ausgeführt) auf Rollback traffic (Traffic zurücksetzen).

gcloud

Führen Sie den Befehl gcloud beta functions upgrade mit dem Flag --rollback-traffic aus.

gcloud beta functions upgrade FUNCTION_NAME --rollback-traffic

Nach dem Rollback des Traffics:

  • Die Funktion der 1. Generation stellt Traffic für die cloudfunctions.net-URL bereit.
  • Die Kopie der Funktion der 2. Generation ist weiterhin verfügbar und kann über die run.app-URL ausgelöst werden.

So prüfen Sie die Funktionsumgebung: Die Ausgabe sollte die Funktionsumgebung als 1st gen anzeigen:

gcloud functions describe --region REGION_NAME FUNCTION_NAME

Das Rollback schlägt fehl, wenn Sie den Traffic nicht an die Funktion der 2. Generation weitergeleitet haben.

Upgrade für HTTP-Funktion committen

Mit diesem Schritt wird das Upgrade abgeschlossen. Danach können Sie den Vorgang nicht mehr abbrechen. Bevor Sie diesen Schritt ausführen, sollten Sie Ihre Funktionen gründlich getestet haben.

Console

Klicken Sie in der Cloud Run Console auf der Seite mit den Details zu Cloud Run Functions im Bereich Upgrade wird ausgeführt auf Upgrade bestätigen.

gcloud

Führen Sie den Befehl gcloud beta functions upgrade mit dem Flag --commit aus.

gcloud beta functions upgrade FUNCTION_NAME --commit

Nach dem Ausführen des Upgrades:

  • Die Funktion der 1. Generation wird gelöscht und die Kopie der Funktion der 2. Generation wird getrennt und wird zu einer vollwertigen Cloud Run-Funktion.
  • Die Cloud Run-Funktion behält die cloudfunctions.net-URL zusammen mit der neuen run.app-URL bei.

  • Sie können prüfen, ob die 1st gen-Funktion nicht mehr vorhanden ist:

    gcloud functions describe --region REGION_NAME FUNCTION_NAME

  • Sie können die Details des Cloud Run-Dienstes prüfen: 

    gcloud run services describe FUNCTION_NAME --format yaml

Die Ausgabe zeigt, dass eine neue Generation erstellt wurde und das Label Goog-managed-by einen leeren Wert hat.

Der Commit schlägt fehl, wenn der Traffic nicht zur Cloud Run-Funktion umgeleitet wurde.

Pub/Sub-Funktionen aktualisieren

In diesem Abschnitt wird beschrieben, wie Sie ein Upgrade einer Pub/Sub-Funktion der 1. Generation auf eine Cloud Run-Funktion durchführen.

Das Upgrade einer Pub/Sub-Funktion der 1. Generation folgt demselben grundlegenden Muster wie das Upgrade einer HTTP-Funktion, es gibt jedoch einige zusätzliche Aspekte zu berücksichtigen:

  • Das Deaktivieren von Wiederholungen bei Fehlern wird in Cloud Run nicht unterstützt, ist aber die Standardeinstellung in der 1. Generation. Möglicherweise haben Sie also Funktionen beider Typen. Was das Upgrade-Tool macht, hängt von dieser Einstellung ab:

    • Wenn für Ihre Funktion der 1. Generation Wiederholungsversuche deaktiviert sind (die Standardeinstellung für die 1. Generation), erstellt das Upgrade-Tool einen Eventarc-Pub/Sub-Trigger zusammen mit einer Warteschlange für unzustellbare Nachrichten (Dead Letter Queue, DLQ). Das Upgrade-Tool legt die IAM-Richtlinie (Identity and Access Management) für Abos und ihre Themen fest. Nach Abschluss des Upgrades werden die nicht zugestellten Nachrichten im Thema für die Warteschlange für unzustellbare Nachrichten gespeichert. Sie können sie abrufen, indem Sie ein neues Abo für die Warteschlange für unzustellbare Nachrichten erstellen.
    • Wenn für Ihre Funktion der 1. Generation Wiederholungsversuche aktiviert sind, erstellt das Upgrade-Tool einen Eventarc-Pub/Sub-Trigger mit Standardeinstellungen.

Upgrade für die Pub/Sub-Funktion starten

In diesem Schritt wird eine Kopie der Funktion der 1. Generation in der 2. Generation erstellt.

Console

  1. Wechseln Sie in der Google Cloud Console zur Seite „Cloud Functions (1. Generation)“:

    Zu Cloud Functions (1. Generation)

  2. Suchen Sie die Funktion der 1. Generation, die Sie aktualisieren möchten, und prüfen Sie, ob ihr Status in der Spalte Upgradestatus Bereit für Upgrade ist.

  3. Klicken Sie auf den Funktionsnamen, um die zugehörige Detailseite aufzurufen.

  4. Klicken Sie auf der Seite „Funktionsdetails“ unter Für Upgrade verfügbar auf Upgrade.

Wenn diese Phase abgeschlossen ist, wird das Feld Upgrade wird ausgeführt angezeigt. Klicken Sie auf den Link Zu Cloud Run, um mit dem Upgrade fortzufahren.

gcloud

Führen Sie den Befehl gcloud beta functions upgrade mit dem Flag --setup-config aus.

gcloud beta functions upgrade FUNCTION_NAME --setup-config

Ersetzen Sie FUNCTION_NAME durch den Namen Ihrer Funktion der 1. Generation.

Optional können Sie ein Dienstkonto für den Trigger angeben:

gcloud beta functions upgrade FUNCTION_NAME --setup-config --trigger-service-account=CUSTOM_SA_EMAIL

Ersetzen Sie CUSTOM_SA_EMAIL durch die E-Mail-Adresse Ihres benutzerdefinierten Dienstkontos.

Wenn dem Dienstkonto des Triggers (Compute Engine-Standarddienstkonto oder angegebenes benutzerdefiniertes Dienstkonto) die Berechtigung run.route.invoke fehlt, werden Sie aufgefordert, die Rolle roles/run.invoker zu binden.

Nach dem Start des Upgrades:

  • Die Funktion der 1. Generation stellt weiterhin Traffic über ihre ursprüngliche URL bereit.
  • Es wird eine Kopie der 2. Generation Ihrer Funktion der 1. Generation erstellt. Sie können sie über die Cloud Run-URL auslösen.
  • Die Funktion der 1. Generation stellt weiterhin Traffic für ihre cloudfunctions.net-URL bereit.

Pub/Sub-Funktion nach dem Start des Upgrades testen

  • So können Sie prüfen, ob die Kopie der 2. Generation Ihrer Funktion der 1. Generation vorhanden ist:

    gcloud run services describe FUNCTION_NAME --format yaml

  • Sie können die Umgebung der 1st gen-Funktion überprüfen. In der Ausgabe sollte die Funktionsumgebung als 1st gen angezeigt werden:

    gcloud functions describe --region REGION_NAME FUNCTION_NAME

  • Veröffentlichen Sie eine Nachricht im Zielthema, um die Funktion der 1. Generation auszulösen.

  • Wenn Sie die neue Funktion testen möchten, fügen Sie ihr einen Pub/Sub-Trigger hinzu und prüfen Sie, ob die Funktion wie erwartet auf den Trigger reagiert:

    1. Wählen Sie die Funktion in der Cloud Run Console aus und öffnen Sie den Tab Trigger.
    2. Klicken Sie auf Trigger hinzufügen und wählen Sie im Bereich Eventarc-Trigger ein Thema aus, um die Funktion auszulösen. Standardmäßig wird die Funktion ausgelöst, wenn eine Nachricht im Thema veröffentlicht wird.
    3. Klicken Sie im Bereich Upgrade wird ausgeführt auf Funktion testen.
    4. Veröffentlichen Sie im Cloud Code for Cloud Shell-Fenster, das sich öffnet, eine Nachricht für das Thema, das Sie auf dem Tab Triggers (Auslöser) hinzugefügt haben.
    5. Wechseln Sie in der Cloud Run-Konsole zu Beobachtbarkeit > Logs, um zu prüfen, ob Ihre Funktion die Nachricht veröffentlicht hat. Alternativ können Sie die Befehlszeile in Cloud Code für Cloud Shell verwenden, um die Logausgabe anzusehen.

    Angenommen, Sie haben eine einfache Hello World-Funktion, die eine Begrüßung veröffentlicht. Nachdem Sie den neuen Trigger angegeben haben, können Sie ihn in Cloud Code for Cloud Shell so testen:

    gcloud pubsub topics publish YOUR_TOPIC_NAME --message YOUR_NAME
gcloud functions logs read --region YOUR_REGION --limit 50

Fehlerbehebung beim Start des Pub/Sub-Upgrades

Das Upgrade schlägt unter den folgenden Bedingungen fehl:

  • Eine Cloud Run-Funktion mit demselben Namen ist in derselben Region und demselben Projekt bereits vorhanden.
  • Sie haben versucht, eine Funktion der 2. Generation zu aktualisieren.
  • Die Funktion der 1. Generation wird bereits aktualisiert.
  • Die 1st gen-Funktion ist nicht vorhanden.
  • Die Funktion der 1. Generation befindet sich in einem Fehlerstatus.
  • Die Funktion der 1. Generation ist weder eine HTTP- noch eine Pub/Sub-Funktion.
  • Dem Aufrufer fehlt die Berechtigung cloudfunctions.functions.generationUpgrade. Der Aufrufer benötigt die Rolle roles/cloudfunctions.admin oder eine entsprechende Rolle für das Projekt.

Traffic für Pub/Sub-Funktion weiterleiten

In diesem Schritt wird der Traffic von der Cloud Functions-URL der 1. Generation zur Kopie der Funktion der 2. Generation weitergeleitet.

Console

  1. Klicken Sie auf der Seite mit den Details zu Cloud Run-Funktionen im Bereich Upgrade wird ausgeführt auf Zu Cloud Run.
  2. Klicken Sie auf Funktion testen, um die Funktion zu testen (optional, aber dringend empfohlen).
  3. Wenn Sie bereit sind, klicken Sie auf Traffic umleiten.

gcloud

Führen Sie den Befehl gcloud beta functions upgrade mit dem Flag --redirect-traffic aus.

gcloud beta functions upgrade FUNCTION_NAME --redirect-traffic

Nach der Weiterleitung des Traffics verarbeitet die Funktion der 2. Generation Traffic sowohl an der Cloud Functions-URL als auch an der Cloud Run-URL.

Pub/Sub nach der Weiterleitung von Traffic testen

  • Sie können die Funktionsumgebung so überprüfen:

    gcloud functions describe --region REGION_NAME FUNCTION_NAME

    Die Ausgabe zeigt die Umgebung als 2nd gen.

    • Die eventTrigger.retryPolicy entspricht der beim Erstellen der Funktion angegebenen Wiederholungsrichtlinie.
    • eventTrigger.serviceAccountEmail ist entweder das Compute Engine-Standarddienstkonto oder das angegebene benutzerdefinierte Dienstkonto.
    • Wenn Sie eine Nachricht im Zielthema veröffentlichen, wird jetzt die Kopie der Funktion der 2. Generation ausgelöst.

Fehlerbehebung bei Pub/Sub für die Weiterleitung

Die Weiterleitung schlägt unter den folgenden Bedingungen fehl:

  • Sie haben den vorherigen Schritt (--setup-config) nicht ausgeführt.
  • Die Cloud Run-Funktion wurde manuell gelöscht.

Rollback des Traffics für die Pub/Sub-Funktion durchführen

Mit diesem Schritt wird der Traffic wieder zur Funktion der 1. Generation zurückgeleitet.

Console

Klicken Sie auf der Seite mit den Cloud Run-Funktionsdetails im Bereich Upgrade wird ausgeführt auf Rollback-Traffic.

gcloud

Führen Sie den Befehl gcloud beta functions upgrade mit dem Flag --rollback-traffic aus.

gcloud beta functions upgrade FUNCTION_NAME --rollback-traffic

Nach dem Rollback des Traffics:

  • Die Funktion wird auf den Zustand zurückgesetzt, in dem sie sich unmittelbar nach dem ersten Upgradeschritt befand.
  • Die Funktion der 1. Generation stellt Traffic für die cloudfunctions.net-URL bereit.

  • Die Kopie der 2. Generation ist weiterhin verfügbar und kann über die Cloud Run-URL ausgelöst werden.

  • Sie können die Funktionsumgebung so überprüfen:

    gcloud functions describe --region REGION_NAME FUNCTION_NAME

    In der Ausgabe sollte die Funktionsumgebung als 1st gen angezeigt werden.

  • Wenn eine Nachricht im Zielthema veröffentlicht wird, wird die Funktion der 1. Generation ausgelöst.

Das Rollback schlägt fehl, wenn Sie keinen Traffic an die Cloud Run-Funktion weitergeleitet haben.

Commit für das Upgrade der Pub/Sub-Funktion durchführen

Mit diesem Schritt wird das Upgrade abgeschlossen. Danach können Sie den Vorgang nicht mehr abbrechen. Dieser Schritt kann nicht rückgängig gemacht werden. Bevor Sie diesen Schritt ausführen, müssen Sie Ihre Funktionen gründlich getestet haben.

Console

Klicken Sie auf der Seite mit den Details zu Cloud Run Functions im Bereich Upgrade wird ausgeführt auf Upgrade bestätigen.

gcloud

Führen Sie den Befehl gcloud beta functions upgrade mit dem Flag --commit aus.

gcloud beta functions upgrade FUNCTION_NAME --commit

Nach dem Ausführen des Upgrades:

  • Die Funktion der 1. Generation wird gelöscht.
  • Die Cloud Run-Funktion behält die cloudfunctions.net-URL bei.
  • Sie können prüfen, ob die Funktion nicht mehr in der Liste angezeigt wird: 
    gcloud functions describe --region REGION_NAME FUNCTION_NAME
  • Sie können die Details des Cloud Run-Dienstes prüfen: 
    gcloud run services describe FUNCTION_NAME --format yaml
    • Die Ausgabe zeigt, dass eine neue Generation erstellt wurde. Das Label Goog-managed-by sollte einen leeren Wert haben.
  • Wenn Sie die Funktion der 1. Generation erstellt haben, ohne Retry on Failures (Bei Fehlern wiederholen) zu aktivieren, hat das Pub/Sub-Abo für den Trigger eine Warteschlange für unzustellbare Nachrichten (Dead Letter Queue, DLQ).
  • Wenn Sie eine Nachricht im Zielthema veröffentlichen, wird jetzt die Cloud Run-Funktion ausgelöst.

Der Commit schlägt unter den folgenden Bedingungen fehl:

  • Der Traffic wurde nicht an die Cloud Run-Funktion weitergeleitet.
  • Die Cloud Run-Funktion wurde manuell gelöscht.

Upgrade abbrechen

Durch diese Aktion wird der Upgrade-Vorgang abgebrochen. Die neue Kopie der Funktion der 2. Generation wird gelöscht und die Funktion der 1. Generation stellt weiterhin Traffic für die ursprüngliche cloudfunctions.net-URL bereit. Sie können diese Aktion jederzeit während des Upgradevorgangs ausführen, bevor Sie das Upgrade durchführen.

Wenn Sie das Upgrade über die Google Cloud Console durchführen, können Sie den Vorgang in der Benutzeroberfläche nur unmittelbar nach dem ersten Upgradevorgang abbrechen. Die Schaltfläche Abbrechen befindet sich oben links in der Konsole für Functions (1. Generation). Wenn Sie die Google Cloud CLI verwenden, können Sie das Upgrade jederzeit abbrechen, bevor Sie es bestätigen. Danach ist der Vorgang nicht mehr rückgängig zu machen.

Sie können ein Funktions-Upgrade mit der Google Cloud CLI abbrechen, auch wenn Sie das Upgrade über die Google Cloud Console durchgeführt haben:

gcloud beta functions upgrade FUNCTION_NAME --abort

Nach dem Abbrechen des Upgrades:

  • Die Kopie der Funktion der 2. Generation wird gelöscht.
  • Die Funktion der 1. Generation stellt Traffic für die cloudfunctions.net-URL bereit.
  • In der Google Cloud Console ändert sich der Upgradestatus der Funktion von Konfiguration kopiert zurück zu Bereit für Upgrade.

  • Sie können prüfen, ob der Cloud Run-Dienst nicht mehr in der Liste angezeigt wird:

    gcloud run services list

  • Sie können die Funktionsumgebung so überprüfen:

    gcloud functions describe --region REGION_NAME FUNCTION_NAME

Die Ausgabe zeigt die Funktionsumgebung als 1st gen.

Der Abbruchvorgang schlägt fehl, wenn Sie das Upgrade bereits übernommen haben.

Konvertierte IAM-Richtlinien prüfen

Während des Upgrades werden Rollen und Berechtigungen zwischen Cloud Functions der 1. Generation und den neuen Cloud Run-Funktionen nach Möglichkeit konvertiert.

Beim Upgrade werden IAM-Rollen für Cloud Functions (1. Generation) in entsprechende Cloud Run-Rollen konvertiert.

Conversion-Regeln:

  • roles/cloudfunctions.invoker wird in roles/run.invoker umgewandelt.
  • roles/cloudfunctions.developer wird in roles/run.sourceDeveloper umgewandelt.
  • roles/cloudfunctions.viewer wird in roles/run.sourceViewer umgewandelt.
  • roles/cloudfunctions.admin wird in roles/run.admin und roles/run.sourceDeveloper konvertiert.

Das Upgrade der IAM-Richtlinie schlägt fehl, wenn dem Aufrufer die Berechtigungen projects.getIamPolicy oder run.setIamPolicy fehlen. Der Aufrufer benötigt die Rolle roles/cloudfunctions.admin oder eine entsprechende Rolle für das Projekt.

IAM-Richtlinien-Upgrade prüfen

Prüfen Sie Ihre IAM-Richtlinien in jeder Phase des Upgrades, um sicherzustellen, dass sie die erwarteten Werte haben:

  1. Starten Sie den Upgradevorgang für Ihre Funktion:

    gcloud beta functions upgrade FUNCTION_NAME --setup-config

    In der Ausgabe wird eine Warnmeldung angezeigt, wenn benutzerdefinierte Rollenbindungen erkannt werden.

  2. Prüfen Sie, ob die für die Funktion der 1. Generation festgelegten IAM-Richtlinien in die Cloud Run-Funktion konvertiert und aktualisiert wurden:

    gcloud functions get-iam-policy FUNCTION_NAME
gcloud run services get-iam-policy FUNCTION_NAME

  3. Prüfen Sie, ob die Rollenbindung des Cloud Run Functions-Aufrufers auf Projektebene in die Cloud Run-Funktion konvertiert und aktualisiert wurde:

    gcloud projects get-iam-policy PROJECT_ID | grep "roles/cloudfunctions.invoker"
gcloud run services get-iam-policy FUNCTION_NAME

Nächste Schritte