Express Links konfigurieren

Mit Express-Links in Ambient Networking können Sie einen Cloud Run-Quelldienst mit einem Cloud Run-Zieldienst im selben Projekt und in derselben Region verbinden, ohne Authentifizierungscode in Ihre Anwendung schreiben oder ein Service Mesh konfigurieren zu müssen.

Wenn ein Cloud Run-Dienst einen anderen durch Identity and Access Management (IAM) geschützten Cloud Run-Dienst aufruft, muss die Anfrage ein OpenID Connect-ID-Token (OIDC) enthalten, damit das Ziel die Identität und Berechtigungen des Aufrufers prüfen kann. Ohne Express Link müssen Sie entweder Code für die Dienst-zu-Dienst-Authentifizierung in Ihre Anwendung schreiben, um Tokens vom Metadatenserver abzurufen und anzuhängen, oder Cloud Service Mesh-Ressourcen wie ein VPC-Netzwerk (Virtual Private Cloud), Backend-Dienste und Routingregeln konfigurieren. Ein Express Link lagert diese Authentifizierungs- und Routing-Arbeit an den vollständig verwalteten Ambient-Sidecar-Container aus. So bleibt Ihr Anwendungscode portabel und konzentriert sich auf die Geschäftslogik.

Anwendungsfälle

Sie können Express Links für die folgenden Szenarien verwenden:

  • Dienst-zu-Dienst-Authentifizierung aus dem Anwendungscode auslagern: Verbinden Sie einen aufrufenden Cloud Run-Dienst über einfaches HTTP mit einem IAM-geschützten Cloud Run-Zieldienst. Der Ambient-Sidecar ruft automatisch das OIDC-ID-Token des Quelldienstes ab, fügt es ein und verschlüsselt die Anfrage über HTTPS.
  • Ziel-URLs mit benutzerdefinierten Hostnamen abstrahieren: Konfigurieren Sie einen benutzerdefinierten Hostnamen für den Express Link mit dem Flag --matches-hostname, damit Ihre Quellanwendung Anfragen an eine logische Adresse wie http://my-backend sendet, anstatt die deterministische URL des Ziels hartzucodieren. Wenn sich der Zieldienst ändert, können Sie den Express Link neu erstellen, sodass er auf das neue Ziel verweist, ohne den Quell-Anwendungscode Ihrer Anwendung zu ändern oder neu bereitzustellen.
  • Punkt-zu-Punkt-Dienstaufrufe ohne Service Mesh vereinfachen: Sie erhalten eine automatische Einfügung von Anmeldedaten zwischen Cloud Run-Diensten, ohne ein VPC-Netzwerk, Netzwerk-Endpunktgruppen, Backend-Dienste oder Cloud DNS-Einträge bereitstellen zu müssen, die für Cloud Service Mesh erforderlich sind.

In der folgenden Tabelle werden die Schritte zum Einrichten der authentifizierten Dienst-zu-Dienst-Kommunikation mit und ohne Express Link verglichen:

Schritt Ohne Express Link Mit einem Express Link
1. Zieldienst bereitstellen Stellen Sie den Cloud Run-Zieldienst mit erforderlicher IAM-Authentifizierung (--no-allow-unauthenticated) bereit. Gleich.
2. Aufruferberechtigung gewähren Weisen Sie dem Dienstkonto des Quelldienstes die Rolle „Cloud Run-Aufrufer“ (roles/run.invoker) für den Zieldienst zu. Gleich.
3. Ausgehende Anfrage konfigurieren Schreiben Sie Code in Ihrer Quellanwendung, um ein OIDC-ID-Token für die Ziel-URL abzurufen und es über HTTPS an den Authorization: Bearer-Header anzuhängen. Senden Sie eine einfache http://-Anfrage an die Ziel-URL oder den benutzerdefinierten Hostnamen ohne Authentifizierungscode in Ihrer Quellanwendung.
4. Quelldienst bereitstellen Stellen Sie den Cloud Run-Quelldienst bereit. Stellen Sie den Cloud Run-Quelldienst mit aktiviertem Ambient Networking bereit und erstellen Sie dann einen Express-Link zwischen dem bereitgestellten Quell- und Zieldienst.

