Menu Close

3.6. 使用操作器部署 APIcast 网关自助管理解决方案

本指南提供了通过 Openshift Container Platform 控制台使用 APIcast operator 部署 APIcast 网关自助管理解决方案的步骤。

先决条件

  • OpenShift 容器平台(OCP)4.x 或更高版本,具有管理员特权。
  • 您将遵循 安装 APIcast operator 中的步骤。

流程

  1. 使用具有管理员特权的帐户登录 OCP 控制台。
  2. Operators > Installed Operators
  3. Installed Operators 列表中点 APIcast Operator
  4. APIcast > Create APIcast

3.6.1. APIcast 部署和配置选项

您可以使用两种方法部署和配置 APIcast 网关自我管理解决方案:

另请参阅:

3.6.1.1. 提供 3scale 系统端点

流程

  1. 创建一个包含 3scale 系统管理门户端点信息的 OpenShift secret:

    oc create secret generic ${SOME_SECRET_NAME} --from-literal=AdminPortalURL=${MY_3SCALE_URL}
    • ${SOME_SECRET_NAME} 是 secret 的名称,只要它与现有 secret 不冲突,可以是您想要的任何名称。
    • ${MY_3SCALE_URL} 是包含 3scale 访问令牌和 3scale 系统门户端点的 URI。如需了解更多详细信息,请参阅 THREESCALE_PORTAL_ENDPOINT

      示例

      oc create secret generic 3scaleportal --from-literal=AdminPortalURL=https://access-token@account-admin.3scale.net

      有关机密内容的更多信息,请参阅 管理门户配置 secret 参考。

  2. 为 APIcast 创建 OpenShift 对象

    apiVersion: apps.3scale.net/v1alpha1
    kind: APIcast
    metadata:
      name: example-apicast
    spec:
      adminPortalCredentialsRef:
        name: SOME_SECRET_NAME

    spec.adminPortalCredentialsRef.name 必须是包含 3scale 系统管理门户端点信息的现有 OpenShift secret 的名称。

  3. 确认与 APIcast 对象关联的 OpenShift Deployment 的 readyReplicas 字段是否为 1,以验证 APIcast 容器集正在运行并已就绪。或者,等待字段设置为:

    $ echo $(oc get deployment apicast-example-apicast -o jsonpath='{.status.readyReplicas}')
    1
3.6.1.1.1. 验证 APIcast 网关正在运行且可用

流程

  1. 确保 OpenShift Service APIcast 已公开给您的本地计算机,并执行测试请求。通过将 APIcast OpenShift Service 端口转发到 localhost:8080 来做到这一点:

    oc port-forward svc/apicast-example-apicast 8080
  2. 向配置的 3scale 服务发出请求,以验证 HTTP 响应是否成功。使用在服务的 Staging Public Base URLProduction Public Base URL 设置中配置的域名。例如:

    $ curl 127.0.0.1:8080/test -H "Host: myhost.com"
3.6.1.1.2. 通过 Kubernetes 入口公开 APIcast

要通过 Kubernetes Ingress 向外部公开 APIcast,请设置并配置 exposeHost 部分。当设置 exposeHost 部分中的 host 字段时,这会创建一个 Kubernetes Ingress 对象。然后,以前安装的和现有的 Kubernetes Ingress Controller 可以使用 Kubernetes Ingress 对象,使 APIcast 从外部访问。

要了解 Ingress Controller 可用于使 APIcast 外部访问,以及如何配置它们,请参阅 Kubernetes Ingress Controller 文档

以下示例使用主机名 myhostname.com 公开 APIcast:

apiVersion: apps.3scale.net/v1alpha1
kind: APIcast
metadata:
  name: example-apicast
spec:
  ...
  exposedHost:
    host: "myhostname.com"
  ...

这个示例使用 HTTP 在端口 80 上创建一个 Kubernetes Ingress 对象。当 APIcast 部署位于 OpenShift 环境中时,OpenShift 默认 Ingress Controller 将使用 Ingress 对象 APIcast 创建 Route 对象,以允许从外部访问 APIcast 安装。

