透過 ESPv2 開始使用 Kubernetes 適用的 Cloud Endpoints

下載範例程式碼

根據需要下載範例程式碼，在本教學課程中，您會部署預先建立的容器映像檔，因此無須從範例程式碼中建構容器。但是您可能會想要下載包含多種語言版本的範例程式碼，以協助您瞭解範例 API 的運作方式。

下載程式碼範例：

取得 Kubernetes 設定檔案

1. 複製包含本教學課程中使用的 yaml 檔案的存放區至本機電腦：

    git clone https://github.com/googlecloudplatform/endpoints-samples

   您也可以下載範例 ZIP 檔案，然後解壓縮。

2. 切換到包含設定檔的目錄：

    cd endpoints-samples/kubernetes

設定 Endpoints

範例程式碼中包含以 OpenAPI 規格 v2.0 為基礎的 OpenAPI 設定檔 openapi.yaml。如要設定 Endpoints：

1. 在範例程式碼目錄中開啟 openapi.yaml 設定檔。
   swagger: "2.0"
   info:
     description: "A simple Google Cloud Endpoints API example."
     title: "Endpoints Example"
     version: "1.0.0"
   host: "echo-api.endpoints.YOUR-PROJECT-ID.cloud.goog"

   注意事項：

   • 設定範例會顯示 host 欄位附近的文字行，您必須修改這些文字行。如要將 openapi.yaml 檔案部署至 Endpoints，您必須使用完整的 OpenAPI 文件。
   • 範例 openapi.yaml 檔案中包含用來設定驗證作業的區段，不過本教學課程無須執行這個步驟。您不需要設定含有 YOUR-SERVICE-ACCOUNT-EMAIL 和 YOUR-CLIENT-ID 的文字行。
   • OpenAPI 是一種各語言通用的規範。為求方便，相同的 openapi.yaml 檔案皆位於每個語言 GitHub 存放區的 getting-started 範例中。

2. 將 host 欄位中的文字替換為 Endpoints 服務名稱，格式如下所示：

   host: "echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog"

   將 YOUR_PROJECT_ID 替換為您的 Google Cloud 專案 ID。例如：

   host: "echo-api.endpoints.example-project-12345.cloud.goog"

請注意，echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog 是 Endpoints 服務名稱，而不是您用來將要求傳送至 API 的完整網域名稱 (FQDN)。

如要瞭解 Endpoints 所需的 OpenAPI 文件欄位，請參閱「設定 Endpoints」一文。

完成下列所有設定步驟後，您就能使用 IP 位址成功將要求傳送至範例 API。請參閱「為 Endpoints 設定 DNS」，瞭解如何將 echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog 設為 FQDN。

部署 Endpoints 設定

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

如何部署 Endpoints 設定：

1. 確認您位於 endpoints-samples/kubernetes 目錄。
2. 上傳設定並建立代管服務：

   gcloud endpoints services deploy openapi.yaml
   

接著，gcloud 指令會呼叫 Service Management API，並使用您在 openapi.yaml 檔案 host 欄位中指定的名稱建立代管服務。Service Management 會依據 openapi.yaml 檔案中的設定建立服務。變更 openapi.yaml 時，您必須重新部署檔案才能更新 Endpoints 服務。

Service Management 在建立和設定服務時，會輸出資訊至終端機。您可以放心忽略 openapi.yaml 檔案中路徑不需要 API 金鑰的警告。完成服務設定程序之後，Service Management 會顯示含有服務設定 ID 與服務名稱的訊息，類似於以下內容：

Service Configuration [2017-02-13r0] uploaded for service [echo-api.endpoints.example-project-12345.cloud.goog]

在上方的範例中，2017-02-13r0 是服務設定 ID，echo-api.endpoints.example-project-12345.cloud.goog 則為 Endpoints 服務。服務設定 ID 是由一個日期戳記和一個修訂版本編號所組成。如果您在同一天再次部署 openapi.yaml 檔案，服務設定 ID 中的修訂版本編號就會遞增。您可以在控制台的「Endpoints」 >「Services」(服務) 頁面中查看 Endpoints 服務設定。 Google Cloud

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

檢查必要服務

在大多數情況下，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 服務。

為服務建立憑證

為了妥善管理您的 API，ESP 和 ESPv2 都需要使用服務基礎架構中的服務。ESP 和 ESPv2 必須使用存取憑證才能呼叫這些服務。當您將 ESP 或 ESPv2 部署至 GKE、Compute Engine 或 App Engine 彈性環境等 Google Cloud 環境時，ESP 和 ESPv2 會透過Google Cloud 中繼資料服務為您取得存取權杖。

