Erste Schritte mit Cloud Endpoints für GKE mit ESPv2

OpenAPI | gRPC

In dieser Anleitung wird beschrieben, wie Sie eine Beispiel-API und den Extensible Service Proxy V2 (ESPv2) für einen Google Kubernetes Engine-Cluster (GKE) konfigurieren und bereitstellen.

Die REST API des Beispielcodes wird in der OpenAPI-Spezifikation beschrieben. Sie erfahren außerdem, wie Sie einen API-Schlüssel erstellen und beim Senden von Anfragen an die API verwenden.

In der Anleitung werden vorkonfigurierte Container-Images des Beispielcodes und des ESPv2 verwendet, die in Container Registry gespeichert sind.

Eine Übersicht über Cloud Endpoints finden Sie in den Abschnitten Über Cloud Endpoints und Architekturübersicht zu Cloud Endpoints.

Ziele

Beim Durcharbeiten der Anleitung können Sie sich an der folgenden Aufgabenliste orientieren. Alle Aufgaben in Teil 1 sind erforderlich, um Anfragen an die API zu senden.

Teil 1

1. Richten Sie ein Google Cloud-Projekt ein. Siehe Vorbereitung.
2. In GKE einen Container-Cluster erstellen. Siehe Container-Cluster erstellen.
3. Die in der Anleitung verwendete Software installieren und konfigurieren. Siehe Erforderliche Software installieren und konfigurieren.
4. Den Beispielcode herunterladen. Siehe Beispielcode abrufen.
5. Konfigurieren Sie die Datei openapi.yaml, mit der Cloud Endpoints konfiguriert wird. Siehe Endpoints konfigurieren.
6. Die Endpoints-Konfiguration bereitstellen, um einen Endpoints-Dienst zu erstellen. Siehe Endpoints-Konfiguration bereitstellen.
7. Stellen Sie die API und den ESPv2 im Cluster bereit. Siehe API-Back-End bereitstellen.
8. Externe IP-Adresse des Clusters abrufen. Siehe Externe IP-Adresse des Clusters abrufen.
9. Über eine IP-Adresse eine Anfrage an die API senden. Siehe Anfrage über eine IP-Adresse senden.
10. API-Aktivitäten verfolgen. Siehe API-Aktivitäten verfolgen.

Teil 2

1. Einen DNS-Eintrag für die Beispiel-API konfigurieren. Siehe DNS für Endpoints konfigurieren.
2. Senden Sie mit einem vollständig qualifizierten Domainnamen eine Anfrage an die API. Siehe Anfrage über FQDN senden.

Clean-up

Wenn Sie fertig sind, lesen Sie den Abschnitt Bereinigen, um Gebühren für Ihr Google Cloud-Konto zu vermeiden.

Kosten

In dieser Anleitung werden die folgenden kostenpflichtigen Komponenten von Google Cloud verwendet:

• GKE
• Endpoints

Mit dem Preisrechner können Sie eine Kostenschätzung für Ihre voraussichtliche Nutzung vornehmen. Neuen Google Cloud-Nutzern steht möglicherweise eine kostenlose Testversion zur Verfügung.

Nach Abschluss dieser Anleitung können Sie weitere Kosten vermeiden, indem Sie die erstellten Ressourcen löschen. Weitere Informationen finden Sie unter Bereinigen.

Hinweise

1. Melden Sie sich bei Ihrem Google Cloud-Konto an. Wenn Sie mit Google Cloud noch nicht vertraut sind, erstellen Sie 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. Wählen Sie in der Google Cloud Console auf der Seite der Projektauswahl ein Google Cloud-Projekt aus oder erstellen Sie eines.

   Hinweis: Wenn Sie die Ressourcen, die Sie in diesem Verfahren erstellen, nicht behalten möchten, erstellen Sie ein Projekt, anstatt ein vorhandenes Projekt auszuwählen. Wenn Sie fertig sind, können Sie das Projekt löschen und dadurch alle mit dem Projekt verknüpften Ressourcen entfernen.

   Zur Projektauswahl

3. Die Abrechnung für das Cloud-Projekt muss aktiviert sein. So prüfen Sie, ob die Abrechnung für Ihr Projekt aktiviert ist.

4. Wählen Sie in der Google Cloud Console auf der Seite der Projektauswahl ein Google Cloud-Projekt aus oder erstellen Sie eines.

   Hinweis: Wenn Sie die Ressourcen, die Sie in diesem Verfahren erstellen, nicht behalten möchten, erstellen Sie ein Projekt, anstatt ein vorhandenes Projekt auszuwählen. Wenn Sie fertig sind, können Sie das Projekt löschen und dadurch alle mit dem Projekt verknüpften Ressourcen entfernen.

   Zur Projektauswahl

5. Die Abrechnung für das Cloud-Projekt muss aktiviert sein. So prüfen Sie, ob die Abrechnung für Ihr Projekt aktiviert ist.

6. Notieren Sie sich die Google Cloud-Projekt-ID, da sie später benötigt wird.

Containercluster erstellen

Sie müssen in GKE einen Container-Cluster erstellen und einrichten, in dem der API-Back-End-Beispielcode ausgeführt wird. Der Cluster benötigt einen IP-Alias, um das containernative Load-Balancing zu verwenden. So erstellen Sie einen Containercluster mit einem IP-Alias für die Beispiel-API:

