安装 3scale

Red Hat 3Scale 2-saas

安装和配置 3scale API 管理。

摘要

本指南提供用于安装和配置 3scale API 管理的信息。

前言

本指南将帮助您安装和配置 3scale

使开源包含更多

红帽致力于替换我们的代码、文档和 Web 属性中存在问题的语言。我们从这四个术语开始:master、slave、黑名单和白名单。由于此项工作十分艰巨,这些更改将在即将推出的几个发行版本中逐步实施。详情请查看我们的 CTO Chris Wright 信息

第 1 章 3scale 的 registry 服务帐户

要在带有 3scale 2-saas 的共享环境中使用 registry.redhat.io 中的容器镜像,您必须使用 Registry 服务帐户而不是单独的用户的客户门户网站 凭证。

要创建和修改 registry 服务帐户,请执行以下部分中所述的步骤:

1.1. 创建 registry 服务帐户

要创建 registry 服务帐户,请按照以下步骤操作。

流程

  1. 进入 Registry Service Accounts 页面并登录。
  2. New Service Account
  3. Create a New Registry Service Account 页面上填写表单。

    1. 服务帐户 添加名称。

      :您将在表单字段前面看到一个固定长度、随机生成的数字字符串。

    2. 输入 描述
    3. Create
  4. 切回到您的 服务帐户
  5. 您创建的 服务帐户。
  6. 记录用户名,包括前缀字符串,如 12345678|username 和您的密码。此用户名和密码将用于登录 registry.redhat.io
注意

Token Information 页面中提供了相应的选项卡,用于显示如何使用身份验证令牌。例如,Token Information 选项卡显示格式为 12345678|username 的用户名,其下的密码字符串为。

1.2. 配置容器 registry 身份验证

作为 3scale 管理员,在 OpenShift 中部署 3scale 之前,使用 registry.redhat.io 配置身份验证。

先决条件

  • 具有管理员凭证的 Red Hat OpenShift Container Platform (OCP) 帐户。
  • 已安装 OpenShift oc 客户端工具。如需了解更多详细信息,请参阅 OpenShift CLI 文档

流程

  1. 以管理员身份登录您的 OpenShift 集群:

    $ oc login -u system:admin
  2. 打开您要在其中部署 3scale 的项目:

    oc project your-openshift-project
  3. 使用您的红帽客户门户网站帐户创建一个 docker-registry secret,将 threescale-registry-auth 替换为要创建的 secret:

    $ oc create secret docker-registry threescale-registry-auth \
      --docker-server=registry.redhat.io \
      --docker-username="customer_portal_username" \
      --docker-password="customer_portal_password" \
      --docker-email="email_address"

    您将看到以下输出:

    secret/threescale-registry-auth created
  4. 将机密链接到您的服务帐户,以使用机密拉取镜像。服务帐户名称必须与 OpenShift 容器集使用的名称匹配。这个示例使用 default 服务帐户:

    $ oc secrets link default threescale-registry-auth --for=pull
  5. 将 secret 链接到 builder 服务帐户,以使用 secret 推送和拉取构建镜像:

    $ oc secrets link builder threescale-registry-auth

其他资源

有关向容器镜像进行身份验证的更多详情:

1.3. 修改 registry 服务帐户

您可以使用表中每个身份验证令牌右侧的弹出菜单,从 Registry Service Account 页面编辑或删除服务帐户。

警告

重新生成或删除 服务帐户 会影响使用该令牌对 registry.redhat.io 进行身份验证和检索内容的系统。

每个功能的描述如下:

  • 重新生成令牌:允许授权用户重置与服务帐户关联的 密码

    备注:您无法修改服务帐户的用户名

  • 更新描述:允许授权用户更新服务帐户的描述。
  • 删除帐户:允许授权用户删除服务帐户

1.4. 其他资源

第 2 章 安装 APIcast

APIcast 是基于 NGINX 的 API 网关,用于将您的内部和外部 API 服务与 Red Hat 3scale Platform 集成。APIcast 利用循环实现负载平衡。

在本指南中,您将了解部署选项、提供的环境以及如何入门。

先决条件

APIcast 不是独立的 API 网关。需要连接到 3scale API Manager。

  • 3scale 托管帐户。

要安装 APIcast,请执行以下部分中所述的步骤:

2.1. APIcast 部署选项

