第 7 章 3scale 适配器

7.1. 使用 3scale Istio 适配器

3scale Istio 适配器是一个可选适配器，允许您在 Red Hat OpenShift Service Mesh 中标记运行的服务，并将该服务与 3scale API 管理解决方案集成。Red Hat OpenShift Service Mesh 不需要该适配器。

7.1.1. 将 3scale 适配器与 Red Hat OpenShift Service Mesh 集成

您可以使用这些示例来配置对使用 3scale Istio 适配器的服务的请求。

先决条件

  • Red Hat OpenShift Service Mesh 0.12.0+
  • 一个有效的 3scale 账户 (SaaS 或 3scale 2.5 On-Premises)
  • Red Hat OpenShift Service Mesh 的先决条件
  • 启用了 Mixer 强制功能。“更新 Mixer 策略强制”部分提供了检查当前 Mixer 策略实施状态和启用策略强制状态的信息。
注意

要配置 3scale Istio 适配器，请参考“Red Hat OpenShift Service Mesh 自定义资源”来获得在自定义资源文件中添加适配器参数的说明。

注意

请特别注意 kind: handler 资源。您必须使用 3scale 凭据和您要管理的 API 服务 ID 更新此功能。

  1. 使用 3scale 配置修改处理器配置。

    处理器配置示例

      apiVersion: "config.istio.io/v1alpha2"
  kind: handler
  metadata:
   name: threescale
  spec:
   adapter: threescale
   params:
     service_id: "<SERVICE_ID>"
     system_url: "https://<organization>-admin.3scale.net/"
     access_token: "<ACCESS_TOKEN>"
   connection:
     address: "threescale-istio-adapter:3333"

您可以选择在 params 部分提供一个 backend_url 字段来覆盖 3scale 配置提供的 URL。如果适配器与 3scale 内部实例在同一集群中运行，且您希望利用内部集群 DNS，这可能很有用。

  1. 用 3scale 配置来修改规则配置，将规则发送到 3scale 处理器。

    规则配置示例

      apiVersion: "config.istio.io/v1alpha2"
  kind: rule
  metadata:
    name: threescale
  spec:
    match: destination.labels["service-mesh.3scale.net"] == "true"
    actions:
      - handler: threescale.handler
        instances:
          - threescale-authorization.instance

7.1.1.1. 生成 3scale 自定义资源

适配器包括了一个可以用来生成 handler、instance 和 rule 自定义资源的工具。

表 7.1. 使用方法

选项描述必需的默认值

-h, --help

显示可用选项的帮助信息

不是

 

--name

这个 URL 的唯一名称，令牌对

是

 

-n, --namespace

生成模板的命名空间

不是

istio-system

-t, --token

3scale 访问令牌

是

 

-u, --url

3scale Admin Portal URL

是

 

--backend-url

3scale 后端 URL。如果设定，它会覆盖从系统配置中读取的值。

不是

 

-s, --service

3scale API/Service ID

不是

 

--auth

3scale 的认证方法（1=Api Key, 2=App Id/App Key, 3=OIDC）

不是

混合

-o, --output

保存产生的清单的文件

不是

标准输出

--version

输出 CLI 版本并立即退出

不是

 
7.1.1.1.1. 从 URL 示例生成模板

  • 这个示例生成模板，允许多个服务作为单一处理器共享令牌， URL 对： 

    $ 3scale-gen-config --name=admin-credentials --url="https://<organization>-admin.3scale.net:443" --token="[redacted]"

  • 这个示例生成带有内嵌在处理器中的服务 ID 的模板： 

    $ 3scale-gen-config --url="https://<organization>-admin.3scale.net" --name="my-unique-id" --service="123456789" --token="[redacted]"

7.1.1.2. 从部署的适配器生成清单

  1. 运行这个命令从在 istio-system命名空间中部署的适配器生成清单： 

    $ export NS="istio-system" URL="https://replaceme-admin.3scale.net:443" NAME="name" TOKEN="token"
oc exec -n ${NS} $(oc get po -n ${NS} -o jsonpath='{.items[?(@.metadata.labels.app=="3scale-istio-adapter")].metadata.name}') \
-it -- ./3scale-config-gen \
--url ${URL} --name ${NAME} --token ${TOKEN} -n ${NS}
  2. 这将在终端中输出示例。如果需要，请编辑这些样本，并使用 oc create 命令创建对象。

  3. 当请求到达适配器时，适配器需要知道服务如何被映射到一个 3scale 中的 API。您可以以两种方式提供这个信息：

    1. 标记（label）工作负载（推荐）
    2. 硬编码处理器为 service_id

  4. 使用所需注解更新工作负载：

    注意

    如果服务 ID 没有被嵌入到处理器中，您只需要更新本示例中的服务 ID。处理器中的设置会优先使用。 

    $ export CREDENTIALS_NAME="replace-me"
