部署 API 後端

App Engine

只要額外透過簡單的設定步驟 (如下列步驟所述) 就可以部署您的 API，進而將 API 交由 Endpoints 代管，如同將任何應用程式部署到 App Engine 彈性環境。請按照 App Engine 說明文件進行下列操作：

• 整理您的設定檔。
• 建立 app.yaml 設定檔
• 如果您的應用程式是以微服務為基礎，請參閱部署多個服務應用程式說明文件以瞭解針對各項服務設定 app.yaml 檔案的相關資訊。

您可以使用 gcloud app deploy 指令將您的 API 部署到 App Engine。這個指令會使用 Container Builder 服務自動建構容器映像檔，然後將映像檔部署到 App Engine 彈性環境。

部署之前的準備：

• Google Cloud 專案的擁有者必須先建立 App Engine 應用程式。
• 確認您的使用者帳戶擁有必要權限。

Compute Engine

如要讓 Endpoints 管理您的 API，您必須為您的 API 安裝並設定 ESP 以及後端伺服器程式碼。您必須在 Compute Engine VM 執行個體上安裝 Docker，才能執行 Artifact Registry 中免費提供的 ESP Docker 映像檔。

部署之前的準備：

下列內容會從較高的層次概要說明您在 Compute Engine 部署 API 和 ESP 之前必須採取的步驟。一般來說，您需要進行在 Compute Engine 上執行後端伺服器程式碼時通常需要的所有步驟。

1. 建立、設定和啟動您的 VM 執行個體。請參閱 Compute Engine 說明文件。
2. 在您的 VM 執行個體上安裝 Docker Enterprise Edition (EE) 或 Docker Community Edition (CE)。請參閱安裝 Docker 說明。
3. 為您的後端伺服器程式碼建立 Docker 容器。請參閱 Cloud Build 說明文件。
4. 將容器推送至 Artifact Registry 或其他登錄檔。
5. 確認您能夠完成下列操作：
   • 連線至 VM 執行個體。
   • 執行 Docker 映像檔以在 VM 執行個體上啟動您的後端伺服器。詳情請參閱 Docker 執行參考資料。
   • 傳送要求至您的 API。

GKE

當您在 Google Cloud 主控台中建立叢集時，根據預設，授予叢集服務帳戶的 OAuth 範圍包含 Endpoints 要求的範圍：

• Service Control：已啟用
• Service Management：唯讀

使用 gcloud container clusters create 指令或使用第三方設定檔建立叢集時，請確認已指定下列範圍：

• "https://www.googleapis.com/auth/servicecontrol"
• "https://www.googleapis.com/auth/service.management.readonly"

詳情請參閱何謂存取權範圍？

部署之前的準備：

只要在您的部署資訊清單檔案中加入一個小區段，就可以在您的容器叢集和容器化應用程式上執行 ESP Docker 映像檔。下列內容會從較高的層次概要說明您在 GKE 部署 API 和 ESP 之前必須採取的步驟。一般來說，您需要進行在 GKE 上執行後端伺服器程式碼時通常需要的所有步驟。

1. 將您的容器化應用程式部署至容器叢集。GKE 說明文件中所述的一般步驟包括：
   1. 將您的應用程式封裝至 Docker 映像檔中。
   2. 將這個映像檔上傳至登錄檔。
   3. 建立容器叢集。
   4. 將您的應用程式部署到叢集。
   5. 將您的應用程式公開發布到網際網路。
2. 確認您能夠完成下列操作：
   • 啟動 API 的伺服器。
   • 傳送要求至您的 API。

App Engine

如何將 API 和 ESP 部署至 App Engine：

