第 5 章 APIcast Policies

APIcast 策略是修改 APIcast 操作方式的功能单元。可以启用、禁用和配置策略,以控制它们如何修改 APIcast。使用策略添加默认 APIcast 部署中不可用的功能。您可以创建自己的策略,或使用 Red Hat 3scale 提供的标准策略

以下主题提供有关标准 APIcast 策略的信息,创建您自己的自定义 APIcast 策略并创建策略链。

使用策略链控制服务策略。策略链执行以下操作:

  • 指定 APIcast 使用的策略
  • 为策略 3scale 提供配置信息
  • 指定 3scale 加载策略的顺序
注意

红帽 3scale 提供了一种添加自定义策略的方法,但不支持自定义策略。

要使用自定义策略修改 APIcast 的行为,您必须执行以下操作:

  • 在 APIcast 中添加自定义策略
  • 定义配置 APIcast 策略的策略链
  • 将策略链添加到 APIcast

5.1. APIcast 标准策略

Red Hat 3scale 提供以下标准策略:

您可以在 3scale API Management 中 启用和配置 标准策略。

5.1.1. 3scale Auth 缓存策略

3scale 身份验证缓存策略会缓存对 APIcast 发出的身份验证调用。您可以选择操作模式来配置缓存操作。

3scale Auth 缓存在以下模式中可用:

1.Strict - Cache only authorized calls.

"strict"模式仅缓存授权的调用。如果策略在"strict"模式下运行,并且调用失败或被拒绝,策略会使缓存条目失效。如果后端无法访问,则所有缓存的调用都会被拒绝,无论它们缓存的状态如何。

2.Resilient – Authorize according to last request when backend is down.

"弹性"模式会缓存授权和拒绝调用。如果策略在"弹性"模式下运行,则失败的调用不会使现有的缓存条目无效。如果后端变得不可访问,则命中缓存的调用仍会根据缓存的状态继续获得授权或拒绝。

3.Allow - When backend is down, allow everything unless seen before and denied.

"Allow"模式会缓存授权和被拒绝的调用。如果策略在"allow"模式下运行,则缓存的调用根据缓存的状态继续被拒绝或允许。但是,任何新调用都将缓存为授权。

重要

在"允许"模式下操作存在安全隐患。在使用"allow"模式时,请考虑以上问题并进行练习。

4.none - 禁用缓存。

"None"模式禁用缓存。如果您希望策略保持活动状态,但不想使用缓存,则此模式非常有用。

配置属性

属性描述必需?

caching_type

caching_type 属性允许您定义缓存将在其中操作的模式。

数据类型:枚举的字符串 [resilient, strict, allow, none]

策略对象示例

{
  "name": "caching",
  "version": "builtin",
  "configuration": {
    "caching_type": "allow"
  }
}

有关如何配置策略的详情,请参考文档中的创建策略链 部分。

5.1.2. 3scale Batcher 策略

3scale Batcher 策略提供了标准的 APIcast 授权机制的替代方案,其中为 APIcast 接收的每个 API 请求调用 3scale 后端(Service Management API)。

3scale Batcher 策略通过显著减少到 3scale 后端的请求数量来减少延迟并增加吞吐量。为了达到此目的,此策略会缓存授权状态和批处理使用情况报告。

当 3scale Batcher 策略被启用时,APIcast 会使用以下授权流:

  1. 在每个请求中,策略检查是否缓存凭证:

    • 如果缓存了凭据,策略将使用缓存的授权状态,而不是调用 3scale 后端。
    • 如果没有缓存凭据,策略会调用后端,并使用可配置的生存时间(TTL)来缓存授权状态。
  2. 策略不立即向 3scale 后端报告与请求对应的使用量,而是累计使用计数器将它们报告到批处理中的后端。单独的线程在单个调用中报告 3scale 后端的总用量计数器,具有可配置的频率。

3scale Batcher 策略提高了吞吐量,但准确性较低。使用限制和当前利用率存储在 3scale 中,APIcast 只能在向 3scale 后端发出调用时获取正确的授权状态。启用 3scale Batcher 策略时,在一个时间段内 APIcast 不会发送调用到 3scale。在此窗口中,调用的应用程序可能会超过定义的限值。

如果吞吐量比速率限制的准确性更重要,则将此策略用于高负载 API。当报告频率和授权 TTL 低于速率限制周期时,3scale Batcher 策略可以带来更好的准确性。例如,如果限制是每天的,并且报告频率和授权 TTL 被配置为几分钟。

