2.23. 使用 3scale WebAssembly 模块

Service Mesh 提供了一个自定义资源定义，用于为 sidecar 代理（称为 WasmPlugin ）指定并应用 Proxy-WASM 扩展。Service Mesh 将此自定义资源应用到需要使用 3scale 管理 HTTP API 的工作负载集合。

如需更多信息，请参阅自定义资源定义。

3scale WebAssembly 模块配置的架构取决于 3scale 帐户和授权服务，以及要处理的服务列表。

3scale WebAssembly 模块的 api 顶级字符串定义模块要使用的配置版本。

apiVersion: extensions.istio.io/v1alpha1
kind: WasmPlugin
metadata:
  name: <threescale_wasm_plugin_name>
  namespace: <info>
spec:
  pluginConfig:
    api: v1
# ...

api 条目定义配置的其余值。唯一接受的值是 v1。破坏与当前配置兼容性或需要更多使用 v1 的模块无法处理的逻辑的新设置将需要不同的值。

system 顶级对象指定如何访问特定帐户的 3scale 帐户管理 API。upstream 字段是对象最重要的部分。upstream 对象是可选的，但建议使用，除非您要为 3scale WebAssembly 模块提供完全静态的配置，如果您不想提供到 3scale 的 system 组件的连接，则此选项是一个选项。

当您在 system 对象之外提供静态配置对象时，静态配置对象始终优先。

apiVersion: extensions.istio.io/v1alpha1
kind: WasmPlugin
metadata:
  name: <threescale_wasm_plugin_name>
spec:
  pluginConfig:
    system:
      name: <saas_porta>
      upstream: <object>
      token: <my_account_token>
      ttl: 300
# ...

upstream 对象描述代理可以对其执行调用的外部主机。

apiVersion: maistra.io/v1
upstream:
  name: outbound|443||multitenant.3scale.net
  url: "https://myaccount-admin.3scale.net/"
  timeout: 5000
# ...

backend 顶级对象指定如何访问 3scale Service Management API 来授权和报告 HTTP 请求。此服务由 3scale 的 Backend 组件提供。

apiVersion: extensions.istio.io/v1alpha1
kind: WasmPlugin
metadata:
  name: <threescale_wasm_plugin_name>
spec:
  pluginConfig:
# ...
    backend:
      name: backend
      upstream: <object>
# ...

services 顶级对象指定由 module 的特定实例处理哪些服务标识符。

由于帐户具有多个服务，您必须指定处理哪些服务。其余的配置会围绕如何配置服务。

services 字段是必需的。它是必须至少包含一个服务的数组，才可使用。

apiVersion: extensions.istio.io/v1alpha1
kind: WasmPlugin
metadata:
  name: <threescale_wasm_plugin_name>
spec:
  pluginConfig:
# ...
    services:
    - id: "2555417834789"
      token: service_token
      authorities:
        - "*.app"
        - 0.0.0.0
        - "0.0.0.0:8443"
      credentials: <object>
      mapping_rules: <object>
# ...

services 数组中的每个元素代表 3scale 服务。

credentials 对象是 service 对象的组件。credentials 指定要查找的凭证类型，以及执行此操作的步骤。

所有字段均为可选，但您必须至少指定一个 user_key 或 app_id。指定每个凭据的顺序无关紧要，因为它由模块预先建立。仅指定每个凭证的一个实例。

apiVersion: extensions.istio.io/v1alpha1
kind: WasmPlugin
metadata:
  name: <threescale_wasm_plugin_name>
spec:
  pluginConfig:
# ...
    services:
    - credentials:
        user_key: <array_of_lookup_queries>
        app_id: <array_of_lookup_queries>
        app_key: <array_of_lookup_queries>
# ...

lookup query 对象是 credentials 对象中任何字段的一部分。它指定如何查找和处理给定凭证字段。评估之后，成功解析意味着找到一个或多个值。失败的解决方案意味着没有找到任何值。

lookup queries 的数组描述了一个短电路或关系：成功解析其中一个查询会停止评估任何剩余查询，并将值或值分配到指定的凭证类型。数组中的每个查询相互独立。

lookup queries 由单个字段（一个源对象）组成，它可以是多个源类型之一。请参见以下示例：

apiVersion: extensions.istio.io/v1alpha1
kind: WasmPlugin
metadata:
  name: <threescale_wasm_plugin_name>
