Diese Seite wurde von der Cloud Translation API übersetzt.

Erste Schritte mit Endpoints für Kubernetes mit ESP

OpenAPI | gRPC

In dieser Anleitung erfahren Sie, wie Sie mit dem Extensible Service Proxy (ESP) einen einfachen gRPC in einem Kubernetes-Cluster bereitstellen, der nicht inGoogle Cloudausgeführt wird. Dafür wird in der Anleitung die Python-Version des Beispiels bookstore-grpc verwendet. gRPC-Beispiele in anderen Sprachen finden Sie unter Weitere Informationen.

In der Anleitung werden vorkonfigurierte Container-Images des Beispielcodes und des ESP verwendet, die in Artifact Registry gespeichert sind. Wenn Sie nicht mit Containern vertraut sind, finden Sie weitere Informationen auf den folgenden Seiten:

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

Endpoints konfigurieren

Das bookstore-grpc-Beispiel enthält die Dateien, die Sie lokal kopieren und konfigurieren müssen.

Create a self-contained protobuf descriptor file from your service .proto file:
1. Save a copy of bookstore.proto from the example repository. This file defines the Bookstore service's API.
2. Create the following directory: mkdir generated_pb2
3. Create the descriptor file, api_descriptor.pb, by using the protoc protocol buffers compiler. Run the following command in the directory where you saved bookstore.proto:
```
python -m grpc_tools.protoc \
    --include_imports \
    --include_source_info \
    --proto_path=. \
    --descriptor_set_out=api_descriptor.pb \
    --python_out=generated_pb2 \
    --grpc_python_out=generated_pb2 \
    bookstore.proto
```
  In the preceding command, --proto_path is set to the current working directory. In your gRPC build environment, if you use a different directory for .proto input files, change --proto_path so the compiler searches the directory where you saved bookstore.proto.
Create a gRPC API configuration YAML file:
1. Save a copy of the api_config.yamlfile. This file defines the gRPC API configuration for the Bookstore service.
2. Replace MY_PROJECT_ID in your api_config.yaml file with your Google Cloud project ID. For example:
```
#
# Name of the service configuration.
#
name: bookstore.endpoints.example-project-12345.cloud.goog
```
  Note that the apis.name field value in this file exactly matches the fully-qualified API name from the .proto file; otherwise deployment won't work. The Bookstore service is defined in bookstore.proto inside package endpoints.examples.bookstore. Its fully-qualified API name is endpoints.examples.bookstore.Bookstore, just as it appears in the api_config.yaml file.
```
apis:
  - name: endpoints.examples.bookstore.Bookstore
```

Weitere Informationen finden Sie unter Endpoints konfigurieren.

Endpoints-Konfiguration bereitstellen

Die Endpoints-Konfiguration wird mit dem Befehl gcloud endpoints services deploy bereitgestellt. Dieser Befehl verwendet Service Infrastructure, die grundlegende Dienstplattform von Google. Sie wird von Endpoints und anderen Diensten verwendet, um APIs und Dienste zu erstellen und zu verwalten.

Make sure you are in the directory where the api_descriptor.pb and api_config.yaml files are located.
Confirm that the default project that the gcloud command-line tool is currently using is the Google Cloud project that you want to deploy the Endpoints configuration to. Validate the project ID returned from the following command to make sure that the service doesn't get created in the wrong project.
```
gcloud config list project
```
If you need to change the default project, run the following command:
```
gcloud config set project YOUR_PROJECT_ID
```
Deploy the proto descriptor file and the configuration file by using the Google Cloud CLI:
```
gcloud endpoints services deploy api_descriptor.pb api_config.yaml
```
As it is creating and configuring the service, Service Management outputs information to the terminal. When the deployment completes, a message similar to the following is displayed:
```
Service Configuration [CONFIG_ID] uploaded for service [bookstore.endpoints.example-project.cloud.goog]
```
CONFIG_ID is the unique Endpoints service configuration ID created by the deployment. For example:
```
Service Configuration [2017-02-13r0] uploaded for service [bookstore.endpoints.example-project.cloud.goog]
```
In the previous example, 2017-02-13r0 is the service configuration ID and bookstore.endpoints.example-project.cloud.goog is the service name. The service configuration ID consists of a date stamp followed by a revision number. If you deploy the Endpoints configuration again on the same day, the revision number is incremented in the service configuration ID.

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

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 vorhandenesGoogle 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

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.

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