您也可以为 exposeHost 部分配置 TLS。下表中可用字段的详情:

表 3.3. APIcastExposedHost 参考表

json/yaml 项Type必需默认值描述

主机

字符串

不适用

路由到网关的域名

tls

[]extensions.IngressTLS

不适用

ingress TLS 对象的数组。请参阅 TLS 的更多信息。

3.6.1.2. 提供配置 secret

流程

  1. 使用配置文件创建 secret:

    $ curl https://raw.githubusercontent.com/3scale/APIcast/master/examples/configuration/echo.json -o $PWD/config.json
    
    oc create secret generic apicast-echo-api-conf-secret --from-file=$PWD/config.json

    配置文件必须名为 config.json。这是一个 APIcast CRD 引用 要求。

    有关机密内容的更多信息,请参阅 管理门户配置 secret 参考。

  2. 创建 APIcast 自定义资源

    $ cat my-echo-apicast.yaml
    apiVersion: apps.3scale.net/v1alpha1
    kind: APIcast
    metadata:
      name: my-echo-apicast
    spec:
      exposedHost:
        host: YOUR DOMAIN
      embeddedConfigurationSecretRef:
        name: apicast-echo-api-conf-secret
    
    $ oc apply -f my-echo-apicast.yaml
    1. 以下是嵌入式配置 secret 的示例:

      apiVersion: v1
      kind: Secret
      metadata:
        name: SOME_SECRET_NAME
      type: Opaque
      stringData:
        config.json: |
          {
            "services": [
              {
                "proxy": {
                  "policy_chain": [
                    { "name": "apicast.policy.upstream",
                      "configuration": {
                        "rules": [{
                          "regex": "/",
                          "url": "http://echo-api.3scale.net"
                        }]
                      }
                    }
                  ]
                }
              }
            ]
          }
  3. 在创建 APIcast 对象时设置以下内容:

    apiVersion: apps.3scale.net/v1alpha1
    kind: APIcast
    metadata:
      name: example-apicast
    spec:
      embeddedConfigurationSecretRef:
        name: SOME_SECRET_NAME

    spec.embeddedConfigurationSecretRef.name 必须是包含网关配置的现有 OpenShift secret 的名称。

  4. 确认与 APIcast 对象关联的 OpenShift Deployment 的 readyReplicas 字段是否为 1,以验证 APIcast 容器集正在运行并已就绪。或者,等待字段设置为:

    $ echo $(oc get deployment apicast-example-apicast -o jsonpath='{.status.readyReplicas}')
    1
3.6.1.2.1. 验证 APIcast 网关正在运行且可用

