本頁面由 Cloud Translation API 翻譯而成。

透過 ESPv2 使用 GKE 適用的 Endpoints

OpenAPI | gRPC

本教學課程說明如何在 Google Kubernetes Engine (GKE) 上，使用可擴充服務 Proxy V2 (ESPv2) 部署簡單的 gRPC 服務範例。本教學課程使用 Python 版本的 bookstore-grpc 範例。如需其他語言的 gRPC 範例，請參閱後續步驟一節。

本教學課程使用範例程式碼與 ESPv2 的預先建構容器映像檔，這些映像檔儲存在 Artifact Registry 中。如果您對於容器不熟悉，請參閱以下詳細資訊：

如需 Cloud Endpoints 的總覽，請參閱關於 Endpoints 和 Endpoints 架構。

目標

請根據以下的主要工作清單，逐步進行本教學課程的各個步驟。您必須完成所有工作才能成功傳送要求至 API。

設定 Google Cloud 專案，並下載必要軟體。請參閱事前準備。
從 bookstore-grpc 範例複製並設定檔案。詳情請參閱設定 Endpoints 一節。
部署 Endpoints 設定以建立 Endpoints 服務。請參閱部署 Endpoints 設定一節。
建立後端來提供及部署 API。請參閱部署 API 後端一節。
取得服務的外部 IP 位址。詳情請參閱取得服務的外部 IP 位址一節。
傳送要求至 API。請參閱傳送要求至 API 一節。
避免系統向您的 Google Cloud 帳戶收取費用。請參閱「清除所用資源」一節。

費用

在本文件中，您會使用 Google Cloud的下列計費元件：

您可以使用 Pricing Calculator 根據預測用量產生預估費用。新 Google Cloud 使用者可能符合申請免費試用的資格。

完成本文件所述工作後，您可以刪除已建立的資源，避免繼續計費。詳情請參閱「清除所用資源」。

事前準備

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

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

Go to project selector

Make sure that billing is enabled for your Google Cloud project.

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

Go to project selector

Make sure that billing is enabled for your Google Cloud project.

記下 Google Cloud 專案 ID，以便在稍後使用。
安裝並初始化 Google Cloud CLI。
更新 gcloud CLI 並安裝 Endpoints 元件。
```
gcloud components update
```
確認 Google Cloud CLI (gcloud) 已取得授權，可存取您在 Google Cloud中的資料與服務：
```
gcloud auth login
```
系統將開啟新的瀏覽器分頁，並提示您選擇一個帳戶。
將預設專案設為您的專案 ID。
```
gcloud config set project YOUR_PROJECT_ID
```
將 YOUR_PROJECT_ID 替換為您的專案 ID。

如果您有其他 Google Cloud 專案，而且想要使用 gcloud 加以管理，請參閱管理 gcloud CLI 設定。
安裝 kubectl：
```
gcloud components install kubectl
```
取得新的使用者憑證以做為應用程式預設憑證使用。您需要使用者憑證才能對 kubectl 進行授權。
```
gcloud auth application-default login
```
在開啟的新瀏覽器分頁中選擇一個帳戶。
按照 gRPC Python 快速入門導覽課程中的步驟安裝 gRPC 和 gRPC 工具。

設定 Endpoints

bookstore-grpc 範例包含了需要在本機複製及設定的檔案。

從您的服務 .proto 檔案中建立獨立的 protobuf 描述元檔案：
1. 儲存範例存放區中的 bookstore.proto 副本，這個檔案定義了 Bookstore 服務的 API。
2. 建立以下目錄：mkdir generated_pb2
3. 使用 protoc 通訊協定緩衝區編譯器建立描述元檔案 api_descriptor.pb。在儲存 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
```
  在上述指令中，--proto_path 會設為目前的工作目錄。在您的 gRPC 建構環境中，如果您為 .proto 輸入檔案使用不同的目錄，請變更 --proto_path 以讓編譯器能夠搜尋您儲存 bookstore.proto 的目錄。
建立 gRPC API 設定 YAML 檔案：
1. 請儲存 api_config.yaml 檔案的副本。這個檔案定義了 Bookstore 服務的 gRPC API 設定。
2. 將 api_config.yaml 檔案中的 MY_PROJECT_ID 替換為您的 Google Cloud 專案 ID。例如：
```
#
# Name of the service configuration.
#
name: bookstore.endpoints.example-project-12345.cloud.goog
```
  請注意，這個檔案中的 apis.name 欄位值必須與 .proto 檔案中的完整 API 名稱完全相同，否則無法部署。Bookstore 服務會在套件 endpoints.examples.bookstore 內的 bookstore.proto 中定義。其完整的 API 名稱為 endpoints.examples.bookstore.Bookstore，就像 api_config.yaml 檔案中的名稱一樣。
```
apis:
  - name: endpoints.examples.bookstore.Bookstore
