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


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

部署 APIcast 时,默认设置适用于生产环境。您始终可以调整这些设置来部署 staging 环境。例如,使用以下 oc 命令:

$ oc patch apicast/{apicast_name} --type=merge -p '{"spec":{"deploymentEnvironment":"staging","configurationLoadMode":"lazy"}}'

如需更多信息,请参阅:APIcast 自定义资源参考

先决条件

流程

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

3.5.1. APIcast 部署和配置选项

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

另请参阅:

3.5.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.5.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: 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.5.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 项类型必填默认值描述

主机

字符串

N/A

路由到网关的域名

tls

[]networkv1.IngressTLS

N/A

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

3.5.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.5.1.2.1. 验证 APIcast 网关正在运行且可用

流程

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

    $ oc port-forward svc/apicast-example-apicast 8080

3.5.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,以便 secret 包含更新。APIcast operator 会监视是否有更新,并在找到更新时自动重新部署。

3.5.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 operator 会监视是否有更新,并在找到更新时自动重新部署。

3.5.1.5. 使用 APIcast operator 配置 OpenTracing

在使用自助管理的 APIcast 的 3scale 安装中,您可以使用 APIcast operator 来配置 OpenTracing。通过启用 OpenTracing,您可以在 APIcast 实例上获取更多见解和更好的可观察性。

先决条件

流程

  1. stringData.config 中包含您的 OpenTracing 配置详情的 secret。这是包含您的 OpenTracing 配置详细信息的属性的唯一有效值。任何其他规格都阻止 APIcast 收到您的 OpenTracing 配置详细信息。以下示例显示了一个有效的 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.例如,如果您将以前的 secret 定义保存到 myjaeger.yaml 文件中,您将运行以下命令:

    $ oc create -f 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. 创建配置 OpenTracing 的 APIManager 自定义资源。例如,如果您将 APIcast 自定义资源保存在 apicast1.yaml 文件中,您将运行以下命令:

    $ oc apply -f apicast1.yaml

后续步骤

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

Red Hat logoGithubRedditYoutubeTwitter

学习

尝试、购买和销售

社区

关于红帽文档

通过我们的产品和服务,以及可以信赖的内容,帮助红帽用户创新并实现他们的目标。

让开源更具包容性

红帽致力于替换我们的代码、文档和 Web 属性中存在问题的语言。欲了解更多详情,请参阅红帽博客.

關於紅帽

我们提供强化的解决方案,使企业能够更轻松地跨平台和环境(从核心数据中心到网络边缘)工作。

© 2024 Red Hat, Inc.