流程

  1. 确保 OpenShift Service APIcast 已公开给您的本地计算机,并执行测试请求。通过将 APIcast OpenShift Service 端口转发到 localhost:8080 来做到这一点:

    oc port-forward svc/apicast-example-apicast 8080
  2. 向配置的 3scale 服务发出请求,以验证 HTTP 响应是否成功。使用在服务的 Staging Public Base URLProduction Public Base URL 设置中配置的域名。例如:

    $  curl 127.0.0.1:8080/test -H "Host: localhost"
    {
      "method": "GET",
      "path": "/test",
      "args": "",
      "body": "",
      "headers": {
        "HTTP_VERSION": "HTTP/1.1",
        "HTTP_HOST": "echo-api.3scale.net",
        "HTTP_ACCEPT": "*/*",
        "HTTP_USER_AGENT": "curl/7.65.3",
        "HTTP_X_REAL_IP": "127.0.0.1",
        "HTTP_X_FORWARDED_FOR": ...
        "HTTP_X_FORWARDED_HOST": "echo-api.3scale.net",
        "HTTP_X_FORWARDED_PORT": "80",
        "HTTP_X_FORWARDED_PROTO": "http",
        "HTTP_FORWARDED": "for=10.0.101.216;host=echo-api.3scale.net;proto=http"
      },
      "uuid": "603ba118-8f2e-4991-98c0-a9edd061f0f0"

3.6.1.3. 使用 APIcast operator 注入自定义虚拟环境

在使用自我管理的 APIcast 的 3scale 安装中,您可以使用 APIcast operator 注入自定义环境。自定义环境定义 APIcast 适用于网关服务的所有上游 API 的行为。要创建自定义环境,请在 Lua 代码中定义全局配置。

您可以注入自定义环境,作为 APIcast 安装的一部分或安装后。在注入自定义环境后,您可以将其删除,APIcast operator 会协调更改。

先决条件

  • 已安装 APIcast operator。

流程

  1. 编写用于定义您要注入的自定义环境的 Lua 代码。例如,以下 env1.lua 文件显示 APIcast operator 为所有服务加载的自定义日志策略。

    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 },
    }
  2. 从定义自定义环境的 Lua 文件创建 secret。例如:

    oc create secret generic custom-env-1 --from-file=./env1.lua

    secret 可以包含多个自定义虚拟环境。为定义自定义环境的每个文件指定 -from-file 选项。Operator 会加载每个自定义环境。

  3. 定义一个 APIcast 自定义资源,用于引用您刚才创建的 secret。以下示例显示了相对于引用定义自定义环境的 secret 的内容。

    apiVersion: apps.3scale.net/v1alpha1
    kind: APIcast
    metadata:
      name: apicast1
    spec:
      customEnvironments:
        - secretRef:
            name: custom-env-1

    APIcast 自定义资源可以引用定义自定义虚拟环境的多个 secret。Operator 会加载每个自定义环境。

  4. 创建 APIcast 自定义资源来添加自定义虚拟环境。例如,如果您在 apicast.yaml 文件中保存 APIcast 自定义资源,请运行以下命令:

    oc apply -f apicast.yaml

后续步骤

您无法更新定义自定义环境的 secret 的内容。如果您需要更新自定义环境,请更新定义自定义环境的 Lua 文件,然后执行以下操作之一:

  • 推荐的选项是使用不同的名称创建 secret,然后为您更新的自定义环境更新 APIcast 自定义资源字段 spec.customEnvironments[].secretRef.name。Operator 会触发滚动更新并加载更新的自定义环境。
  • 或者,您可以更新现存的 secret,把 spec.replicas 设置为 0 来重新部署 APIcast,然后将 spec.replicas 设置为以前的值来再次重新部署 APIcast。

3.6.1.4. 使用 APIcast operator 注入自定义策略

在使用自助管理的 APIcast 的 3scale 安装中,您可以使用 APIcast operator 注入自定义策略。注入自定义策略会将策略代码添加到 APIcast。然后,您可以使用以下任一策略将自定义策略添加到 API 产品策略链中:

  • 3scale API
  • 产品自定义资源

要使用 3scale 管理门户将自定义策略添加到产品策略链中,还必须使用 CustomPolicyDefinition 自定义资源注册自定义策略的 schema。自定义策略注册是只有在您要使用管理门户配置产品策略链时才需要。

您可以注入自定义策略,作为 APIcast 安装的一部分或之后。注入自定义策略后,您可以将其删除,并且 APIcast 运算符协调更改。

先决条件

  • APIcast operator 已安装,或正在安装它。
  • 您已定义一个自定义策略,如写您自己的策略中所述。即,已创建了定义自定义策略的 my-first-custom-policy.luaapicast-policy.jsoninit.lua 文件,