Architektur

Wenn Sie Ambient Networking für einen Cloud Run-Quelldienst aktivieren und einen Express Link erstellen, konfiguriert Cloud Run den vollständig verwalteten Envoy-Sidecar-Container, der in jeder Containerinstanz neben Ihrem Anwendungscontainer ausgeführt wird.

Wenn Ihre Anwendung eine einfache HTTP-Anfrage an die deterministische URL des Zieldienstes oder an einen benutzerdefinierten Hostnamen sendet, den Sie im Express Link konfigurieren, führt der Ambient-Sidecar-Container automatisch Folgendes aus:

  1. Fängt ausgehende HTTP-Anfragen ab, die für den Zieldienst bestimmt sind.
  2. Ruft ein OIDC-ID-Token für das Dienstkonto des Quelldienstes ab und fügt es in den Header Authorization ein.
  3. Verschlüsselt die Anfrage und leitet sie über HTTPS (One-Way-TLS) an den Cloud Run-Zieldienst weiter, der die IAM-Berechtigungen des Aufrufers überprüft.
Ein Anwendungscontainer in einem Cloud Run-Quelldienst, der eine einfache HTTP-Anfrage an den Ambient-Sidecar-Container sendet. Dieser fängt die Anfrage ab, fügt ein OIDC-ID-Token ein und leitet das ID-Token und die Nutzlast über HTTPS über einen Express Link an einen Cloud Run-Zieldienst weiter.
Abbildung 1. Der Ambient-Sidecar-Container fängt ausgehende Anfragen von Ihrem Quelldienst ab, fügt ein OIDC-ID-Token ein und leitet die Anfrage über HTTPS (One-Way-TLS) an den Zieldienst weiter.

Netzwerkverbindung und Datenebene

Ein Express Link konfiguriert das Abfangen ausgehender Anfragen und das Einfügen von Anmeldedaten im Ambient-Sidecar, ersetzt aber nicht den zugrunde liegenden Netzwerkpfad zwischen Ihren Diensten. Sie müssen jedoch dafür sorgen, dass der Quelldienst den Pfad für eingehenden Traffic des Zieldienstes erreichen kann:

Hinweis

  1. Melden Sie sich in Ihrem Google Cloud Konto an. Wenn Sie mit Google Cloudnoch nicht vertraut sind, erstellen Sie einfach ein Konto, um die Leistungsfähigkeit unserer Produkte in der Praxis sehen und bewerten zu können. Neukunden erhalten außerdem ein Guthaben von 300 $, um Arbeitslasten auszuführen, zu testen und bereitzustellen.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  5. Verify that billing is enabled for your Google Cloud project.

  6. Aktivieren Sie die Cloud Run, Network Services und Traffic Director APIs, falls sie noch nicht aktiviert sind.

    Rollen, die zum Aktivieren von APIs erforderlich sind

    Zum Aktivieren von APIs benötigen Sie die Berechtigung serviceusage.services.enable. Wenn Sie das Projekt erstellt haben, haben Sie diese Berechtigung wahrscheinlich bereits über die Inhaberrolle (roles/owner). Andernfalls können Sie diese Berechtigung über die Rolle „Service Usage-Administrator“ (roles/serviceusage.serviceUsageAdmin) erhalten. Informationen zum Zuweisen von Rollen

    APIs aktivieren

  7. Sie benötigen einen vorhandenen Cloud Run-Quelldienst und einen vorhandenen Cloud Run-Zieldienst im selben Projekt und in derselben Region.
  8. Prüfen Sie, ob Ambient Networking aktiviert ist, und zwar mit dem Bereich global für Ihren Cloud Run-Quelldienst. Führen Sie beispielsweise gcloud beta run services update SOURCE_SERVICE --ambient-networking --ambient-scope=global --region=REGION aus und denken Sie daran, zuerst die CPU- und Arbeitsspeicherlimits Ihres Dienstes zu erhöhen.

  9. Informationen zur Nutzung von Sidecars für Ambient Networking finden Sie auf der Seite mit den Preisen für Cloud Run. Die Abrechnung für Ambient-Features wird während der Vorabversion nicht erzwungen.

