1.14. 使用 3scale Istio 适配器

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

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

先决条件

Red Hat OpenShift Service Mesh 版本 1.x
一个有效的 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 更新此功能。

使用 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，这可能很有用。

用 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

1.14.1.1. 生成 3scale 自定义资源

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

表 1.13. 使用方法
选项	描述	必需的	默认值
`-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 版本并立即退出	不是

1.14.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]"

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

运行这个命令从在 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}

这将在终端中输出示例。如果需要，请编辑这些样本，并使用 oc create 命令创建对象。
当请求到达适配器时，适配器需要知道服务如何被映射到一个 3scale 中的 API。您可以以两种方式提供这个信息：
1. 标记（label）工作负载（推荐）
2. 硬编码处理器为 service_id

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

注意

如果服务 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}"''

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

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

先决条件

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

流程

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

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

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

注意

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

流程

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

1.14.3. 缓存行为

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

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

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

1.14.4. 身份验证请求

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

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

1.14.4.1. 应用验证模式

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

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

注意

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

1.14.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"]。

1.14.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"]。

1.14.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

1.14.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"] | ""

1.14.5. 3scale Adapter 指标数据

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