运行指南

本页面适用于 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 文档。

如何获取 API 密钥

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

注意：如果您是经验丰富的 Apigee 用户，您会很熟悉以下步骤，因为它们是标准 Apigee 配置；但是，您需要严格按照这些说明操作，因为它们需要您插入具体的产品和开发者应用配置。

1. 登录 Apigee

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

2. 创建开发者

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

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

3. 创建 API 产品

请按照下方提供的产品创建示例操作。另请参阅关于 API 产品。

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

字段	值
名称	httpbin-product
显示名	httpbin product
环境	your_environment 将此字段设置为您使用 apigee-remote-service-cli 预配 Apigee Adapter for Envoy 时使用的环境。
访问	Private
配额	每 1 分钟 5 个请求 另请参阅 API 产品配置简介。

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

   属性	值	说明
   目标名称	输入目标服务的名称。例如：httpbin.org	以 Envoy 代理为前端的目标端点。
   API 代理	remote-service	在 Envoy Adapter 安装期间在 Apigee 上预配的 remote-service 代理。
   路径	输入 /resource_path 来匹配特定路径。例如：/httpbin。	目标端点上要匹配的请求路径。对此路径的 API 代理调用将匹配此 API 产品。

6. 点击保存。

4. 创建开发者应用

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

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

4. 接下来，向应用添加两个产品：
   1. 首先，在“凭据”部分，点击 + 添加产品，然后选择您刚刚配置的产品：httpbin-product。
   2. 然后，添加 remote-service 产品。此产品在您预配 Apigee 时已自动创建。
5. 点击创建。
6. 在“凭据”下，点击密钥旁边的显示。
7. 复制使用方密钥的值。此值是您将用于对 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 令牌。对于 Apigee Hybrid 环境，您可以使用以下命令创建 Kubernetes Secret 以保存 JWT。

概览

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

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

创建 Apigee JWT 令牌

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

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

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

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

注意：必须提供 Content-type 标头。

使用 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 来检查令牌。示例

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

或

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

调试

请参阅有效 API 密钥失败。

日志

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

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

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

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

更改政策 Secret 名称

部署到集群的 Kubernetes Secret 包含适配器需要用于对与远程服务代理之间的通信进行身份验证的凭据。此 Secret 需要卷装载点，卷装载点是可配置的。默认装载点为 /policy-secret。要更改装载点，请按以下步骤操作：

1. 执行以下命令：

   $REMOTE_SERVICE_HOME/apigee-remote-service-envoy --policy-secret '/new-mount_point_name

   例如：

   $REMOTE_SERVICE_HOME/apigee-remote-service-envoy --policy-secret '/my-mount-point

2. 在编辑器中打开 $CLI_HOME/samples/apigee-envoy-adapter.yaml。
3. 将装载点名称更改为新名称：

   volumeMounts:
     - mountPath: /config
       name: apigee-remote-service-envoy
       readOnly: true
     - mountPath: /opt/apigee/tls
       name: tls-volume
       readOnly: true
     - mountPath: /my-mount-point
       name: policy-secret
       readOnly: true

4. 保存该文件并将其应用于服务网格：

   kubectl apply -f $REMOTE_SERVICE_HOME/samples/apigee-envoy-adapter.yaml

使用网络代理

通过在 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 服务概览。