您可以使用托管或自我管理的 APIcast。在这两种情况下,APIcast 必须连接到 3scale API 管理平台的其余部分:

  • 托管 APIcast :3scale 在云环境中托管 APIcast。在这种情况下,APIcast 已为您部署,它每天有 50,000 个调用的限制。
  • 自我管理的 APIcast :您可以随时随地部署 APIcast。以下是部署 APIcast 的几个推荐选项:

2.2. APIcast 环境

默认情况下,当您创建 3scale 帐户或创建新 API 服务时,您将获得在两个不同的环境中 托管的 APIcast:

  • Staging:仅在配置和测试 API 集成时使用。当您确认您的设置按预期工作时,您可以选择将其部署到生产环境中。
  • Production:每天限制为 50,000 个调用,并支持以下开箱即用的身份验证选项:API 密钥、应用程序 ID 和应用程序密钥对 OpenID Connect。

使用自助管理部署时,您仍然具有相同的两个环境,您需要为每个环境部署 APIcast 实例。您可以通过设置环境变量 THREESCALE_DEPLOYMENT_ENV(值为 stagingproduction) 来指定 APIcast 实例将要使用哪个配置(Staging 或 Production)。

2.3. 配置集成设置

作为 3scale 管理员,配置运行 3scale 的环境的集成设置。

先决条件

具有管理员特权的 3scale 帐户。

流程

  1. 进入 [Your_API_name] > Integration > Settings
  2. Deployment 中,默认选项如下:

    • 部署选项:托管的 APIcast
    • 身份验证模式:API 密钥。
  3. 更改到您首选的选项。
  4. 要保存您的更改,请点击 Update Product

2.4. 配置服务

您必须在 Private Base URL 字段中声明您的 API 后端,这是 API 后端的端点主机。在处理了所有身份验证、授权、速率限值和统计数据后,APIcast 将所有流量重定向到您的 API 后端。

本节将指导您配置服务:

2.4.1. 声明 API 后端

通常,您的 API 的私有基本 URL 将会像 https://api-backend.yourdomain.com:443 一样在您管理的域中(yourdomain.com)。例如,如果您与 Twitter API 集成,则私有基本 URL 为 https://api.twitter.com/

在本例中,您将使用 3scale 托管的 Echo API,它是一个简单的 API,接受任何路径并返回有关请求的信息(路径、请求参数、标头等)。其专用基础 URL 是 https://echo-api.3scale.net:443

流程

  • 测试您的私有(非受管)API 是否正常工作。例如,对于 Echo API,您可以使用 curl 命令进行以下调用:

    curl "https://echo-api.3scale.net:443"

    您将获得以下响应:

    {
        "method": "GET",
        "path": "/",
        "args": "",
        "body": "",
        "headers": {
          "HTTP_VERSION": "HTTP/1.1",
          "HTTP_HOST": "echo-api.3scale.net",
          "HTTP_ACCEPT": "*/*",
          "HTTP_USER_AGENT": "curl/7.51.0",
          "HTTP_X_FORWARDED_FOR": "2.139.235.79, 10.0.103.58",
          "HTTP_X_FORWARDED_HOST": "echo-api.3scale.net",
          "HTTP_X_FORWARDED_PORT": "443",
          "HTTP_X_FORWARDED_PROTO": "https",
          "HTTP_FORWARDED": "for=10.0.103.58;host=echo-api.3scale.net;proto=https"
        },
        "uuid": "ee626b70-e928-4cb1-a1a4-348b8e361733"
      }

2.4.2. 配置身份验证设置

您可以在 [Your_product_name] > Integration > SettingsAUTHENTICATION 部分中为 API 配置身份验证设置。

表 2.1. 可选的身份验证字段

字段描述

Auth user key

设置与凭据位置关联的用户密钥。

Credentials location

定义凭据是作为 HTTP 标头、查询参数还是 HTTP 基本身份验证传递。

Host Header

定义自定义主机请求标头。如果您的 API 后端仅接受来自特定主机的流量,则需要此设置。

Secret Token

用于阻止开发人员向 API 后端发出请求。设置此处标头的值,并确保您的后端只允许使用此机密标头调用。

另外,您可以在 [Your_product_name] > Integration > Settings 下配置 GATEWAY RESPONSE 错误代码。为错误定义 Response CodeContent-typeResponse Body:身份验证失败、缺少身份验证和不匹配。

