Apigee 和 Hybrid 適用的原生 Envoy 範例

本頁適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

本例說明如何在本機安裝及執行 Envoy，而非在 Kubernetes 叢集中，以便使用 Apigee Adapter for Envoy。您可以按照本文件中的範例，安裝 Apigee 和 Apigee Hybrid。

API Proxy 呼叫會透過 Envoy 以原生應用程式執行。Apigee 提供 API 管理服務，例如建立 API 產品和開發人員應用程式。Envoy 會透過轉接程式的遠端服務，與 Apigee 管理層通訊。轉換器也會將數據分析資料推送至 Apigee，您可以在 Apigee Analytics 中查看這些資料。

必要條件

事前準備：

檢查 gcloud 設定

  1. 請確認 gcloud 設定已設為與 Apigee 機構相關聯的 Google Cloud 專案。

    如要列出目前的設定，另請參閱 gcloud config。

    gcloud config list

    如有需要，請使用下列指令設定正確的 Google Cloud 專案 ID：

    gcloud config set project project-id
  2. 您必須使用 Google Cloud SDK (gcloud) 驗證 Google Cloud 專案。另請參閱 gcloud auth login。
    gcloud auth login

設定 Apigee

在這個步驟中，您將使用遠端服務 CLI 為 Envoy 資產佈建 Apigee 轉接器。這項佈建指令會部署用於 Apigee 轉接程式操作的 API Proxy，在 Apigee 上設定憑證，並產生遠端服務會用來從您的系統安全連線至 Apigee 的憑證。

  1. 前往 $CLI_HOME 目錄：
    cd $CLI_HOME
  2. (選用) 根據預設，轉接器會在 Google Cloud 專案中尋找預設服務帳戶憑證，以便取得將數據分析資料傳送至 Apigee 的權限。如果您不想使用預設服務帳戶憑證，可以建立服務帳戶，並在佈建指令中參照該帳戶的金鑰。服務帳戶必須具備 apigee.analyticsAgent 角色。如需詳細操作說明，請參閱「建立及管理服務帳戶」。
  3. 建立下列環境變數。這些變數會用做佈建指令碼的參數：
    export ORG=organization_name
export ENV=environment_name
export RUNTIME=host_alias_url
export NAMESPACE=hybrid_runtime_namespace  ## Apigee hybrid only
export AX_SERVICE_ACCOUNT=analytics_service_account  ## Optional

    其中：

    變數 說明
    organization_name Apigee 機構的名稱。
    environment_name 貴機構中的環境名稱。
    host_alias_url
    • 針對 Apigee Hybrid，這是包含混合型設定中定義虛擬主機的 hostAlias 的網址。
    • 對於 Apigee，則是包含環境的環境群組主機名稱。您可以在 Apigee UI 的「Admin」>「Environments」>「Groups」下方找到環境群組。

      • 注意：網址開頭必須是 https://。 例如：https://apitest.mydomain.net
    hybrid_runtime_namepace (僅限 Apigee Hybrid) Hybrid 執行階段元件部署的命名空間。

    注意：混合式部署的預設命名空間為 apigee。

    analytics_service_account (選用) 具有 Apigee Analytics Agent 角色的 Google Cloud 服務帳戶金鑰 JSON 檔案路徑。如需此參數的詳細說明，請參閱預留指令。
  4. 如果您不是與 Apigee 機構相關聯的 Google Cloud 專案擁有者，請確認您的 Google Cloud 使用者帳戶具備 Apigee 機構管理員角色，或是具備 API 建立者和 部署者角色。請參閱「授予、變更及撤銷資源的存取權」。
  5. 取得存取權杖： 
    TOKEN=$(gcloud auth print-access-token);echo $TOKEN
  6. 為 Apigee 佈建遠端服務 Proxy。指令輸出內容會重新導向至您稍後會使用的設定檔。

    如果您不升級，請使用這個指令來佈建 Apigee。如果您要為 Apigee hybrid 進行佈建，請務必新增 --namespace $NAMESPACE 參數：

    ./apigee-remote-service-cli provision --organization $ORG --environment $ENV \
     --runtime $RUNTIME --analytics-sa $AX_SERVICE_ACCOUNT --token $TOKEN > config.yaml

    如果您要升級，請使用此指令搭配 --force-proxy-install 旗標來佈建 Apigee。 如果您要為 Apigee hybrid 進行佈建，請務必新增 --namespace $NAMESPACE 參數：

    ./apigee-remote-service-cli provision --force-proxy-install --organization $ORG --environment $ENV \
     --runtime $RUNTIME --analytics-sa $AX_SERVICE_ACCOUNT --token $TOKEN > config.yaml
  7. 檢查 config.yaml 檔案的內容。內容應如下所示： 
    # Configuration for apigee-remote-service-envoy (platform: Google Cloud)
