Erste Schritte mit Cloud Endpoints für Kubernetes mit ESPv2

In dieser Anleitung wird erklärt, wie Sie eine Beispiel-API und den Extensible Service Proxy V2 (ESPv2) konfigurieren und in einem Kubernetes-Cluster bereitstellen, der sich nicht in Google Cloud befindet. Wenn Sie Google Kubernetes Engine (GKE) verwenden möchten, lesen Sie die Anleitung Erste Schritte mit Cloud Endpoints in GKE.

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

In der Anleitung werden vorkonfigurierte Container-Images des Beispielcodes und des ESPv2 verwendet, die in Container Registry gespeichert sind. Wenn Sie nicht mit Containern vertraut sind, finden Sie im Folgenden weitere Informationen:

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

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. Die in der Anleitung verwendete Software installieren und konfigurieren. Siehe Erforderliche Software installieren und konfigurieren.
  3. Optional kann der Beispielcode heruntergeladen werden. Siehe Beispielcode abrufen.
  4. Laden Sie die Kubernetes-Konfigurationsdatei herunter. Siehe Kubernetes-Konfigurationsdatei abrufen.
  5. Konfigurieren Sie die Datei openapi.yaml, mit der Endpoints konfiguriert wird. Siehe Endpoints konfigurieren.
  6. Stellen Sie die Endpoints-Konfiguration bereit, um einen Cloud Endpoints-Dienst zu erstellen. Siehe Endpoints-Konfiguration bereitstellen.
  7. Erstellen Sie Anmeldedaten für Ihren Endpoints-Dienst. Siehe Anmeldedaten für Ihren Dienst erstellen.
  8. Stellen Sie die API und den ESPv2 im Cluster bereit. Siehe API-Back-End bereitstellen.
  9. Rufen Sie die externe IP-Adresse des Diensts ab. Siehe Externe IP-Adresse abrufen.
  10. Über eine IP-Adresse eine Anfrage an die API senden: Siehe Anfrage über eine IP-Adresse senden.
  11. API-Aktivitäten verfolgen. Siehe API-Aktivitäten verfolgen.

Teil 2

  1. Konfigurieren Sie einen DNS-Eintrag für die Beispiel-API. Siehe DNS für Endpoints konfigurieren.
  2. Senden Sie mithilfe des Domainnamens eine Anfrage an die API. Siehe Anfrage über FQDN senden.

Clean-up

Lesen Sie am Ende den Abschnitt Bereinigen, damit keine Gebühren für Ihr Google Cloud-Konto anfallen.

Kosten

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

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

Es wird vorausgesetzt, dass Sie bereits Minikube oder einen Kubernetes-Cluster eingerichtet haben. Weitere Informationen finden Sie in der Kubernetes-Dokumentation.

  1. Melden Sie sich bei Ihrem Google-Konto an.

    Wenn Sie noch kein Konto haben, melden Sie sich hier für ein neues Konto an.

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

    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. Notieren Sie sich die Google Cloud-Projekt-ID, da sie später benötigt wird.

Erforderliche Software installieren und konfigurieren

