透過 ESPv2 在代管執行個體群組中使用 Cloud Endpoints gRPC 的入門指南

OpenAPI   |  gRPC

本教學課程說明如何在受管理執行個體群組中，使用可擴充服務 Proxy V2 (ESPv2) 部署簡單的 gRPC 服務範例。

本教學課程使用 Python 版本的 bookstore-grpc 範例。如需其他語言的 gRPC 範例，請參閱「後續步驟」一節。

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

設定 Endpoints

從 GitHub 複製 bookstore-grpc 範例存放區。

如要設定 Endpoints：

1. 從您的服務 .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 的目錄。

2. 建立 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 建立代管服務。

1. 確認您所在的目錄有 api_descriptor.pb 和 api_config.yaml 檔案。
2. 確認 gcloud 指令列工具目前使用的預設專案，就是您要部署 Endpoints 設定的 Google Cloud 專案。請利用下列指令傳回的專案 ID 進行驗證，以確保系統沒有將服務建立在錯誤的專案中。

   gcloud config list project
   

   如要變更預設的專案，請執行下列指令：

   gcloud config set project YOUR_PROJECT_ID
   

3. 使用 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」頁面。「服務名稱」欄下方會顯示可能的 ENDPOINTS_SERVICE_NAME 清單。

• 如果是 OpenAPI，ENDPOINTS_SERVICE_NAME 是您在 OpenAPI 規格的 host 欄位中指定的內容。如果是 gRPC，ENDPOINTS_SERVICE_NAME 是您在 gRPC Endpoints 設定的 name 欄位中指定的內容。

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

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

部署 API 後端

到目前為止，您已經將 API 設定部署到 Service Management，但還沒有部署會提供 API 後端的程式碼。本節將逐步引導您在受管理執行個體群組上設定 Docker，並在 Docker 容器中執行 API 後端程式碼和 ESPv2。

建立執行個體範本

建立範本，以便用來建立一組 VM 執行個體。每個利用範本建立的執行個體，都會啟動 ESPv2 和後端應用程式伺服器。

1. 前往 Google Cloud 控制台的「Instance Templates」(執行個體範本) 頁面。

   前往「Instance templates」(執行個體範本) 頁面

2. 點選「建立執行個體範本」。

3. 在「Name」(名稱) 下方輸入 load-balancing-espv2-template。

4. 在「Machine configuration」(機器設定) 下，將「Machine type」(機器類型) 設為 e2-micro。

5. 在「Boot disk」(開機磁碟) 下，將「Image」(映像檔) 設為 Container Optimized OS stable version。

6. 在「Firewall」(防火牆) 下，選取 [Allow HTTP traffic] (允許 HTTP 流量)。

7. 按一下 [Management, security, disks, networking, sole tenancy] (管理、安全性、磁碟、網路、單獨租用) 即可顯示進階設定。

8. 按一下 [Management] (管理) 分頁標籤。在「Automation」(自動) 下方輸入以下開機指令碼：請記得更新「ENDPOINTS_SERVICE_NAME」。

   sudo docker network create --driver bridge esp_net
   sudo docker run \
     --detach \
     --name=bookstore \
     --net=esp_net \
     gcr.io/endpointsv2/python-grpc-bookstore-server:1
   sudo docker run \
     --detach \
     --name=esp \
     --publish=80:9000 \
     --net=esp_net \
     gcr.io/endpoints-release/endpoints-runtime:2 \
     --service=ENDPOINTS_SERVICE_NAME \
     --rollout_strategy=managed \
     --listener_port=9000 \
     --healthz=/healthz \
     --backend=grpc://bookstore:8000
   

   執行個體啟動時，指令碼會取得、安裝並啟動 Echo 應用程式伺服器和 ESPv2 Proxy 伺服器。

9. 點選「建立」。

請等候範本建立完成後再繼續操作。

建立地區代管執行個體群組

如要執行應用程式，請使用執行個體範本建立地區代管執行個體群組：

1. 前往 Google Cloud 控制台的「Instance groups」(執行個體群組) 頁面。

   前往執行個體群組

2. 點選「建立執行個體群組」。

3. 在「Name」(名稱) 下方輸入 load-balancing-espv2-group。

4. 在「Location」(位置) 下，選取 [Multiple zones] (多區域)。

   實用提示：Compute Engine 建議您在多個區域中發布應用程式，以確保即使發生極端情況 (例如區域服務中斷)，應用程式仍可供使用。