1. 取得您 API 的服務名稱。這是您在 OpenAPI 文件的 host 欄位中指定的名稱。
2. 編輯 app.yaml，並新增名為 endpoints_api_service 的區段，其中包含了服務名稱。您可以從教學課程使用 app.yaml 檔案中來做為模型：
   Java

   endpoints_api_service:
     # The following values are to be replaced by information from the output of
     # 'gcloud endpoints services deploy openapi-appengine.yaml' command.
     name: ENDPOINTS-SERVICE-NAME
     rollout_strategy: managed

   Python

   endpoints_api_service:
     # The following values are to be replaced by information from the output of
     # 'gcloud endpoints services deploy openapi-appengine.yaml' command.
     name: ENDPOINTS-SERVICE-NAME
     rollout_strategy: managed

   Go

   endpoints_api_service:
     # The following values are to be replaced by information from the output of
     # 'gcloud endpoints services deploy openapi-appengine.yaml' command.
     name: ENDPOINTS-SERVICE-NAME
     rollout_strategy: managed

   PHP

   endpoints_api_service:
     # The following values are to be replaced by information from the output of
     # 'gcloud endpoints services deploy openapi-appengine.yaml' command. If you have
     # previously run the deploy command, you can list your existing configuration
     # ids using the 'configs list' command as follows:
     #
     #     gcloud endpoints configs list --service=YOUR-PROJECT-ID.appspot.com
     #
     name: ENDPOINTS-SERVICE-NAME
     rollout_strategy: managed

   Ruby

   endpoints_api_service:
     # The following values are to be replaced by information from the output of
     # 'gcloud endpoints services deploy openapi-appengine.yaml' command.
     name: ENDPOINTS-SERVICE-NAME
     rollout_strategy: managed

   NodeJS

   endpoints_api_service:
     # The following values are to be replaced by information from the output of
     # 'gcloud endpoints services deploy openapi-appengine.yaml' command.
     name: ENDPOINTS-SERVICE-NAME
     rollout_strategy: managed

   將您的 API 服務名稱替換為 ENDPOINTS-SERVICE-NAME。 例如：

   endpoints_api_service:
     name: example-project-12345.appspot.com
     rollout_strategy: managed
     

   rollout_strategy: managed 選項可將 ESP 設為使用最新部署的服務設定。指定此選項時，在您部署新服務設定後 5 分鐘內，ESP 會偵測到變更並自動開始使用新設定。建議您指定此選項而非讓 ESP 使用特定的設定 ID。

   如果您的應用程式以微服務為基礎，則必須在每個 app.yaml 檔案中加入 endpoints_api_service 區段。

3. 儲存 app.yaml 檔案 (或多個檔案)。
4. 將後端程式碼和 ESP 部署到 App Engine：

   gcloud app deploy

因為您已將 endpoints_api_service 區段加入 app.yaml 檔案，因此 gcloud app deploy 指令會設定獨立容器中的 ESP，並部署至您的 App Engine 彈性環境。所有的要求流量都會透過 ESP 轉送，且 ESP 代理往返 (執行後端伺服器程式碼的) 容器的要求與回應。

如果您必須將 ESP 設定為使用特定的設定 ID：

1. 在您 app.yaml 檔案的 endpoints_api_service 區段中新增 config_id 欄位，並將這個欄位設為特定的設定 ID。
2. 移除 rollout_strategy: managed 或將 rollout_strategy 設定為 fixed。fixed 選項會將 ESP 設定為使用您在 config_id 中指定的服務設定。
3. 重新部署 API 和 ESP：gcloud app deploy

建議您不要長時間將 ESP 設定為使用特定的設定 ID，否則在您部署更新的服務設定後，必須重新啟動 ESP 才能使用新的設定。

如何移除特定的設定 ID：

1. 從 app.yaml 檔案中移除 config_id 選項。
2. 新增 rollout_strategy: managed 選項。
3. 發出 gcloud app deploy 指令

使用 rollout_strategy: managed 選項時，請勿在 app.yaml 檔案中加入 config_id: YOUR_SERVICE_CONFIG_ID。如果那樣做，gcloud app deploy 就會失敗並顯示下列錯誤：

config_id is forbidden when rollout_strategy is set to "managed".

當您第一次將 API 部署到 App Engine 彈性環境時，可能會因為系統設定虛擬機器 (VM) 和其他基礎架構而發生延遲。詳情請參閱 App Engine 說明文件中的確保成功部署。

Compute Engine

如何利用 Docker 將您的 API 和 ESP 部署到 Compute Engine：

1. 連線到您的 VM 執行個體。將您的 VM 執行個體名稱替換為 INSTANCE_NAME。

   gcloud compute ssh INSTANCE_NAME

2. 建立自己的容器網路，名稱為 esp_net：

   sudo docker network create --driver bridge esp_net

3. 執行後端伺服器程式碼的映像檔執行個體，並連線到 esp_net 容器網路：

   sudo docker run \
       --detach \
       --name=YOUR_API_CONTAINER_NAME \
       --net=esp_net \
       gcr.io/YOUR_PROJECT_ID/YOUR_IMAGE:1.0

   • 將您的容器名稱替換為 YOUR_API_CONTAINER_NAME。
   • 將 YOUR_PROJECT_ID 替換為您在推送映像檔時使用的 Google Cloud 專案 ID。
   • 將您的映像檔名稱替換為 YOUR_IMAGE。
