Apigee 和 Apigee Hybrid 的原生 Envoy 示例

本页面适用于 ApigeeApigee Hybrid

查看 Apigee Edge 文档。

此示例演示如何通过在本地(而不是在 Kubernetes 集群内)安装和运行 Envoy 来使用 Apigee Adapter for Envoy。您可以按照本文档中的示例安装 Apigee 和 Apigee Hybrid。

API 代理调用将通过作为原生应用运行的 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 将 Apigee Adapter for Envoy 资源预配到 Apigee。预配命令会部署用于 Apigee 适配器操作的 API 代理,在 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,此变量为包含 Hybrid 配置中定义的虚拟主机的 hostAlias 的网址。
    • 对于 Apigee,此变量为相应环境所在的环境组中的主机名。您可以在 Apigee 界面的管理 > 环境 > 群组下找到环境群组。
    • 注意:网址必须以 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 Organization Admin 角色,或者同时具有 API CreatorDeployer 角色。请参阅授予、更改和撤消对资源的访问权限
  5. 获取访问令牌:
    TOKEN=$(gcloud auth print-access-token);echo $TOKEN
  6. 将远程服务代理预配到 Apigee。系统会将命令输出重定向到配置文件,以便在后续步骤中使用。

    如果您进行升级,请使用以下命令预配 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

运行 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
包含 Boring Crypto 的 Ubuntu google/apigee-envoy-adapter:v2.0.3-boring

例如,如需通过卷装载将暂存映像与 /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 文件。

如需了解详情,请参阅示例命令

安装并运行 Envoy 代理

请按照以下步骤安装并运行 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. 无论您选择在何处运行(在本地或在 Docker 上)Envoy 适配器,都请将它移除。
  2. 从 Apigee 环境中删除 remote-serviceremote-token 代理。请参阅删除 API 代理
  3. 移除 Envoy 适配器用例使用的所有未使用的 API 产品或操作。请参阅删除 API 产品

后续步骤

通往 httpbin 服务的 API 流量现在由 Apigee 管理。下面是您可以探索和试用的一些功能:

  • 在 Edge 界面中访问 Apigee Analytics。转到分析 > API 指标 > API 代理性能
  • 探索参考文档中的 CLI 选项。