spec:
  pluginConfig:
# ...
    services:
    - credentials:
        user_key:
          - <source_type>: <object>
          - <source_type>: <object>
# ...
        app_id:
          - <source_type>: <object>
# ...
        app_key:
          - <source_type>: <object>
# ...

source 对象作为任何 credentials 对象字段中的源数组的一部分存在。对象字段名称，称为 source 类型代表以下任意一个：

所有 source 类型对象至少具有以下两个字段：

filter 字段名称具有所需的 path 条目，用于显示用于查找数据的元数据中的路径。

当 key 与输入数据匹配时，不会评估其余的密钥，而且源解析算法会跳转到执行指定的操作（ops），如果存在。如果没有指定 ops，则返回匹配 key 的结果值（若有）。

Operations 提供了一种方式，用于您在第一阶段查找 key 后为输入指定某些条件和转换。当您需要转换、解码和断言属性时，请使用 Operations，但它们不提供成熟的语言来满足所有需求并缺少 Turing-completeness。

存储 operations 输出的堆栈。评估时，lookup query 通过在堆栈的底部分配值或值来完成，具体取决于凭据使用的值。

属于特定 source type 的 ops 数组中的每个元素都是 operation 对象，可以应用转换到值或执行测试。用于此类对象的字段名称是 operation 本身的名称，任何值都是 operation 的参数，可以是结构对象，例如，带有字段和值、列表或字符串的映射。

大多数 operation 都参与一个或多个输入，产生一个或多个输出。当它们消耗输入或生成输出时，它们与一个堆栈相关：操作消耗的每个值都从堆栈中弹出，最初填充任何 source 匹配。它们输出的值将推送到堆栈。其他 operations 没有使用或生成的输出不是声明的特定属性，但您检查值的堆栈。

有几个不同的 operations 类别：

所有操作都由名称标识符以字符串形式指定。

mapping_rules 对象是 service 对象的一部分。它指定一组 REST 路径模式和相关 3scale 指标，并在模式匹配时指定要使用的递增数。

如果 system 顶级对象中没有提供动态配置，则需要该值。如果对象在 system 顶级条目外提供，则首先评估 mapping_rules 对象。

mapping_rules 是一个数组对象。该数组的每个元素都是 mapping_rule 对象。传入请求上评估的匹配映射规则提供了一组 3scale methods，用于授权并向 APIManager 报告。当多个匹配规则指代相同的 methods 时，调用 3scale 时会有一个 deltas 的总结。例如，如果两个规则使用 deltas 1 和 3 将 Hits 方法增加两次，则报告至 3scale 的 Hits 的单一方法条目的 delta 为 4。

mapping_rule 对象是 mapping_rules 对象中的数组的一部分。

mapping_rule 对象字段指定以下信息：

以下示例独立于 3scale 中方法之间的现有层次结构。也就是说，在 3scale 侧运行的任何内容都不会受到影响。例如，Hits 指标可以是全部的父项，因此它存储了 4 个命中，因为授权请求中的所有报告方法总和，并调用 3scale Authrep API 端点。

以下示例使用到匹配所有规则的路径 /products/1/sold 的 GET 请求。

apiVersion: extensions.istio.io/v1alpha1
kind: WasmPlugin
metadata:
  name: <threescale_wasm_plugin_name>
spec:
  pluginConfig:
# ...
    mapping_rules:
      - method: GET
        pattern: /
        usages:
          - name: hits
            delta: 1
      - method: GET
        pattern: /products/
        usages:
          - name: products
            delta: 1
      - method: ANY
        pattern: /products/{id}/sold
        usages:
          - name: sales
            delta: 1
          - name: products
            delta: 1
# ...

所有 usages 都会添加到模块执行的请求中使用用量数据 3scale，如下所示：

以下示例在查询字符串参数或相同名称的标头中查找 user_key ：

apiVersion: extensions.istio.io/v1alpha1
kind: WasmPlugin
metadata:
  name: <threescale_wasm_plugin_name>
spec:
# ...
    services:
# ...
      credentials:
        user_key:
          - query_string:
              keys:
                - <user_key>
          - header:
              keys:
                - <user_key>
# ...

以下示例在查询或标头中查找 app_key 和 app_id 凭据。

apiVersion: extensions.istio.io/v1alpha1
kind: WasmPlugin
metadata:
  name: <threescale_wasm_plugin_name>