```

詳情請參閱設定 Endpoints。

部署 Endpoints 設定

如要部署 Endpoints 設定，請使用 gcloud endpoints services deploy 指令。這個指令使用 Service Management 建立代管服務。

確認您所在的目錄有 api_descriptor.pb 和 api_config.yaml 檔案。
確認 gcloud 指令列工具目前使用的預設專案，就是您要部署 Endpoints 設定的 Google Cloud 專案。請利用下列指令傳回的專案 ID 進行驗證，以確保系統沒有將服務建立在錯誤的專案中。
```
gcloud config list project
```
如要變更預設的專案，請執行下列指令：
```
gcloud config set project YOUR_PROJECT_ID
```
使用 Google Cloud CLI 部署 proto descriptor 檔案和設定檔：
```
gcloud endpoints services deploy api_descriptor.pb api_config.yaml
```
Service Management 在建立並設定服務時，會把資訊輸出到終端機。部署完成後，您將看到類似以下的訊息：
```
Service Configuration [CONFIG_ID] uploaded for service [bookstore.endpoints.example-project.cloud.goog]
```
CONFIG_ID 是部署作業建立的 Endpoints 服務設定 ID。例如：
```
Service Configuration [2017-02-13r0] uploaded for service [bookstore.endpoints.example-project.cloud.goog]
```
在上方範例中，2017-02-13r0 是服務設定 ID，bookstore.endpoints.example-project.cloud.goog 則是服務名稱。服務設定 ID 是由一個日期戳記和一個修訂版本編號所組成。如果您在同一天再次部署 Endpoints 設定，服務設定 ID 中的修訂編號將會增加。

檢查必要服務

Endpoints 和 ESP 至少需要啟用下列 Google 服務：

名稱	標題
`servicemanagement.googleapis.com`	Service Management API
`servicecontrol.googleapis.com`	Service Control API

在大多數情況下，gcloud endpoints services deploy 指令會啟用這些必要服務。不過在以下情況中，即便您成功執行 gcloud 指令，還是無法啟用必要服務：

您使用 Terraform 之類的第三方應用程式，而其中未包含這些服務。
您已將 Endpoints 設定部署至現有Google Cloud 專案，但在專案中已明確停用這些服務。

使用下列指令確認已啟用必要服務：

gcloud services list

如果必要的服務並未列出，請執行下列指令加以啟用：

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

並啟用 Endpoints 服務：

gcloud services enable ENDPOINTS_SERVICE_NAME

如要判斷 ENDPOINTS_SERVICE_NAME，您可以採取下列任一做法：

部署 Endpoints 設定後，請前往 Cloud 控制台的「Endpoints」頁面。Service name 欄下方會列出可能的 ENDPOINTS_SERVICE_NAME 清單。
針對 OpenAPI，ENDPOINTS_SERVICE_NAME 是您在 OpenAPI 規格 host 欄位中指定的值。針對 gRPC，ENDPOINTS_SERVICE_NAME 是您在 gRPC Endpoints 設定的 name 欄位中指定的值。

如要進一步瞭解 gcloud 指令，請參閱 gcloud 服務。

如果您收到錯誤訊息，請參閱排解 Endpoints 設定部署問題一文。

詳情請參閱部署 Endpoints 設定一文。

部署 API 後端

到目前為止，您已將服務設定部署到 Service Management，但尚未部署為 API 後端提供服務的程式碼。本節將指導您建立一個 GKE 叢集以託管 API 後端與部署 API。

建立容器叢集

叢集需要IP 別名才能使用容器原生負載平衡。如要為此範例建立一個含有 IP 別名的容器叢集：

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

上述指令會建立一個名為 espv2-demo-cluster 的叢集，而 us-central1-a 區域含有一個自動佈建的子網路。

將 `kubectl` 驗證至容器叢集

如要使用 kubectl 來建立並管理叢集資源，您必須取得叢集憑證以供 kubectl 使用。如要進行這項操作，請執行下列指令，將 NAME 替換為您的新叢集名稱，並將 ZONE 替換為其叢集區域。

gcloud container clusters get-credentials NAME --zone ZONE

檢查必要權限

ESP 和 ESPv2 會呼叫 Google 服務，並使用 IAM 驗證呼叫身分是否具備足夠的權限，可存取所使用的 IAM 資源。呼叫身分是部署 ESP 和 ESPv2 的附加服務帳戶。

在 GKE pod 中部署時，附加的服務帳戶是節點服務帳戶。通常是 Compute Engine 的預設服務帳戶。請按照這項權限建議選擇適當的節點服務帳戶。

如果使用 Workload Identity，除了節點服務帳戶之外，您還可以使用其他服務帳戶與 Google 服務通訊。您可以為 Pod 建立 Kubernetes 服務帳戶，以便執行 ESP 和 ESPv2，並建立 Google 服務帳戶，然後將 Kubernetes 服務帳戶與 Google 服務帳戶建立關聯。

請按照這些步驟將 Kubernetes 服務帳戶與 Google 服務帳戶建立關聯。這個 Google 服務帳戶就是附加的服務帳戶。

如果所附服務帳戶是專案的 Compute Engine 預設服務帳戶，且端點服務設定已部署在同一個專案中，服務帳戶應具備足夠的權限來存取 IAM 資源，因此可以略過 IAM 角色設定步驟。否則，請將下列 IAM 角色新增至已附加的服務帳戶。

新增必要的 IAM 角色：

本節說明 ESP 和 ESPv2 使用的 IAM 資源，以及附加服務帳戶存取這些資源時所需的 IAM 角色。

端點服務設定

ESP 和 ESPv2 會呼叫 Service Control，後者會使用 Endpoints 服務設定。端點服務設定是 IAM 資源，ESP 和 ESPv2 需要服務控制器角色才能存取。

IAM 角色是在端點服務設定中，而非在專案中。一個專案可以有多個端點服務設定。

使用下列 gcloud 指令，將角色新增至端點服務設定的已連結服務帳戶。

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

其中：
* SERVICE_NAME 是端點服務名稱
* SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID.iam.gserviceaccount.com 是已附加的服務帳戶。

Cloud Trace

ESP 和 ESPv2 會呼叫 Cloud Trace 服務，將 Trace 匯出至專案。這項專案稱為追蹤專案。在 ESP 中，追蹤專案和擁有端點服務設定的專案相同。在 ESPv2 中，您可以使用 --tracing_project_id 旗標指定追蹤專案，預設為部署專案。

ESP 和 ESPv2 需要 Cloud Trace 代理人角色才能啟用 Cloud Trace。

使用下列 gcloud 指令，將角色新增至已連結的服務帳戶：

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

其中
* TRACING_PROJECT_ID 是追蹤專案 ID
* SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID.iam.gserviceaccount.com 是已附加的服務帳戶。詳情請參閱「什麼是角色和權限？」。

設定 SSL 金鑰和憑證

容器原生負載平衡會使用 HTTP2 LB，且必須使用 TLS 加密。這需要將 TLS 憑證部署至 GKE 入口和 ESPv2。您可以自備憑證，也可以使用自行簽署的憑證。

使用 openssl 建立自行簽署的憑證和金鑰。請確認在系統要求輸入「Common Name(CN)」時，您輸入的是相同的 FQDN bookstore.endpoints.MY_PROJECT_ID.cloud.goog。用戶端會使用這個名稱驗證伺服器憑證。
```
openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
-keyout ./server.key -out ./server.crt
```
使用 SSL 金鑰和憑證建立 Kubernetes 密鑰。請注意，憑證會複製到 server.crt 和 tls.crt 兩個位置，因為密鑰會提供給 GKE ingress 和 ESPv2。GKE ingress 會尋找憑證路徑 tls.crt，而 ESPv2 會尋找憑證路徑 server.crt。
```
kubectl create secret generic esp-ssl \
--from-file=server.crt=./server.crt --from-file=server.key=./server.key \
--from-file=tls.crt=./server.crt --from-file=tls.key=./server.key
```

將範例 API 和 ESPv2 部署至叢集

將範例 gRPC 服務部署至叢集，讓客戶端可使用該服務：

git clone 這個 repo，並開啟編輯 grpc-bookstore.yaml 部署資訊清單檔案。

將 SERVICE_NAME 替換為入口和 ESPv2 容器的 Endpoints 服務名稱。這與您在 api_config.yaml 檔案的 name 欄位中設定的名稱相同。

# Copyright 2016 Google Inc.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License

# Use this file to deploy the container for the grpc-bookstore sample
# and the container for the Extensible Service Proxy (ESP) to
# Google Kubernetes Engine (GKE).

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: esp-grpc-bookstore
  annotations:
    kubernetes.io/ingress.class: "gce"
    kubernetes.io/ingress.allow-http: "false"
spec:
  tls:
  - hosts:
    - SERVICE_NAME
    secretName: esp-ssl
  backend:
    serviceName: esp-grpc-bookstore
    servicePort: 443
---
apiVersion: cloud.google.com/v1
kind: BackendConfig
metadata:
  name: esp-grpc-bookstore
spec:
  healthCheck:
    type: HTTP2
    requestPath: /healthz
    port: 9000
---
apiVersion: v1
kind: Service
metadata:
  name: esp-grpc-bookstore
  annotations:
    service.alpha.kubernetes.io/app-protocols: '{"esp-grpc-bookstore":"HTTP2"}'
    cloud.google.com/neg: '{"ingress": true, "exposed_ports": {"443":{}}}'
    cloud.google.com/backend-config: '{"default": "esp-grpc-bookstore"}'
spec:
  ports:
  # Port that accepts gRPC and JSON/HTTP2 requests over TLS.
  - port: 443
    targetPort: 9000
    protocol: TCP
    name: esp-grpc-bookstore
  selector:
    app: esp-grpc-bookstore
  type: ClusterIP
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: esp-grpc-bookstore
spec:
  replicas: 1
  selector:
    matchLabels:
      app: esp-grpc-bookstore
  template:
    metadata:
      labels:
        app: esp-grpc-bookstore
    spec:
      volumes:
      - name: esp-ssl
        secret:
          secretName: esp-ssl
      containers:
      - name: esp
        image: gcr.io/endpoints-release/endpoints-runtime:2
        args: [
          "--listener_port=9000",
          "--service=SERVICE_NAME",
          "--rollout_strategy=managed",
          "--backend=grpc://127.0.0.1:8000",
          "--healthz=/healthz",
          "--ssl_server_cert_path=/etc/esp/ssl",
        ]
        ports:
          - containerPort: 9000
        volumeMounts:
        - mountPath: /etc/esp/ssl
          name:  esp-ssl
          readOnly: true
      - name: bookstore
        image: gcr.io/endpointsv2/python-grpc-bookstore-server:1
        ports:
          - containerPort: 8000

--rollout_strategy=managed 選項可將 ESPv2 設為使用最新部署的服務設定。指定此選項時，在您部署新服務設定後一分鐘內，ESPv2 會偵測到變更並自動開始使用新設定。建議您指定此選項，而非讓 ESPv2 使用特定的設定 ID。如要進一步瞭解 ESPv2 引數，請參閱 ESPv2 啟動選項。

例如：

    spec:
      containers:
      - name: esp
        image: gcr.io/endpoints-release/endpoints-runtime:2
        args: [
          "--listener_port=9000",
          "--service=bookstore.endpoints.example-project-12345.cloud.goog",
          "--rollout_strategy=managed",
          "--backend=grpc://127.0.0.1:8000"
        ]

如果您在同一個 Google Cloud 專案中執行大量 Endpoints (超過 100 個)，建議您為容器掛載服務設定，而非使用 --rollout_strategy=managed 標記從 Service Management API 提取服務設定。Service Management API 有預設配額。如果大量 Endpoints 使用 --rollout_strategy=managed，所有 Endpoints 都會輪詢最新的服務設定。車隊可能會超出配額，導致服務設定更新失敗。請按照下列步驟掛載服務設定。

下載服務設定 JSON 設定檔。

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"

使用 JSON 設定檔建立 Kubernetes 設定對應資源。

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

將設定資源對應圖掛載至容器，並使用「--service_config_path」標記指定設定檔的路徑。

例如：

  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

啟動服務：
```
kubectl create -f grpc-bookstore.yaml
```

如果您收到錯誤訊息，請參閱在 GKE 中疑難排解 Endpoints 一文。

取得服務的外部 IP 位址

您需要取得服務的外部 IP 位址，才能向範例 API 傳送要求。當您在容器中啟動服務後，系統可能需要幾分鐘的時間才能備妥外部 IP 位址。

查看外部 IP 位址：
```
kubectl get ingress
```
記下 EXTERNAL-IP 的值，並儲存在 SERVER_IP 環境變數中。系統會使用外部 IP 位址將要求傳送至範例 API。
```
export SERVER_IP=YOUR_EXTERNAL_IP
```

傳送要求至 API

如要傳送要求至範例 API，您可以使用以 Python 編寫的範例 gRPC 用戶端。

複製託管 gRPC 用戶端程式碼的 git 存放區：

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

變更您的工作目錄：

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

安裝依附元件：

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

為自行簽署的憑證建立根 CA

openssl x509 -in server.crt -out client.pem -outform PEM

傳送要求至範例 API：
```
python bookstore_client.py --host SERVER_IP --port 443 \
--servername bookstore.endpoints.MY_PROJECT_ID.cloud.goog --use_tls true --ca_path=client.pem
```
- 在「Endpoints」>「Services」(服務) 頁面中查看 API 的活動圖表。
  
  前往 Endpoints 服務頁面
  
  要求可能需要一些時間才能反映在圖表中。
- 在「Logs Explorer」(記錄檔探索工具) 頁面中查看您的 API 要求記錄。
  
  前往「Logs Explorer」頁面

如果您未取得成功的回應，請參閱排解回應錯誤一文。

您已在 Endpoints 中部署並測試了 API！

清除所用資源

如要避免系統向您的 Google Cloud 帳戶收取本教學課程中所用資源的相關費用，請刪除含有該項資源的專案，或者保留專案但刪除個別資源。

刪除 API：
```
gcloud endpoints services delete SERVICE_NAME
```
將 SERVICE_NAME 替換為您的 API 名稱。

刪除 GKE 叢集：

gcloud container clusters delete NAME --zone ZONE

後續步驟

瞭解如何針對 Cloud Endpoints 設定您自己的 gRPC API。
詳閱 GitHub 上的 Bookstore 範例。用戶端和伺服器都提供 Python 與 Java 版本。
您可以在 GitHub 取得下列程式語言的 getting-started-grpc 範例：
- Java
- Python
- Ruby
- Go
- Node.js

透過 ESPv2 使用 GKE 適用的 Endpoints 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

目標

費用

事前準備

設定 Endpoints

部署 Endpoints 設定

檢查必要服務

部署 API 後端

建立容器叢集

將 kubectl 驗證至容器叢集

檢查必要權限

新增必要的 IAM 角色：

端點服務設定

Cloud Trace

設定 SSL 金鑰和憑證

將範例 API 和 ESPv2 部署至叢集

取得服務的外部 IP 位址

傳送要求至 API

清除所用資源

後續步驟

透過 ESPv2 使用 GKE 適用的 Endpoints

將 `kubectl` 驗證至容器叢集