表 2.2. 响应代码和默认响应正文

响应代码响应正文

403

身份验证失败

403

缺少身份验证参数

404

没有匹配的映射规则

429

超过用量限制

2.4.3. 配置 API 测试调用

配置 API 涉及使用产品测试后端,并将 APIcast 配置提升到暂存和生产环境,以根据请求调用进行测试。

对于每个产品,请求会根据路径重定向到对应的后端。当您将后端添加到产品时会配置这个路径。例如,如果您在某个产品中添加了两个后端,每个后端都有自己的路径。

先决条件

流程

  1. 进入到 [Your_product_name] > Integration > Configuration,将 APIcast 配置提升到 Staging。
  2. APIcast 配置 下,您将看到添加到产品的每个后端的映射规则。点 Promote v.[n] to Staging APIcast

    • v.[n] 表示要提升的版本号。
  3. 提升到暂存后,您可以将其提升为 Production。在 Staging APIcast 下,点 Promote v.[n] to Production APIcast

    • v.[n] 表示要提升的版本号。
  4. 要在命令行中测试对您的 API 的请求,请使用用于测试的curl 示例中提供的命令。

    • curl 命令示例基于产品中的第一个映射规则。

在测试对 API 的请求时,您可以通过添加方法和指标来修改映射规则

每次修改配置时,并在调用 API 之前,请确保提升到 Staging 和 Production 环境。当要提升到 Staging 环境的待处理更改时,您会在管理门户中看到一个声明标记,它位于 Integration 菜单项的旁边。

3scale Hosted APIcast 网关进行凭证验证,并应用您为 API 应用计划定义的速率限制。如果您在没有凭证的调用或具有无效凭证的调用,您会看到出错信息,Authentication failed

2.5. 安装 APIcast Operator

本指南提供通过 OpenShift Container Platform(OCP)控制台安装 APIcast Operator 的步骤。

流程

  1. 使用具有管理员特权的帐户登录 OCP 控制台。
  2. Projects > Create Project 中创建新项目 operator-test
  3. Operators > Installed Operators
  4. Filter by keyword 框中键入 apicast 以查找 APIcast operator。不要使用社区版本。
  5. 单击 APIcast 操作器。您将看到有关 APIcast 操作器的信息。
  6. InstallCreate Operator Subscription 页面会打开。
  7. Subscribe 接受 Create Operator Subscription 页面中的所有默认选择。

    1. 订阅升级状态 显示为最新
  8. Operators > Installed Operators 来验证 APIcast operator ClusterServiceVersion (CSV)状态是否在 operator-test 项目中显示为 InstallSucceeded

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

2.6.1. APIcast 部署和配置选项

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

另请参阅:

2.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
2.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"
2.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。下表中可用字段的详情:

表 2.3. APIcastExposedHost 参考表

json/yaml 项类型必需默认值描述

主机

字符串

N/A

路由到网关的域名

tls

[]extensions.IngressTLS

N/A

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

2.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
2.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"

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

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

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

    oc apply -f apicast1.yaml

后续步骤

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

2.7. 其他资源

要获取有关最新发布的及受支持 APIcast 版本的信息,请参阅文章:

第 3 章 APIcast 托管

完成本教程后,您将拥有完全受云的安全网关保护的 API。

如果您要尽可能快速启动 API,或者您要在其中进行最小基础架构更改,APIcast 托管的最佳部署选项。

先决条件

3.1. 使用在 staging 环境中托管的 APIcast 部署 API

第一步是配置 API 并在您的 staging 环境中进行测试:

流程

  1. 定义私有基础 URL 及其端点。
  2. 选择凭证放置和其他配置详情。如需更多信息,请参阅 APIcast Hosted 文档
  3. Update Product 保存配置设置。这些设置通过 APIcast 暂存实例进入您的 API。

配置完成后,您将看到一个绿色确认消息。

在继续下一步之前,请确保已将 secret 令牌配置为后端服务验证。您可以在 Authentication Settings 下为 secret 令牌定义值。这将确保 nobody 可以绕过 APIcast 访问控制。

3.2. 使用托管到生产环境中的 APIcast 部署 API

此时,您已准备好将 API 配置引入生产环境。部署 3scale Hosted APIcast 实例:

流程

  1. 返回到 Integration and Configuration 页面,然后点 'Promote to v.x to Production' 按钮。
  2. 重复此步骤,将 staging 环境中的进一步更改提升到生产环境。