Mithilfe dieser Anleitung installieren Sie das Cloud SDK, um die gcloud-Befehlszeilenschnittstelle zum Verwalten Ihres Projekts zu verwenden. Mit der Befehlszeilenschnittstelle kubectl führen Sie Befehle für Kubernetes-Cluster aus. Sie müssen die API außerdem 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 Tab 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 Cloud SDK-Konfigurationen verwalten.

  6. Installieren Sie kubectl:
    gcloud components install kubectl
  7. Rufen Sie neuen Nutzeranmeldedaten ab, die als Standardanmeldedaten für Anwendungen verwendet werden sollen. Mit den Nutzeranmeldedaten wird kubectl autorisiert.
    gcloud auth application-default login
  8. Ein neuer Browsertab wird geöffnet. Wählen Sie dort ein Konto aus.
  9. Führen Sie den folgenden Befehl aus, um zu überprüfen, ob der Kubernetes-Client richtig konfiguriert ist:
    kubectl version

    Die Ausgabe sollte in etwa so aussehen:

       Client Version: version.Info{Major:"1", Minor:"8", GitVersion:"v1.8.4",
         GitCommit:"9befc2b8928a9426501d3bf62f72849d5cbcd5a3", GitTreeState:"clean",
         BuildDate:"2017-11-20T05:28:34Z", GoVersion:"go1.8.3", Compiler:"gc",
         Platform:"linux/amd64"}
       Server Version: version.Info{Major:"1", Minor:"7+",
         GitVersion:"v1.7.8-gke.0",
         GitCommit:"a7061d4b09b53ab4099e3b5ca3e80fb172e1b018", GitTreeState:"clean",
         BuildDate:"2017-10-10T18:48:45Z", GoVersion:"go1.8.3", Compiler:"gc",
         Platform:"linux/amd64"}
       

Beispielcode herunterladen

Optional kann der Beispielcode heruntergeladen werden. In dieser Anleitung stellen Sie ein vorgefertigtes Container-Image bereit, sodass Sie keinen Container aus dem Beispielcode erstellen müssen. Möglicherweise möchten Sie dennoch den Beispielcode herunterladen, der in mehreren Sprachen bereitgestellt wird, damit Sie besser verstehen, wie die Beispiel-API funktioniert.

So laden Sie den Beispielcode herunter:

Java

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

  1. Klonen Sie das Repository der Beispielanwendung 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 klonen Sie die Beispiel-API oder laden diese herunter:

  1. Klonen Sie das Repository der Beispielanwendung 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 -u -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 klonen Sie die Beispiel-API oder laden diese herunter:

  1. Klonen Sie das Repository der Beispielanwendung 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 klonen Sie die Beispiel-API oder laden diese herunter:

  1. Klonen Sie das Repository der Beispielanwendung 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 klonen Sie die Beispiel-API oder laden diese herunter:

  1. Klonen Sie das Repository der Beispielanwendung 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

Kubernetes-Konfigurationsdatei abrufen

  1. Klonen Sie das GitHub-Repository, das die in dieser Anleitung verwendete Datei yaml enthält, auf Ihrem lokalen Computer:

     git clone https://github.com/googlecloudplatform/endpoints-samples

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

  2. Öffnen Sie das Verzeichnis, das die Konfigurationsdateien enthält:

     cd endpoints-samples/kubernetes

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.

    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, erfahren Sie unter DNS für Endpoints konfigurieren, wie Sie konfigurieren Sie echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog als FQDN.

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-samples/kubernetes 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 Bereitstellung von Cloud Endpoints-Konfigurationen.

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.

Anmeldedaten für den Dienst erstellen

Zur Verwaltung Ihrer API benötigt sowohl ESP als auch ESPv2 die Dienste in der Service Infrastructure. ESP und ESPv2 müssen Zugriffstokens verwenden, um diese Dienste aufzurufen. Wenn Sie ESP oder ESPv2 in Google Cloud-Umgebungen wie GKE, Compute Engine oder der flexiblen App Engine-Umgebung bereitstellen, rufen ESP und ESPv2 Zugriffstokens über den Google Cloud-Metadatendienst ab.

Wenn Sie ESP oder ESPv2 in einer Cloud-Umgebung bereitstellen, die nicht von Google Cloud stammt, z. B. auf Ihrem lokalen Desktop, einem lokalen Kubernetes-Cluster oder einem anderen Cloud-Anbieter, müssen Sie eine JSON-Datei für ein Dienstkonto bereitstellen, die einen privaten Schlüssel enthält. ESP und ESPv2 verwenden das Dienstkonto, um Zugriffstoken zu generieren und damit die Dienste aufzurufen, die für die Verwaltung der API erforderlich sind.