Erforderliche Rollen

Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Konfigurieren von Express Links benötigen:

  • Express Link konfigurieren: Cloud Run-Entwickler (roles/run.developer) und Dienstkontonutzer (roles/iam.serviceAccountUser) für das Projekt
  • Express Link-Ressourcen verwalten: Network Services-Administrator (roles/networkservices.admin) für das Projekt

Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

Sie können die erforderlichen Berechtigungen auch über benutzerdefinierte Rollen oder andere vordefinierte Rollen erhalten.

Die Dienstidentität des Cloud Run-Quelldienstes muss außerdem die folgenden Rollen für das Projekt haben:

  • Traffic Director-Client (roles/trafficdirector.client)
  • Cloud Trace-Agent (roles/cloudtrace.agent)

Verwenden Sie gcloud, um der Dienstidentität diese Rollen zuzuweisen:

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:RUN_CLIENT_SA@PROJECT_ID.iam.gserviceaccount.com" \
    --role="roles/trafficdirector.client"

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:RUN_CLIENT_SA@PROJECT_ID.iam.gserviceaccount.com" \
    --role="roles/cloudtrace.agent"

Ersetzen Sie Folgendes:

  • PROJECT_ID: Projekt-ID in Google Cloud .
  • RUN_CLIENT_SA: Der Name des Dienstkontos, das an Ihren Cloud Run-Quelldienst angehängt ist.

Wenn die Cloud Run-Dienstidentität diese Rollen nicht hat, wird der Cloud Run-Dienst trotzdem bereitgestellt, aber Features, die von Ambient Networking abhängen, funktionieren nicht. Dieses Verhalten unterscheidet sich von Cloud Service Mesh, bei dem der Cloud Run-Dienst nicht bereitgestellt werden kann, wenn die erforderlichen Rollen fehlen.

Beschränkungen

Für Express Links gelten die folgenden Einschränkungen:

  • Als Quell- und Zielressourcen werden nur Cloud Run-Dienste unterstützt. Cloud Run-Jobs, Worker-Pools und Instanzen werden nicht unterstützt.
  • Projekt- und regionenübergreifende Konfigurationen werden nicht unterstützt. Der Cloud Run-Quelldienst und der Cloud Run-Zieldienst müssen sich im selben Projekt und in derselben Region befinden.
  • Express Links erfordern Ambient Networking mit dem Bereich global für den Quelldienst. Wenn der Quelldienst den Bereich regional verwendet, wird der Express Link erstellt, aber der Traffic wird nicht weitergeleitet.
  • Sie müssen die Cloud Run-Quell- und ‑Zieldienste erstellen, bevor Sie den Express-Link erstellen. Die Erstellung in falscher Reihenfolge wird nicht unterstützt. Wenn Sie einen Zieldienst löschen, kann der Express Link weiterhin die veraltete Konfiguration anzeigen und bereitstellen, bis Sie den Express Link löschen oder neu erstellen.
  • Sie können den Quelldienst, den Zieldienst oder den benutzerdefinierten Hostnamen eines vorhandenen Express Link nicht direkt aktualisieren. Mit dem Befehl gcloud beta network-services express-links update wird nur die Beschreibung des Express Link aktualisiert. Wenn Sie die Routingkonfiguration ändern möchten, löschen Sie den Express Link und erstellen Sie ihn neu.
  • Für Cloud Run-Zieldienste muss die Standard-URL run.app aktiviert sein, auch wenn Sie benutzerdefinierte URLs oder benutzerdefinierte Domains verwenden oder einen benutzerdefinierten Hostnamen mit dem Flag --matches-hostname konfigurieren.
  • Anfragen, die an die nicht deterministische URL des Ziels gesendet werden, werden nicht abgefangen und schlagen mit dem Fehler 403 Forbidden fehl. Wenn der Zieldienst keine deterministische URL hat, weil der kombinierte Dienstname und die Projektnummer 63 Zeichen überschreiten, müssen Sie --matches-hostname angeben. Andernfalls schlägt die Erstellung des Express-Links mit dem Fehler Cloud Run Service name is too long fehl.
  • Wenn Sie den vollständigen Status eines Express Links aufrufen, werden nur Informationen zum Zieldienst zurückgegeben. Details zu den Cloud Run-Quellversionen und der ausgehandelten Authentifizierung fehlen möglicherweise oder enthalten veraltete Daten. Dies hat keine Auswirkungen darauf, wie der Express Link Traffic weiterleitet oder authentifiziert.
  • Cloud Run-Quelldienste, die mit Agent-Identität und mTLS-gebundenen Tokens konfiguriert sind, werden nicht unterstützt.
  • Cloud Run-Quelldienste, die so konfiguriert sind, dass ausgehender Traffic über Agent Gateway in Cloud Run und Secure Web Proxy weitergeleitet wird, werden nicht unterstützt. Express Links erfordern den globalen Ambient Networking-Bereich, während Agent Gateway den regionalen Bereich erfordert.
  • Wenn eine ausgehende Anfrage vom Quelldienst bereits einen Authorization-Header enthält, leitet der Express Link die Anfrage mit diesem Header unverändert weiter und fügt kein Token ein. Das automatische Einfügen von Tokens in den Header X-Serverless-Authorization wird nicht unterstützt.
  • Traffic, der von Sandbox-Containern in Cloud Run generiert wird, wird nicht unterstützt.
  • Sie können Express Links nicht verwenden, um Traffic an Cloud Run-Zieldienste weiterzuleiten, die durch Identity-Aware Proxy geschützt sind.
  • Jeder Express Link unterstützt einen Cloud Run-Zieldienst. Sie können bis zu 5.000 Express Links pro Projekt erstellen.

