OpenShift 文档正在迁移，不久后将仅在 docs.redhat.com（所有 Red Hat 产品文档的所在地）提供。立即体验 新的文档体验。
  1. 文档
    2. history bug_report picture_as_pdf
×

使用3scale Istio适配器

您正在查看不再受支持的Red Hat OpenShift服务网格版本的文档。

服务网格版本1.0和1.1控制平面不再受支持。有关升级服务网格控制平面的信息，请参见升级服务网格。

有关特定Red Hat OpenShift服务网格发行版的支持状态信息，请参见产品生命周期页面。

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

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

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

先决条件

  • Red Hat OpenShift Service Mesh 1.x 版本

  • 一个可用的 3scale 账户（SaaS 或 3scale 2.5 本地部署）

  • 启用后端缓存需要 3scale 2.9 或更高版本

  • Red Hat OpenShift Service Mesh 预备条件

要配置 3scale Istio 适配器，请参阅 Red Hat OpenShift Service Mesh 自定义资源，了解有关将适配器参数添加到自定义资源文件的说明。

特别注意 `kind: handler` 资源。您必须使用您的 3scale 账户凭据更新此资源。您可以选择向处理程序添加 `service_id`，但这仅为了向后兼容性而保留，因为它会使处理程序仅对 3scale 账户中的一个服务有用。如果您向处理程序添加 `service_id`，则要为其他服务启用 3scale，需要创建更多具有不同 `service_id` 的处理程序。

按照以下步骤，为每个 3scale 账户使用单个处理程序

步骤

  1. 为您的 3scale 账户创建一个处理程序，并指定您的账户凭据。省略任何服务标识符。

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

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

  2. 编辑或修补属于您的 3scale 账户的任何服务的 Deployment 资源，如下所示

    1. 添加标签 `"service-mesh.3scale.net/service-id"`，其值为有效的 `service_id`。

    2. 添加标签 `"service-mesh.3scale.net/credentials"`，其值为步骤 1 中的 *处理程序资源名称*。

  3. 每当您打算添加更多服务时，请执行步骤 2，将其链接到您的 3scale 账户凭据及其服务标识符。

  4. 使用您的 3scale 配置修改规则配置，以将规则分派到 threescale 处理程序。

    规则配置示例
      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

生成 3scale 自定义资源

该适配器包含一个工具，允许您生成 `handler`、`instance` 和 `rule` 自定义资源。

表 1. 用法
选项 描述 必填 默认值

-h, --help

显示可用选项的帮助输出

否

--name

此 URL 和 token 对的唯一名称

是

-n, --namespace

生成模板的命名空间

否

istio-system

-t, --token

3scale 访问令牌

是

-u, --url

3scale 管理门户 URL

是

--backend-url

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

否

-s, --service

3scale API/服务 ID

否

--auth

要指定的 3scale 身份验证模式 (1=API 密钥, 2=应用 ID/应用密钥, 3=OIDC)

否

混合

-o, --output

保存生成的清单的文件

否

标准输出

--version

输出 CLI 版本并立即退出

否

从 URL 示例生成模板

  • 通过 从已部署的适配器生成清单 中的 3scale 适配器容器镜像，通过 `oc exec` 运行以下命令。

  • 使用 `3scale-config-gen` 命令可以避免 YAML 语法和缩进错误。

  • 如果您使用注释，可以省略 `--service`。

  • 此命令必须通过 `oc exec` 从容器镜像内部调用。
步骤

  • 使用 `3scale-config-gen` 命令自动生成模板文件，允许多个服务共享 token 和 URL 对作为单个处理程序。

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

  • 以下示例生成在处理程序中嵌入服务 ID 的模板

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

从已部署的适配器生成清单

  • `NAME` 是您用来标识您正在使用 3scale 管理的服务的标识符。

  • `CREDENTIALS_NAME` 引用是与规则配置中的 `match` 部分对应的标识符。如果您使用 CLI 工具，则会自动将其设置为 `NAME` 标识符。

  • 它的值不需要是任何特定值：标签值只需与规则的内容匹配即可。有关更多信息，请参阅 通过适配器路由服务流量。

  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. 标记工作负载（推荐）

    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}"''

通过适配器路由服务流量

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

先决条件

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

步骤

  1. 匹配您之前在 `kind: rule` 资源的配置中创建的规则 `destination.labels["service-mesh.3scale.net/credentials"] == "threescale"`。

  2. 将上述标签添加到目标工作负载的 Deployment 上的 `PodTemplateSpec` 以集成服务。值 `threescale` 指的是生成的处理程序的名称。此处理程序存储调用 3scale 所需的访问令牌。

  3. 将标签 `destination.labels["service-mesh.3scale.net/service-id"] == "replace-me"` 添加到工作负载，以便在请求时通过实例将服务 ID 传递给适配器。

配置 3scale 中的集成设置

请按照此步骤配置 3scale 集成设置。