gcloud container clusters create espv2-demo-cluster \
    --enable-ip-alias \
    --create-subnetwork="" \
    --network=default \
    --zone=us-central1-a

Mit dem obigen Beispielbefehl wird der Cluster espv2-demo-cluster mit einem automatisch bereitgestellten Subnetzwerk in der Zone us-central1-a erstellt.

Notieren Sie sich den Namen und die Zone des Clusters, da beides für die Authentifizierung von kubectl für den Container-Cluster benötigt wird.

Erforderliche Software installieren und konfigurieren

Mithilfe dieser Anleitung installieren Sie das Cloud SDK, um das gcloud-Befehlszeilentool zum Verwalten Ihres Projekts verwenden zu können. Mit kubectl führen Sie Befehle für GKE-Cluster aus. Sie müssen außerdem die API testen können.

Wenn Sie die erforderliche Software bereits installiert haben, können Sie mit dem nächsten Schritt fortfahren.

So installieren und konfigurieren Sie die erforderliche Software:

1. Sie benötigen eine Anwendung, um Anfragen an die Beispiel-API zu senden.

   • Nutzer von Linux und macOS: Diese Anleitung enthält ein Beispiel, bei dem curl verwendet wird. Das Tool ist normalerweise auf Ihrem Betriebssystem vorinstalliert. Wenn curl nicht installiert ist, können Sie es von der Seite Releases und Downloads für curl herunterladen.
   • Nutzer von Windows: Diese Anleitung enthält ein Beispiel, bei dem Invoke-WebRequest verwendet wird. Der Befehl wird in PowerShell ab Version 3.0 unterstützt.
2. Installieren und initialisieren Sie das Cloud SDK.
3. Aktualisieren Sie das Cloud SDK und installieren Sie die Endpoints-Komponenten:

   gcloud components update

4. Das Cloud SDK (gcloud) muss berechtigt sein, auf Ihre Daten und Dienste auf Google Cloud zuzugreifen:

   gcloud auth login

   Ein neuer Browsertab wird geöffnet. Wählen Sie dort ein Konto aus.
5. Legen Sie für das Standardprojekt Ihre Projekt-ID fest:

   gcloud config set project YOUR_PROJECT_ID

   Ersetzen Sie YOUR_PROJECT_ID durch Ihre Projekt-ID. Wenn Sie weitere Google Cloud-Projekte mit gcloud verwalten möchten, lesen Sie SDK-Konfigurationen verwalten.

6. Installieren Sie kubectl:

   gcloud components install kubectl

7. Rufen Sie die neuen Nutzeranmeldedaten ab, die als Standardanmeldedaten für Anwendungen verwendet werden sollen. Die Nutzeranmeldedaten sind für die Autorisierung von kubectl erforderlich.

   gcloud auth application-default login

   Ein neuer Browsertab wird geöffnet. Wählen Sie dort ein Konto aus.

Beispielcode herunterladen

Damit Sie schnell einsteigen können, ist Beispielcode in mehreren Sprachen verfügbar. So laden Sie den Beispielcode auf Ihren lokalen Rechner herunter:

Java

So können Sie die Beispiel-API klonen oder herunterladen:

1. Klonen Sie das Repository der Beispiel-App auf Ihren lokalen Computer:

   git clone https://github.com/GoogleCloudPlatform/java-docs-samples

   Sie können auch das Beispiel als ZIP-Datei herunterladen und entpacken.

2. Wechseln Sie zu dem Verzeichnis, das den Beispielcode enthält:

   cd java-docs-samples/endpoints/getting-started

Python

So können Sie die Beispiel-API klonen oder herunterladen:

1. Klonen Sie das Repository der Beispiel-App auf Ihren lokalen Computer:

   git clone https://github.com/GoogleCloudPlatform/python-docs-samples

   Sie können auch das Beispiel als ZIP-Datei herunterladen und entpacken.

2. Wechseln Sie zu dem Verzeichnis, das den Beispielcode enthält:

   cd python-docs-samples/endpoints/getting-started

Go

So klonen Sie die Beispiel-API oder laden diese herunter:

1. Prüfen Sie, ob die Umgebungsvariable GOPATH festgelegt ist.
2. Klonen Sie das Repository der Beispielanwendung auf Ihren lokalen Computer:

   go get -d github.com/GoogleCloudPlatform/golang-samples/endpoints/getting-started

3. Wechseln Sie zu dem Verzeichnis, das den Beispielcode enthält:

   cd $GOPATH/src/github.com/GoogleCloudPlatform/golang-samples/endpoints/getting-started

PHP

So können Sie die Beispiel-API klonen oder herunterladen:

1. Klonen Sie das Repository der Beispiel-App auf Ihren lokalen Computer:

   git clone https://github.com/GoogleCloudPlatform/php-docs-samples

   Sie können auch das Beispiel als ZIP-Datei herunterladen und entpacken.

2. Wechseln Sie zu dem Verzeichnis, das den Beispielcode enthält:

   cd php-docs-samples/endpoints/getting-started

Ruby

So können Sie die Beispiel-API klonen oder herunterladen:

1. Klonen Sie das Repository der Beispiel-App auf Ihren lokalen Computer:

   git clone https://github.com/GoogleCloudPlatform/ruby-docs-samples

   Sie können auch das Beispiel als ZIP-Datei herunterladen und entpacken.

2. Wechseln Sie zu dem Verzeichnis, das den Beispielcode enthält:

   cd ruby-docs-samples/endpoints/getting-started

NodeJS

So können Sie die Beispiel-API klonen oder herunterladen:

1. Klonen Sie das Repository der Beispiel-App auf Ihren lokalen Computer:

   git clone https://github.com/GoogleCloudPlatform/nodejs-docs-samples

   Sie können auch das Beispiel als ZIP-Datei herunterladen und entpacken.

2. Wechseln Sie zu dem Verzeichnis, das den Beispielcode enthält:

   cd nodejs-docs-samples/endpoints/getting-started

Endpoints konfigurieren

Der Beispielcode enthält die OpenAPI-Konfigurationsdatei openapi.yaml, die auf der OpenAPI-Spezifikation Version 2.0 beruht. So konfigurieren Sie Endpoints:

1. Öffnen Sie im Verzeichnis mit dem Beispielcode die Konfigurationsdatei openapi.yaml.
   Java

   endpoints/getting-started/openapi.yaml

   Auf GitHub ansehen

   swagger: "2.0"
   info:
     description: "A simple Google Cloud Endpoints API example."
     title: "Endpoints Example"
     version: "1.0.0"
   host: "echo-api.endpoints.YOUR-PROJECT-ID.cloud.goog"

   Python

   endpoints/getting-started/openapi.yaml

   Auf GitHub ansehen

   swagger: "2.0"
   info:
     description: "A simple Google Cloud Endpoints API example."
     title: "Endpoints Example"
     version: "1.0.0"
   host: "echo-api.endpoints.YOUR-PROJECT-ID.cloud.goog"

   Go

   endpoints/getting-started/openapi.yaml

   Auf GitHub ansehen

   swagger: "2.0"
   info:
     description: "A simple Google Cloud Endpoints API example."
     title: "Endpoints Example"
     version: "1.0.0"
   host: "echo-api.endpoints.YOUR-PROJECT-ID.cloud.goog"

   PHP

   endpoints/getting-started/openapi.yaml

   Auf GitHub ansehen

   swagger: "2.0"
   info:
     description: "A simple Google Cloud Endpoints API example."
     title: "Endpoints Example"
     version: "1.0.0"
   host: "echo-api.endpoints.YOUR-PROJECT-ID.cloud.goog"

   Ruby

   endpoints/getting-started/openapi.yaml

   Auf GitHub ansehen

   swagger: "2.0"
   info:
     description: "A simple Google Cloud Endpoints API example."
     title: "Endpoints Example"
     version: "1.0.0"
   host: "echo-api.endpoints.YOUR-PROJECT-ID.cloud.goog"

   NodeJS

   endpoints/getting-started/openapi.yaml

   Auf GitHub ansehen

   swagger: "2.0"
   info:
     description: "A simple Google Cloud Endpoints API example."
     title: "Endpoints Example"
     version: "1.0.0"
   host: "echo-api.endpoints.YOUR-PROJECT-ID.cloud.goog"

   Wichtige Hinweise:

   • Im Konfigurationsbeispiel sind die Zeilen in der Nähe des Feldes host zu sehen, die Sie ändern müssen. Zum Bereitstellen der Datei openapi.yaml für Endpoints ist das vollständige OpenAPI-Dokument erforderlich.
   • Die Beispieldatei openapi.yaml enthält einen Abschnitt zum Konfigurieren der Authentifizierung, der für diese Anleitung nicht benötigt wird. Die Zeilen mit YOUR-SERVICE-ACCOUNT-EMAIL und YOUR-CLIENT-ID müssen Sie nicht konfigurieren.
   • OpenAPI ist eine sprachunabhängige Spezifikation. Die Datei openapi.yaml für das Beispiel getting-started ist im GitHub-Repository aller Sprachen die gleiche.

2. Ersetzen Sie im Feld host den Text durch den Namen des Endpoints-Diensts. Er sollte das folgende Format haben:

   host: "echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog"
   

   Ersetzen Sie YOUR_PROJECT_ID durch Ihre Google Cloud-Projekt-ID. Beispiel:

   host: "echo-api.endpoints.example-project-12345.cloud.goog"
   

echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog ist der Name des Endpoints-Diensts. Sie verwenden nicht den vollständig qualifizierten Domainnamen (FQDN) zum Senden von Anfragen an die API.

Informationen zu den Feldern im OpenAPI-Dokument, die für Endpoints erforderlich sind, finden Sie unter Endpoints konfigurieren.

Wenn Sie die folgenden Konfigurationsschritte durchgeführt haben und Anfragen erfolgreich über eine IP-Adresse an die Beispiel-API senden können, lesen Sie unter DNS für Endpoints konfigurieren, wie echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog als FQDN konfiguriert wird.

Endpoints-Konfiguration bereitstellen

Die Endpoints-Konfiguration wird mit dem Befehl gcloud endpoints services deploy bereitgestellt. Dieser Befehl erstellt mithilfe von Service Management einen verwalteten Dienst.

So stellen Sie die Endpoints-Konfiguration bereit:

1. Sie müssen sich im Verzeichnis endpoints/getting-started befinden.
2. Laden Sie die Konfiguration hoch und erstellen Sie einen verwalteten Dienst:

   gcloud endpoints services deploy openapi.yaml
   

Der Befehl gcloud ruft dann die Service Management API auf, um einen verwalteten Dienst mit dem Namen zu erstellen, den Sie im Feld host der Datei openapi.yaml angegeben haben. In der Service Management API wird der Dienst gemäß den Einstellungen in der Datei openapi.yaml konfiguriert. Wenn Sie Änderungen an openapi.yamlopenapi.yaml vornehmen, müssen Sie die Datei noch einmal bereitstellen, um den Endpoints-Dienst zu aktualisieren.

Beim Erstellen und Konfigurieren des Dienstes gibt Service Management Informationen an das Terminal aus. Warnungen mit dem Hinweis, dass für die Pfade in der Datei openapi.yaml kein API-Schlüssel erforderlich ist, können Sie ignorieren. Nach Abschluss der Dienstkonfiguration wird von Service Management eine Meldung mit der Dienstkonfigurations-ID und dem Dienstnamen angezeigt, die etwa so aussieht:

Service Configuration [2017-02-13r0] uploaded for service [echo-api.endpoints.example-project-12345.cloud.goog]

Im vorherigen Beispiel ist 2017-02-13r0 die Dienstkonfigurations-ID und echo-api.endpoints.example-project-12345.cloud.goog der Name des Endpoints-Dienstes. Die Dienstkonfigurations-ID besteht aus einem Datumsstempel und einer Überarbeitungsnummer. Wenn Sie die Datei openapi.yaml am selben Tag noch einmal bereitstellen, erhöht sich die Überarbeitungsnummer in der Dienstkonfigurations-ID. Sie können die Endpoints-Dienstkonfiguration in der Cloud Console auf der Seite Endpoints > Dienste aufrufen.

Wenn Sie eine Fehlermeldung erhalten, lesen Sie Fehlerbehebung bei der Endpoints-Konfigurationsbereitstellung.

Erforderliche Dienste prüfen

Für Endpoints und ESP müssen mindestens die folgenden Google-Dienste aktiviert sein:

Name	Titel
servicemanagement.googleapis.com	Service Management API
servicecontrol.googleapis.com	Service Control API
endpoints.googleapis.com	Google Cloud Endpoints

In der Regel werden die erforderlichen Dienste mit dem Befehl gcloud endpoints services deploy aktiviert. Unter folgenden Umständen kann es vorkommen, dass der Befehl gcloud erfolgreich ausgeführt wird, die erforderlichen Dienste jedoch nicht aktiviert werden:

• Wenn Sie eine Drittanbieteranwendung wie Terraform verwendet haben und Sie diese Dienste nicht hinzufügen.

• Wenn Sie die Endpoints-Konfiguration für ein vorhandenes Google Cloud-Projekt bereitgestellt haben, in dem diese Dienste explizit deaktiviert wurden.

Prüfen Sie mit dem folgenden Befehl, ob die erforderlichen Dienste aktiviert sind:

gcloud services list

Wenn die erforderlichen Dienste nicht aufgeführt sind, müssen Sie sie aktivieren:

gcloud services enable servicemanagement.googleapis.com
gcloud services enable servicecontrol.googleapis.com
gcloud services enable endpoints.googleapis.com

Aktivieren Sie auch Ihren Endpoints-Dienst:

gcloud services enable ENDPOINTS_SERVICE_NAME

Zum Ermitteln des ENDPOINTS_SERVICE_NAME haben Sie folgende Möglichkeiten:

• Rufen Sie nach der Bereitstellung der Endpoints-Konfiguration die Seite Endpoints in der Cloud Console auf. Die Liste der möglichen ENDPOINTS_SERVICE_NAME wird in der Spalte Dienstname angezeigt.

• Bei OpenAPI ist ENDPOINTS_SERVICE_NAME der Wert, den Sie im Feld host Ihrer OpenAPI-Spezifikation angegeben haben. Bei gRPC ist der ENDPOINTS_SERVICE_NAME das, was Sie im Feld name Ihrer gRPC-Endpoints-Konfiguration angegeben haben.

Weitere Informationen zu den gcloud-Befehlen finden Sie unter gcloud-Dienste.

API-Back-End bereitstellen

Bisher haben Sie zwar das OpenAPI-Dokument für Service Management bereitgestellt, den Code für das API-Back-End haben Sie jedoch noch nicht implementiert. In diesem Abschnitt wird die Bereitstellung vorkonfigurierter Container für die Beispiel-API und den ESPv2 im Cluster beschrieben.

Erforderliche Berechtigungen prüfen

ESP und ESPv2 ruft Google-Dienste auf, die mit IAM prüfen, ob die aufrufende Identität ausreichende Berechtigungen für den Zugriff auf die verwendeten IAM-Ressourcen hat. Die aufrufende Identität ist das angehängte Dienstkonto, das ESP und ESPv2 bereitstellt.

Bei Bereitstellung im GKE-Pod ist das angehängte Dienstkonto das Knoten-Dienstkonto. Normalerweise ist dies das Compute Engine-Standarddienstkonto. Folgen Sie dieser Berechtigungsempfehlung, um ein geeignetes Knotendienstkonto auszuwählen.