Sie können entweder die Cloud Console oder das gcloud-Befehlszeilentool verwenden, um das Dienstkonto und die Datei mit dem privaten Schlüssel zu erstellen und dem Dienstkonto die folgenden Rollen zuzuweisen:

Console

  1. Rufen Sie in der Cloud Console die Seite Dienstkonten auf.

    Zur Seite "Dienstkonten"

  2. Klicken Sie auf Auswählen.
  3. Wählen Sie das Projekt aus, in dem Ihre API erstellt wurde, und klicken Sie auf Öffnen.
  4. Klicken Sie auf + Dienstkonto erstellen.
  5. Geben Sie im Feld Name des Dienstkontos den Namen für das Dienstkonto ein.
  6. Klicken Sie auf Erstellen.
  7. Klicken Sie auf Weiter.
  8. Klicken Sie auf Fertig.
  9. Wählen Sie das neu erstellte Dienstkonto aus, klicken Sie ganz rechts auf das Menü Aktion und klicken Sie auf den Menüpunkt Schlüssel erstellen.
  10. Wählen Sie im Pop-up-Steuerfeld unter "Private Schlüssel erstellen" den Schlüsseltyp aus und verwenden Sie den Standardtyp JSON.
  11. Klicken Sie auf Erstellen.

Dadurch wird das Dienstkonto erstellt und der private Schlüssel in eine JSON-Datei heruntergeladen.

gcloud

  1. Geben Sie Folgendes ein, um sich die Projekt-IDs für Ihre Google Cloud-Projekte anzeigen zu lassen:

    gcloud projects list
  2. Ersetzen Sie im folgenden Befehl PROJECT_ID, damit das Projekt, in dem sich Ihre API befindet, zum Standardprojekt wird:

    gcloud config set project PROJECT_ID

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

    gcloud auth login

    Wenn Sie mehrere Konten haben, wählen Sie das Konto aus, das sich im Google Cloud-Projekt mit der API befindet. Wenn Sie gcloud auth list ausführen, wird das von Ihnen ausgewählte Konto als aktives Konto für das Projekt angezeigt.

  4. Führen Sie zum Erstellen eines Dienstkontos folgenden Befehl aus und ersetzen Sie SERVICE_ACCOUNT_NAME und My Service Account durch den zu verwendenden Namen bzw. Anzeigenamen:

    gcloud iam service-accounts create SERVICE_ACCOUNT_NAME 
    --display-name "My Service Account"

    Mit dem Befehl wird dem Dienstkonto eine E-Mail-Adresse im folgenden Format zugewiesen:

    SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com

    Diese E-Mail-Adresse wird für die nachfolgenden Befehle benötigt.

  5. Erstellen Sie eine Dienstkonto-Schlüsseldatei:

    gcloud iam service-accounts keys create ~/service-account-creds.json \
          --iam-account SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com

Erforderliche IAM-Rollen hinzufügen:

Die folgenden IAM-Rollen sind für das Dienstkonto erforderlich, das für ESP und ESPv2 verwendet wird.

So fügen Sie dem Dienstkonto die IAM-Rollen „Dienstüberwacher“ und „Cloud Trace-Agent“ hinzu:

Console

  1. Wählen Sie in der Cloud Console das Projekt aus, in dem das Dienstkonto erstellt wurde.
  2. Öffnen Sie die Seite IAM/Iam

    Zur Seite „IAM/Iam“

    . Auf der Seite sollten alle IAM-Mitglieder einschließlich aller Dienstkonten aufgelistet sein.
  3. Wählen Sie das Dienstkonto aus und klicken Sie rechts auf Bearbeiten.
  4. Das Fenster Berechtigungen bearbeiten wird geöffnet.
  5. Klicken Sie auf + Weitere Rolle hinzufügen.
  6. Klicken Sie auf Rolle auswählen und wählen Sie Dienstverwaltung > Dienstüberwacher aus.
  7. Klicken Sie auf + Weitere Rolle hinzufügen.
  8. Klicken Sie auf Rolle auswählen und wählen Sie Cloud Trace > Cloud Trace-Agent aus.
  9. Klicken Sie auf Speichern.
  10. Nun sollten Sie die Rollen Dienstüberwacher und Cloud Trace-Agent in der Spalte Rolle Ihres Dienstkontos auf der IAM-Seite sehen.

