运行指南

<ph type="x-smartling-placeholder"></ph> 您正在查看 Apigee Edge 文档。
转到 Apigee X 文档。 信息

如何获取 API 密钥

以下示例展示了如何获取 API 密钥，您可以使用该密钥来验证对通过 Apigee Adapter for Envoy 进行代理的目标服务的 API 调用。

1. 登录 Apigee

1. 在浏览器中打开 Apigee 界面。
2. 进入界面后，选择您用于配置适用于 Envoy 的 Apigee Adapter 的同一组织。

2. 创建开发者

您可以使用现有开发者进行测试，也可以按如下步骤创建新的开发者：

1. 在侧边导航菜单中选择发布 > 开发者。
2. 点击 + 开发者。
3. 填写对话框以创建新开发者。您可以根据需要使用任何开发者名称/电子邮件。

3. 创建 API 产品

请按照下方提供的产品创建示例操作。另请参阅 API 产品配置简介。

1. 在侧边导航菜单中选择发布 > API 产品。
2. 点击 + API 产品。
3. 填写“商品详情”页面，如下所示。

字段	值
名称	httpbin-product
显示名	httpbin product
环境	your_environment 请将此项设置为您在为 Envoy 预配 Apigee Adapter 时使用的环境。
访问	Private
配额	每 1 分钟 5 个请求 另请参阅配额。

4. 在 Apigee 远程服务目标部分中，点击添加 Apigee 远程服务目标。
5. 在 Apigee 远程服务目标对话框中，添加以下值：

   属性	值	说明
   目标名称	输入目标服务的名称。例如：httpbin.org	以 Envoy 代理为前端的目标端点。
   路径	输入要匹配的服务上的资源路径。对于 示例：/headers。	目标端点上要匹配的请求路径。对此路径的 API 代理调用将匹配此 API 产品。

6. 点击保存。

4. 创建开发者应用

1. 在侧边导航菜单中选择发布 > 应用。
2. 点击 + 应用。
3. 根据下表填写开发者应用页面。在系统提示保存之前请勿保存。

名称	httpbin-app
显示名	httpbin app
开发者	选择您之前创建的开发者，或者从列表中选择任意开发者。