Wenn Workload Identity verwendet wird, kann ein anderes Dienstkonto als das Knoten-Dienstkonto verwendet werden, um mit Google-Diensten zu kommunizieren. Sie können ein Kubernetes-Dienstkonto für den Pod erstellen, um ESP und ESPv2 auszuführen, ein Google-Dienstkonto erstellen und das Kubernetes-Dienstkonto dem Google-Dienstkonto zuordnen.

Folgen Sie dieser Anleitung, um ein Kubernetes-Dienstkonto mit einem Google-Dienstkonto zu verknüpfen. Dieses Google-Dienstkonto ist das angehängte Dienstkonto.

Wenn das angehängte Dienstkonto das Compute Engine-Standarddienstkonto des Projekts ist und die Konfiguration des Endpunktdienstes im selben Projekt bereitgestellt wird, sollte das Dienstkonto genügend Berechtigungen für den Zugriff auf die IAM-Ressourcen haben und der folgende Einrichtungsschritt für IAM-Rollen kann übersprungen werden. Andernfalls sollten Sie dem angehängten Dienstkonto folgende IAM-Rollen hinzufügen.

Erforderliche IAM-Rollen hinzufügen:

In diesem Abschnitt werden die von ESP und ESPv2 verwendeten IAM-Ressourcen beschrieben, sowie die IAM-Rollen, die das angehängte Dienstkonto benötigt, um auf diese Ressourcen zuzugreifen.

Endpoint-Dienstkonfiguration

ESP und ESPv2 rufen Service Control auf (nutzt die Endpunktdienst-Konfiguration). Die Endpunktdienst-Konfiguration ist eine IAM-Ressource. ESP und ESPv2 benötigen die Rolle Dienstüberwacher, um auf sie zuzugreifen.

Die IAM-Rolle gilt für die Endpunktdienst-Konfiguration, nicht für das Projekt. Ein Projekt kann mehrere Endpunktdienst-Konfigurationen haben.

Verwenden Sie folgenden gcloud-Befehl, um die Rolle dem angehängten Dienstkonto für die Endpunktdienst-Konfiguration hinzuzufügen.

gcloud endpoints services add-iam-policy-binding SERVICE_NAME \
                --member serviceAccount:SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID.iam.gserviceaccount.com \
                --role roles/servicemanagement.serviceController

Dabei ist
* SERVICE_NAME der Endpunkt-Dienstname
* SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID.iam.gserviceaccount.com das angehängte Dienstkonto.

Cloud Trace

ESP und ESPv2 rufen den Cloud Trace-Dienst auf, um Trace in ein Projekt zu exportieren. Dieses Projekt wird als Tracing-Projekt bezeichnet. In ESP sind das Tracing-Projekt und das Projekt, zu dem die Endpunktdienstkonfiguration gehört, identisch. In ESPv2 kann das Tracing-Projekt mit dem Flag --tracing_project_id angegeben werden und entspricht standardmäßig dem Bereitstellungsprojekt.

ESP und ESPv2 benötigen die Rolle Cloud Trace-Agent, um Cloud Trace zu aktivieren.

Verwenden Sie den folgenden gcloud-Befehl, um die Rolle dem angehängten Dienstkonto hinzuzufügen:

gcloud projects add-iam-policy-binding TRACING_PROJECT_ID \
                --member serviceAccount:SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID.iam.gserviceaccount.com \
                --role roles/cloudtrace.agent

Dabei ist
* TRACING_PROJECT_ID die Tracing-Projekt-ID
* SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID.iam.gserviceaccount.com ist das angehängte Dienstkonto. Weitere Informationen finden Sie unter Was sind Rollen und Berechtigungen?

Container in einem Cluster bereitstellen

Container bieten einen logischen Mechanismus für die Paketerstellung, bei dem Anwendungen von der Umgebung, in der sie ausgeführt werden, abstrahiert werden. Mit dem folgenden Verfahren stellen Sie die Beispiel-API und ESPv2 im Cluster bereit. So stellen Sie die Container für den Cluster bereit:

1. Rufen Sie die Anmeldedaten für den Cluster ab und stellen Sie sie für kubectl bereit:

       gcloud container clusters get-credentials NAME --zone ZONE
       

   Ersetzen Sie NAME durch den Clusternamen und ZONE durch die Clusterzone.
