第 4 章 APIcast 策略

以下示例显示了策略链配置：

"policy_chain": [
    {
      "name": "apicast.policy.apicast"
    },
    {
      "name": "apicast.policy.camel",
      "configuration": {
          "all_proxy": "http://192.168.15.103:8080/",
          "http_proxy": "http://192.168.15.103:8080/",
          "https_proxy": "http://192.168.15.103:8443/"
      }
    }
]

如果未定义 http _proxy 或 https_proxy，则使用 all_proxy 值。

确定是否可以使用 JSON 表达条件策略链中的策略并使用临时模板的条件。

本例检查请求路径是否为 /example_path ：

{
  "left": "{{ uri }}",
  "left_type": "liquid",
  "op": "==",
  "right": "/example_path",
  "right_type": "plain"
}

左操作对象和右运算对象都可以评估为算子或纯字符串。纯文本字符串是默认值。

您可以将操作与 and 或.此配置检查与上例相同，外加 Backend 标头值：

{
  "operations": [
    {
      "left": "{{ uri }}",
      "left_type": "liquid",
      "op": "==",
      "right": "/example_path",
      "right_type": "plain"
    },
    {
      "left": "{{ headers['Backend'] }}",
      "left_type": "liquid",
      "op": "==",
      "right": "test_upstream",
      "right_type": "plain"
    }
  ],
  "combine_op": "and"
}

如需了解更多详细信息，请参阅 策略配置模式。

{
   "name":"conditional",
   "version":"builtin",
   "configuration":{
      "condition":{
         "operations":[
            {
               "left":"{{ headers['Backend'] }}",
               "left_type":"liquid",
               "op":"==",
               "right":"staging"
            }
         ]
      },
      "policy_chain":[
         {
            "name":"upstream",
            "version": "builtin",
            "configuration":{
               "rules":[
                  {
                     "regex":"/",
                     "url":"http://my_staging_environment"
                  }
               ]
            }
         }
      ]
   }
}

NGINX 代理_cache_valid 指令信息只能全局设置，使用 APICAST_CACHE_STATUS_CODES 和 APICAST_CACHE_MAX_TIME。如果您的上游需要与超时相关的不同行为，请使用 Cache-Control 标头。

下图显示了未缓存身份验证的请求流示例，以及身份验证缓存时的流。

如果上游 API 返回 400 状态，此策略会按标头递增来递增指标错误：

{
  "name": "apicast.policy.custom_metrics",
  "configuration": {
    "rules": [
      {
        "metric": "error",
        "increment": "{{ resp.headers['increment'] }}",
        "condition": {
          "operations": [
            {
              "right": "{{status}}",
              "right_type": "liquid",
              "left": "400",
              "op": "=="
            }
          ],
          "combine_op": "and"
        }
      }
    ]
  }
}

如果上游 API 返回 200 状态，则此策略使用 status_code 信息递增 hits 指标：

{
  "name": "apicast.policy.custom_metrics",
  "configuration": {
    "rules": [
      {
        "metric": "hits_{{status}}",
        "increment": "1",
        "condition": {
          "operations": [
            {
              "right": "{{status}}",
              "right_type": "liquid",
              "left": "200",
              "op": "=="
            }
          ],
          "combine_op": "and"
        }
      }
    ]
  }
}

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

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

这些限制有一个键，对用于定义限制的实体进行编码，如 IP 地址、服务、端点、标识符、特定标头的值和实体。此密钥在限制器的 key 参数中指定。

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

每个限制也具有一些因类型而异的参数：

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

Edge Limiting 策略允许通过在键中支持 Liquid 变量来指定动态密钥的限制。为此，密钥的 name_type 参数必须设置为 random，name 参数可以使用 Liquid 变量。例如，客户端 IP 地址 {{ remote_addr }} 或 JWT 令牌 子 声明的 {{ jwt.sub }}。

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

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

每个限制器必须具有定义何时应用限制器的条件。条件在限制器的 condition 属性中指定。

条件 由以下属性定义：

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

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

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

为了基于 JWT 声明的值进行路由，您需要链中的策略验证 JWT，并将声明存储在策略共享的上下文中。