gcloud

  1. Fügen Sie die Rolle "Dienstüberwacher" hinzu:

    gcloud projects add-iam-policy-binding PROJECT_ID \
            --member serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com \
            --role roles/servicemanagement.serviceController
  2. Fügen Sie die Rolle "Cloud Trace Agent" hinzu, um Cloud Trace zu aktivieren:

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

Weitere Informationen finden Sie unter Was sind Rollen und Berechtigungen?

See
[`gcloud iam service-accounts`](/sdk/gcloud/reference/iam/service-accounts/){: track-type="tutorial" track-name="internalLink" track-metadata-position="body" }
for more information about the commands.

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 ESPv2 Beta in Kubernetes beschrieben.

Erforderliche Berechtigungen prüfen

Gewähren Sie dem Dienstkonto, das Ihrem Cluster zugeordnet ist, die erforderlichen Berechtigungen:

gcloud projects add-iam-policy-binding PROJECT_NAME \
    --member "serviceAccount:SERVICE_ACCOUNT" \
    --role roles/servicemanagement.serviceController

Weitere Informationen finden Sie unter Was sind Rollen und Berechtigungen?

Dienst-Anmeldedaten für ESPv2 bereitstellen

Der ESPv2, der in einem Container ausgeführt wird, benötigt Zugriff auf die lokal in der Datei service-account-creds.json gespeicherten Anmeldedaten. Damit der ESPv2 Zugriff auf die Anmeldedaten erhält, müssen Sie ein Kubernetes Secret erstellen und als Kubernetes Volume bereitstellen.

So erstellen Sie das Kubernetes Secret und stellen das Volume bereit:

  1. Wichtig ist, dass Sie die JSON-Datei in service-account-creds.json umbenennen und in endpoints-samples/kubernetes kopieren, wenn sie in ein anderes Verzeichnis heruntergeladen wurde. Auf diese Weise stimmt der Name mit den Optionen überein, die in der Bereitstellungsmanifestdatei echo.yaml angegeben sind.
  2. Sie müssen sich im Verzeichnis endpoints-samples/kubernetes befinden.
  3. Erstellen Sie mit dem folgenden Befehl ein Kubernetes-Secret mit den Anmeldedaten des Dienstkontos:

    kubectl create secret generic service-account-creds \
       --from-file=service-account-creds.json
    

    Wenn der Vorgang gelingt, wird die folgende Meldung angezeigt:

    secret "service-account-creds" created

Die Bereitstellungsmanifestdatei, die zum Bereitstellen der API und des ESPv2 für Kubernetes verwendet wird, enthält bereits das Secret-Volume, wie in den folgenden beiden Abschnitten der Datei gezeigt:

volumes:
  - name: service-account-creds
    secret:
      secretName: service-account-creds
volumeMounts:
  - mountPath: /etc/esp/creds
    name: service-account-creds
    readOnly: true

Dienstname konfigurieren und Dienst starten

Der ESPv2 muss den Namen des Diensts kennen, damit er die zuvor mithilfe des Befehls gcloud endpoints services deploy bereitgestellte Konfiguration ermitteln kann.