# generated by apigee-remote-service-cli provision on 2020-11-20 02:49:28
apiVersion: v1
kind: ConfigMap
metadata:
  name: apigee-remote-service-envoy
  namespace: apigee
data:
  config.yaml: |
    tenant:
      remote_service_api: https://apitest.mydomain.com/remote-service
      org_name: my-org
      env_name: test
    analytics:
      collection_interval: 10s
    auth:
      jwt_provider_key: https://apitest.mydomain.com/remote-service/token
---
apiVersion: v1
kind: Secret
metadata:
  name: my-org-new-test-policy-secret
  namespace: apigee
type: Opaque
data:
  remote-service.crt: eyJrZXlzIjpbeyJrdHkiOiJSU0EiLCJhbGci...
  remote-service.key: LS0tLS1CRUdJTiBSU0EgUFJJVkFURS...
  remote-service.properties: a2lkPTIwMjAtMDctMDZ...
---
apiVersion: v1
kind: Secret
metadata:
  name: my-org-new-test-analytics-secret
  namespace: apigee
type: Opaque
data:
  client_secret.json: ewogICJ0eXBlIjogInNlcnZ...
---
apiVersion: v1
kind: ServiceAccount
metadata:
  name: apigee-remote-service-envoy
  namespace: apigee
  8. 如果您使用的是 Apigee hybrid，請將服務設定 (佈建指令產生的檔案輸出內容) 套用至在步驟 1：建立叢集中安裝 Apigee hybrid 的叢集。

執行 apigee-remote-service-envoy

您可以將遠端服務當作原生二進位檔或在 Docker 上執行。

原生執行服務

使用佈建指令輸出的設定檔，執行服務二進位檔：

$REMOTE_SERVICE_HOME/apigee-remote-service-envoy -c config_file_path/config.yaml

在 Docker 上執行服務

Docker 映像檔會搭配版本標記發布。請使用最新版本進行安裝。有三種圖片變化版本可供選擇：

變化版本 圖片
Google distroless google/apigee-envoy-adapter:v2.0.3
Ubuntu google/apigee-envoy-adapter:v2.0.3-ubuntu
搭配 BoringCrypto 的 Ubuntu google/apigee-envoy-adapter:v2.0.3-boring

舉例來說，如要透過掛載的磁碟機執行 Scratch 映像檔，並使用本機 config.yaml 做為 /config.yaml，請使用下列指令：

docker run -v ./config.yaml:/config.yaml google/apigee-envoy-adapter:v2.0.3

建立 Envoy 設定檔範例

使用 CLI 產生 Envoy 設定檔範例：

  1. 確認您位於 $ENVOY_HOME 目錄。
  2. 列出可用的設定範本： 
    $CLI_HOME/apigee-remote-service-cli samples templates

  3. 執行範例指令。針對 TEMPLATE，請替換為支援的 Envoy 範本：

    $CLI_HOME/apigee-remote-service-cli samples create --template TEMPLATE -c ./config.yaml

    這個指令會建立 ./samples/envoy-config.yaml 檔案。