Wenn Sie Ihre Cloud Run-Dienste verbinden möchten, erstellen Sie einen Express Link, indem Sie den Quelldienst und den Zieldienst angeben. Weisen Sie dann dem Zieldienst die Rolle „Cloud Run-Aufrufer“ zu.

Verbindung zu einem anderen Cloud Run-Dienst herstellen

Wenn Sie einen Cloud Run-Quelldienst mit einem Cloud Run-Zieldienst verbinden möchten, erstellen Sie einen Express-Link mit gcloud oder YAML.

gcloud

Verwenden Sie den Befehl gcloud beta network-services express-links create, um einen Express Link zu erstellen:

gcloud beta network-services express-links create EXPRESS_LINK_NAME \
    --location=global \
    --source-services=//run.googleapis.com/projects/PROJECT_ID/locations/REGION/services/SOURCE_SERVICE \
    --destination-services=//run.googleapis.com/projects/PROJECT_ID/locations/REGION/services/DESTINATION_SERVICE

Ersetzen Sie Folgendes:

  • EXPRESS_LINK_NAME: Ein Name für Ihren Express Link.
  • PROJECT_ID: Projekt-ID in Google Cloud .
  • REGION: die Region, in der Ihre Cloud Run-Dienste bereitgestellt werden.
  • SOURCE_SERVICE: der Name des Cloud Run-Quelldienstes.
  • DESTINATION_SERVICE: der Name des Cloud Run-Zieldienstes.

Nach Abschluss des Befehls kann es bis zu 2 Minuten dauern, bis die Routingkonfiguration an die ausgeführten Quelldienstinstanzen weitergegeben wird.

Standardmäßig fängt der Express Link nur Anfragen ab, die an die deterministische URL des Zieldienstes gesendet werden, nicht an die nicht deterministische URL. Wenn Sie einen benutzerdefinierten Hostnamen verwenden möchten, übergeben Sie den Hostnamen ohne Schema im Flag --matches-hostname="HOSTNAME", z. B. --matches-hostname="DESTINATION_SERVICE", und senden Sie Anfragen von Ihrer Quellanwendung an http://HOSTNAME. Wenn Sie --matches-hostname angeben, wird die deterministische URL ersetzt, anstatt sie zu ergänzen.

YAML

  1. Erstellen Sie eine Konfigurationsdatei, z. B. express-link.yaml:

    name: "projects/PROJECT_ID/locations/global/expressLinks/EXPRESS_LINK_NAME"
