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

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

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

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

目標

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

  1. 設定 Google Cloud 專案，並下載必要軟體。請參閱「事前準備」。
  2. 從 bookstore-grpc 範例複製並設定檔案。請參閱「設定 Endpoints」。
  3. 部署 Endpoints 設定以建立 Endpoints 服務。請參閱部署 Endpoints 設定一節。
  4. 在代管執行個體群組後端部署 API 和 ESPv2。 請參閱部署 API 後端一節。
  5. 傳送要求至 API，請參閱傳送要求至 API 一節。
  6. 避免系統向您的 Google Cloud 帳戶收取相關費用。請參閱清除所用資源一節。

費用

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

如要根據預測用量估算費用，請使用 Pricing Calculator。

初次使用 Google Cloud 的使用者可能符合免費試用資格。

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

事前準備

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

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

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

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

    Go to project selector

  5. Verify that billing is enabled for your Google Cloud project.

  6. 記下專案 ID，後續步驟將會用到。
  7. 安裝並初始化 Google Cloud CLI。
  8. 更新 gcloud CLI 並安裝 Endpoints 元件：
    gcloud components update
  9. 確認 Google Cloud CLI (gcloud) 已取得授權，可存取您在 Google Cloud上的資料與服務：
    gcloud auth login
     在開啟的新瀏覽器分頁中選取一個帳戶。
  10. 將預設專案設為您的專案 ID。
    gcloud config set project YOUR_PROJECT_ID

    將 YOUR_PROJECT_ID 替換為專案 ID。如果您有其他 Google Cloud 專案，並想使用 gcloud 加以管理，請參閱「管理 gcloud CLI 設定」。

  11. 按照 gRPC Python 快速入門導覽課程中的步驟安裝 gRPC 和 gRPC 工具。

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

設定 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] (多區域)。

  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。

  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 中部署並測試了 API！

清除所用資源

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

  1. 確認 gcloud CLI (gcloud) 已取得授權，可存取您在 Google Cloud上的資料與服務：

    gcloud auth login

  2. 輸入下列指令，以顯示 Google Cloud專案的專案 ID：

    gcloud projects list

  3. 使用在上一個步驟中顯示的專案 ID，將預設Google Cloud 專案設為您的應用程式所屬專案：

    gcloud config set project [YOUR_PROJECT_ID]

  4. 取得 Google Cloud 專案中所有代管服務的名稱：

    gcloud endpoints services list

  5. 從 Service Management 中刪除該服務。將 SERVICE_NAME 替換為您要移除的服務名稱。

    gcloud endpoints services delete SERVICE_NAME

    執行 gcloud endpoints services delete 並不會立即刪除代管服務。Service Management 會先將該代管服務停用 30 天，在這段期間內您可以視需要將其還原。30 天後，Service Management 就會永久刪除該代管服務。

  6. 前往「Load Balancer」(負載平衡器) 頁面。

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

    刪除負載平衡器 espv2-load-balancer 和健康檢查 espv2-load-balancer-check。

  7. 前往「Instance Groups」(執行個體群組) 頁面。

    前往「Instance Groups」(執行個體群組)

    刪除「load-balancing-espv2-group」

  8. 前往「執行個體範本」頁面。

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

    刪除 load-balancing-espv2-template。

後續步驟