export SERVICE_ID="replace-me"
export DEPLOYMENT="replace-me"
patch="$(oc get deployment "${DEPLOYMENT}"
patch="$(oc get deployment "${DEPLOYMENT}" --template='{"spec":{"template":{"metadata":{"labels":{ {{ range $k,$v := .spec.template.metadata.labels }}"{{ $k }}":"{{ $v }}",{{ end }}"service-mesh.3scale.net/service-id":"'"${SERVICE_ID}"'","service-mesh.3scale.net/credentials":"'"${CREDENTIALS_NAME}"'"}}}}}' )"
oc patch deployment "${DEPLOYMENT}" --patch ''"${patch}"''

7.1.1.3. 通过适配器的路由服务流量

按照以下步骤，通过 3scale 适配器为您的服务驱动流量。

先决条件

  • 3scale 管理员的凭据和服务 ID。

流程

  1. 匹配在以前创建的配置中的 destination.labels["service-mesh.3scale.net/credentials"] == "threescale"（在 kind: rule 资源中）。
  2. 在部署目标负载时为 PodTemplateSpec添加上面的标签以集成服务 。threescale是生成的处理器的名称。这个处理器存储了调用 3scale 所需的访问令牌。
  3. 为工作负载添加 destination.labels["service-mesh.3scale.net/service-id"] == "replace-me" 标签，以便在请求时通过实例将服务 ID 传递给适配器。

7.1.2. 在 3scale 中配置集成设置

按照以下步骤配置 3scale 集成设置。

注意

对于 3scale SaaS 客户，Red Hat OpenShift Service Mesh 作为 Early Access 项目的一部分被启用。

流程

  1. 进入 [your_API_name] → Integration → Configuration。
  2. 点 Integration 页右上角的 edit integration settings。
  3. 在 Service Mesh 标题下，点 Istio 选项。
  4. 滚动到页面底部并点击 Update Service。

7.1.3. 缓存行为

在适配器中，来自 3scale System API 的响应会被默认缓存。当条目存在的时间超过 cacheTTLSeconds 所指定的值时，条目会从缓存清除 。另外，默认情况下，根据cacheRefreshSeconds 的值，在缓存的条目过期前会尝试进行自动刷新。您可以通过设置高于 cacheTTLSeconds 的值来禁用自动刷新。

把 cacheEntriesMax 设置为一个非正数的值可以完全禁用缓存。

通过使用刷新功能，那些代表已无法访问的主机的缓存项，会在其过期并最终被删除前重新尝试进行检索。

7.1.4. 身份验证请求

这个发行版本支持以下验证方法：

  • 标准 API 键：使用一个随机字符串或哈希值作为标识符和 secret 令牌。
  • 应用程序标识符和键对：不可改变的标识符和可变的密键字符串。
  • OpenID 验证方法：从 JSON Web Token 解析的客户端 ID 字符串。

7.1.4.1. 应用验证模式

如以下验证方法示例所示，修改 instance 自定义资源来配置身份验证的方法。您可以接受以下身份验证凭证：

  • 请求的标头（header）
  • 请求参数
  • 请求标头和查询参数
注意

当通过标头指定值时，必须为小写。例如，如果需要发送一个标头为 User-Key，则需要在配置中使用 request.headers["user-key"] 来指代它。

7.1.4.1.1. API 键验证方法

根据在 subject 自定义资源参数的 user 选项，Service Mesh 在查询参数和请求标头中查找 API 键。它会按照自定义资源文件中给出的顺序检查这些值。您可以通过跳过不需要的选项，把对 API 键的搜索限制为只搜索查询参数或只搜索请求标头。

在这个示例中，Service Mesh 在 user_key 查询参数中查找 API 键。如果 API 键不在查询参数中，Service Mesh 会检查 user-key 标头。

API 键验证方法示例

apiVersion: "config.istio.io/v1alpha2"
kind: instance
metadata:
  name: threescale-authorization
  namespace: istio-system