source:
  services:
    - "//run.googleapis.com/projects/PROJECT_ID/locations/REGION/services/SOURCE_SERVICE"
destination:
  services:
    - "//run.googleapis.com/projects/PROJECT_ID/locations/REGION/services/DESTINATION_SERVICE"

    Ersetzen Sie Folgendes:

    • PROJECT_ID: Projekt-ID in Google Cloud .
    • REGION: die Region, in der Ihre Dienste bereitgestellt werden.
    • EXPRESS_LINK_NAME: Ein Name für Ihren Express Link.
    • SOURCE_SERVICE: der Name des Cloud Run-Quelldienstes.
    • DESTINATION_SERVICE: der Name des Cloud Run-Zieldienstes.

  2. Importieren Sie die YAML-Datei mit dem Befehl gcloud beta network-services express-links import:

    gcloud beta network-services express-links import EXPRESS_LINK_NAME \
    --location=global \
    --source=YAML_FILENAME.yaml

    Ersetzen Sie Folgendes:

    • EXPRESS_LINK_NAME: Ein Name für Ihren Express Link.
    • YAML_FILENAME: der Name Ihrer YAML-Datei.

Aufruferberechtigungen für den Zieldienst gewähren

Damit der Quelldienst einen IAM-geschützten Zieldienst aufrufen kann, weisen Sie dem Dienstkonto des Quelldienstes im Cloud Run-Zieldienst die Rolle Cloud Run-Aufrufer (roles/run.invoker) zu. Dies ist erforderlich, damit die Authentifizierung auf der Datenebene funktioniert.

gcloud run services add-iam-policy-binding DESTINATION_SERVICE \
    --member="serviceAccount:SOURCE_SA@PROJECT_ID.iam.gserviceaccount.com" \
    --role="roles/run.invoker" \
    --region=REGION

Ersetzen Sie Folgendes:

  • DESTINATION_SERVICE: der Name des Cloud Run-Zieldienstes.
  • SOURCE_SA: der Name des Dienstkontos, das an Ihren Cloud Run-Quelldienst angehängt ist.
  • PROJECT_ID: Projekt-ID in Google Cloud .
  • REGION: die Region, in der Ihr Zieldienst bereitgestellt wird.

Status des Express Link prüfen

Verwenden Sie den Befehl gcloud beta network-services express-links describe, um die grundlegende Konfiguration Ihres Express Link aufzurufen:

gcloud beta network-services express-links describe EXPRESS_LINK_NAME \
    --location=global

Wenn Sie den vollständigen Status des Express Link aufrufen möchten, einschließlich connectionStatus (aktiver Routentyp, übereinstimmende Hostnamen und Quellversions-URI) und cloudRunSourceInfo (konfigurierte Authentifizierungsmethoden und VPC-Netzwerk), fügen Sie ?view=EXPRESS_LINK_VIEW_FULL# in den Ressourcennamen ein:

gcloud beta network-services express-links describe 'EXPRESS_LINK_NAME?view=EXPRESS_LINK_VIEW_FULL#' \
    --location=global

Ersetzen Sie EXPRESS_LINK_NAME durch den Namen Ihres Express Link. Behalten Sie die einfachen Anführungszeichen und das nachgestellte Zeichen # bei, wenn Sie die vollständige Ansicht abfragen.

Wenn Sie einen Express Link entfernen und die automatische Einfügung von Anmeldedaten und das Abfangen von Traffic vom Quelldienst beenden möchten, verwenden Sie den Befehl gcloud beta network-services express-links delete:

gcloud beta network-services express-links delete EXPRESS_LINK_NAME \
    --location=global

Ersetzen Sie EXPRESS_LINK_NAME durch den Namen Ihres Express Links.

Wenn Sie einen vorhandenen Express Link auf einen anderen Zieldienst verweisen oder die Einstellung --matches-hostname ändern möchten, löschen Sie den Express Link mit dem vorherigen Befehl und erstellen Sie dann einen neuen Express Link mit der aktualisierten Konfiguration.

Nächste Schritte