如果您要將 ESP 或 ESPv2 部署至非Google Cloud 環境 (例如本機電腦、內部部署的 Kubernetes 叢集，或是其他雲端服務平台)，則必須提供含有私密金鑰的服務帳戶 JSON 檔案。ESP 和 ESPv2 會使用服務帳戶產生存取權杖，以呼叫管理 API 所需的服務。

您可以使用 Google Cloud 控制台或 Google Cloud CLI 建立服務帳戶和私密金鑰檔案：

新增必要的 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 是已附加的服務帳戶。詳情請參閱「 什麼是角色和權限？」。

如要進一步瞭解指令，請參閱 gcloud iam service-accounts。

部署 API 後端

您目前已將 OpenAPI 文件部署至 Service Management，但尚未部署為 API 後端提供服務的程式碼。本節會逐步引導您針對 API 範例和 ESPv2，將預先建構的容器部署至 Kubernetes。

檢查必要權限

將必要權限授予與叢集相關聯的服務帳戶：

gcloud endpoints services add-iam-policy-binding SERVICE_NAME \
    --member "serviceAccount:SERVICE_ACCOUNT" \
    --role roles/servicemanagement.serviceController

詳情請參閱「 什麼是角色和權限？」。

為 ESPv2 提供服務憑證

在容器內部執行的 ESPv2 必須能存取儲存在本機 service-account-creds.json 檔案中的憑證。如果要讓 ESPv2 能存取憑證，您可以建立 Kubernetes 密鑰，並將 Kubernetes 密鑰掛接成 Kubernetes 磁碟區。

如何建立 Kubernetes 密鑰並掛接磁碟區：

1. 如果 JSON 檔案已經下載至不同目錄，請記得將 JSON 檔案重命名為 service-account-creds.json，並將其複製到endpoints-samples/kubernetes。這樣一來，名稱就會與 echo.yaml 部署資訊清單檔案中指定的選項相符。
2. 確認您位於 endpoints-samples/kubernetes 目錄。

3. 使用下列指令，透過服務帳戶憑證建立 Kubernetes 密鑰：

   kubectl create secret generic service-account-creds \
      --from-file=service-account-creds.json
   

   成功之後，系統會顯示以下訊息：

   secret "service-account-creds" created

您用來將 API 和 ESPv2 部署至 Kubernetes 的部署資訊清單檔案，已包含密鑰磁碟區，如下列檔案的兩個區段所示：

volumes:
  - name: service-account-creds
    secret:
      secretName: service-account-creds

volumeMounts:
  - mountPath: /etc/esp/creds
    name: service-account-creds
    readOnly: true

設定服務名稱並啟動服務

ESPv2 必須知道您的服務名稱，才能使用 gcloud endpoints services deploy 指令找出先前部署的設定。

如何設定服務名稱及啟動服務：

1. 開啟部署資訊清單檔案 echo.yaml，並將 ESPv2 啟動選項中的 SERVICE_NAME 替換成您的服務名稱。這與您在 OpenAPI 文件的 host 欄位中設定的名稱相同。例如：

   "--service=echo-api.endpoints.example-project-12345.cloud.goog"

   containers:
   - name: esp
     image: gcr.io/endpoints-release/endpoints-runtime:2
     args: [
       "--listener_port=8080",
       "--backend=127.0.0.1:8081",
       "--service=SERVICE_NAME",
       "--rollout_strategy=managed",
       "--non_gcp",
       "--service_account_key=/etc/esp/creds/service-account-creds.json"
     ]
     ports:
       - containerPort: 8080
     volumeMounts:
       - mountPath: /etc/esp/creds
         name: service-account-creds
         readOnly: true
   - name: echo
     image: gcr.io/endpoints-release/echo:latest
     ports:
       - containerPort: 8081
   

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

2. 使用下列指令啟動服務，以在 Kubernetes 上部署 Endpoints 服務：

   kubectl create -f echo.yaml

   如果您看到類似以下內容的錯誤訊息：

   The connection to the server localhost:8080 was refused - did you specify the right host or port?

   這表示您未正確設定 kubectl，詳情請參閱「設定 kubectl」一節。詳情請參閱「在 Kubernetes 上部署 Endpoints」。

取得服務的外部 IP 位址

如果您使用 Minikube，請直接前往「使用 IP 位址傳送要求」一節。在容器中啟動服務之後，系統可能需要幾分鐘的時間才能備妥外部 IP 位址。

如何查看服務的外部 IP 位址：

1. 請執行下列指令：

   kubectl get service

2. 記下 EXTERNAL-IP 的值，傳送要求至範例 API 時，將會使用這個 IP 位址。

使用 IP 位址傳送要求

在容器叢集中執行範例 API 之後，您就能向 API 傳送要求。

建立 API 金鑰並設定環境變數

範例程式碼需要 API 金鑰。為了簡化要求，請設定 API 金鑰的環境變數。