spec:
  template: authorization
  params:
    subject:
      user: request.query_params["user_key"] | request.headers["user-key"] | ""
    action:
      path: request.url_path
      method: request.method | "get"

如果您希望适配器检查不同的查询参数或请求标头，请根据情况更改名称。例如：要在名为 "key" 的查询参数中检查 API 键，把 request.query_params["user_key"] 改为 query_params["key"]。

7.1.4.1.2. 应用程序 ID 和应用程序键对验证方法

根据 subject 自定义资源参数中的 properties 选项，Service Mesh 在查询参数和请求标头中查找应用程序 ID 和应用程序键。应用程序键是可选的。它会按照自定义资源文件中给出的顺序检查这些值。通过不使用不需要的选项，可以将搜索凭证限制为只搜索查询参数或只搜索请求标头。

在这个示例中，Service Mesh 会首先在查询参数中查找应用程序 ID 和应用程序键，如果需要，再对请求标头进行查找。

应用程序 ID 和应用程序键对验证方法示例

apiVersion: "config.istio.io/v1alpha2"
kind: instance
metadata:
  name: threescale-authorization
  namespace: istio-system
spec:
  template: authorization
  params:
    subject:
        app_id: request.query_params["app_id"] | request.headers["app-id"] | ""
        app_key: request.query_params["app_key"] | request.headers["app-key"] | ""
    action:
      path: request.url_path
      method: request.method | "get"

如果您希望适配器检查不同的查询参数或请求标头，请根据情况更改名称。例如，要在名为 identification 的查询参数中查找应用程序 ID，把 request.query_params["app_id"] 改为 request.query_params["identification"]。

7.1.4.1.3. OpenID 验证方法

要使用 OpenID Connect (OIDC) 验证方法，使用 subject 字段中的 properties 值设定 client_id 及可选的 app_key。

您可以使用前面描述的方法操作这个对象。在下面的示例配置中，客户标识符（应用程序 ID）是从标签 azp 下的 JSON Web Token (JWT) 解析出来的。您可以根据需要修改它。

OpenID 验证方法示例

  apiVersion: "config.istio.io/v1alpha2"
  kind: instance
  metadata:
    name: threescale-authorization
  spec:
    template: threescale-authorization
    params:
      Subject:
  properties:
          app_key: request.query_params["app_key"] | request.headers["app-key"] | ""
          client_id: request.auth.claims["azp"] | ""
      action:
        path: request.url_path
        method: request.method | "get"
          service: destination.labels["service-mesh.3scale.net/service-id"] | ""

要使这个集成服务可以正常工作，OIDC 必须在 3scale 中完成，以便客户端在身份提供者 (IdP) 中创建。您应该为需要保护的服务在相同的命名空间内创建最终用户验证 。JWT 由请求的 Authorization 标头传递。

在下面定义的 Policy 示例中，根据情况替换 issuer 和 jwksUri。

OpenID 策略示例

  apiVersion: authentication.istio.io/v1alpha1
  kind: Policy
  metadata:
    name: jwt-example
    namespace: bookinfo
  spec:
    origins:
      - jwt:
          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
    principalBinding: USE_ORIGIN
    targets:
      - name: productpage

7.1.4.1.4. 混合验证方法

您可以选择不强制使用一个特定的验证方法，而是接受任何有效的凭证。如果 API 键和应用程序 ID/应用程序键对都被提供，则 Service Mesh 会使用 API 键。

在这个示例中，Service Mesh 在查询参数中检查一个 API 键，然后是请求标头。如果没有 API 键，则会在查询参数中检查应用程序 ID 和键，然后查询请求标头。

混合验证方法示例

apiVersion: "config.istio.io/v1alpha2"
kind: instance
metadata:
  name: threescale-authorization
spec:
  template: authorization
  params:
    subject:
      user: request.query_params["user_key"] | request.headers["user-key"] |
      properties:
        app_id: request.query_params["app_id"] | request.headers["app-id"] | ""
        app_key: request.query_params["app_key"] | request.headers["app-key"] | ""
        client_id: request.auth.claims["azp"] | ""
    action:
      path: request.url_path
      method: request.method | "get"
        service: destination.labels["service-mesh.3scale.net/service-id"] | ""

7.1.5. 3scale Adapter 指标数据

在默认情况下，适配器默会通过 /metrics 端点的端口 8080 提供各种 Prometheus 指标数据。这些指标可让您了解适配器和 3scale 之间的交互是如何执行的。该服务被标记为由 Prometheus 自动发现和弃用。