2. Stellen Sie einen Kubernetes-Dienst im GKE-Cluster bereit. Der Kubernetes-Dienst implementiert die API. Wenden Sie git clone auf dieses Repository an und gehen Sie mit cd getting-started/ zu dem Ordner, um die Kubernetes-Konfigurationsdatei LANG-deployment.yaml zu bearbeiten, und ersetzen Sie in den ESPv2 Beta-Startoptionen SERVICE_NAME durch den Namen Ihres Dienstes.
   Java

   getting-started/java-deployment.yaml

   Auf GitHub ansehen

   - name: esp
     image: gcr.io/endpoints-release/endpoints-runtime:2
     args: [
       "--listener_port=8081",
       "--backend=127.0.0.1:8080",
       "--service=SERVICE_NAME",
       "--rollout_strategy=managed",
       "--healthz=/healthz",
     ]
     readinessProbe:
       httpGet:
         path: /healthz
         port: 8081

   Python

   getting-started/python-deployment.yaml

   Auf GitHub ansehen

   - name: esp
     image: gcr.io/endpoints-release/endpoints-runtime:2
     args: [
       "--listener_port=8081",
       "--backend=http://127.0.0.1:8080",
       "--service=SERVICE_NAME",
       "--rollout_strategy=managed",
       "--healthz=/healthz",
     ]
     readinessProbe:
       httpGet:
         path: /healthz
         port: 8081

   Go

   getting-started/golang-deployment.yaml

   Auf GitHub ansehen

   - name: esp
     image: gcr.io/endpoints-release/endpoints-runtime:2
     args: [
       "--listener_port", "8081",
       "--backend", "127.0.0.1:8080",
       "--service", "SERVICE_NAME",
       "--rollout_strategy", "managed",
       "--healthz=/healthz",
     ]
     readinessProbe:
       httpGet:
         path: /healthz
         port: 8081

   PHP

   getting-started/php-deployment.yaml

   Auf GitHub ansehen

   - name: esp
     image: gcr.io/endpoints-release/endpoints-runtime:2
     args: [
       "--listener_port", "8081",
       "--backend", "127.0.0.1:8080",
       "--service", "SERVICE_NAME",
       "--rollout_strategy", "managed",
       "--healthz=/healthz",
     ]

   Ruby

   getting-started/ruby-deployment.yaml

   Auf GitHub ansehen

   - name: esp
     image: gcr.io/endpoints-release/endpoints-runtime:2
     args: [
       "--listener_port", "8081",
       "--backend", "127.0.0.1:8080",
       "--service", "SERVICE_NAME",
       "--rollout_strategy", "managed",
       "--healthz=/healthz",
     ]

   NodeJS

   getting-started/nodejs-deployment.yaml

   Auf GitHub ansehen

   - name: esp
     image: gcr.io/endpoints-release/endpoints-runtime:2
     args: [
       "--listener_port", "8081",
       "--backend", "127.0.0.1:8080",
       "--service", "SERVICE_NAME",
       "--rollout_strategy", "managed",
       "--healthz=/healthz",
     ]
     readinessProbe:
       httpGet:
         path: /healthz
         port: 8081

   Beispiel:

     args: [
       "--listener_port=8081",
       "--backend=http://127.0.0.1:8080",
       "--service=echo-api.endpoints.example-project-12345.cloud.goog ",
       "--rollout_strategy=managed",
     ]
   

   Mit der Option --rollout_strategy=managed legen Sie fest, dass der ESPv2 die zuletzt bereitgestellte Dienstkonfiguration verwendet. Wenn Sie diese Option angeben, erkennt der ESPv2 innerhalb einer Minute nach Bereitstellung einer neuen Dienstkonfiguration die Änderung und verwendet automatisch die neue Konfiguration. Wir empfehlen, diese Option festzulegen, anstatt eine bestimmte Konfigurations-ID anzugeben, die von ESPv2 verwendet werden soll. Informationen zu den anderen verwendeten ESPv2-Optionen finden Sie unter ESPv2-Startoptionen.

   Es wird empfohlen, imagePullPolicy in der Containerspezifikation oben auf Always festzulegen. Dadurch können neu erstellte Pods immer die neueste Version des ESPv2 abrufen. Weitere Informationen finden Sie unter Best Practices für die Konfiguration. Wenn eine neue Version des ESPv2 veröffentlicht wird, können Sie einen rollierenden Neustart aller Pods durchführen, um sicherzustellen, dass die neueste Version verwendet wird.

   Wenn Sie eine große Flotte von Endpoints im selben Google Cloud-Projekt ausführen (mehr als 100), empfehlen wir, den Dienst bereitzustellen. Konfiguration für den Container anstelle des Flags --rollout_strategy=managed, um die Dienstkonfiguration aus der Service Management API abzurufen. Die Service Management API hat ein Standardkontingent. Wenn eine große Flotte von Endpoints --rollout_strategy=managed verwendet, fragen alle Endpoints die neueste Dienstkonfiguration ab. Die Flotte überschreitet möglicherweise das Kontingent und führt daher zu Fehlern bei der Aktualisierung der Dienstkonfiguration. Führen Sie die folgenden Schritte aus, um die Dienstkonfiguration bereitzustellen.

   • Laden Sie die JSON-Konfiguration für die Dienstkonfiguration herunter.

   curl -o "/tmp/service_config.json" -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://servicemanagement.googleapis.com/v1/services/SERVICE/configs/CONFIG_ID?view=FULL"
   

   • Erstellen Sie eine Kubernetes-Konfigurationszuordnungsressource aus der JSON-Konfiguration.

   kubectl create configmap service-config-configmap \
     --from-file=service_config.json:/tmp/service_config.json
   

   • Stellen Sie die ConfigMap-Ressource im Container bereit und verwenden Sie das Flag "--service_config_path", um den Pfad der Konfigurationsdatei anzugeben.

   Beispiel:

     containers:
     - args:
       - --listener_port=8081
       - --backend=http://127.0.0.1:8080
       - --service_json_path=/etc/espv2_config/service_config.json
       - --healthz=/healthz
       image: gcr.io/endpoints-release/endpoints-runtime:2
       name: esp
       ports:
       - containerPort: 8081
         protocol: TCP
       volumeMounts:
       - mountPath: /etc/espv2_config
         name: service-config-volume
     volumes:
     - configMap:
         defaultMode: 420
         name: service-config-configmap
       name: service-config-volume
   