5. 在「Region」(地區) 下，選取 [us-central1]。

6. 按一下 [Configure zones] (設定區域) 下拉式選單，即可查看「Zones」(區域)。選取下列區域：

   • us-central1-b
   • us-central1-c
   • us-central1-f

7. 在「Instance template」(執行個體範本) 下，選取 load-balancing-espv2-template。

8. 在「Autoscaling」(自動調度資源) 下方，選取「Don't autoscale」(不要自動調整資源配置)。

9. 將「Number of instances」(執行個體數量) 設為 3。

   實用秘訣：建立地區代管執行個體群組時，Compute Engine 建議佈建足夠的執行個體，如此一來，如果任何一個區域內的所有執行個體同時無法使用，其餘執行個體仍能達到所需的執行個體數量下限。 不過，如果佈建的執行個體數量超過實際所需，可能會產生額外費用。詳情請參閱選取執行個體群組大小以確保可用性的相關說明。

10. 在「Instance redistribution」(執行個體重新分配) 下，選取 [On] (啟用)。

11. 在「Autohealing」(自動修復) 與「Health check」(健康狀態檢查) 下，選取 [No health check] (不執行健康狀態檢查)。

12. 按一下 [Create] (建立)，系統就會將您重新導向至「Instance groups」(執行個體群組) 頁面。

    注意：您可能需要稍候幾分鐘，等待群組中的所有執行個體都在執行並可顯示網頁應用程式。

建立負載平衡器

本節說明建立區域負載平衡器的所需步驟，藉此將 TCP 流量導向執行個體群組。

1. 前往 Google Cloud 控制台的「Create a load balancer」(建立負載平衡器) 頁面。

   前往「建立負載平衡器」

2. 按一下「TCP 負載平衡」下方的「開始設定」。

3. 在「Internet facing or internal only」(連結網際網路或僅限內部) 下方，選取「From Internet to my VMs」(從網際網路到我的 VM)。

4. 在「Multiple regions or single region」(多地區或單一地區) 下方，選取「Single region only」(僅限單一地區)。

5. 在「Backend type」(後端類型) 下方，選取「Backend Service」(後端服務)。

6. 按一下「繼續」。

7. 在「Name」(名稱) 下方輸入 espv2-load-balancer。

8. 在「Backend configuration」(後端設定) 下方，選取「us-central1」區域。

9. 選取執行個體群組 load-balancing-espv2-group。

10. 在「健康狀態檢查」下方，建立新的健康狀態檢查。

    • 在名稱下方輸入 espv2-load-balancer-check。
    • 確認「通訊協定」為「TCP」，「通訊埠」為「80」。

11. 在「前端設定」下方，輸入通訊埠編號 80。

12. 在「檢查並完成」下方，確認

    • 「Instance group」(執行個體群組) 為 load-balancing-espv2-group。
    • 「區域」為 us-central1。
    • 「Protocol」(通訊協定) 為 TCP。
    • 「IP:Port」為 EPHEMERAL:80。

13. 建立負載平衡器後，請在「Load Balancer」頁面中找出 IP 位址。

    前往「Load Balancer」(負載平衡器)

傳送要求至 API

如果您要從執行 Docker 容器的相同執行個體傳送要求，可以使用 localhost 取代 SERVER_IP，否則請使用執行個體的外部 IP 取代 SERVER_IP。

您可以執行以下指令來取得外部 IP 位址：

gcloud compute instances list

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

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

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

2. 變更您的工作目錄：

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

3. 安裝依附元件：

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

4. 傳送要求至範例 API：

   python bookstore_client.py --host SERVER_IP --port 80
   

   • 在「Endpoints」>「Services」(服務) 頁面中查看 API 的活動圖表。
     

     前往 Endpoints 服務頁面

     要求可能需要一些時間才能反映在圖表中。

   • 在「Logs Explorer」(記錄檔探索工具) 頁面中查看您的 API 要求記錄。
     

     前往「Logs Explorer」頁面

如果您沒有收到成功的回應，請參閱排解回應錯誤一文。

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

注意事項：如想告訴我們您對這個教學課程的想法，歡迎在本頁面底端提供意見回饋。您的意見回饋可協助我們改善教學課程。
如果您在過程中看見錯誤訊息，不妨加入 google-cloud-endpoints Google 群組，告知我們何處發生問題。這個網上論壇可接收來自其他 Endpoints 使用者的回應，以及負責管理論壇 Google 工程師的回覆。