Weitere Informationen finden Sie unter Endpoints-Konfiguration bereitstellen.

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 oder Compute Engine bereitstellen, rufen ESP und ESPv2 Zugriffstokens über den Google Cloud Metadatendienst ab.

Wenn Sie ESP oder ESPv2 in einer Umgebung bereitstellen, die nicht vonGoogle 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 Google Cloud Console oder die Google Cloud CLI verwenden, um das Dienstkonto und die Datei mit dem privaten Schlüssel zu erstellen:

Console

Rufen Sie in der Google Cloud Console die Seite Dienstkonten auf .
Zur Seite „Dienstkonten“
Klicken Sie auf Auswählen.
Wählen Sie das Projekt aus, in dem Ihre API erstellt wurde, und klicken Sie auf Öffnen.
Klicken Sie auf + Dienstkonto erstellen.
Geben Sie im Feld Name des Dienstkontos den Namen für das Dienstkonto ein.
Klicken Sie auf Erstellen.
Klicken Sie auf Weiter.
Klicken Sie auf Fertig.
Klicken Sie auf die E-Mail-Adresse des neu erstellten Dienstkontos.
Klicken Sie auf Schlüssel.
Klicken Sie auf Schlüssel hinzufügen > Neuen Schlüssel erstellen.
Klicken Sie auf Erstellen. Daraufhin wird eine JSON-Schlüsseldatei auf Ihren Computer heruntergeladen.

Bewahren Sie die Schlüsseldatei sicher auf, da sie zur Authentifizierung als Ihr Dienstkonto verwendet werden kann. Sie können diese Datei beliebig verschieben und umbenennen.
Klicken Sie auf Schließen.

`gcloud`

Geben Sie Folgendes ein, um sich die Projekt-IDs für IhreGoogle Cloud -Projekte anzeigen zu lassen:
```
gcloud projects list
```
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
```
Wichtig :Sie müssen das Dienstkonto im selben Projekt erstellen, in dem sich auch die API befindet.
Die Google Cloud CLI (gcloud) muss berechtigt sein, auf Ihre Daten und Dienste auf Google Cloudzuzugreifen:
```
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.
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.

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:

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.comdas angehängte Dienstkonto. Weitere Informationen finden Sie unter Was sind Rollen und Berechtigungen?

Weitere Informationen zu den Befehlen finden Sie unter gcloud iam service-accounts.

API-Back-End bereitstellen

Sie haben jetzt die Dienstkonfiguration für Service Management, aber noch nicht den Code für das Back-End der API bereitgestellt. In diesem Abschnitt wird die Bereitstellung vorkonfigurierter Container für die API und den ESP in Kubernetes beschrieben.

Dienstanmeldedaten für ESP bereitstellen

Der ESP, der in einem Container ausgeführt wird, benötigt Zugriff auf die lokal in der Datei service-account-creds.json gespeicherten Anmeldedaten. Damit der ESP 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:

Falls Sie die Google Cloud -Konsole zum Erstellen des Dienstkontos verwendet haben, benennen Sie die JSON-Datei in service-account-creds.json um. Verschieben Sie diese in das Verzeichnis, in dem sich auch api_descriptor.pb und api_config.yaml befinden.
Erstellen Sie mit den Anmeldedaten des Dienstkontos ein Kubernetes-Secret:
```
 kubectl create secret generic service-account-creds
      --from-file=service-account-creds.json
```
Bei Erfolg wird die folgende Mitteilung angezeigt: secret "service-account-creds" created.