3scale Batcher 策略支持以下配置设置:

  • auths_ttl :当授权缓存过期时,以秒为单位设置 TTL。

    当缓存当前调用的授权时,APIcast 将使用缓存的值。在 auths_ttl 参数中设置的时间后,APIcast 会移除缓存并调用 3scale 后端来检索授权状态。

  • batch_report_seconds :设置批处理报告的频率发送到 3scale 后端。默认值为 10 秒。
重要

要使用此策略,请在策略链中同时启用 3scale APIcast3scale 批处理器策略

5.1.3. 匿名访问策略

匿名访问策略会在没有身份验证的情况下公开一个服务。例如,这对无法适应发送身份验证参数的传统应用程序很有用。匿名策略只支持使用 API Key 和 App Id / App Key 身份验证选项的服务。当为未提供任何凭证的 API 请求启用策略时,APIcast 将授权调用使用策略中配置的默认凭据。若要授权 API 调用,配置有凭据的应用必须存在并且处于活动状态。

使用 Application Plans,您可以配置用于默认凭证的应用程序的速率限值。

注意

在策略链中同时使用这些策略时,您需要将匿名访问策略放在 APIcast 策略的前面。

以下是策略所需的配置属性:

  • auth_type:从以下其中一个备选中选择一个值,并确保属性与为 API 配置的身份验证选项对应:

    • app_id_and_app_key :用于 App ID / App Key 身份验证选项。
    • user_key: 用于 API 密钥身份验证选项。
  • app_id (仅适用于 app_id_and_app_key auth 类型):如果没有通过 API 调用提供凭证,则将用于授权的应用程序 Id。
  • app_key (仅适用于 app_id_and_app_key auth 类型):如果没有通过 API 调用提供凭据,则应用程序的 App Key 用于授权。
  • user_key (只适用于 user_key auth_type):API 调用中不提供任何凭据时将用于授权的应用的 API 密钥。

图 5.1. 匿名访问策略

匿名访问策略

5.1.4. CORS 请求处理策略

通过允许您指定以下指定来控制 CORS 行为,可通过交叉资源共享(CORS)请求处理策略来控制 CORS:

  • 允许的标头
  • 允许的方法
  • 允许凭证
  • 允许的源标头

CORS 请求处理策略将阻止所有未指定的 CORS 请求。

注意

当在策略链中使用这两个策略时,您需要将 CORS Request 处理策略放在 APIcast 策略的前面。

配置属性

属性描述必需?

allow_headers

allow_headers 属性是一个数组,您可以在其中指定允许哪些 CORS 标头。

data type:字符串数组,必须是 CORS 标头

allow_methods

allow_methods 属性是一个数组,您可以在其中指定 APIcast 允许的 CORS 方法。

data type:枚举字符串的数组 [GET, HEAD, POST, PUT, DELETE, PATCH, OPTIONS, TRACE, CONNECT]

allow_origin

allow_origin 属性允许您指定原始域 APIcast 允许

数据类型:字符串

allow_credentials

allow_credentials 属性允许您指定 APIcast 是否允许带有凭证的 CORS 请求

数据类型:布尔值

策略对象示例

{
  "name": "cors",
  "version": "builtin",
  "configuration": {
    "allow_headers": [
      "App-Id", "App-Key",
      "Content-Type", "Accept"
    ],
    "allow_credentials": true,
    "allow_methods": [
      "GET", "POST"
    ],
    "allow_origin": "https://example.com"
  }
}

有关如何配置策略的详情,请参考文档的创建策略链部分。

5.1.5. echo Policy

echo 策略会向客户端显示传入的请求,以及可选的 HTTP 状态代码。

配置属性

属性描述必需?

status

Echo 策略将返回到客户端的 HTTP 状态代码

数据类型:整数

exit

指定回显策略将使用的退出模式。request 退出模式将停止处理传入请求。set exit 模式跳过重写阶段。

data type:枚举字符串 [request, set]

策略对象示例

{
  "name": "echo",
  "version": "builtin",
  "configuration": {
    "status": 404,
    "exit": "request"
  }
}

有关如何配置策略的详情,请参考文档的创建策略链部分。

5.1.6. 边缘限制策略