如果 JWT Claim Check 策略正在阻止资源和方法，该策略也会验证 JWT 操作。另外，如果方法资源不匹配，则请求将继续至后端 API。

示例：如果 GET 请求，JWT 需要将角色声明设为 admin，否则请求将被拒绝。另一方面，任何非 GET 请求都不会验证 JWT 操作，因此允许 POST 资源而无需 JWT 约束。

{
  "name": "apicast.policy.jwt_claim_check",
  "configuration": {
      "error_message": "Invalid JWT check",
      "rules": [
          {
              "operations": [
                  {"op": "==", "jwt_claim": "role", "jwt_claim_type": "plain", "value": "admin"}
              ],
              "combine_op":"and",
              "methods": ["GET"],
              "resource": "/resource",
              "resource_type": "plain"
          }
      ]
  }
}

要在策略链中配置 JWT Claim Check 策略，请执行以下操作：

日志记录选项有助于避免出现 API 中未正确格式化的日志问题。可以设置自定义 APIcast 环境变量，并且所有 API 都实施日志记录策略。以下是载入在所有服务中的策略示例： custom_env.lua

local cjson = require('cjson')
local PolicyChain = require('apicast.policy_chain')
local policy_chain = context.policy_chain

local logging_policy_config = cjson.decode([[
{
  "enable_access_logs": false,
  "custom_logging": "\"{{request}}\" to service {{service.id}} and {{service.name}}"
}
]])

policy_chain:insert( PolicyChain.load_policy('logging', 'builtin', logging_policy_config), 1)

return {
  policy_chain = policy_chain,
  port = { metrics = 9421 },
}

使用这个特定环境运行 APIcast：

docker run --name apicast --rm -p 8080:8080 \
    -v $(pwd):/config \
    -e APICAST_ENVIRONMENT=/config/custom_env.lua \
    -e THREESCALE_PORTAL_ENDPOINT=https://ACCESS_TOKEN@ADMIN_PORTAL_DOMAIN \
    quay.io/3scale/apicast:master

这些是要考虑的 Docker 命令的关键概念：

本节论述了使用日志记录策略的一些示例。这些示例考虑以下注意事项：

{
  "name": "apicast.policy.logging",
  "configuration": {
    "enable_access_logs": false
  }
}

{
  "name": "apicast.policy.logging",
  "configuration": {
    "enable_access_logs": false,
    "custom_logging": "[{{time_local}}] {{host}}:{{server_port}} {{remote_addr}}:{{remote_port}} \"{{request}}\" {{status}} {{body_bytes_sent}} ({{request_time}}) {{post_action_impact}}",
  }
}

{
  "name": "apicast.policy.logging",
  "configuration": {
    "enable_access_logs": false,
    "custom_logging": "\"{{request}}\" to service {{service.id}} and {{service.name}}",
  }
}

{
  "name": "apicast.policy.logging",
  "configuration": {
    "enable_access_logs": false,
    "enable_json_logs": true,
    "json_object_config": [
      {
        "key": "host",
        "value": "{{host}}",
        "value_type": "liquid"
      },
      {
        "key": "time",
        "value": "{{time_local}}",
        "value_type": "liquid"
      },
      {
        "key": "custom",
        "value": "custom_method",
        "value_type": "plain"
      }
    ]
  }
}

{
  "name": "apicast.policy.logging",
  "configuration": {
    "enable_access_logs": false,
    "custom_logging": "\"{{request}}\" to service {{service.id}} and {{service.name}}",
    "condition": {
      "operations": [
        {"op": "==", "match": "{{status}}", "match_type": "liquid", "value": "200"}
      ],
      "combine_op": "and"
    }
  }
}

{
  "name": "apicast.policy.logging",
  "configuration": {
    "enable_access_logs": false,
    "custom_logging": "\"{{request}}\" to service {{service.id}} and {{service.name}}",
    "condition": {
      "operations": [
        {"op": "==", "match": "{{status}}", "match_type": "liquid", "value": "200"},
        {"op": "==", "match": "{{status}}", "match_type": "liquid", "value": "500"}
      ],
      "combine_op": "or"
    }
  }
}

对于自定义日志记录，您可以使用 Liquid 模板和导出的变量。这些变量包括：

以下示例显示了策略链配置：