4. 接下来，将 API 产品添加到应用中： <ph type="x-smartling-placeholder">
   </ph>
   1. 在“凭据”部分，点击 + 添加产品，然后选择您刚刚配置的产品：httpbin-product。
   2. 点击创建。
   3. 在“凭据”下，点击密钥旁边的显示。
   4. 复制使用方密钥的值。此值是您将用于对 httpbin 服务进行 API 调用的 API 密钥。

   API 产品简介

   API 产品是 Apigee 远程服务的主要控制点。在您创建 API 产品并将其绑定到目标服务时，您也创建了一个政策，该政策将应用于您配置 Apigee Adapter for Envoy 处理的任何请求。

   API 产品定义

   在 Apigee 中定义 API 产品时，您可以设置多个将用于评估请求的参数：

   • 目标
   • 请求路径
   • 配额
   • OAuth 范围

   远程服务目标

   如果请求同时与目标绑定（例如 httpbin.org）和请求路径（例如 /httpbin）匹配，则 API 产品定义将应用于该请求。潜在目标列表存储为 API 产品中的一个特性。

   默认情况下，Apigee 远程服务会根据其目标列表检查 Envoy 的特殊 :authority (host) 标头；但是您可以将其配置为使用其他标头。

   API 资源路径

   输入的路径根据如下规则进行匹配：

   • 单个斜杠 (/) 本身匹配任何路径。
   • * 在任何位置都有效，并且在一个路径段（斜杠之间）之内匹配。
   • ** 在末尾有效，并且匹配到行尾的任何内容。

   配额

   配额指定应用在一个小时、一天、一周或一个月内允许提交到 API 的请求消息的数量。当应用达到其配额限制时，后续的 API 调用将被拒绝。

   配额用例

   通过配额，您可以强制执行客户端在给定时间内可对服务发出的请求数。配额通常用于执行开发者和合作伙伴之间的业务合同或服务等级协议 (SLA)，而不是运营流量管理。例如，配额可用于限制免费服务的流量，同时允许付费客户完全访问。

   配额在 API 产品中定义

   配额参数在 API 产品中进行配置。例如，在创建 API 产品时，您可以选择设置允许的配额限制、时间单位和时间间隔。

   

   由于 API 密钥会映射回 API 产品，因此，每次验证 API 密钥时，相应的配额计数器都会递减（如果在关联的产品中定义了配额）。

   与 Apigee 运行时不同，产品定义中输入的配额由 Apigee 远程服务自动执行。授权请求将计入允许的配额。

   配额的维护位置

   配额由远程服务进程在本地维护和检查，并与 Apigee 运行时进行异步维护。这意味着配额不够精确， 如果有多个远程服务维持配额，则会超出部分限制。如果与 Apigee 运行时的连接中断，则本地配额将作为独立配额继续运行，直到重新连接到 Apigee 运行时为止。

   OAuth 范围

   如果您使用的是 JWT 令牌，可以将令牌限制为允许的 OAuth 范围的子集。分配给您的签发的 JWT 令牌的范围将根据 API 产品的范围进行检查。

   开发者应用简介

   配置 API 产品后，您将创建与开发者关联的应用。该应用允许客户端使用 API 密钥或 JWT 令牌访问关联的 API 产品。

   使用基于 JWT 的身份验证

   您可以使用 JWT 令牌（而不是使用 API 密钥）进行经过身份验证的 API 代理调用。这个 部分介绍了如何使用 apigee-remote-service-cli token 命令来 创建、检查和轮替 JWT 令牌。

   概览

   JWT 验证和身份验证由 Envoy 使用其 JWT 身份验证过滤器进行处理。

   通过身份验证后，Envoy ext-authz 过滤器会将请求标头和 JWT 发送到 apigee-remote-service-envoy。它会将 JWT 的 api_product_list 和 scope 声明与 Apigee API 产品进行匹配，从而根据请求的目标进行授权。

   创建 Apigee JWT 令牌

   您可以使用 CLI 创建 Apigee JWT 令牌：

   $CLI_HOME/apigee-remote-service-cli token create -c config.yaml --id $KEY --secret $SECRET

   也可以使用标准 OAuth 令牌端点。Curl 示例：

   curl https://org-env.apigee.net/remote-token/token -d '{"client_id":"myclientid","client_secret":"myclientsecret","grant_type":"client_credentials"}' -H "Content-type: application/json"

   使用 JWT 令牌

   获得令牌后，只需在 Authorization 标头中将其传递给 Envoy。示例：

   curl localhost:8080/httpbin/headers -i -H "Authorization:Bearer $TOKEN"

   JWT 令牌故障

   Envoy 拒绝

   如果 Envoy 拒绝令牌，您可能会看到如下消息：

   Jwks remote fetch is failed

   在这种情况下，请确保您的 Envoy 配置在 remote_jwks 部分中提供有效的 URI，可由 Envoy 访问，并且您在安装 Apigee 代理时正确设置了证书。您应该能够使用 GET 调用直接调用 URI，并收到有效的 JSON 响应。

   示例：

   curl https://myorg-eval-test.apigee.net/remote-service/certs

   来自 Envoy 的其他消息可能如下所示：

   • “不允许使用 Jwt 中的受众”
   • “未配置 Jwt 签发者”

   它们来自 Envoy 配置中可能需要修改的要求。

   检查令牌

   您可以使用 CLI 来检查令牌。示例

   $CLI_HOME/apigee-remote-service-cli -c config.yaml token inspect -f path/to/file

   或

   $CLI_HOME/apigee-remote-service-cli -c config.yaml token inspect <<< $TOKEN

   调试

   请参阅有效 API 密钥失败。

   日志

   您可以调整 $REMOTE_SERVICE_HOME/apigee-remote-service-envoy 服务的日志记录级别。所有日志记录都会发送到 stdout 和 stderr。

   元素	必填	说明
   -l、--log-level	有效级别：调试、信息、警告、错误。	调整日志记录级别。默认值：信息
   -j、--json-log		将日志输出为 JSON 记录。

   Envoy 提供日志记录。如需了解详情，请参阅以下 Envoy 文档链接：

   • 应用日志记录
   • 访问日志
   • 搭配使用 Stackdriver Logging 和 GKE

   使用网络代理

   通过在 apigee-remote-service-envoy 二进制文件环境中使用 HTTP_PROXY 和 HTTPS_PROXY 环境变量，您可以插入 HTTP 代理。使用这些环境变量时，NO_PROXY 环境变量还可用于排除通过代理发送的特定主机。

   HTTP_PROXY=http://[user]:[pass]@[proxy_ip]:[proxy_port]
   HTTPS_PROXY=http://[user]:[pass]@[proxy_ip]:[proxy_port]
   NO_PROXY=127.0.0.1,localhost

   请记住，必须能够从 apigee-remote-service-envoy 访问代理。

   指标和分析简介

   :5001/metrics 提供了 Prometheus 指标端点。您可以配置此端口号。请参阅配置文件。

   Envoy 分析

   以下链接提供了有关获取 Envoy 代理分析数据的信息：

   • Admin 接口
   • 统计信息
   • 集群统计信息

   Istio 分析

   以下链接提供了有关获取 Envoy 代理分析数据的信息：

   • 可观测性任务
   • 遥测配置

   Apigee 分析

   Apigee Remote Service for Envoy 将请求统计信息发送给 Apigee 进行分析处理。Apigee 会通过关联的 API 产品名称报告这些请求。

   如需了解 Apigee 分析，请参阅 Analytics 服务概览。

   多租户环境支持

   现在，您可以让适配器处理 Apigee 组织内的多个环境。通过此功能，您可以使用与 Apigee 组织关联的一个 Apigee Adapter for Envoy 来处理多个环境。在进行此项更改之前，一个适配器始终与一个 Apigee 环境相关联。

   如需配置多个环境支持，请在 config.yaml 文件中将 tenant:env_name 的值更改为 *。例如：

   1. 通过编辑器打开 config.yaml 文件。
   2. 将 tenant.env_name 的值更改为 *。例如：

      apiVersion: v1
      kind: ConfigMap
      metadata:
        name: apigee-remote-service-envoy
        namespace: apigee
      data:
        config.yaml: |
          tenant:
            remote_service_api: https://myorg-myenv.apigee.net/remote-service
            org_name: apigee-docs-hybrid-a
            env_name: *
            allow_unverified_ssl_cert: true
          analytics:
            collection_interval: 10s
          auth:
            jwt_provider_key: https://myorg-myenv.apigee.net.net/remote-token/token

   3. 保存文件。
   4. 应用此文件：

      kubectl apply -f $CLI_HOME/config.yaml

   配置多个环境模式时，您还必须通过在 envoy-config.yaml 文件的 virtual_hosts:routes 部分中添加以下元数据，将 Envoy 配置为将适当的环境值发送给适配器。例如：

   1. 使用 CLI 生成 envoy-config.yaml 文件。例如：

      $CLI_HOME/apigee-remote-service-cli samples create \
        -t envoy-1.16 -c ./config.yaml --out myconfigs

   2. 打开生成的文件（文件名为 envoy-config.yaml）。
   3. 在文件的 virtual_host 或 routes 部分添加以下元数据：

      typed_per_filter_config:
        envoy.filters.http.ext_authz:
          "@type": type.googleapis.com/envoy.extensions.filters.http.ext_authz.v3.ExtAuthzPerRoute
          check_settings:
            context_extensions:
              apigee_environment: test

      以下示例展示了定义多个路由的 virtual_host 的配置，其中每个路由将流量发送到特定环境：

      filter_chains:
          - filters:
            - name: envoy.filters.network.http_connection_manager
              typed_config:
                "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
                stat_prefix: ingress_http
                route_config:
                  virtual_hosts:
                  - name: default
                    domains: "*"
                    routes:
                    - match: { prefix: /test }
                      route:
                        cluster: httpbin
                      typed_per_filter_config:
                        envoy.filters.http.ext_authz:
                          "@type": type.googleapis.com/envoy.extensions.filters.http.ext_authz.v3.ExtAuthzPerRoute
                          check_settings:
                            context_extensions:
                               apigee_environment: test
                    - match: { prefix: /prod }
                      route:
                        cluster: httpbin
                      typed_per_filter_config:
                        envoy.filters.http.ext_authz:
                          "@type": type.googleapis.com/envoy.extensions.filters.http.ext_authz.v3.ExtAuthzPerRoute
                          check_settings:
                            context_extensions:
                               apigee_environment: prod

   4. 根据需要重复上一步以添加其他环境。
   5. 保存并应用文件。

   在适配器和 Apigee 运行时之间配置 mTLS

   您可以在适配器 config.yaml 文件的 tenant 部分提供客户端 TLS 证书，在适配器和 Apigee 运行时之间使用 mTLS。此更改应用到所有受支持的 Apigee 平台。它还为允许将 mTLS 用于 Apigee Edge for Private Cloud 平台的分析。例如：

   tenant:
     tls:
       ca_file: path/ca.pem
       cert_file: path/cert.pem
       key_file: path/key.pem
       allow_unverified_ssl_cert: false