Edge Limiting 策略旨在为发送到后端 API 的流量提供灵活的速率限制,并可与默认的 3scale 授权一起使用。策略支持的用例的一些示例包括:

  • 最终用户速率限制:速率受到请求的 Authorization 头中的 JWT 令牌中的 "sub" (subject) 声明值的限制(配置为 {{ jwt.sub }})。
  • 请求每秒(RPS)速率限制.
  • 每个服务的全球速率限值:每个服务应用限制而不是每个应用程序。
  • 并发连接限制:设置允许的并发连接数。

5.1.6.1. 限制类型

该策略支持 lua-resty-limit-traffic 库提供的以下类型的限制:

  • leaky_bucket_limiters :基于基于基于平均请求数和最大突发大小的"leaky_bucket"算法。
  • fixed_window_limiters: 基于固定的时间窗口(最后 X 秒)。
  • connection_limiters :基于并发连接数。

您可以通过服务或全局限制来限制任何限制。

5.1.6.2. 限制定义

限制具有一个键,用于对用来定义限制(IP、服务、端点、ID、特定标头等)的实体进行编码。Key 在限制者的 key 参数中指定。

key 是由以下属性定义的对象:

  • 名称 :键的名称。它在范围内必须是唯一的。
  • Scope :它定义密钥的范围。支持的范围有:

    • 每个影响一个服务(service)的服务范围。
    • 影响所有服务(global)的全局范围。
  • name_type: 它定义如何评估"name"值:

    • 纯文本(plain
    • Liquid(liquid

每个限制也有一些参数因类型而异:

  • leaky_bucket_limiters: rate, burst.

    • 速率 :它定义每秒可进行的请求数量,而没有延迟。
    • burst :它定义每秒可以超过允许的速率的请求数。对于超过允许率(由 rate 指定)的请求引入人工延迟。在超过 burst 中定义的每秒请求数后,请求将被拒绝。
  • fixed_window_limiters: count, window.计数 定义了在 窗口 中定义的每秒数发出的请求数量。
  • connection_limitersconnburstdelay.

    • conn :定义允许的最大并发连接数。它允许通过每秒 burst 连接超过该数量。
    • delay :这是延迟超过限制的连接的秒数。

例子

  1. 每分钟允许 10 个请求到 service_A:

    {
      "key": { "name": "service_A" },
      "count": 10,
      "window": 60
    }
  2. 允许 100 个连接,带有 10 个突发,延迟为 1 秒:

    {
      "key": { "name": "service_A" },
      "conn": 100,
      "burst": 10,
      "delay": 1
    }

您可以为每个服务定义多个限制。如果定义了多个限制,则在至少达到一个限值时请求可以被拒绝或延迟。

5.1.6.3. 移动模板

Edge Limiting 策略允许通过在键中支持 Liquid 变量来指定动态密钥的限制。对于这个,键的 name_type 参数必须设置为 "liquid",而 name 参数则可使用 Liquid 变量。示例:{ { remote_addr }} 用于客户端 IP 地址,或者 {{ jwt.sub }} 用于 JWT 令牌的"sub"声明。

例如:

{
  "key": { "name": "{{ jwt.sub }}", "name_type": "liquid" },
  "count": 10,
  "window": 60
}

有关 Liquid 支持的详情请参考 第 6.1 节 “在策略中使用变量和过滤器”

5.1.6.4. 应用条件

该条件定义 API 网关何时应用限制器。您必须在每个限制器的 condition 属性中至少指定一个操作。

condition 由以下属性定义:

  • combine_op.它是应用于操作列表的布尔值运算符。支持以下两个值:
  • operations。它是需要评估的条件列表。每个操作都由一个具有以下属性的对象表示:

    • left :操作的左侧。
    • left_type :如何评估 属性(解释或静止)。
    • 正确 :操作的正确部分。
    • right_type :如何评估 正确的 属性(解释或查询)。
    • op :在左侧和右部分之间应用的 Operator。支持以下两个值: == (等于)和 != (不等于)。

例如:

"condition": {
  "combine_op": "and",
  "operations": [
    {
      "op": "==",
      "right": "GET",
      "left_type": "liquid",
      "left": "{{ http_method }}",
      "right_type": "plain"
    }
  ]
}

5.1.6.5. 配置存储

默认情况下,Edge 限制策略将 OpenResty 共享字典用于速率限制计数器。但是,可以使用外部 Redis 服务器而不是共享字典。这在使用多个 APIcast 实例时很有用。Redis 服务器可以使用 redis_url 参数进行配置。

5.1.6.6. 错误处理

限制器支持以下参数来配置错误的处理方式:

  • limits_exceeded_error 允许配置在超过配置的限制时返回到客户端的错误状态代码和消息。应配置以下参数:

    • status_code :超过限制时请求的状态代码。默认:429
    • error_handling :如何处理错误。

      • 退出: "Respond with an error"。
      • 日志 :"记录请求通过,仅输出日志"
  • configuration_error 允许配置错误状态代码,并在配置错误时返回到客户端的消息。应配置以下参数:

    • status_code :配置问题时的状态代码。默认:500。
    • error_handling :如何处理错误。

      • 退出: "Respond with an error"。
      • 日志 :"记录请求通过且仅输出日志"。

5.1.7. 标头修改策略

标头修改策略允许您修改现有标头,或者定义额外的标头以添加到或从传入的请求或响应中删除。您可以修改响应和请求标头。

Header 修改策略支持以下配置参数:

  • request: 应用到请求标头的操作列表
  • response:应用到响应标头的操作列表

每个操作都由以下参数组成:

  • op :指定要应用的操作。add 操作会为现有标头添加一个值。这个 set 操作会创建一个标头和值,如果已存在该标头的值,则会覆盖现有的标头值。push 操作会创建一个标头和值,但如果已存在,则不会覆盖现有的标头值。相反,push 会将值添加到现有标头中。delete 操作会删除标头。
  • 标题 :指定要创建的标头或修改,并且可以用作标头名称(如 Custom-Header)的任何字符串。
  • value_type :定义如何评估标题值,可以是 plain(纯文本)或 liquid(Liquid 模板)。更多信息请参阅 第 6.1 节 “在策略中使用变量和过滤器”
  • value: 指定用于标头的值。对于值类型"liquid",值应当采用 {{ variable_from_context }} 格式。删除时不需要.

策略对象示例

{
  "name": "headers",
  "version": "builtin",
  "configuration": {
    "response": [
      {
        "op": "add",
        "header": "Custom-Header",
        "value_type": "plain",
        "value": "any-value"
      }
    ],
    "request": [
      {
        "op": "set",
        "header": "Authorization",
        "value_type": "plain",
        "value": "Basic dXNlcm5hbWU6cGFzc3dvcmQ="
      },
      {
        "op": "set",
        "header": "Service-ID",
        "value_type": "liquid",
        "value": "{{service.id}}"
      }
    ]
  }
}

有关如何配置策略的详情,请参考文档中的创建策略链 部分。

5.1.8. IP 检查策略

IP 检查策略用于根据 IP 列表拒绝或允许请求。

配置属性

属性描述数据类型必需?

check_type

check_type 属性有两个可能的值,即 whitelistblacklistblacklist 将拒绝来自 IP 的所有请求。whitelist 将拒绝不是来自列表中的 IP 的所有请求。

字符串,必须是 whitelistblacklist

ips

ips 属性允许您指定 IP 地址列表以列入白名单或黑名单。可以使用单一 IP 和 CIDR 范围。

字符串数组,必须是有效的 IP 地址

error_msg

error_msg 属性允许您配置在请求被拒绝时返回的错误消息。

字符串

client_ip_sources

client_ip_sources 属性允许您配置如何检索客户端 IP。默认情况下使用最后一个调用者 IP。其他选项有 X-Forwarded-ForX-Real-IP

字符串数组,有效选项为 X-Forwarded-For, X-Real-IP, last_caller

策略对象示例

{
  "name": "ip_check",
  "configuration": {
    "ips": [ "3.4.5.6", "1.2.3.0/4" ],
    "check_type": "blacklist",
    "client_ip_sources": ["X-Forwarded-For", "X-Real-IP", "last_caller"],
    "error_msg": "A custom error message"
  }
}

有关如何配置策略的详情,请参考文档的创建策略链部分。

5.1.9. liquid 上下文调试策略

注意

Liquid Context Debug 策略仅用于开发环境中而不是生产环境中的调试用途。

此策略使用 JSON 响应 API 请求,其包含上下文中可用的对象和值,并可用于评估 Liquid 模板。与 3scale APIcast 或 上游策略结合使用时,必须将 Liquid Context Debug 放置在策略链中才能正常工作。为避免循环引用,该策略仅包含重复的对象,并将其替换为 stub 值。

启用策略时 APIcast 返回的值示例:

{
  "jwt": {
    "azp": "972f7b4f",
    "iat": 1537538097,
    ...
    "exp": 1537574096,
    "typ": "Bearer"
  },
  "credentials": {
    "app_id": "972f7b4f"
  },
  "usage": {
    "deltas": {
      "hits": 1
    },
    "metrics": [
      "hits"
    ]
  },
  "service": {
    "id": "2",
    ...
  }
  ...
}

5.1.10. 日志记录策略

日志记录策略允许单独启用或禁用 APIcast(NGINX)访问日志。默认情况下,策略链中不启用此策略。

此策略仅支持 enable_access_logs 配置参数。要禁用服务的访问日志记录,启用策略,取消选择 enable_access_logs 参数,然后单击 Submit 按钮。要启用访问日志,请选择 enable_access_logs 参数或禁用 Logging 策略。

日志记录策略配置

您可以将 Logging 策略与访问日志位置的全局设置合并。设置 APICAST_ACCESS_LOG_FILE 环境变量,以配置 APIcast 访问日志的位置。默认情况下,此变量设置为 /dev/stdout,这是标准输出设备。有关全局 APIcast 参数的详情,请参考 ???

5.1.11. OAuth 2.0 令牌内省策略

OAuth 2.0 Token Introspection 策略允许使用令牌签发者(Red Hat Single Sign-On)的 Token Introtion Endpoint(Red Hat Single Sign-On)验证选项来验证用于通过 OpenID Connect 身份验证选项的 JSON Web Token Token 令牌(JWT)令牌。

APIcast 支持 auth_type 字段中的以下身份验证类型,以确定 Token Introspection Endpoint 和调用此端点时使用的凭证 APIcast:

use_3scale_oidc_issuer_endpoint

使用这个设置,APIcast 使用在 Service Integration 页面中配置的 OpenID Connect Issuer 设置中的客户端凭证(客户端 ID 和客户端 Secret)和令牌内省端点。

APIcast 从 token_introspection_endpoint 字段发现 Token Introspection 端点,.well-known/openid-configuration 端点返回。

例 5.1. 身份验证类型设置为 use_3scale_oidc_issuer_endpoint

如果身份验证类型被设置为 use_3scale_oidc_issuer_endpoint,则是一个配置示例:

"policy_chain": [
…​
  {
    "name": "apicast.policy.token_introspection",
    "configuration": {
      "auth_type": "use_3scale_oidc_issuer_endpoint"
    }
  }
…​
],
client_id+client_secret

这个选项允许您指定不同的令牌内省端点,以及客户端 ID 和客户端 Secret APIcast 用来请求令牌信息。

使用这个选项时,请设置以下配置参数:

  • client_id :为令牌内省端点设置客户端 ID。
  • client_secret :为令牌内省端点设置客户端 Secret。
  • introspection_url :设置 Introspection Endpoint URL。

    例 5.2. 身份验证类型设置为 client_id+client_secret

    如果身份验证类型被设置为 client_id+client_secret,则如下是配置示例:

    "policy_chain": [
    …​
      {
        "name": "apicast.policy.token_introspection",
        "configuration": {
          "auth_type": "client_id+client_secret",
          "client_id": "myclient",
          "client_secret": "mysecret",
          "introspection_url": "http://red_hat_single_sign-on/token/introspection"
        }
      }
    …​
    ],

无论 auth_type 字段中的设置是什么,APIcast 都会使用 Basic Authentication 来授权 Token Introspection 调用(Authorization: Basic <token> 头,其中 <token> 是 Base64 编码的 <client_id>:<client_secret> 设置)。

OAuth 2.0 令牌内省配置

Token Introspection Endpoint 的响应中包含 active 属性。APIcast 检查此属性的值。根据属性的值,APIcast 授权或拒绝调用:

  • true :调用已被授权
  • false: 调用被拒绝,且 Authentication Failed 错误

该策略允许缓存令牌,以避免在相同 JWT 令牌的每个调用中调用 Token Introspection Endpoint。要为 Token Introspection Policy 启用令牌缓存,请将 max_cached_tokens 字段设置为从 0 (禁用该功能)到 10000 直接的值。另外,您可以在 max_ttl_tokens 字段中将令牌的值从 1 设置为 3600 秒。

5.1.12. Referrer 策略

Referrer 策略启用了 Referrer Filtering 功能。当在服务策略链中启用策略时,APIcast 会在 referrer 参数中将后续请求的 Referer 策略发送到 Service Management API(AuthRep 调用)。有关如何过滤工作的更多信息,请参阅 身份验证模式 中的" 引用器过滤 "部分。

5.1.13. RH-SSO/Keycloak 角色检查策略

此策略在与 OpenID Connect 身份验证选项一起使用时添加角色检查。此策略会验证红帽单点登录发布的访问令牌中的 realm 角色和客户端角色。当您要为每一个客户端的资源或 3Scale 添加角色检查时,会指定 realm 角色。

以下是两种角色类型,用于检查 类型 属性是否在策略配置中指定:

  • 白名单 (默认):当使用 白名单 时,APIcast 将检查 JWT 令牌中是否存在指定的范围,并在 JWT 中没有范围时拒绝调用。
  • blacklist :当使用 黑名单 时,如果 JWT 令牌包含黑名单范围,APIcast 将拒绝调用。

同一策略中无法同时配置 blacklistwhitelist 检查,但您可以在 APIcast 策略链中添加多个 RH-SSO/Keycloak 角色检查 策略链。

您可以通过策略配置的 scopes 属性配置范围列表。

每个 scope 对象具有以下属性:

  • 资源 :角色控制的资源(端点)。这个格式与映射规则相同。模式从字符串开头匹配,若要完全匹配,您必须在末尾附加 $
  • resource_type :这定义了 资源 值的评估方式。

    • 以纯文本(plain)形式:以纯文本形式评估 资源 值。示例: /api/v1/products$.
    • 作为 Liquid 文本(liquid):允许在 资源 值中使用 Liquid。示例: /resource_{{ jwt.aud }} 管理对资源的访问,包括客户端 ID(包含在 JWT 仲裁 声明中)。
  • realm_roles :使用它来检查 realm 角色(请参阅 Red Hat Single Sign-On 文档中的 Realm 角色 )。

    域角色存在于红帽单点登录发布的 JWT 中。

      "realm_access": {
        "roles": [
          "<realm_role_A>", "<realm_role_B>"
        ]
      }

    策略中必须指定实际角色。

    "realm_roles": [
      { "name": "<realm_role_A>" }, { "name": "<realm_role_B>" }
    ]

    以下是 realm_roles 数组中每个对象的可用属性:

  • name :指定角色的名称。
  • name_type :定义必须如何评估名称;它可以是 的 或 liquid (与 resource_type的相同)。
  • client_roles :使用 client_roles 检查客户端命名空间中的特定访问角色(请参阅 Red Hat Single Sign-On 文档中的客户端角色 )。

    客户端角色存在于 JWT 中的 resource_access 声明下。

      "resource_access": {
        "<client_A>": {
          "roles": [
            "<client_role_A>", "<client_role_B>"
          ]
        },
        "<client_B>": {
          "roles": [
            "<client_role_A>", "<client_role_B>"
          ]
        }
      }

    指定策略中的客户端角色。

    "client_roles": [
      { "name": "<client_role_A>", "client": "<client_A>" },
      { "name": "<client_role_B>", "client": "<client_A>" },
      { "name": "<client_role_A>", "client": "<client_B>" },
      { "name": "<client_role_B>", "client": "<client_B>" }
    ]

    以下是 client_roles 数组中每个对象的可用属性:

  • name :指定角色的名称。
  • name_type :定义必须如何评估 name 值;它可以是 的 或 liquid (与 resource_type的相同)。
  • client :指定角色的客户端。如果未定义,此策略将 aud 声明用作客户端。
  • client_type: 定义 client 值如何被评估。可以是 plainliquid(与 resource_type 相同)。

5.1.14. Prometheus Metrics

Prometheus是一个独立的开源系统监视和警报工具包。

重要

在这个 Red Hat 3scale 版本中,不支持 Prometheus 安装和配置。另外,您可以使用 Prometheus 的社区版本 视觉化 API 服务的指标和警报。

Prometheus 指标可用性

以下部署选项提供了与 Prometheus 的 APIcast 集成:

  • 自我管理的 APIcast(包括托管或内部 API 管理器)
  • 内置 APIcast 内部
注意

托管 API Manager 和托管的 APIcast 不提供与 Prometheus 的 APIcast 集成。

Prometheus metrics 列表

以下指标始终可用:

指标描述类型标签

nginx_http_connections

HTTP 连接数

gauge

state(accepted,active,handled,reading,total,waiting,writing)

nginx_error_log

APIcast 错误

计数

level(debug,info,notice,warn,error,crit,alert,emerg)

openresty_shdict_capacity

worker 共享字典的能力

gauge

dict(one for every dictionary)

openresty_shdict_free_space

worker 共享字典的可用空间

gauge

dict(one for every dictionary)

nginx_metric_errors_total

管理指标的 Lua 库错误数

计数

-

total_response_time_seconds

向客户端发送响应所需的时间(以秒为单位)

histogram

-

upstream_response_time_seconds

来自上游服务器的响应时间(以秒为单位)

histogram

-

upstream_status

来自上游服务器的 HTTP 状态

计数

status

threescale_backend_calls

授权并报告请求到 3scale 后端(Apisonator)

计数

endpoint(authrep, auth, report), status(2xx, 4xx, 5xx)

只有在使用 3scale Batcher 策略时,以下指标才可用:

指标描述类型标签

batching_policy_auths_cache_hits

按 3scale 批处理策略的 auths 缓存中的内容

计数

-

batching_policy_auths_cache_misses

3scale 批处理策略的 auths 缓存中丢失

计数

-

没有值的指标

如果指标没有值,则指标会被隐藏。例如,如果 nginx_error_log 没有报告错误,则不会显示 nginx_error_log 指标。只有当它有值时才可见。

5.1.15. SOAP 策略

SOAP 策略与 HTTP 请求的 SOAPActionContent-Type 标头中提供的 SOAP 操作 URI 匹配策略中指定的映射规则。

配置属性

属性描述必需?

pattern

pattern 属性允许您在 SOAPAction URI 中指定 APIcast 将寻找匹配项的字符串。

数据类型:字符串

metric_system_name

metric_system_name 属性允许您指定匹配模式将注册命中的 3scale 后端指标。

数据类型:字符串,必须是一个有效的 metric

策略对象示例

{
  "name": "soap",
  "version": "builtin",
  "configuration": {
    "mapping_rules": [
      {
        "pattern": "http://example.com/soap#request",
        "metric_system_name": "soap",
        "delta": 1
      }
    ]
  }
}

有关如何配置策略的详情,请参考文档的创建策略链部分。

5.1.16. 上游策略

通过 Upstream 策略,您可以使用正则表达式来解析主机请求标头,并将私有基本 URL 中定义的上游 URL 替换为不同的 URL。

例如:

具有 regex /foo 的策略和 URL 字段 newexample.com 将 URL https://www.example.com/foo/123/ 替换为 newexample.com

策略链参考:

属性描述必需?

regex

regex 属性允许您指定在搜索与请求路径匹配项时 Upstream 策略要使用的正则表达式。

数据类型:字符串,必须是一个有效的正则表达式语法

url

使用 url 属性,您可以在匹配项中指定替换 URL。请注意,Upstream 策略不会检查这个 URL 是否有效。

数据类型:字符串,确定这是有效的 URL

策略对象示例

{
  "name": "upstream",
  "version": "builtin",
  "configuration": {
    "rules": [
      {
        "regex": "^/v1/.*",
        "url": "https://api-v1.example.com",

      }
    ]
  }
}

有关如何配置策略的详情,请参考文档的创建策略链部分。

5.1.17. URL 重写策略

URL 重写策略允许您修改请求的路径和查询字符串。

当与 3scale APIcast 政策结合使用时,如果将 URL 重新编写策略放在策略链中的 3scale APIcast 策略之前,APIcast 映射规则将应用到修改后的路径。如果在 APIcast 链中的 APIcast 后放置了 URL 重写策略,则映射规则将应用到原始路径。

该策略支持以下两组操作:

  • commands:要应用的命令列表来重写请求的路径。
  • query_args_commands :要应用的命令列表来重写请求的查询字符串。

5.1.17.1. 重写路径的命令

以下是 commands 列表中每个命令的配置参数,其中包括:

  • op:要应用的操作。可用的选项包括:subgsubsub 操作仅用您指定的正则表达式替换第一个匹配项。gsub 操作会将所有匹配项替换为您指定的正则表达式。请参阅有关 subgsub 操作的文档。
  • 正则表达式 :要匹配的与 Perl 兼容的正则表达式。
  • 替换 :替换在匹配项中使用的 : 替换字符串。
  • Options(可选):定义正则表达式的执行方式 的选项。有关可用选项的详情,请查看 OpenResty Lua 模块项目文档中的 ngx.re.match 部分。
  • break(可选):当启用复选框设置为 true 时,如果命令重新编写该 URL,它将是应用的最后一个,并且列表中的所有 posterior 命令将被丢弃。

5.1.17.2. 重写查询字符串的命令

以下是 query_args_commands 列表中每个命令由以下部分组成的配置参数:

  • op: 操作要应用到查询参数。可用的选项如下:

    • 添加: 为现有参数添加一个值。
    • 设置 :在未设置时创建 arg,并在设置时替换其值。
    • push :在未设置时创建 arg,并在设置时添加值。
    • 删除 :删除 arg。
  • ARG :用于操作的查询参数名称。
  • value:指定用于查询参数的值。对于值类型"liquid",值应当采用 {{ variable_from_context }} 格式。对于 delete 操作,不考虑该值。
  • value_type (可选): 定义查询参数值的评估方式,可以是 plain(纯文本)或 liquid(作为 Liquid 模板评估)。更多信息请参阅 第 6.1 节 “在策略中使用变量和过滤器”。如果没有指定,则默认使用类型"plain"。

示例

URL 重写策略配置如下:

{
  "name": "url_rewriting",
  "version": "builtin",
  "configuration": {
    "query_args_commands": [
      {
        "op": "add",
        "arg": "addarg",
        "value_type": "plain",
        "value": "addvalue"
      },
      {
        "op": "delete",
        "arg": "user_key",
        "value_type": "plain",
        "value": "any"
      },
      {
        "op": "push",
        "arg": "pusharg",
        "value_type": "plain",
        "value": "pushvalue"
      },
      {
        "op": "set",
        "arg": "setarg",
        "value_type": "plain",
        "value": "setvalue"
      }
    ],
    "commands": [
      {
        "op": "sub",
        "regex": "^/api/v\\d+/",
        "replace": "/internal/",
        "options": "i"
      }
    ]
  }

发送到 APIcast 的原始请求 URI:

https://api.example.com/api/v1/products/123/details?user_key=abc123secret&pusharg=first&setarg=original

应用 URL 重写后 APIcast 发送到 API 后端的 URI:

https://api-backend.example.com/internal/products/123/details?pusharg=first&pusharg=pushvalue&setarg=setvalue

应用以下转换:

  1. 子字符串 /api/v1/ 匹配唯一的路径重写命令,它被 /internal/ 替换。
  2. 已删除 user_key 查询参数。
  3. pushvalue 作为 pusharg 查询参数的额外值添加。
  4. 查询参数 setargoriginal 值替换为配置的值 setvalue
  5. 命令 add 没有被应用,因为原始 URL 中不存在查询参数 addarg

有关如何配置策略的详情,请参考文档中的创建策略链 部分。

5.1.18. 使用 Captures 策略的 URL 重写

使用 Captures 策略的 URL Rewriting 是 第 5.1.17 节 “URL 重写策略” 策略的替代,并允许在将 API 请求传递给 API 后端前重写 API 请求的 URL。

URL 使用 Captures 策略检索 URL 中的参数,并在重写 URL 中使用其值。

该策略支持 transformations 配置参数。这是一个对象列表,用于描述将哪些转换应用到请求 URL。每个调整对象由两个属性组成:

  • match_rule :此规则与传入请求 URL 匹配。它可以包含 {nameOfArgument} 格式的命名参数;这些参数可以在重写 URL 中使用。将 URL 与 match_rule 进行比较,作为正则表达式。匹配指定参数的值必须只包含以下字符(在 PCRE regex 表示法中): [\w-.~%!$&'()*+,;=@:]+。可以在 match_rule 表达式中使用其他 regex 令牌,如 ^ 表示字符串开头,$ 代表字符串末尾。
  • template:使用重写原始 URL 的 URL 模板;它可以使用 match_rule 中的指定参数。

原始 URL 的查询参数与 template 中指定的查询参数合并。

示例

使用 Captures 的 URL 重写如下:

{
  "name": "rewrite_url_captures",
  "version": "builtin",
  "configuration": {
    "transformations": [
      {
        "match_rule": "/api/v1/products/{productId}/details",
        "template": "/internal/products/details?id={productId}&extraparam=anyvalue"
      }
    ]
  }
}

发送到 APIcast 的原始请求 URI:

https://api.example.com/api/v1/products/123/details?user_key=abc123secret

应用 URL 重写后 APIcast 发送到 API 后端的 URI:

https://api-backend.example.com/internal/products/details?user_key=abc123secret&extraparam=anyvalue&id=123