"policy_chain": [
    {
      "name": "apicast.policy.apicast"
    },
    {
      "name": "apicast.policy.http_proxy",
      "configuration": {
          "all_proxy": "http://192.168.15.103:8888/",
          "https_proxy": "https://192.168.15.103:8888/",
          "http_proxy": "https://192.168.15.103:8888/"
      }
    }
]

如果未定义 http _proxy 或 https_proxy，则使用 all_proxy 值。

每个消息都添加了以下 RateLimit 标头：

默认情况下，当没有配置 Rate Limit Headers 策略或应用程序计划没有任何速率限值限制时，响应消息中没有速率限制标头。

这是路径为 /accounts 时路由到 http://example.com 的配置：

 {
    "name": "routing",
    "version": "builtin",
    "configuration": {
      "rules": [
        {
          "url": "http://example.com",
          "condition": {
            "operations": [
              {
                "match": "path",
                "op": "==",
                "value": "/accounts"
              }
            ]
          }
        }
      ]
    }
  }

这是当标头 Test-Header 的值为 123 时路由到 http://example.com 的配置 ：

 {
    "name": "routing",
    "version": "builtin",
    "configuration": {
      "rules": [
        {
          "url": "http://example.com",
          "condition": {
            "operations": [
              {
                "match": "header",
                "header_name": "Test-Header",
                "op": "==",
                "value": "123"
              }
            ]
          }
        }
      ]
    }
  }

这是当查询参数 test_query_arg 为 123 时路由到 http://example.com 的配置 ：

 {
    "name": "routing",
    "version": "builtin",
    "configuration": {
      "rules": [
        {
          "url": "http://example.com",
          "condition": {
            "operations": [
              {
                "match": "query_arg",
                "query_arg_name": "test_query_arg",
                "op": "==",
                "value": "123"
              }
            ]
          }
        }
      ]
    }
  }

若要基于 JWT 声明的值进行路由，链中需要有一个策略来验证 JWT 并将其存储在策略共享的上下文中。

这是当 JWT 声明 test_claim 的值为 123 时路由到 http://example.com 的配置 ：

 {
    "name": "routing",
    "version": "builtin",
    "configuration": {
      "rules": [
        {
          "url": "http://example.com",
          "condition": {
            "operations": [
              {
                "match": "jwt_claim",
                "jwt_claim_name": "test_claim",
                "op": "==",
                "value": "123"
              }
            ]
          }
        }
      ]
    }
  }

只有所有上游都评估为 true 时（使用 'and' combine_op），或者至少有一个规则被评估为 true（使用 'or' combine _op），规则可以有多个操作并路由到给定上游 。combine _op 的默认值为 'and'。

这是在请求的路径为 /accounts 以及标头 Test-Header 的值为 123 时路由到 http://example.com 的配置：

 {
    "name": "routing",
    "version": "builtin",
    "configuration": {
      "rules": [
        {
          "url": "http://example.com",
          "condition": {
            "combine_op": "and",
            "operations": [
              {
                "match": "path",
                "op": "==",
                "value": "/accounts"
              },
              {
                "match": "header",
                "header_name": "Test-Header",
                "op": "==",
                "value": "123"
              }
            ]
          }
        }
      ]
    }
  }

这是在请求的路径为 /accounts 或者标头 Test-Header 的值为 123 时路由到 http://example.com 的配置 ：

 {
    "name": "routing",
    "version": "builtin",
    "configuration": {
      "rules": [
        {
          "url": "http://example.com",
          "condition": {
            "combine_op": "or",
            "operations": [
              {
                "match": "path",
                "op": "==",
                "value": "/accounts"
              },
              {
                "match": "header",
                "header_name": "Test-Header",
                "op": "==",
                "value": "123"
              }
            ]
          }
        }
      ]
    }
  }

规则可以合并。当有多个规则时，上游选择是首批评估为 true 的规则之一。

这是包含多个规则的配置：

 {
    "name": "routing",
    "version": "builtin",
    "configuration": {
      "rules": [
        {
          "url": "http://some_upstream.com",
          "condition": {
            "operations": [
              {
                "match": "path",
                "op": "==",
                "value": "/accounts"
              }
            ]
          }
        },
        {
          "url": "http://another_upstream.com",
          "condition": {
            "operations": [
              {
                "match": "path",
                "op": "==",
                "value": "/users"
              }
            ]
          }
        }
      ]
    }
  }