流程

  1. 从定义一个自定义策略的文件创建 secret。例如:

    oc create secret generic my-first-custom-policy-secret \
     --from-file=./apicast-policy.json \
     --from-file=./init.lua \
     --from-file=./my-first-custom-policy.lua

    如果您有多个自定义策略,请为每个自定义策略创建一个 secret。secret 只能包含一个自定义策略。

  2. 定义一个 APIcast 自定义资源,用于引用您刚才创建的 secret。以下示例显示有关引用定义自定义策略的 secret 的内容。

    apiVersion: apps.3scale.net/v1alpha1
    kind: APIcast
    metadata:
      name: apicast1
    spec:
      customPolicies:
        - name: my-first-custom-policy
          version: "0.1"
          secretRef:
            name: my-first-custom-policy-secret

    APIcast 自定义资源可以引用定义自定义策略的多个 secret。Operator 加载每个自定义策略。

  3. 创建 APIcast 自定义资源,以添加自定义策略。例如,如果您在 apicast.yaml 文件中保存 APIcast 自定义资源,请运行以下命令:

    oc apply -f apicast.yaml

后续步骤

您无法更新定义自定义策略的 secret 的内容。如果您需要更新自定义策略,更新其文件,然后执行以下操作之一:

  • 推荐的选项是使用不同的名称创建 secret,然后为您更新的自定义策略更新 APIcast 自定义资源字段 spec.customPolicies[].secretRef.name。Operator 会触发滚动更新并加载更新的自定义策略。
  • 或者,您可以更新现存的 secret,把 spec.replicas 设置为 0 来重新部署 APIcast,然后将 spec.replicas 设置为以前的值来再次重新部署 APIcast。

3.6.1.5. 使用 APIcast operator 配置 OpenTracing

在使用自助管理的 APIcast 的 3scale 安装中,您可以使用 APIcast operator 来配置 OpenTracing。通过启用 OpenTracing,您可以在 APIcast 实例上获得更深入的观察功能。

先决条件

流程

  1. 定义在 stringData.config 中包含您的 OpenTracing 配置详情的机密。这是包含 OpenTracing 配置详细信息的 属性的唯一有效值。任何其他规格都可防止 APIcast 接收您的 OpenTracing 配置详细信息。folowing 示例显示了一个有效的 secret 定义:

    apiVersion: v1
    kind: Secret
    metadata:
      name: myjaeger
    stringData:
      config: |-
          {
          "service_name": "apicast",
          "disabled": false,
          "sampler": {
            "type": "const",
            "param": 1
          },
          "reporter": {
            "queueSize": 100,
            "bufferFlushInterval": 10,
            "logSpans": false,
            "localAgentHostPort": "jaeger-all-in-one-inmemory-agent:6831"
          },
          "headers": {
            "jaegerDebugHeader": "debug-id",
            "jaegerBaggageHeader": "baggage",
            "TraceContextHeaderName": "uber-trace-id",
            "traceBaggageHeaderPrefix": "testctx-"
          },
          "baggage_restrictions": {
              "denyBaggageOnInitializationFailure": false,
              "hostPort": "127.0.0.1:5778",
              "refreshInterval": 60
          }
          }
    type: Opaque
  2. 创建 secret.例如,如果您在 myjaeger.yaml 文件中保存了之前的 secret 定义,您应该运行以下命令:

    oc create secret generic myjaeger --from-file myjaeger.yaml
  3. 定义 APIcast 自定义资源,该资源指定 OpenTracing 属性。在 CR 定义中,将 spec.tracingConfigSecretRef.name 属性设置为包含 OpenTracing 配置详情的 secret 的名称。下例仅显示与配置 OpenTracing 相关的内容。

    apiVersion: apps.3scale.net/v1alpha1
    kind: APIcast
    metadata:
      name: apicast1
    spec:
      ...
      openTracing:
        enabled: true
        tracingConfigSecretRef:
          name: myjaeger
        tracingLibrary: jaeger
    ...
  4. 创建 APIcast 自定义资源来配置 OpenTracing。例如,如果您在 apicast1.yaml 文件中保存 APIcast 自定义资源,您将运行以下命令:

    oc apply -f apicast1.yaml

后续步骤

根据 OpenTracing 的安装方式,您应该在 Jaeger 服务用户界面中看到 trace。