配置需要 5 到 7 分钟后,部署并传播到所有云 APIcast 实例。在重新部署过程中,您的 API 将不会遇到任何停机时间。API 调用可能会根据哪个实例为调用而返回不同的响应。当生产环境框中已打开绿色时,部署可以成功。

staging 和生产 APIcast 实例在 apicast.io 域中都有基本 URL。您可以区分它们,因为 staging 环境 URL 有 staging 子域。例如:

3.3. 附加信息

  • 通过 APIcast 生产云实例实现 API 有每天最多 50,000 次的调用。您可以在管理门户的 Analytics 部分中检查您的 API 使用量。
  • 对 API 流量中的任何 spike 都有硬节流限制为 20 次/秒。
  • 在节流限制之上,APIcast 返回响应代码 403。这与应用的默认值高于速率限值。如果要区分错误,请检查响应正文。

第 4 章 在 Docker 容器化环境中部署 APIcast

这是一个分步骤指南,可在 Docker 容器引擎中部署 APIcast,它可以用作 Red Hat 3scale API 网关。

注意

在 Docker 容器化环境中部署 APIcast 时,受支持的 Red Hat Enterprise Linux(RHEL)和 Docker 版本如下:

  • RHEL 7.7
  • Docker 1.13.1

先决条件

要在 docker 容器化环境中部署 APIcast,请执行以下部分中所述的步骤:

4.1. 安装 Docker 容器化环境

本指南涵盖了在 RHEL 7.x 上设置 Docker 容器化环境的步骤。

红帽提供的 Docker 容器引擎作为 RHEL 中的 Extras 频道的一部分发布。要启用其他存储库,您可以使用 Subscription Manageryum-config-manager 选项。详情请查看 RHEL 产品文档

要在 Amazon Web Services(AWS)Amazon Elastic Compute Cloud(Amazon EC2)实例上部署 RHEL 7.x,请执行以下步骤:

流程

  1. 列出所有存储库:sudo yum repolist all.
  2. 查找 *-extras 存储库。
  3. 启用 extras 存储库:sudo yum-config-manager --enable rhui-REGION-rhel-server-extras.
  4. 安装 Docker 容器化环境软件包:sudo yum install docker

其他资源

对于其他操作系统,请参阅以下 Docker 文档:

4.2. 运行 Docker 容器化环境网关

重要

在 3scale 2.11 中,对作为 RHEL 7 中容器运行的 APIcast 部署的支持已弃用。在以后的发行版本中,3scale 将只支持 RHEL 8 和 Podman。如果您作为容器运行 APIcast 自我管理,请将安装升级到受支持的配置。

要运行 docker 容器化环境网关,请执行以下操作:

流程

  1. 启动 Docker 守护进程:

    sudo systemctl start docker.service
  2. 检查 Docker 守护进程是否正在运行:

    sudo systemctl status docker.service

您可以从 Red Hat registry 下载可以使用 Docker 容器引擎镜像:

+

sudo docker pull registry.redhat.io/3scale-amp2/apicast-gateway-rhel7:3scale2.13
  1. 在 Docker 容器引擎中运行 APIcast:

    sudo docker run --name apicast --rm -p 8080:8080 -e THREESCALE_PORTAL_ENDPOINT=https://<access_token>@<domain>-admin.3scale.net registry.redhat.io/3scale-amp2/apicast-gateway-rhel7:3scale2.13

    在这里,<access_token> 是 3scale 帐户管理 API 的访问令牌。您可以使用 Provider Key 而不是访问令牌。<domain>-admin.3scale.net 是 3scale 管理门户的 URL。

此命令在端口 8080 上运行名为 "apicast" 的 Docker 容器引擎,并从 3scale 管理门户获取 JSON 配置文件。有关其他配置选项,请参阅 安装 APIcast

4.2.1. docker 命令选项

