运行指南

您正在查看的是 Apigee Edge 文档。
转到 Apigee X 文档
信息

如何获取 API 密钥

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

1. 登录 Apigee

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

2. 创建开发者

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

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

3. 创建 API 产品

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

  1. 在侧边导航菜单中选择发布 > API 产品
  2. 点击 + API 产品
  3. 在“商品详情”页面中填写以下内容。
  4. 字段
    名称 httpbin-product
    显示名 httpbin product
    环境 your_environment

    请将此项设置为您在预配 Apigee Adapter for Envoy 时使用的环境。

    访问 Private
    配额 每 1 分钟 5 个请求

    另请参阅配额

  5. Apigee 远程服务目标部分中,点击添加 Apigee 远程服务目标
  6. 在 Apigee 远程服务目标对话框中,添加以下值:
    属性 说明
    目标名称 输入目标服务的名称。例如:httpbin.org 以 Envoy 代理为前端的目标端点。
    路径 输入要匹配的服务的资源路径。例如:/headers 目标端点上要匹配的请求路径。对此路径的 API 代理调用将匹配此 API 产品。
  7. 点击保存

4. 创建开发者应用

  1. 在侧边导航菜单中选择发布 > 应用
  2. 点击 + 应用
  3. 根据下表填写开发者应用页面。在系统提示保存之前请勿保存。
  4. 名称 httpbin-app
    显示名 httpbin app
    开发者 选择您之前创建的开发者,或者从列表中选择任意开发者。
  5. 接下来,将 API 产品添加到应用中:
    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_listscope 声明与 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 有效级别:debug、info、warn、error。 调整日志记录级别。默认值:信息
    -j、--json-log 将日志输出为 JSON 记录。

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

    使用网络代理

    通过在 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 代理分析数据的信息:

    Istio 分析

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

    Apigee Analytics

    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_hostroutes 部分添加以下元数据:
      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