So konfigurieren Sie den Dienstnamen und starten den Dienst:

  1. Öffnen Sie die Bereitstellungsmanifestdatei echo.yaml und ersetzen Sie SERVICE_NAME in den ESPv2-Startoptionen durch den Namen Ihres Dienstes. Dies ist der Name, den Sie im Feld host Ihres OpenAPI-Dokuments konfiguriert haben. Beispiel:

    "--service=echo-api.endpoints.example-project-12345.cloud.goog"
    containers:
    - name: esp
      image: gcr.io/endpoints-release/endpoints-runtime:2
      args: [
        "--listener_port=8080",
        "--backend=127.0.0.1:8081",
        "--service=SERVICE_NAME",
        "--rollout_strategy=managed",
        "--service_account_key=/etc/esp/creds/service-account-creds.json"
      ]
      ports:
        - containerPort: 8080
      volumeMounts:
        - mountPath: /etc/esp/creds
          name: service-account-creds
          readOnly: true
    - name: echo
      image: gcr.io/endpoints-release/echo:latest
      ports:
        - containerPort: 8081
    

    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.

  2. Starten Sie den Dienst mit dem folgenden Befehl, um den Endpoints-Dienst auf Kubernetes bereitzustellen:

    kubectl create -f echo.yaml

    Möglicherweise erhalten Sie eine Fehlermeldung, die so aussieht:

    The connection to the server localhost:8080 was refused - did you specify the right host or port?

    Dies weist darauf hin, dass kubectl nicht richtig konfiguriert ist. Weitere Informationen finden Sie im Artikel zum Installieren und Einrichten von kubectl. Weitere Informationen finden Sie im Abschnitt Cloud Endpoints auf Kubernetes bereitstellen.

Externe IP-Adresse des Diensts abrufen

Wenn Sie Minikube verwenden, fahren Sie mit Anfrage über eine IP-Adresse senden fort. Nach dem Start Ihres Diensts im Container kann es einige Minuten dauern, bevor die externe IP-Adresse bereit ist.

So rufen Sie die externe IP-Adresse des Diensts ab:

  1. Führen Sie den folgenden Befehl aus:

    kubectl get service

  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

Nachdem die Beispiel-API im Containercluster ausgeführt wird, 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 "Anmeldedaten"

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

Senden Sie die Anfrage an minikube.

In den folgenden Befehlen wird die zuvor festgelegte Umgebungsvariable ENDPOINTS_KEY verwendet.

Linux oder macOS

NODE_PORT=`kubectl get service esp-echo --output='jsonpath={.spec.ports[0].nodePort}'`
MINIKUBE_IP=`minikube ip`
curl --request POST \
    --header "content-type:application/json" \
    --data '{"message":"hello world"}' \
    ${MINIKUBE_IP}:${NODE_PORT}/echo?key=${ENDPOINTS_KEY}

PowerShell

$Env:NODE_PORT=$(kubectl get service esp-echo --output='jsonpath={.spec.ports[0].nodePort}')
$Env:MINIKUBE_IP=$(minikube ip)
(Invoke-WebRequest -Method POST -Body '{"message": "hello world"}' `
    -Headers @{"content-type"="application/json"} `
    -URI "http://$Env:MINIKUBE_IP:$Env:NODE_PORT/echo?key=$Env:ENDPOINTS_KEY").Content

Anfrage an andere Kubernetes-Cluster 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!

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.

    Zur Seite "Endpoints-Dienste"


    Es kann einen Moment dauern, bis die Anfrage in den Grafiken angezeigt wird.

  2. Sehen Sie sich auf der Seite "Loganzeige" die Anfragelogs an.

    Loganzeige aufrufen

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 an den FQDN senden

Sie haben den DNS-Eintrag für die Beispiel-API konfiguriert. Senden Sie nun 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. Das ist eine Website zur Interaktion mit der Beispiel-API. Weitere Informationen finden Sie unter Übersicht über das Cloud Endpoints-Portal.

Bereinigen

So vermeiden Sie, dass Ihrem Google Cloud Platform-Konto die in dieser Anleitung verwendeten Ressourcen in Rechnung gestellt werden:

  • Löschen Sie den Kubernetes-Dienst und das -Deployment:
    kubectl delete -f echo.yaml

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

Weitere Informationen