您可以在 docker run 命令中使用以下选项:

  • --rm:容器退出时自动删除容器。
  • -d--detach:在后台运行容器并打印容器 ID。如果未指定,容器将以前台模式运行,您可以使用 CTRL + c 来停止容器。以分离模式启动时,您可以使用 docker attach 命令重新连接到容器,例如 docker attach apicast
  • -p--publish:将容器的端口发布到主机。该值的格式应为 <host port="">:<container port="">,因此 -p 80:8080 将容器的端口 8080 绑定到主机计算机的端口 80。例如,管理 API 使用端口 8090,因此您可能希望通过在 docker run 命令中添加 -p 8090:8090 来发布此端口。
  • -e--env :设置环境变量。
  • -v--volume :挂载卷。该值通常表示为 <host path="">:<container path="">[:<options>]<options> 是一个可选属性;您可以将其设置为 :ro 以指定卷是只读(默认情况下,以读写模式挂载)。示例: -v /host/path:/container/path:ro

4.2.2. 测试 APIcast

前面的步骤确保 Docker 容器引擎使用您自己的配置文件和 3scale registry 中的 Docker 容器镜像来运行。您可以通过 APIcast 在端口 8080 上测试调用,并提供正确的身份验证凭据,您可以从 3scale 帐户获得这些凭据。

测试调用不仅验证 APIcast 是否在正确运行,还验证身份验证和报告是否得到成功处理。

注意

确保您用于调用的主机与 Integration 页面的 Public Base URL 字段中配置的主机相同。

其他资源

4.3. 其他资源

第 5 章 在 Podman 上部署 APIcast

这是在 Pod Manager(Podman)容器环境中部署 APIcast 的逐步指南,用作 Red Hat 3scale API 网关。

注意

在 Podman 容器环境中部署 APIcast 时,受支持的 Red Hat Enterprise Linux(RHEL)和 Podman 版本如下:

  • RHEL 8.x
  • Podman 1.4.2

先决条件

要在 Podman 容器环境中部署 APIcast,请执行以下部分中所述的步骤:

5.1. 安装 Podman 容器环境

本指南涵盖了在 RHEL 8.x 上设置 Podman 容器环境的步骤。RHEL 8.x 中不包括 Docker,因此请使用 Podman 来运行容器。

有关 RHEL 8.x 的 Podman 的详情,请参阅容器命令行参考

流程

  • 安装 Podman 容器环境软件包:

    sudo dnf install podman

其他资源

对于其他操作系统,请参阅以下 Podman 文档:

5.2. 运行 Podman 环境

要运行 Podman 容器环境,请按照以下步骤操作。

流程

  1. 从 Red Hat registry 下载就绪的 Podman 容器镜像:

    podman pull registry.redhat.io/3scale-amp2/apicast-gateway-rhel8:3scale2.13
  2. 在 Podman 中运行 APIcast:

    podman run --name apicast --rm -p 8080:8080 -e THREESCALE_PORTAL_ENDPOINT=https://<access_token>@<domain>-admin.3scale.net registry.redhat.io/3scale-amp2/apicast-gateway-rhel8:3scale2.13

    在这里,<access_token> 是 3scale 帐户管理 API 的访问令牌。您可以使用 Provider Key 而不是访问令牌。<domain>-admin.3scale.net 是 3scale 管理门户的 URL。

此命令在端口 8080 上运行名为 "apicast" 的 Podman 容器引擎,并从 3scale 管理门户获取 JSON 配置文件。有关其他配置选项,请参阅 安装 APIcast

5.2.1. 使用 Podman 测试 APIcast

上述步骤确保 Podman 容器引擎使用您自己的配置文件和 3scale registry 中的 Podman 容器镜像来运行。您可以通过 APIcast 在端口 8080 上测试调用,并提供正确的身份验证凭据,您可以从 3scale 帐户获得这些凭据。

测试调用不仅验证 APIcast 是否在正确运行,还验证身份验证和报告是否得到成功处理。

注意

确保您用于调用的主机与 Integration 页面的 Public Base URL 字段中配置的主机相同。

5.3. podman 命令选项

您可以在 podman 命令中使用以下选项示例:

  • -d :以 detached mode 运行容器并打印容器 ID。如果未指定,容器将以前台模式运行,您可以使用 CTRL + c 来停止容器。以分离模式启动时,您可以使用 podman attach 命令重新附加到容器,例如 podman attach apicast
  • ps-a :Podman ps 用于列出创建和运行容器。将 -a 添加到 ps 命令将显示所有运行和停止的容器,例如 podman ps -a
  • inspect-l :检查正在运行的容器。例如,使用 inspect 查看分配给容器的 ID。使用 -l 获取最新容器的详细信息,例如 podman inspect -l | grep Id\":

5.4. 其他资源