3. Starten Sie den Kubernetes-Dienst mit dem Befehl kubectl apply:
   Java

   kubectl apply -f java-deployment.yaml

   Python

   kubectl apply -f python-deployment.yaml

   Go

   kubectl apply -f golang-deployment.yaml

   PHP

   kubectl apply -f php-deployment.yaml

   Ruby

   kubectl apply -f ruby-deployment.yaml

   NodeJS

   kubectl apply -f nodejs-deployment.yaml

Wenn Sie eine Fehlermeldung erhalten, lesen Sie die Informationen unter Fehlerbehebung bei Endpoints in GKE. Weitere Informationen finden Sie unter API-Back-End bereitstellen.

Externe IP-Adresse des Clusters abrufen

Zum Senden von Anfragen an die API ist die externe IP des Dienstes erforderlich. Nach dem Start Ihres Dienstes im Container kann es einige Minuten dauern, bis die externe IP-Adresse bereit ist.

1. Rufen Sie die externe IP-Adresse auf: kubectl get ingress
2. Notieren Sie sich den Wert für EXTERNAL-IP. Sie benötigen diese IP-Adresse, wenn Sie eine Anfrage an die Beispiel-API senden.

Anfrage über eine IP-Adresse senden

Der Dienst wird jetzt im Containercluster ausgeführt und Sie haben die externe IP-Adresse, also können Sie Anfragen an die API senden.

API-Schlüssel erstellen und Umgebungsvariable festlegen

Für den Beispielcode ist ein API-Schlüssel erforderlich. Zur Vereinfachung der Anfrage legen Sie eine Umgebungsvariable für den API-Schlüssel fest.

1. Erstellen Sie in dem Google Cloud-Projekt, das Sie für Ihre API verwendet haben, auf der Seite mit den API-Anmeldedaten einen API-Schlüssel. Informationen zum Erstellen eines API-Schlüssels in einem anderen Google Cloud-Projekt finden Sie unter API im Google Cloud-Projekt aktivieren.

   Zur Seite "Domainbestätigung"

2. Klicken Sie auf Anmeldedaten erstellen und wählen Sie anschließend API-Schlüssel aus.
3. Kopieren Sie den Schlüssel in die Zwischenablage.
4. Klicken Sie auf Schließen.
5. Fügen Sie den API-Schlüssel auf Ihrem lokalen Computer ein, um ihn einer Umgebungsvariable zuzuweisen:
   • In Linux oder macOS: export ENDPOINTS_KEY=AIza...
   • In Windows PowerShell: $Env:ENDPOINTS_KEY="AIza..."

Anfrage senden

Linux oder macOS

Senden Sie mit curl eine HTTP-Anfrage unter Verwendung der zuvor festgelegten Umgebungsvariablen ENDPOINTS_KEY. Ersetzen Sie IP_ADDRESS durch die externe IP-Adresse Ihrer Instanz.

curl --request POST \
   --header "content-type:application/json" \
   --data '{"message":"hello world"}' \
   "http://IP_ADDRESS:80/echo?key=${ENDPOINTS_KEY}"

Im vorherigen Beispiel für curl gilt:

• Durch die Option --data werden die an die API zu übertragenden Daten festgelegt.
• Durch die Option --header wird angegeben, dass die Daten im JSON-Format vorliegen.

PowerShell

Senden Sie mit Invoke-WebRequest eine HTTP-Anfrage unter Verwendung der zuvor festgelegten Umgebungsvariablen ENDPOINTS_KEY. Ersetzen Sie IP_ADDRESS durch die externe IP-Adresse Ihrer Instanz.

(Invoke-WebRequest -Method POST -Body '{"message": "hello world"}' `
    -Headers @{"content-type"="application/json"} `
    -URI "http://IP_ADDRESS:80/echo?key=$Env:ENDPOINTS_KEY").Content

In diesem Beispiel enden die ersten beiden Zeilen mit einem Graviszeichen. Achten Sie beim Einfügen des Beispiels in PowerShell darauf, dass nach dem Graviszeichen kein Leerzeichen folgt. Informationen zu den in der Beispielanfrage verwendeten Optionen finden Sie in der Microsoft-Dokumentation unter Invoke-WebRequest.

Drittanbieteranwendung

Sie können eine Drittanbieteranwendung wie die Chrome-Browsererweiterung Postman zum Senden der Anfrage verwenden:

• Wählen Sie POST als HTTP-Verb aus.
• Wählen Sie für den Header den Schlüssel content-type und den Wert application/json aus.
• Geben Sie als Text Folgendes ein:
  {"message":"hello world"}
• Verwenden Sie in der URL den tatsächlichen API-Schlüssel und nicht die Umgebungsvariable. Beispiel:
  http://192.0.2.0:80/echo?key=AIza...

Die API gibt die von Ihnen gesendete Meldung zurück und reagiert mit folgender Zeile:

{
  "message": "hello world"
}

Wenn Sie als Antwort einen Fehler erhalten haben, lesen Sie die Informationen unter Fehlerbehebung bei Antwortfehlern.