Die Bereitstellungsmanifestdatei, die zum Bereitstellen der API und des ESP 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/nginx/creds
    name: service-account-creds
    readOnly: true

Dienstname konfigurieren und Dienst starten

Der ESP 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:

Speichern Sie eine Kopie der Bereitstellungsmanifestdatei k8s-grpc-bookstore.yaml im selben Verzeichnis wie service-account-creds.json.
Öffnen Sie k8s-grpc-bookstore.yaml und ersetzen Sie SERVICE_NAME durch den Namen Ihres Endpoints-Diensts. Dies ist der Name, den Sie in der Datei api_config.yaml im Feld name konfiguriert haben.
```
containers:
  - name: esp
    image: gcr.io/endpoints-release/endpoints-runtime:1
    args: [
      "--http2_port=9000",
      "--service=SERVICE_NAME",
      "--rollout_strategy=managed",
      "--backend=grpc://127.0.0.1:8000",
      "--service_account_key=/etc/nginx/creds/service-account-creds.json"
    ]
```
Mit der Option --rollout_strategy=managed legen Sie fest, dass der ESP die zuletzt bereitgestellte Dienstkonfiguration verwendet. Wenn Sie diese Option innerhalb von 5 Minuten nach der Bereitstellung einer neuen Dienstkonfiguration angeben, erkennt der ESP die Änderung und verwendet automatisch die neue Konfiguration. Wir empfehlen, diese Option anstelle einer konkreten Konfigurations-ID anzugeben, die vom ESP verwendet werden soll. Weitere Informationen zu den ESP-Argumenten finden Sie unter ESP-Startoptionen.

Hinweis: Wenn Sie MiniKube verwenden, müssen Sie in der Konfigurationsdatei das Feld type des Dienstes von LoadBalancer in NodePort ändern.
Hinweis: Es wird empfohlen, imagePullPolicy in der oben genannten Containerspezifikation auf Always festzulegen. Dadurch können neu erstellte Pods immer die neueste Version des ESP abrufen. Weitere Informationen finden Sie unter Best Practices für die Konfiguration. Wenn eine neue Version des ESP veröffentlicht wird, können Sie einen fortlaufenden Neustart aller Pods durchführen, um sicherzustellen, dass die neueste Version verwendet wird.
Starten Sie den Dienst, um ihn auf Kubernetes bereitzustellen:
```
kubectl create -f k8s-grpc-bookstore.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 unter kubectl konfigurieren.

Externe IP-Adresse des Diensts abrufen

Sie benötigen die externe IP-Adresse des Diensts, um Anfragen an die Beispiel-API senden zu können. Nach dem Start Ihres Diensts im Container kann es einige Minuten dauern, bevor die externe IP-Adresse bereit ist.

Rufen Sie die externe IP-Adresse auf:
```
kubectl get service
```
Notieren Sie sich den Wert für EXTERNAL-IP und speichern Sie ihn in der Umgebungsvariablen SERVER_IP, die beim Versenden von Anfragen an die Beispiel-API verwendet wird.
```
export SERVER_IP=YOUR_EXTERNAL_IP
```

Anfrage an die API senden

To send requests to the sample API, you can use a sample gRPC client written in Python.

Clone the git repo where the gRPC client code is hosted:

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

Change your working directory:

cd python-docs-samples/endpoints/bookstore-grpc/

Install dependencies:

pip install virtualenv
virtualenv env
source env/bin/activate
python -m pip install -r requirements.txt

Send a request to the sample API:
```
python bookstore_client.py --host SERVER_IP --port 80
```
- Look at the activity graphs for your API in the Endpoints > Services page.
  
  Go to the Endpoints Services page
  
  It may take a few moments for the request to be reflected in the graphs.
- Look at the request logs for your API in the Logs Explorer page.
  
  Go to the Logs Explorer page

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!