对于 3scale SaaS 客户，Red Hat OpenShift Service Mesh 作为抢先体验计划的一部分启用。
步骤

  1. 导航到 **[your_API_name]** → **集成**

  2. 点击 **设置**。

  3. 在 *部署* 下选择 **Istio** 选项。

    • 默认情况下选择 *身份验证* 下的 **API 密钥 (user_key)** 选项。

  4. 点击 **更新产品** 以保存您的选择。

  5. 点击 **配置**。

  6. 点击 **更新配置**。

缓存行为

3scale 系统 API 的响应默认情况下会在适配器中缓存。当条目超过 `cacheTTLSeconds` 值指定的时长时，它们将从缓存中清除。同样默认情况下，在缓存条目过期前 `cacheRefreshSeconds` 值指定的秒数，会尝试自动刷新缓存条目。可以通过将此值设置为高于 `cacheTTLSeconds` 值来禁用自动刷新。

可以通过将 `cacheEntriesMax` 设置为非正值来完全禁用缓存。

通过使用刷新流程，当缓存的主机不可达时，缓存值会在最终过期清除之前尝试重试。

请求认证

此版本支持以下认证方法

  • 标准 API 密钥：充当标识符和密钥令牌的单个随机字符串或哈希值。

  • 应用程序标识符和密钥对：不可变的标识符和可变的密钥字符串。

  • OpenID 认证方法：从 JSON Web 令牌中解析的客户端 ID 字符串。

应用认证模式

修改 `instance` 自定义资源，如以下认证方法示例所示，以配置认证行为。您可以从以下位置接收认证凭据：

  • 请求头

  • 请求参数

  • 请求头和查询参数

指定来自请求头的值时，必须是小写。例如，如果您想发送一个名为 `User-Key` 的请求头，则在配置中必须将其引用为 `request.headers["user-key"]`。

API 密钥认证方法

Service Mesh 会根据 `subject` 自定义资源参数中的 `user` 选项指定的规则，在查询参数和请求头中查找 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"]` 更改为 `request.query_params["key"]`。

应用程序 ID 和应用程序密钥对认证方法

Service Mesh 会根据 `subject` 自定义资源参数中的 `properties` 选项指定的规则，在查询参数和请求头中查找应用程序 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"]`。

OpenID 认证方法

要使用OpenID Connect (OIDC) 认证方法，请使用 `subject` 字段上的 `properties` 值来设置 `client_id`，并可选地设置 `app_key`。

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

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

为了使此集成正常工作，仍然必须在 3scale 中完成 OIDC，以便在身份提供者 (IdP) 中创建客户端。您应该为要在与该服务相同的命名空间中受保护的服务创建一个请求授权。JWT 通过请求的 `Authorization` 头传递。

在下面定义的示例 `RequestAuthentication` 中，请根据需要替换 `issuer`、`jwksUri` 和 `selector`。

OpenID策略示例
apiVersion: security.istio.io/v1beta1
kind: RequestAuthentication
metadata:
  name: jwt-example
  namespace: bookinfo
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

混合认证方法

您可以选择不强制执行特定的认证方法，并接受任何有效的凭据。如果同时提供了 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"] | ""

3scale 适配器指标

适配器默认情况下会报告各种 Prometheus 指标，这些指标在端口 `8080` 的 `/metrics` 端点上公开。这些指标提供了对适配器和 3scale 之间交互性能的洞察。该服务被标记为可被 Prometheus 自动发现和抓取。

3scale Istio 适配器验证

您可能需要检查 3scale Istio 适配器是否按预期工作。如果您的适配器无法工作，请使用以下步骤来帮助排除问题。

步骤

  1. 确保 *3scale-adapter* pod 正在 Service Mesh 控制平面命名空间中运行

    $ oc get pods -n istio-system

  2. 检查 *3scale-adapter* pod 是否已打印出有关其启动的信息，例如其版本

    $ oc logs istio-system

  3. 在对受 3scale 适配器集成保护的服务执行请求时，始终尝试缺少正确凭据的请求并确保它们失败。检查 3scale 适配器日志以收集更多信息。

其他资源

3scale Istio 适配器故障排除清单

作为安装 3scale Istio 适配器的管理员，可能有多种情况会导致您的集成无法正常运行。使用以下列表来排除安装故障

  • YAML 缩进错误。

  • 缺少 YAML 部分。

  • 忘记将 YAML 中的更改应用到集群。

  • 忘记使用 `service-mesh.3scale.net/credentials` 密钥标记服务工作负载。

  • 当使用不包含 `service_id` 的处理程序时（以便它们可以跨帐户重用），忘记使用 `service-mesh.3scale.net/service-id` 标记服务工作负载。

  • 规则自定义资源指向错误的处理器或实例自定义资源，或者引用缺少相应的命名空间后缀。

  • 规则自定义资源的match部分无法匹配您正在配置的服务，或者它指向当前未运行或不存在的目标工作负载。

  • 处理器中3scale管理门户的访问令牌或URL错误。

  • 实例自定义资源的params/subject/properties部分未能列出app_id、app_key或client_id的正确参数，原因可能是它们指定了错误的位置（例如查询参数、标头和授权声明），或者参数名称与用于测试的请求不匹配。

  • 未能使用配置生成器，而没有意识到它实际上位于适配器容器镜像中，需要使用oc exec来调用它。