4. 取得您 API 的服務名稱。這是您在 OpenAPI 文件的 host 欄位中指定的名稱。
5. 執行 ESP Docker 映像檔的執行個體：

   sudo docker run \
       --name=esp \
       --detach \
       --publish=80:8080 \
       --net=esp_net \
       gcr.io/endpoints-release/endpoints-runtime:1 \
       --service=SERVICE_NAME \
       --rollout_strategy=managed \
       --backend=YOUR_API_CONTAINER_NAME:8080

   • 將 SERVICE_NAME 改為您的服務名稱。
   • 將您的 API 容器名稱替換為 YOUR_API_CONTAINER_NAME。

   --rollout_strategy=managed 選項可將 ESP 設為使用最新部署的服務設定。指定此選項時，在您部署新服務設定後 5 分鐘內，ESP 會偵測到變更並自動開始使用新設定。建議您指定此選項而非讓 ESP 使用特定的設定 ID。

如果您必須將 ESP 設定為使用特定的設定 ID：

1. 加上 --version 選項並設定為特定的設定 ID。
2. 移除 --rollout_strategy=managed 選項或將 --rollout_strategy 設定為 fixed。fixed 選項會將 ESP 設定為使用您在 --version 中指定的服務設定。
3. 再次發出 docker run 指令。

如果您同時指定 --rollout_strategy=managed 和 --version 選項，則 ESP 一開始會使用您在 --version 中指定的設定，但隨後會在代管模式下執行並取得最新的設定。

建議您不要長時間將 ESP 設定為使用特定的設定 ID，否則在您部署更新的服務設定後，必須重新啟動 ESP 才能使用新的設定。

如何移除特定的設定 ID：

1. 在 docker run 的 ESP 標記中，移除 --version 選項。
2. 新增 --rollout_strategy=managed 選項。
3. 發出 docker run 指令以重新啟動 ESP。

如需啟動 ESP 時可指定的完整選項清單，請參閱 ESP 啟動選項。

GKE

如何將 ESP 部署到 GKE：

1. 取得 API 服務名稱，這是您在 OpenAPI 文件 host 欄位中指定的名稱。
2. 開啟您的部署資訊清單檔案 (稱為 deployment.yaml 檔案)，並將下列內容加入容器區段：

   containers:
   - name: esp
     image: gcr.io/endpoints-release/endpoints-runtime:1
     args: [
       "--http_port=8081",
       "--backend=127.0.0.1:8080",
       "--service=SERVICE_NAME",
       "--rollout_strategy=managed"
     ]

   使用您的 API 服務名稱取代 SERVICE_NAME。

   --rollout_strategy=managed" 選項可將 ESP 設為使用最新部署的服務設定。指定此選項時，在您部署新服務設定後 5 分鐘內，ESP 會偵測到變更並自動開始使用新設定。建議您指定此選項而非讓 ESP 使用特定的設定 ID。

3. 使用 kubectl create 指令啟動 Kubernetes 服務：

   kubectl create -f deployment.yaml

如果您必須將 ESP 設定為使用特定的設定 ID：

1. 在您的部署資訊清單檔案中，新增 --version 選項並將其設定為特定的設定 ID。
2. 移除 --rollout_strategy=managed 或將 --rollout_strategy 設定為 fixed。fixed 選項將 ESP 設定為使用您在 --version 中指定的服務設定。
3. 啟動 Kubernetes 服務：kubectl create -f deployment.yaml

如果您同時指定 --rollout_strategy=managed 和 --version 選項，則 ESP 一開始會使用您在 --version 中指定的設定，但隨後會在代管模式下執行並取得最新的設定。

建議您不要長時間將 ESP 設定為使用特定的設定 ID，否則在您部署更新的服務設定後，必須重新啟動 ESP 才能使用新的設定。

如何移除特定的設定 ID：

1. 在您的部署資訊清單檔案中，移除 --version 選項。
2. 新增 --rollout_strategy=managed。
3. 啟動 Kubernetes 服務：kubectl create -f deployment.yaml

如需啟動 ESP 時可指定的完整選項清單，請參閱 ESP 啟動選項。