1. 在您用於 API 的 Google Cloud 專案中，在 API 憑證頁面上建立 API 金鑰。如果您想在不同的 Google Cloud 專案中建立 API 金鑰，請參閱在 Google Cloud 專案中啟用 API。

   前往憑證頁面

2. 按一下 [Create credentials] (建立憑證)，然後選取 [API key] (API 金鑰)。
3. 將金鑰複製到剪貼簿。
4. 按一下 [Close] (關閉)。
5. 在本機電腦中貼上 API 金鑰，以便指派給環境變數：
   • 在 Linux 或 macOS 中：export ENDPOINTS_KEY=AIza...
   • 在 Windows PowerShell 中：$Env:ENDPOINTS_KEY="AIza..."

傳送要求至 minikube

下列指令使用您前面所設定的 ENDPOINTS_KEY 環境變數。

NODE_PORT=`kubectl get service esp-echo --output='jsonpath={.spec.ports[0].nodePort}'`
MINIKUBE_IP=`minikube ip`
curl --request POST \
    --header "content-type:application/json" \
    --data '{"message":"hello world"}' \
    ${MINIKUBE_IP}:${NODE_PORT}/echo?key=${ENDPOINTS_KEY}

$Env:NODE_PORT=$(kubectl get service esp-echo --output='jsonpath={.spec.ports[0].nodePort}')
$Env:MINIKUBE_IP=$(minikube ip)
(Invoke-WebRequest -Method POST -Body '{"message": "hello world"}' `
    -Headers @{"content-type"="application/json"} `
    -URI "http://$Env:MINIKUBE_IP:$Env:NODE_PORT/echo?key=$Env:ENDPOINTS_KEY").Content

傳送要求至其他 Kubernetes 叢集

curl --request POST \
   --header "content-type:application/json" \
   --data '{"message":"hello world"}' \
   "http://IP_ADDRESS:80/echo?key=${ENDPOINTS_KEY}"

(Invoke-WebRequest -Method POST -Body '{"message": "hello world"}' `
    -Headers @{"content-type"="application/json"} `
    -URI "http://IP_ADDRESS:80/echo?key=$Env:ENDPOINTS_KEY").Content

API 會回應您傳送的訊息，並傳回以下內容：

{
  "message": "hello world"
}

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

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

追蹤 API 活動

如要追蹤 API 活動，請執行下列步驟：

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

   前往 Endpoints 服務頁面

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

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

   前往「Logs Explorer」頁面

為 Endpoints 設定 DNS

API 的 Endpoints 服務名稱位於 .endpoints.YOUR_PROJECT_ID.cloud.goog 網域，因此您只需要略為調整 openapi.yaml 檔案的設定，即可將該網域當做完整的網域名稱 (FQDN)。這樣一來，您就能使用 echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog (而非 IP 位址) 將要求傳送至範例 API。

如何設定 Endpoints DNS：

1. 開啟 OpenAPI 設定檔 openapi.yaml，並在檔案最上層新增 x-google-endpoints 屬性 (請勿使用縮排或巢狀結構)，如以下程式碼片段所示：

   host: "echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog"
   x-google-endpoints:
   - name: "echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog"
     target: "IP_ADDRESS"

2. 在 name 屬性中，將 YOUR_PROJECT_ID 替換為您的專案 ID。
3. 在 target 屬性中，將 IP_ADDRESS 替換為您向範例 API 傳送要求時使用的 IP 位址。
4. 將更新的 OpenAPI 設定檔部署至 Service Management：

   gcloud endpoints services deploy openapi.yaml
   

例如，假設 openapi.yaml 檔案的設定如下：

host: "echo-api.endpoints.example-project-12345.cloud.goog"
x-google-endpoints:
- name: "echo-api.endpoints.example-project-12345.cloud.goog"
  target: "192.0.2.1"

您使用前述的 gcloud 指令部署 openapi.yaml 檔案時，Service Management 會建立 DNS A 記錄 echo-api.endpoints.my-project-id.cloud.goog，這個記錄會解析為目標 IP 位址 192.0.2.1。新的 DNS 設定可能需要幾分鐘才會生效。

設定 SSL

如要進一步瞭解如何設定 DNS 和安全資料傳輸層 (SSL)，請參閱「啟用 Endpoints 的安全資料傳輸層 (SSL)」一文。

傳送要求至 FQDN

• 在 Linux 或 macOS 中：

  curl --request POST \
      --header "content-type:application/json" \
      --data '{"message":"hello world"}' \
      "http://echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog:80/echo?key=${ENDPOINTS_KEY}"

• 在 Windows PowerShell 中：

  (Invoke-WebRequest -Method POST -Body '{"message": "hello world"}' -Headers @{"content-type"="application/json"} -URI "http://echo-api.endpoints.[YOUR_PROJECT_ID].cloud.goog:80/echo?key=$Env:ENDPOINTS_KEY").Content