詳情請參閱「Samples 指令」。

安裝並執行 Envoy Proxy

請按照下列步驟安裝及執行 Envoy 代理程式：

  1. 下載 Envoy 二進位檔或建構。
  2. 使用先前為 httpbin.org 服務產生的範例設定檔，執行 Envoy：
    envoy -c ./samples/envoy-config.yaml

測試安裝結果

  1. 按照「如何取得 API 金鑰」一文所述，設定 API 產品並取得 API 金鑰。
  2. 不使用 API 金鑰呼叫 httpbin 服務：
    curl -i http://localhost:8080/headers -H "HOST:httpbin.org"

    服務目前由 Apigee 管理，由於您未提供 API 金鑰，因此呼叫會傳回以下錯誤。

    curl -i http://localhost:8080/headers -H "HOST:httpbin.org"
HTTP/1.1 403 Forbidden
date: Tue, 12 May 2020 17:51:36 GMT
server: envoy
content-length: 0
x-envoy-upstream-service-time: 11
  3. 使用金鑰發出 API 呼叫： 
    export APIKEY=YOUR_API_KEY
curl -i http://localhost:8080/headers -H "HOST:httpbin.org" -H "x-api-key: $APIKEY"

    呼叫應以 200 狀態成功，並在回應中傳回標頭清單。例如： 

    curl -i httpbin.default.svc.cluster.local/headers -H "x-api-key: kyOTalNNLMPfOSy6rnVeclmVSL6pA2zS"
HTTP/1.1 200 OK
server: envoy
date: Tue, 12 May 2020 17:55:34 GMT
content-type: application/json
content-length: 828
access-control-allow-origin: *
access-control-allow-credentials: true
x-envoy-upstream-service-time: 301

{
  "headers": {
    "Accept": "*/*",
    "Content-Length": "0",
    "Host": "httpbin.default.svc.cluster.local",
    "User-Agent": "curl/7.70.0-DEV",
    "X-Api-Key": "kyOTalNNLMPfOSy6rneclmVSL6pA2zS",
    "X-Apigee-Accesstoken": "",
    "X-Apigee-Api": "httpbin.default.svc.cluster.local",
    "X-Apigee-Apiproducts": "httpbin",
    "X-Apigee-Application": "httpbin",
    "X-Apigee-Authorized": "true",
    "X-Apigee-Clientid": "kyOTalNNLMPfOSy6rVeclmVSL6pA2zS",
    "X-Apigee-Developeremail": "user@mydomain.com",
    "X-Apigee-Environment": "test",
    "X-Apigee-Organization": "my-org",
    "X-Apigee-Scope": "",
    "X-B3-Parentspanid": "1476f9a2329bbdfa",
    "X-B3-Sampled": "0",
    "X-B3-Spanid": "1ad5c19bfb4bc96f",
    "X-B3-Traceid": "6f329a34e8ca07811476f9a2329bbdfa"
  }
}

解除安裝 Apigee Envoy 轉接卡

如要移除 Apigee Envoy 轉接程式安裝作業，請按照下列步驟操作：

  1. 請移除您選擇要執行 Envoy 轉接器的位置 (原生或 Docker)。
  2. 從 Apigee 環境中刪除 remote-service 和 remote-token Proxy。請參閱「刪除 API Proxy」。
  3. 移除 Envoy 轉接器用途所使用的任何未使用的 API 產品或作業。請參閱「刪除 API 產品」一文。

後續步驟

httpbin 服務的 API 流量現在由 Apigee 管理。以下是您可以探索及嘗試的部分功能：

  • 在 Edge UI 中存取 Apigee Analytics。依序前往「Analyze」>「API Metrics」>「API Proxy Performance」。
  • 請參閱參考資料，瞭解 CLI 選項。