没有操作的规则始终匹配。这对于定义概括性规则非常有用。

如果路径为 /abc，则此配置将请求路由到 http://some_upstream.com，如果路径是 /def，将请求路由到 http://another_upstream.com，最后，如果之前的规则没有评估为 true，则会将请求路由到 http://default_upstream.com ：

 {
    "name": "routing",
    "version": "builtin",
    "configuration": {
      "rules": [
        {
          "url": "http://some_upstream.com",
          "condition": {
            "operations": [
              {
                "match": "path",
                "op": "==",
                "value": "/abc"
              }
            ]
          }
        },
        {
          "url": "http://another_upstream.com",
          "condition": {
            "operations": [
              {
                "match": "path",
                "op": "==",
                "value": "/def"
              }
            ]
          }
        },
        {
          "url": "http://default_upstream.com",
          "condition": {
            "operations": []
          }
        }
      ]
    }
  }

支持的操作有 ==, != 和 match。后者将字符串与正则表达式匹配，并使用 ngx.re.match来实施

这是使用 != 的配置。当路径不是 /accounts 时，它会路由到 http://example.com：

 {
    "name": "routing",
    "version": "builtin",
    "configuration": {
      "rules": [
        {
          "url": "http://example.com",
          "condition": {
            "operations": [
              {
                "match": "path",
                "op": "!=",
                "value": "/accounts"
              }
            ]
          }
        }
      ]
    }
  }

可以将弹性模板用于配置的值。如果链中的策略将键 my_var 存储在上下文中，则可以使用动态值定义规则。

这是使用该值路由请求的配置：

 {
    "name": "routing",
    "version": "builtin",
    "configuration": {
      "rules": [
        {
          "url": "http://example.com",
          "condition": {
            "operations": [
              {
                "match": "header",
                "header_name": "Test-Header",
                "op": "==",
                "value": "{{ my_var }}",
                "value_type": "liquid"
              }
            ]
          }
        }
      ]
    }
  }

默认情况下，当路由请求时，策略使用匹配的规则的 URL 主机设置 Host 标头。可以通过 host_header 属性指定不同的主机。

这是将 some_host.com 指定为 Host 标头主机的配置：

 {
    "name": "routing",
    "version": "builtin",
    "configuration": {
      "rules": [
        {
          "url": "http://example.com",
          "host_header": "some_host.com",
          "condition": {
            "operations": [
              {
                "match": "path",
                "op": "==",
                "value": "/"
              }
            ]
          }
        }
      ]
    }
  }

APIcast 需要配置为终止 TLS。按照以下步骤配置用户在 APIcast 上提供的客户端证书验证策略。

要在您的策略链中配置 TLS 客户端证书验证，请执行以下操作：

要验证 TLS 客户端证书验证策略的功能，请执行以下操作：

curl https://api-3scale-apicast-staging.$WILDCARD_DOMAIN\?user_key\=[Your_user_key] -v --cacert ca/certs/ca.crt --cert ca/certs/client.crt --key ca/keys/client.key

curl https://api-3scale-apicast-staging.$WILDCARD_DOMAIN\?user_key\=[Your_user_key] -v --cacert ca/certs/ca.crt --cert ca/certs/server.crt --key ca/keys/server.key

curl https://api-3scale-apicast-staging.$WILDCARD_DOMAIN\?user_key\=[Your_user_key] -v --cacert ca/certs/ca.crt

要从白名单中删除证书，请执行以下操作：

有关使用证书的更多信息，请参阅 红帽认证系统。

本节介绍了在策略链中配置 TLS 终止的先决条件和步骤，以及增强保密邮件(PEM)格式的证书。

本节论述了从 TLS 终止策略中删除证书和密钥文件的步骤。

本节论述了在策略链中配置 Upstream Connection 策略的步骤。

本节论述了在策略链中配置 Upstream Mutual TLS 策略的步骤。

推进您的更改：

以下是命令列表中每个 命令的 配置参数，其中包括：

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

示例

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

应用以下转换：

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