运行指南

本页面适用于 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 文档。

如何获取 API 密钥

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

1. 登录 Apigee

登录 Apigee 界面。
选择用于预配 Apigee Adapter for Envoy 的同一组织。

2. 创建开发者

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

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

3. 创建 API 产品

请按照下方提供的产品创建示例操作。

在侧边导航菜单中选择发布 > API 产品。
点击 +创建 (+CREATE)。

根据下表填写产品详情部分。下表中仅提及了必填字段：

字段	值	说明
名称	`httpbin-product`	API 产品的唯一名称。
显示名称	`httpbin product`	您希望在界面或其他显示上下文中看到的描述性名称。
访问权限	`Public`	在此示例中，公共是不错的选择。

在“操作”(Operations) 部分中，点击+添加操作 (+ADD AN OPERATION)。
在来源部分中，选择远程服务。
切换来源切换开关，以允许您在“远程服务”字段中手动输入远程服务的名称。
在远程服务字段中，输入远程服务的名称。这是适配器通过代理将传入 HTTP 请求发送到的目标服务。为进行测试，请将 httpbin.org 或 httpbin.default.svc.cluster.local 与 Kubernetes 搭配使用。
在操作部分中，输入 / 作为路径。如需了解路径选项，请参阅配置资源路径。
点击保存以保存该操作。
点击保存以保存该 API 产品。

如需了解详情，请参阅管理 API 产品。

4. 创建开发者应用

开发者应用包含通过适配器进行 API 代理调用所需的 API 密钥。

在侧边导航菜单中选择发布应用。
点击 + 应用。
填写应用详情部分，如下所示。下表中仅提及了必填字段：

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

在“凭据”部分，点击 + 添加产品，然后选择您刚刚配置的产品：httpbin-product。
点击创建。
在“凭据”下，点击密钥旁边的显示。
复制使用方密钥的值。此值是您将用于通过 Apigee Adapter for Envoy 对 httpbin 服务进行 API 调用的 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-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 has 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 密钥失败。

使用专属身份提供商

默认情况下，Apigee Adapter for Envoy 使用 remote-token API 代理作为身份提供商服务，根据 OAuth 2.0 客户端凭据授权类型对客户端应用进行身份验证并传送 JWT 令牌。但在某些情况下，您可能无法使用 remote-token 代理。如果必须使用非 Apigee 提供的身份提供商，则可以将适配器配置为使用其他身份提供商。如需详细了解此非 Apigee 身份提供商用例和所需配置，请参阅 Apigee 社区上的这篇文章：将专属身份提供商与 Apigee Envoy 适配器搭配使用。

日志记录

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

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

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

更改政策 Secret 名称

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

执行以下命令：

$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

在编辑器中打开 $CLI_HOME/samples/apigee-envoy-adapter.yaml。

将装载点名称更改为新名称：

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

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

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 代理分析数据的信息：

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 的值更改为 "*"。例如：

通过编辑器打开 config.yaml 文件。

将 tenant.env_name 的值更改为 "*"。例如：

apiVersion: v1
kind: ConfigMap
metadata:
  name: apigee-remote-service-envoy
  namespace: apigee
data:
  config.yaml: |
    tenant:
      remote_service_api: https://apitest.mydomain.net/remote-service
      org_name: my-org
      env_name: "*""
      allow_unverified_ssl_cert: true
    analytics:
      collection_interval: 10s
    auth:
      jwt_provider_key: https://apitest.mydomain.net/remote-token/token

保存文件。
应用此文件：
```
kubectl apply -f $CLI_HOME/config.yaml
```

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

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

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

打开生成的文件（文件名为 envoy-config.yaml）。

在文件的 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

根据需要重复上一步以添加其他环境。
保存并应用文件。
注意：如果 config.yaml 中的 env_name 设置为 "*" 以外的任何其他值，则适配器会向 Envoy 返回错误，并且如果适配器的 env_name 配置未设为 "*"，或者 env_name 属性与传递的 apigee_environment 元数据不匹配，则请求将被拒绝。

捕获自定义报告的数据

该适配器支持将 Envoy 元数据传递给 Apigee 的数据捕获功能，该功能可以将您指定的变量中所捕获的数据发送到 Apigee 分析，以便在自定义报告中使用。此功能可提供类似于 Apigee 数据捕获政策的功能。

如需使用此功能，请执行以下操作：

创建 Data Collector REST 资源。
使用 Apigee datacollectors API 定义数据捕获变量。

如果您尚未使用 CLI 生成 envoy-config.yaml 文件，请执行此操作。例如：

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

打开生成的文件（文件名为 envoy-config.yaml）。

使用 Envoy 过滤器为 envoy.filters.http.apigee.datacapture 命名空间中的自定义变量设置值。例如，您可以使用 Header to Metadata 过滤器或 Lua 过滤器。如需详细了解这些过滤器，请参阅 Header-To-Metadata 和 Lua。

自定义变量名称必须采用 dc.XXXXX 格式。

Header to Metadata 过滤器示例：

 - name: envoy.filters.http.header_to_metadata
  typed_config:
    "@type": type.googleapis.com/envoy.extensions.filters.http.header_to_metadata.v3.Config
    request_rules:
      - header: "Host"
        on_header_present:
          metadata_namespace: envoy.filters.http.apigee.datacapture
          key: dc.host  # host (without the prefix) also works
          type: STRING
        remove: false

Lua 过滤器示例：

- name: envoy.filters.http.lua
  typed_config:
    "@type": type.googleapis.com/envoy.extensions.filters.http.lua.v3.Lua
    inline_code: |
      function envoy_on_request(request_handle)
        metadata = request_handle:streamInfo():dynamicMetadata()
        metadata:set("envoy.filters.http.apigee.datacapture", "dc.test", "A test string.")
      end

将所需的过滤器添加到文件。请参阅下面的示例。
保存并应用文件。

在适配器和 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