Sie haben gerade eine API in Cloud Endpoints bereitgestellt und getestet!

Hinweis: Wenn Sie uns mitteilen möchten, was Ihnen an dieser Anleitung gefallen hat, können Sie uns gerne Feedback geben. Ihr Feedback hilft uns bei der Verbesserung dieser Anleitungen.
Wenn Sie eine Fehlermeldung erhalten, können Sie der Google-Gruppe google-cloud-endpoints beitreten und uns mitteilen, was schiefgegangen ist. Sie erhalten in dieser Gruppe Antworten von anderen Endpoints-Nutzern und Google-Entwicklern, die die Diskussion in der Gruppe verfolgen.

API-Aktivität verfolgen

So verfolgen Sie API-Aktivitäten:

1. Sehen Sie sich auf der Seite Endpoints > Dienste die Aktivitätsgrafiken für Ihre API an.
   

   Endpoints-Dienste aufrufen

   
   Es kann einen Moment dauern, bis die Anfrage in den Grafiken angezeigt wird.
2. Sehen Sie sich auf der Seite "Log Explorer" die Anfragelogs an.
   

   Zur Seite „Log-Explorer“

DNS für Endpoints konfigurieren

Da sich der Name des Endpoints-Diensts für die API in der Domain .endpoints.YOUR_PROJECT_ID.cloud.goog befindet, können Sie ihn als vollständig qualifizierten Domainnamen verwenden. Dazu nehmen Sie eine kleine Konfigurationsänderung in Ihrer openapi.yaml -Datei vor. Sie können dadurch Anfragen an die Beispiel-API über echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog senden, anstatt die IP-Adresse zu verwenden.

So konfigurieren Sie das DNS für Endpoints:

1. Öffnen Sie die OpenAPI-Konfigurationsdatei openapi.yaml und fügen Sie das Attribut x-google-endpoints wie im folgenden Snippet gezeigt auf der obersten Ebene der Datei hinzu (nicht eingerückt oder verschachtelt):

   host: "echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog"
   x-google-endpoints:
   - name: "echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog"
     target: "IP_ADDRESS"
   

2. Ersetzen Sie im Attribut name den Parameter YOUR_PROJECT_ID durch Ihre Projekt-ID.
3. Ersetzen Sie im Attribut target den Parameter IP_ADDRESS durch die IP-Adresse, die Sie beim Senden einer Anfrage an die Beispiel-API verwendet haben.
4. Stellen Sie Ihre aktualisierte OpenAPI-Konfigurationsdatei für Service Management bereit:

   gcloud endpoints services deploy openapi.yaml
   

Beispiel: In der Datei openapi.yaml ist Folgendes konfiguriert:

host: "echo-api.endpoints.example-project-12345.cloud.goog"
x-google-endpoints:
- name: "echo-api.endpoints.example-project-12345.cloud.goog"
  target: "192.0.2.1"

Wenn Sie die Datei openapi.yaml mit dem vorherigen gcloud-Befehl bereitstellen, wird in der Service Management API der DNS-A-Eintrag echo-api.endpoints.my-project-id.cloud.goog erstellt und in die Ziel-IP-Adresse 192.0.2.1 aufgelöst. Es kann einige Minuten dauern, bis die neue DNS-Konfiguration verteilt wurde.

SSL konfigurieren

Weitere Informationen zum Konfigurieren von DNS und SSL finden Sie unter SSL für Endpoints aktivieren.

Anfrage über FQDN senden

Sie haben den DNS-Eintrag für die Beispiel-API konfiguriert. Nun senden Sie eine Anfrage über den FQDN (ersetzen Sie dabei YOUR_PROJECT_ID durch Ihre Projekt-ID) und die zuvor festgelegte Umgebungsvariable ENDPOINTS_KEY:

• In Linux oder macOS:

  curl --request POST \
      --header "content-type:application/json" \
      --data '{"message":"hello world"}' \
      "http://echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog:80/echo?key=${ENDPOINTS_KEY}"

• In Windows PowerShell:

  (Invoke-WebRequest -Method POST -Body '{"message": "hello world"}' -Headers @{"content-type"="application/json"} -URI "http://echo-api.endpoints.[YOUR_PROJECT_ID].cloud.goog:80/echo?key=$Env:ENDPOINTS_KEY").Content

Entwicklerportal für die API erstellen

Sie können mit dem Cloud Endpoints-Portal ein Entwicklerportal erstellen. Dabei handelt es sich um eine Website zur Interaktion mit der Beispiel-API. Weitere Informationen finden Sie unter Übersicht über das Cloud Endpoints-Portal.

Bereinigen

Damit Ihrem Google Cloud-Konto die in dieser Anleitung verwendeten Ressourcen nicht in Rechnung gestellt werden, löschen Sie entweder das Projekt, das die Ressourcen enthält, oder Sie behalten das Projekt und löschen die einzelnen Ressourcen.

Informationen zum Beenden der in dieser Anleitung verwendeten Dienste finden Sie unter API und API-Instanzen löschen.

Weitere Informationen

• Docker-Image erstellen
• Endpoints auf Kubernetes bereitstellen
• API mit einem anderen Entwickler teilen
• Authentifizierungsmethode auswählen
• Google Cloud Endpoints-Community
• Fehlerbehebung bei der GKE-Bereitstellung