spec:
# ...
    services:
# ...
      credentials:
        app_id:
          - query_string:
              keys:
                - <app_id>
          - header:
              keys:
                - <app_id>
        app_key:
          - query_string:
              keys:
                - <app_key>
          - header:
              keys:
                - <app_key>
# ...

请求在 authorization 标头中包含 app_id 和 app_key。如果末尾至少输出了一个或两个值，您可以分配 app_key。

如果末尾输出了一两个或两个，此处的解决方法将分配 app_key。

authorization 标头使用授权类型指定值，其值编码为 Base64。这意味着，您可以通过空格字符来划分值，取第二个输出，然后使用冒号(:)作为分隔符再次分割它。例如，如果您使用这种格式 app_id:app_key，则标头类似以下示例 credential ：

aladdin:opensesame:  Authorization: Basic YWxhZGRpbjpvcGVuc2VzYW1l

您必须使用小写标头字段名称，如下例所示：

apiVersion: extensions.istio.io/v1alpha1
kind: WasmPlugin
metadata:
  name: <threescale_wasm_plugin_name>
spec:
# ...
    services:
# ...
      credentials:
        app_id:
          - header:
              keys:
                - authorization
              ops:
                - split:
                    separator: " "
                    max: 2
                - length:
                    min: 2
                - drop:
                    head: 1
                - base64_urlsafe
                - split:
                    max: 2
        app_key:
          - header:
              keys:
                - app_key
# ...

以上用例示例查看 authorization 标头：

assert，最后一个操作表示它使它进入堆栈没有副作用。然后您可以修改堆栈：

对于 Service Mesh 和 3scale Istio 适配器，您必须部署一个 RequestAuthentication，如下例所示，填入您自己的工作负载数据和 jwtRules:

apiVersion: security.istio.io/v1beta1
kind: RequestAuthentication
metadata:
  name: jwt-example
  namespace: info
spec:
  selector:
    matchLabels:
      app: productpage
  jwtRules:
  - issuer: >-
      http://keycloak-keycloak.34.242.107.254.nip.io/auth/realms/3scale-keycloak
    jwksUri: >-
      http://keycloak-keycloak.34.242.107.254.nip.io/auth/realms/3scale-keycloak/protocol/openid-connect/certs

应用 RequestAuthentication 时，它会使用原生插件配置 Envoy 以验证 JWT 令牌。代理会在运行模块前验证所有内容，因此任何失败的请求都不会将其发送到 3scale WebAssembly 模块。

验证 JWT 令牌时，代理将其内容存储在内部元数据对象中，其键取决于插件的具体配置。通过这个用例，您可以通过包含未知密钥名称的单一条目来查找结构对象。

OIDC 的 3scale app_id 与 OAuth client_id 匹配。这可在 JWT 令牌的 azp 或 aud 字段中找到。

要从 Envoy 的原生 JWT 身份验证过滤器获取 app_id 字段，请参阅以下示例：

apiVersion: extensions.istio.io/v1alpha1
kind: WasmPlugin
metadata:
  name: <threescale_wasm_plugin_name>
spec:
# ...
    services:
# ...
      credentials:
        app_id:
          - filter:
              path:
                - envoy.filters.http.jwt_authn
                - "0"
              keys:
                - azp
                - aud
              ops:
                - take:
                    head: 1
# ...

示例指示模块使用 filter 源类型从 Envoy特定的 JWT 身份验证原生插件中查找对象的过滤器元数据。此插件包含 JWT 令牌，作为具有单个条目和预配置名称的结构对象的一部分。使用 0 指定您将仅访问单个条目。

生成值是一个结构，您要解析以下两个字段：

该操作可确保仅保留一个值进行分配。

一些设置可能具有 JWT 令牌的验证流程，验证令牌可通过 JSON 格式的标头访问此模块。

要获得 app_id，请参阅以下示例：

apiVersion: extensions.istio.io/v1alpha1
kind: WasmPlugin
metadata:
  name: <threescale_wasm_plugin_name>
spec:
# ...
    services:
# ...
      credentials:
        app_id:
          - header:
              keys:
                - x-jwt-payload
              ops:
                - base64_urlsafe
                - json:
                  - keys:
                    - azp
                    - aud
                - take:
                    head: 1
# ,,,