安装 3scale

Red Hat 3scale API Management 2.9

安装和配置 3scale API 管理。

摘要

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

前言

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

第 1 章 3scale 的 registry 服务帐户

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

重要

部署 3scale 需要遵循本章中所述的步骤,然后才能使用模板或通过操作器在 OpenShift 上部署,因为这两个选项都使用注册表身份验证。

要创建和修改 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 服务帐户

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

警告

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

每个功能的描述如下:

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

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

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

1.3. 其他资源

第 2 章 在 OpenShift 上安装 3scale

本节介绍了在 OpenShift 上部署 Red Hat 3scale API Management 2.9 的步骤。

用于内部部署的 Red Hat 3scale API 管理解决方案包括:

  • 两个 API 网关:嵌入式 APIcast
  • 使用持久性存储的 3scale 管理门户和开发者门户

部署 3scale 解决方案的方法有两种:

注意
  • 无论是使用操作器部署 3scale 还是通过模板部署 3scale,您必须首先配置红帽容器 registry 的 registry 身份验证。请参阅配置容器 registry 身份验证
  • 3scale Istio 适配器是一个可选适配器,允许在 Red Hat OpenShift Service Mesh 中标记运行的服务,并将该服务与 Red Hat 3scale API 管理集成。如需更多信息,请参阅 3scale 适配器 文档。

先决条件

要在 OpenShift 上安装 3scale,请执行以下小节中介绍的步骤:

2.1. 在 OpenShift 上安装 3scale 的系统要求

本节列出了 3scale - OpenShift 模板的要求。

2.1.1. 环境要求

红帽 3scale API 管理需要在 支持的配置中 指定环境。

如果您使用本地文件系统存储:

持久性卷(PV)

  • 3 RWO(ReadWriteOnce)用于 Redis 和 MySQL 持久性的持久性卷
  • 1 个用于开发人员门户内容和 System-app 资源的 RWX(ReadWriteMany)持久性卷

将 RWX 持久卷配置为可写入组。如需支持所需访问模式的持久卷类型列表,请参阅 OpenShift 文档

如果您在内容管理系统(CMS)存储中使用 Amazon Simple Storage Service(Amazon S3)存储桶:

持久性卷(PV)

  • 3 RWO(ReadWriteOnce)用于 Redis 和 MySQL 持久性的持久性卷

存储

  • 1 Amazon S3 存储桶

2.1.2. 硬件要求

硬件要求取决于您的使用需求。红帽建议您测试和配置您的环境,以满足您的特定要求。以下是在 OpenShift 中为 3scale 配置环境时的建议:

  • 计算优化的节点用于云环境(AWS c4.2xlarge 或 Azure Standard_F8)上的部署。
  • 如果内存要求超过您当前节点的可用 RAM,则非常大型安装可能需要单独节点(AWS M4 系列或 Azure Av2 系列)。
  • 路由和计算任务之间分隔的节点。
  • 用于 3scale 特定任务的专用计算节点.
  • 将后端侦听器的 PUMA_WORKERS 变量设置为计算节点中的内核数。

2.2. 配置节点和权利

在 OpenShift 上部署 3scale 之前,您必须配置必要的节点以及环境的授权,以便从 红帽生态系统目录 获取镜像。执行以下步骤来配置节点和权利:

流程

  1. 在您的每个节点上安装 Red Hat Enterprise Linux(RHEL)
  2. 使用红帽订阅管理器(RHSM)通过 接口命令行向红帽注册您的节点。
  3. 使用 RHSM 将您的节点附加到 3scale 订阅
  4. 根据以下要求,在节点上 安装 OpenShift

  5. 安装 OpenShift 命令行界面
  6. 使用订阅管理器启用对 rhel-7-server-3scale-amp-2-rpms 存储库的访问权限:

    sudo subscription-manager repos --enable=rhel-7-server-3scale-amp-2-rpms
  7. 安装 3scale 模板,取名为 3scale-amp-template。这将保存在 /opt/amp/templates 中。

    sudo yum install 3scale-amp-template

2.2.1. 配置 Amazon Simple Storage Service

重要

如果要使用本地文件系统存储部署 3scale,请跳过此部分。

如果要使用 Amazon Simple Storage Service(Amazon S3)存储桶作为存储,您必须配置存储桶,然后才能在 OpenShift 中部署 3scale。

执行以下步骤为 3scale 配置 Amazon S3 存储桶:

  1. 使用以下默认权限创建 Identity and Access Management(IAM)策略:

    {
        "Version": "2012-10-17",
        "Statement": [
            {
                "Effect": "Allow",
                "Action": "s3:ListAllMyBuckets",
                "Resource": "arn:aws:s3:::*"
            },
            {
                "Effect": "Allow",
                "Action": "s3:*",
                "Resource": [
                    "arn:aws:s3:::targetBucketName",
                    "arn:aws:s3:::targetBucketName/*"
                ]
            }
        ]
    }
  2. 使用以下规则创建 CORS 配置

    <?xml version="1.0" encoding="UTF-8"?>
    <CORSConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
    <CORSRule>
        <AllowedOrigin>https://*</AllowedOrigin>
        <AllowedMethod>GET</AllowedMethod>
    </CORSRule>
    </CORSConfiguration>

2.3. 使用模板在 OpenShift 上部署 3scale

注意

OpenShift Container Platform(OCP)4.x 仅支持使用 Operator 部署 3scale。请参阅使用操作器部署 3scale

先决条件

  • 根据配置节点和授权一节中指定的配置 OpenShift 集群。
  • 解析到 OpenShift 集群的
  • 访问红帽生态系统目录
  • (可选)在本地文件系统外的内容管理系统(CMS)存储的 Amazon Simple Storage Service(Amazon S3)存储桶。
  • (可选)使用 PostgreSQL 部署。

    • 这与 Openshift 上的默认部署相同,但它使用 PostgreSQL 作为内部系统数据库。
  • (可选)用于电子邮件功能的已正常工作 SMTP 服务器。
注意

使用模板在 OpenShift 上部署 3scale 基于 OpenShift Container Platform 3.11

按照以下步骤,使用一个 .yml 模板在 OpenShift 上安装 3scale:

2.4. 配置容器 registry 身份验证

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

先决条件

  • 集群管理员对 OpenShift Container Platform 集群的访问权限。
  • 已安装 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

其他资源

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

2.4.1. 创建 registry 服务帐户

要在 OpenShift 上部署的 3scale 2.9 共享环境中使用来自 registry.redhat.io 的容器镜像,您必须使用 Registry Service 帐户而不是单独的用户的 客户门户网站凭证。

注意

这是一个 3scale 2.8 或更高选项的要求,您可以按照以下步骤操作,然后再使用模板或在 OpenShift 上部署,因为这两种选项都使用 registry 身份验证。

流程

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

    1. 服务帐户 添加名称。

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

  3. 输入 描述
  4. Create
  5. 切回到您的 服务帐户
  6. 您创建的 服务帐户。
  7. 记录用户名,包括前缀字符串,如 12345678|username 和您的密码。

    1. 此用户名和密码将用于登录 registry.redhat.io

      注意

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

2.4.2. 修改 registry 服务帐户

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

警告

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

每个功能的描述如下:

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

    备注:服务帐户的用户名不能更改。

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

2.4.3. 导入 3scale 模板

注意
  • 从 3scale 2.6 开始,通配符路由已被删除

    • 这个功能由 Zync 在后台处理。
  • 创建、更新或删除 API 提供程序时,路由会自动反映这些更改。

执行以下步骤将 3scale 模板导入到 OpenShift 集群中:

流程

  1. 在终端会话中以集群管理员身份登录到 OpenShift:

    oc login
  2. 选择项目或创建新项目:

    oc project <project_name>
    oc new-project <project_name>
  3. 输入 oc new-app 命令:

    1. 使用您作为配置节点和权利的一部分下载的 amp.yml 文件的路径指定 --file 选项。
    2. 通过将 WILDCARD_DOMAIN 参数设置为 OpenShift 集群的域来指定 --param 选项:

      oc new-app --file /opt/amp/templates/amp.yml --param WILDCARD_DOMAIN=<WILDCARD_DOMAIN>

      终端会显示新创建的 3scale 管理门户的主和租户 URL 以及凭据。这个输出应包括以下信息:

      • master admin 用户名
      • master 密码
      • 主令牌信息
      • 租户用户名
      • 租户密码
      • 租户令牌信息
  4. 以 admin/xXxXyz123 身份登录 https://user-admin.3scale-project.example.com

    * With parameters:
    
     * ADMIN_PASSWORD=xXxXyz123 # generated
     * ADMIN_USERNAME=admin
     * TENANT_NAME=user
    
     * MASTER_NAME=master
     * MASTER_USER=master
     * MASTER_PASSWORD=xXxXyz123 # generated
    
    --> Success
    Access your application via route 'user-admin.3scale-project.example.com'
    Access your application via route 'master-admin.3scale-project.example.com'
    Access your application via route 'backend-user.3scale-project.example.com'
    Access your application via route 'user.3scale-project.example.com'
    Access your application via route 'api-user-apicast-staging.3scale-project.example.com'
    Access your application via route 'api-user-apicast-production.3scale-project.example.com'
  5. 记下这些详细信息,以备将来参考。
  6. 当命令返回时,OpenShift 上的 3scale 部署成功:

    oc wait --for=condition=available --timeout=-1s $(oc get dc --output=name)
    注意

    当 OpenShift 上的 3scale 部署成功时,您的登录凭据将正常工作。

2.4.4. 获取管理门户 URL

当使用模板部署 3scale 时,会创建一个带有固定 URL 的默认租户:3scale-admin.${wildcardDomain}

3scale 控制面板显示租户的新门户 URL。例如,如果 <wildCardDomain>3scale-project.example.com,则管理门户 URL 为 :https://3scale-admin.3scale-project.example.com

wildcardDomain 是您在安装过程中提供的 <wildCardDomain> 参数。使用这个命令在浏览器中打开这个唯一 URL:

xdg-open https://3scale-admin.3scale-project.example.com

另外,您还可以在 MASTER 门户 URL 上创建新的租户:master.${wildcardDomain}

2.4.5. 使用 Amazon Simple Storage Service 部署 3scale

使用 Amazon Simple Storage Service(Amazon S3)部署 3scale 是一个可选流程。通过 Amazon S3 部署 3scale,执行以下步骤:

流程

  1. 下载 amp-s3.yml
  2. 从终端会话登录到 OpenShift:

    oc login
  3. 选择项目或创建新项目:

    oc project <project_name>

oc new-project <project_name>
  1. 输入 oc new-app 命令:

    • 使用 amp-s3.yml 文件的路径指定 --file 选项。
    • 使用以下值指定 --param 选项:

      • WILDCARD_DOMAIN : 参数设置为 OpenShift 集群的域。
      • AWS_BUCKET: 带有您的目标存储桶名称。
      • AWS_ACCESS_KEY_ID: 您的 AWS 凭证 ID。
      • AWS_SECRET_ACCESS_KEY: 您的 AWS 凭证 KEY。
      • AWS_REGION: with the AWS: 您的存储桶的区域。
      • AWS_HOSTNAME:默认:Amazon 端点 - AWS S3 兼容供应商端点主机名。
      • AWS_PROTOCOL:默认:HTTPS - AWS S3 兼容供应商端点协议。
      • AWS_PATH_STYLE:默认:false - 当设置为 true 时,存储桶名称始终保留在请求 URI 中,并且永远不会作为子域移到主机。
    • (可选)使用 TENANT_NAME 参数指定 --param 选项,以设置管理门户的自定义名称。如果省略,则默认为 3scale

      oc new-app --file /path/to/amp-s3.yml \
      	--param WILDCARD_DOMAIN=<a-domain-that-resolves-to-your-ocp-cluster.com> \
      	--param TENANT_NAME=3scale \
      	--param AWS_ACCESS_KEY_ID=<your-aws-access-key-id> \
      	--param AWS_SECRET_ACCESS_KEY=<your-aws-access-key-secret> \
      	--param AWS_BUCKET=<your-target-bucket-name> \
      	--param AWS_REGION=<your-aws-bucket-region> \
      	--param FILE_UPLOAD_STORAGE=s3

      终端会显示 master 和租户 URL,以及新创建的 3scale 管理门户的凭据。这个输出应包括以下信息:

    • master admin 用户名
    • master 密码
    • 主令牌信息
    • 租户用户名
    • 租户密码
    • 租户令牌信息
  2. 以 admin/xXxXyz123 身份登录 https://user-admin.3scale-project.example.com

    ...
    
    * With parameters:
     * ADMIN_PASSWORD=xXxXyz123 # generated
     * ADMIN_USERNAME=admin
     * TENANT_NAME=user
     ...
    
     * MASTER_NAME=master
     * MASTER_USER=master
     * MASTER_PASSWORD=xXxXyz123 # generated
     ...
    
    --> Success
    Access your application via route 'user-admin.3scale-project.example.com'
    Access your application via route 'master-admin.3scale-project.example.com'
    Access your application via route 'backend-user.3scale-project.example.com'
    Access your application via route 'user.3scale-project.example.com'
    Access your application via route 'api-user-apicast-staging.3scale-project.example.com'
    Access your application via route 'api-user-apicast-production.3scale-project.example.com'
    Access your application via route 'apicast-wildcard.3scale-project.example.com'
    
    ...
  3. 记下这些详细信息,以备将来参考。
  4. 当命令返回时,OpenShift 上的 3scale 部署成功:

    oc wait --for=condition=available --timeout=-1s $(oc get dc --output=name)
    注意

    当 OpenShift 上的 3scale 部署成功时,您的登录凭据将正常工作。

2.4.6. 使用 PostgreSQL 部署 3scale

使用 PostgreSQL 部署 3scale 是一个可选过程。使用 PostgreSQL 部署 3scale 执行以下步骤:

流程

  1. 下载 amp-postgresql.yml
  2. 从终端会话登录到 OpenShift:

    oc login
  3. 选择项目或创建新项目:

    oc project <project_name>

oc new-project <project_name>
  1. 输入 oc new-app 命令:

    • 使用 amp-postgresql.yml 文件的路径指定 --file 选项。
    • 使用以下值指定 --param 选项:
    • WILDCARD_DOMAIN : 参数设置为 OpenShift 集群的域。
    • (可选)使用 TENANT_NAME 参数指定 --param 选项,以设置管理门户的自定义名称。如果省略,则默认为 3scale

      oc new-app --file /path/to/amp-postgresql.yml \
      	--param WILDCARD_DOMAIN=<a-domain-that-resolves-to-your-ocp-cluster.com> \
      	--param TENANT_NAME=3scale \

      终端会显示 master 和租户 URL,以及新创建的 3scale 管理门户的凭据。这个输出应包括以下信息:

    • master admin 用户名
    • master 密码
    • 主令牌信息
    • 租户用户名
    • 租户密码
    • 租户令牌信息
  2. 以 admin/xXxXyz123 身份登录 https://user-admin.3scale-project.example.com

    ...
    
    * With parameters:
     * ADMIN_PASSWORD=xXxXyz123 # generated
     * ADMIN_USERNAME=admin
     * TENANT_NAME=user
     ...
    
     * MASTER_NAME=master
     * MASTER_USER=master
     * MASTER_PASSWORD=xXxXyz123 # generated
     ...
    
    --> Success
    Access your application via route 'user-admin.3scale-project.example.com'
    Access your application via route 'master-admin.3scale-project.example.com'
    Access your application via route 'backend-user.3scale-project.example.com'
    Access your application via route 'user.3scale-project.example.com'
    Access your application via route 'api-user-apicast-staging.3scale-project.example.com'
    Access your application via route 'api-user-apicast-production.3scale-project.example.com'
    Access your application via route 'apicast-wildcard.3scale-project.example.com'
    
    ...
  3. 记下这些详细信息,以备将来参考。
  4. 当命令返回时,OpenShift 上的 3scale 部署成功:

    oc wait --for=condition=available --timeout=-1s $(oc get dc --output=name)
    注意

    当 OpenShift 上的 3scale 部署成功时,您的登录和凭据将正常工作。

2.4.7. 配置 SMTP 变量(可选)

OpenShift 使用电子邮件发送通知邀请新用户。如果要使用这些功能,则必须提供自己的 SMTP 服务器并在 system-smtp 机密中配置 SMTP 变量。

执行以下步骤在 system-smtp secret 中配置 SMTP 变量:

流程

  1. 如果您还没有登录,请登录到 OpenShift:

    oc login
    1. 使用 oc patch 命令,指定 system-smtpsecret 名称的 secret 类型,后跟 -p 选项,并在 JSON 中为以下变量写入新值:

      变量描述

      address

      允许您将远程邮件服务器指定为中继

      username

      指定您的邮件服务器用户名

      password

      指定您的邮件服务器密码

      domain

      指定 HELO 域

      port

      指定邮件服务器侦听新连接的端口

      身份验证

      指定邮件服务器的身份验证类型。允许的值: plain (发送明文中的密码)、login (发送密码 Base64 编码)或 cram_md5 (交换信息和加密消息目标 5 算法以散列重要信息)

      openssl.verify.mode

      指定在使用 TLS 时,OpenSSL 如何检查证书。允许的值:nonepeer

      示例

      oc patch secret system-smtp -p '{"stringData":{"address":"<your_address>"}}'
      oc patch secret system-smtp -p '{"stringData":{"username":"<your_username>"}}'
      oc patch secret system-smtp -p '{"stringData":{"password":"<your_password>"}}'
  2. 设置 secret 变量后,重新部署 system-appsystem-sidekiq pod:

    oc rollout latest dc/system-app
    oc rollout latest dc/system-sidekiq
  3. 检查推出部署的状态,以确保它已完成:

    oc rollout status dc/system-app
    oc rollout status dc/system-sidekiq

2.5. 3scale 模板的参数

模板参数配置部署期间和之后 3scale(amp.yml)模板的环境变量。

表 2.1. 模板参数

名称描述默认值必需?

APP_LABEL

用于对象应用程序标签

3scale-api-management

ZYNC_DATABASE_PASSWORD

PostgreSQL 连接用户的密码。如果未提供,则随机生成.

N/A

ZYNC_SECRET_KEY_BASE

适用于 Zync 的机密密钥基础.如果未提供,则随机生成.

N/A

ZYNC_AUTHENTICATION_TOKEN

Zync 的身份验证令牌.如果未提供,则随机生成.

N/A

AMP_RELEASE

3scale 发行标签。

2.8.0

ADMIN_PASSWORD

一个随机生成的 3scale 管理员帐户密码。

N/A

ADMIN_USERNAME

3scale 管理员帐户用户名.

admin

APICAST_ACCESS_TOKEN

阅读 APIcast 将用来下载其配置的唯一访问令牌。

N/A

ADMIN_ACCESS_TOKEN

具有所有范围的管理访问令牌,以及用于 API 访问的写入权限。

N/A

WILDCARD_DOMAIN

通配符路由的根域.例如,根域 example.com 将生成 3scale-admin.example.com

N/A

TENANT_NAME

管理门户的 root 下具有 -admin 后缀的租户名称。

3scale

MYSQL_USER

用于访问数据库的 MySQL 用户的用户名。

mysql

MYSQL_PASSWORD

MySQL 用户的密码。

N/A

MYSQL_DATABASE

访问的 MySQL 数据库的名称。

system

MYSQL_ROOT_PASSWORD

Root 用户的密码.

N/A

SYSTEM_BACKEND_USERNAME

用于内部 3scale api 身份验证的内部 3scale API 用户名。

3scale_api_user

SYSTEM_BACKEND_PASSWORD

用于内部 3scale api 身份验证的内部 3scale API 密码。

N/A

REDIS_IMAGE

使用的 redis 镜像

registry.redhat.io/rhscl/redis-5-rhel7:5.0

MYSQL_IMAGE

要使用的 MySQL 镜像

registry.redhat.io/rhscl/mysql-57-rhel7:5.7

MEMCACHED_IMAGE

要使用的 Memcached 镜像

registry.redhat.io/3scale-amp2/memcached-rhel7:3scale2.9

POSTGRESQL_IMAGE

要使用的 PostgreSQL 镜像

registry.redhat.io/rhscl/postgresql-10-rhel7

AMP_SYSTEM_IMAGE

要使用的 3scale 系统镜像

registry.redhat.io/3scale-amp2/system-rhel7:3scale2.9

AMP_BACKEND_IMAGE

要使用的 3scale 后端镜像

registry.redhat.io/3scale-amp2/backend-rhel7:3scale2.9

AMP_APICAST_IMAGE

使用的 3scale APIcast 镜像

registry.redhat.io/3scale-amp2/apicast-gateway-rhel8:3scale2.9

AMP_ZYNC_IMAGE

要使用的 3scale Zync 镜像

registry.redhat.io/3scale-amp2/zync-rhel7:3scale2.9

SYSTEM_BACKEND_SHARED_SECRET

用于将事件从后端导入到系统的共享机密。

N/A

SYSTEM_APP_SECRET_KEY_BASE

系统应用程序 secret 密钥基础

N/A

APICAST_MANAGEMENT_API

APIcast 管理 API 的范围。可以禁用、状态或调试。至少健康检查所需的状态。

status

APICAST_OPENSSL_VERIFY

下载配置时打开/关闭 OpenSSL 对等验证。可以设置为 true/false。

false

APICAST_RESPONSE_CODES

在 APIcast 中启用日志响应代码。

true

APICAST_REGISTRY_URL

解析到 APIcast 策略位置的 URL

http://apicast-staging:8090/policies

MASTER_USER

Master 管理员帐户用户名

master

MASTER_NAME

master 管理门户的子域值将附加 -master 后缀

master

MASTER_PASSWORD

随机生成的 master 管理员密码

N/A

MASTER_ACCESS_TOKEN

具有用于 API 调用 master 级别的权限的令牌

N/A

IMAGESTREAM_TAG_IMPORT_INSECURE

如果服务器可以在镜像导入过程中绕过证书验证或直接通过 HTTP 连接,则设置为 true。

false

2.6. 在 OpenShift 中使用带有 3scale 的 APIcast

APIcast 附带有 3scale 托管的 API Manager,以及 OpenShift Container Platform 中内部安装。两者的配置过程都有所不同。

本节介绍如何在 OpenShift 中使用 API Manager 部署 APIcast。

2.6.1. 在包含 3scale 的现有 OpenShift 集群上部署 APIcast 模板

默认情况下,3scale OpenShift 模板包含两个嵌入式 APIcast。如果需要更多 API 网关,或需要单独的 APIcast 部署,您可以在 OpenShift 集群中部署额外的 APIcast 模板。

执行以下步骤在 OpenShift 集群中部署额外的 API 网关:

流程

  1. 使用以下配置创建访问令牌

    • 作用于帐户管理 API
    • 具有只读访问权限
  2. 登录到您的 APIcast 集群:

    oc login
  3. 创建一个允许 APIcast 与 3scale 通信的 secret。使用 3scale 部署的访问令牌、租户名称和通配符域指定 create secretapicast-configuration-url-secret 参数:

    oc create secret generic apicast-configuration-url-secret --from-literal=password=https://<ACCESS_TOKEN>@<TENANT_NAME>-admin.<WILDCARD_DOMAIN>
    注意

    TENANT_NAME 是管理门户可访问的 root 下的名称。TENANT_NAME 的默认值为 3scale。如果您在 3scale 部署中使用了自定义值,则必须在此使用该值。

  4. 使用 oc new-app 命令导入 APIcast 模板,并使用 apicast.yml 文件指定 --file 选项:

    oc new-app --file /opt/amp/templates/apicast.yml
    注意

    首先安装 APIcast 模板,如配置节点和授权中所述。

2.6.2. 从不同的 OpenShift 集群连接 APIcast

如果在 3scale 集群外在不同的 OpenShift 集群上部署 APIcast,则必须通过公共路由连接:

流程

  1. 使用以下配置创建访问令牌

    • 作用于帐户管理 API
    • 具有只读访问权限
  2. 登录到您的 APIcast 集群:

    oc login
  3. 创建一个允许 APIcast 与 3scale 通信的 secret。使用 3scale 部署的访问令牌、租户名称和通配符域指定 create secretapicast-configuration-url-secret 参数:

    oc create secret generic apicast-configuration-url-secret --from-literal=password=https://<ACCESS_TOKEN>@<TENANT_NAME>-admin.<WILDCARD_DOMAIN>
    注意

    TENANT_NAME 是管理门户可访问的 root 下的名称。TENANT_NAME 的默认值为 3scale。如果您在 3scale 部署中使用了自定义值,则必须使用该值。

  4. 使用 oc new-app 命令,将 APIcast 部署到不同的 OpenShift 集群。指定 --file 选项以及 apicast.yml 文件的路径:

    oc new-app --file /path/to/file/apicast.yml

2.6.3. 更改嵌入式 APIcast 的默认行为

在外部 APIcast 部署中,您可以通过 更改 APIcast OpenShift 模板中的模板参数 来修改默认行为。

在嵌入式 APIcast 部署中,3scale 和 APIcast 从单一模板部署。如果要更改嵌入 APIcast 部署的默认行为,您必须在部署后修改环境变量。

2.6.4. 通过内部服务路由在单个 OpenShift 集群上连接多个 APIcast 部署

如果您将多个 APIcast 网关部署到同一个 OpenShift 集群中,您可以将它们配置为通过后端侦听器服务(而非默认的外部路由配置)使用内部路由进行连接。

您必须安装 OpenShift 软件定义型网络(SDN)插件,才能通过内部服务路由进行连接。如何连接取决于您安装的 SDN:

ovs-subnet

如果您使用 ovs-subnet OpenShift SDN 插件,请执行以下步骤通过内部路由连接:

流程

  1. 如果还没有登录,请登录到您的 OpenShift 集群:

    oc login
  2. 输入以下命令显示 backend-listener 路由 URL:

    oc get route backend
  3. 使用到 apicast.yml 的路径输入 oc new-app 命令:

    oc new-app -f apicast.yml

ovs-multitenant

如果使用 ovs-multitenant OpenShift SDN 插件,请执行以下步骤通过内部路由连接:

流程

  1. 如果还没有登录,请登录到您的 OpenShift 集群:

    oc login
  2. 作为管理员,在 oadm 命令中使用 pod-networkjoin-projects 选项来设置两个项目之间的通信:

    oadm pod-network join-projects --to=<3SCALE_PROJECT> <APICAST_PROJECT>
  3. 输入以下命令显示 backend-listener 路由 URL:

    oc get route backend
  4. 使用到 apicast.yml 的路径输入 oc new-app 命令:

    oc new-app -f apicast.yml

其他资源

如需有关 OpenShift SDN 和项目网络隔离的信息,请参阅 Openshift SDN

2.6.5. 在其他部署中连接 APIcast

如果在 Docker 上部署 APIcast,您可以通过将 OpenShift 上部署的 3scale 设为 3scale 来连接 OpenShift 上部署的 APIcast,方法是将 THREESCALE_PORTAL_ENDPOINT 参数设置为在 OpenShift 上部署的 3scale 管理门户的 URL 和访问令牌。在这种情况下,您不需要设置 BACKEND_ENDPOINT_OVERRIDE 参数。

其他资源

如需了解更多详细信息,请参阅 在 Docker 容器化环境中部署 APIcast

2.7. 使用 Operator 部署 3scale

本节介绍了使用 APIManager 自定义资源通过 3scale 操作器安装和部署 3scale 解决方案。

注意
  • 自 3scale 2.6 起,已删除 通配符路由。

    • 这个功能由 Zync 在后台处理。
  • 创建、更新或删除 API 提供程序时,路由会自动反映这些更改。

先决条件

按照以下步骤,使用 Operator 部署 3scale:

2.7.1. 部署 APIManager 自定义资源

部署 APIManager 自定义资源将使 Operator 开始处理,并从中部署 3scale 解决方案。

流程

  1. Operators > Installed Operators

    1. Installed Operators 列表中,点 3scale Operator
  2. API Manager 选项卡。
  3. Create APIManager
  4. 清除示例内容,并将以下 YAML 定义添加到编辑器中,然后单击 Create

    • 在 3scale 2.8 之前,您可以通过将 HighAvailability 字段设置为 true 来配置自动添加副本。从 3scale 2.8 开始,对副本的添加会通过 APIManager CR 中的 replicas 字段来控制,如下例所示。

      注意

      wildcardDomain 参数可以是您想要将该解析为 IP 地址的任何所需名称,而 IP 地址是一个有效的 DNS 域。

    • 具有最低要求的 APIManager CR:

      apiVersion: apps.3scale.net/v1alpha1
      kind: APIManager
      metadata:
        name: apimanager-sample
      spec:
        wildcardDomain: example.com
    • 配置副本的 APIManager CR:

      apiVersion: apps.3scale.net/v1alpha1
      kind: APIManager
      metadata:
        name: apimanager-sample
      spec:
        system:
          appSpec:
            replicas: 1
          sidekiqSpec:
            replicas: 1
        zync:
          appSpec:
            replicas: 1
          queSpec:
            replicas: 1
        backend:
          cronSpec:
            replicas: 1
          listenerSpec:
            replicas: 1
          workerSpec:
            replicas: 1
        apicast:
          productionSpec:
            replicas: 1
          stagingSpec:
            replicas: 1
        wildcardDomain: example.com

2.7.2. 获取 APIManager 管理门户和主管理门户凭证

要在基于 operator 的部署后登录 3scale 管理门户或主管理门户,您需要每个单独门户的凭据。获取这些凭证:

  1. 运行以下命令以获取管理门户凭证:

    oc get secret system-seed -o json | jq -r .data.ADMIN_USER | base64 -d
    oc get secret system-seed -o json | jq -r .data.ADMIN_PASSWORD | base64 -d
    1. 以 Admin Portal 管理员身份登录,以验证这些凭据是否正常工作。
  2. 运行以下命令来获取主管理门户凭证:

    oc get secret system-seed -o json | jq -r .data.MASTER_USER | base64 -d
    oc get secret system-seed -o json | jq -r .data.MASTER_PASSWORD | base64 -d
    1. 以主管理门户管理员身份登录,以验证这些凭据是否正常工作。

其他资源

如需有关 APIManager 字段的更多信息,请参阅参考文档

2.7.3. 获取管理门户 URL

当使用操作器部署 3scale 时,会创建一个带有固定 URL 的默认租户:3scale-admin.${wildcardDomain}

3scale 控制面板显示租户的新门户 URL。例如,如果 < wildCardDomain&gt; 是 3scale-project.example.com,则管理门户 URL 为: https://3scale-admin.3scale-project.example.com

wildcardDomain 是您在安装过程中提供的 <wildCardDomain> 参数。使用这个命令在浏览器中打开这个唯一 URL:

xdg-open https://3scale-admin.3scale-project.example.com

另外,您还可以在 MASTER 门户 URL 上创建新的租户:master.${wildcardDomain}

2.7.4. 配置微版本的自动应用程序

要获得微版本更新并使其被自动应用,3scale Operator 的批准策略必须设置为 Automatic。下面描述了自动手动设置之间的区别,并概述了从一个设置改为另一个流程的步骤。

自动和手动:

  • 在安装过程中,自动设置是所选选项。随着新的更新可用,就会安装新的更新。您可以在安装过程中或之后更改。
  • 如果您在安装过程中或以后选择了 Manual 选项,会在有可用情况下收到更新。接下来,您必须批准 Install Plan,并自行应用。

流程

  1. Operators > Installed Operators
  2. Installed Operators 列表中,单击 3scale API Management
  3. Subscription 标签页。在 Subscription Details 标题下,您将看到子标题 Approval
  4. Approval 下的链接。默认情况下,链接设置为 Automatic。系统将弹出一个标题为 Change Update Approval Strategy 的模态。
  5. 选择您首选的选项:自动(默认)Manual,然后单击 Save

其他资源

2.7.5. 使用 Operator 的 3scale 的高可用性

使用 operator 的 3scale 中的高可用性(HA) 提供不间断的运行时间(例如,在一个或多个数据库失败的情况下继续工作)。

注意

.spec.highAvailability.enabled 仅适用于外部数据库。

如果要在基于 operator 部署的 3scale 中实现高可用性,请注意以下几点:

  • 在外部部署并配置 3scale 关键数据库,特别是系统数据库、系统 redis 和后端 redis。确保以高可用性方式部署和配置这些数据库。
  • 通过预先填充对应的 Kubernetes Secret,为 3scale 指定连接端点。

  • 在部署 APIManager CR 时,将 .spec.highAvailability.enabled 属性设置为 true,以便为关键数据库启用外部数据库模式:系统数据库、系统 redis 和 backend redis。

另外,如果您希望 zync 数据库高度可用,为了避免 zync 可能会在重启时丢失队列作业数据,请注意:

  • 在外部部署和配置 zync 数据库。确保以高可用性方式部署和配置数据库。
  • 通过预先填充对应的 Kubernetes Secret,指定到 3scale 的 zync 数据库的连接端点。

    • 如需更多信息,请参阅 Zync 数据库 secret
    • 部署 3scale 将 spec.highAvailability.externalZyncDatabaseEnabled 属性设置为 true,以指定 zync 数据库作为外部数据库。

2.8. 使用操作器在 OpenShift 上 3scale 的部署配置选项

本节介绍了使用操作器在 OpenShift 上红帽 3scale API 管理的部署配置选项。

先决条件

2.8.1. 评估部署的概念验证

以下小节描述了适用于 3scale 评估部署的概念验证的配置选项。此部署默认使用内部数据库。

重要

外部数据库的配置是生产环境的标准部署选项。

2.8.1.1. 默认部署配置

  • 容器将具有 Kubernetes 资源限值和请求

    • 这样可确保最低性能水平。
    • 它限制资源以允许外部服务和解决方案分配。
  • 部署内部数据库.
  • 文件存储将基于 Persistence 卷(PV)。

    • 一个系统将需要读取、写入、执行(RWX)访问模式。
    • OpenShift 配置为在请求时提供它们。
  • 将 MySQL 部署为内部关系数据库。

默认配置选项适合客户的概念验证(PoC)或评估。

可以使用 APIManager 自定义资源中的特定字段值覆盖一个或多个默认配置选项。3scale 操作器允许所有可用组合,而模板则允许固定的部署配置集。例如,3scale 操作器允许在评估模式和外部数据库模式中部署 3scale。模板不允许这一具体的部署配置。模板仅适用于最常用的配置选项。

2.8.1.2. 评估安装

对于和评估安装,容器将不会指定 kubernetes 资源限值和请求。例如:

  • 内存占用较小
  • 快速启动
  • 可以在笔记本电脑上运行
  • 适用于售前/销售演示
apiVersion: apps.3scale.net/v1alpha1
kind: APIManager
metadata:
  name: example-apimanager
spec:
  wildcardDomain: lvh.me
  resourceRequirementsEnabled: false

检查 APIManager 自定义资源以作为参考。

2.8.2. 安装外部数据库

外部数据库安装适合需要高可用性(HA)或计划重复使用的数据库。

重要

在启用 3scale 外部数据库安装模式时,以下所有数据库都是外部化的:

  • backend-redis
  • system-redis
  • system-database (mysql, postgresql, 或 oracle)

以下数据库版本支持 3scale 2.8 及以上版本:

数据库版本

redis

5.0

MySQL

5.7

PostgreSQL

10.6

在创建 APIManager 自定义资源 以部署 3scale 之前,您必须使用 OpenShift 机密为外部数据库提供以下连接设置:

2.8.2.1. 后端 Redis secret

部署两个外部 Redis 实例并填写连接设置,如下例所示:

apiVersion: v1
kind: Secret
metadata:
  name: backend-redis
stringData:
  REDIS_STORAGE_URL: "redis://backend-redis-storage"
  REDIS_STORAGE_SENTINEL_HOSTS: "redis://sentinel-0.example.com:26379,redis://sentinel-1.example.com:26379, redis://sentinel-2.example.com:26379"
  REDIS_STORAGE_SENTINEL_ROLE: "master"
  REDIS_QUEUES_URL: "redis://backend-redis-queues"
  REDIS_QUEUES_SENTINEL_HOSTS: "redis://sentinel-0.example.com:26379,redis://sentinel-1.example.com:26379, redis://sentinel-2.example.com:26379"
  REDIS_QUEUES_SENTINEL_ROLE: "master"
type: Opaque

Secret 名称必须是 backend-redis

2.8.2.2. 系统 Redis secret

部署两个外部 Redis 实例并填写连接设置,如下例所示:

apiVersion: v1
kind: Secret
metadata:
  name: system-redis
stringData:
  URL: "redis://system-redis"
  SENTINEL_HOSTS: "redis://sentinel-0.example.com:26379,redis://sentinel-1.example.com:26379, redis://sentinel-2.example.com:26379"
  SENTINEL_ROLE: "master"
  NAMESPACE: ""
  MESSAGE_BUS_URL: "redis://system-redis-messagebus"
  MESSAGE_BUS_SENTINEL_HOSTS: "redis://sentinel-0.example.com:26379,redis://sentinel-1.example.com:26379, redis://sentinel-2.example.com:26379"
  MESSAGE_BUS_SENTINEL_ROLE: "master"
  MESSAGE_BUS_NAMESPACE: ""
type: Opaque

Secret 名称必须是 system-redis

2.8.2.3. 系统数据库 secret

注意

Secret 名称必须是 system-database

当您部署 3scale 时,系统数据库有三个替代方案。为每个替代的相关 secret 配置不同的属性和值。

  • MySQL
  • PostgreSQL
  • Oracle 数据库

要部署 MySQL、PostgreSQL 或 Oracle Database 系统数据库 secret,请填写连接设置,如下例所示:

MySQL 系统数据库 secret

apiVersion: v1
kind: Secret
metadata:
  name: system-database
stringData:
  URL: "mysql2://{DB_USER}:{DB_PASSWORD}@{DB_HOST}:{DB_PORT}/{DB_NAME}"
type: Opaque

PostgreSQL 系统数据库 secret

apiVersion: v1
kind: Secret
metadata:
  name: system-database
stringData:
  URL: "postgresql://{DB_USER}:{DB_PASSWORD}@{DB_HOST}:{DB_PORT}/{DB_NAME}"
type: Opaque

Oracle 系统数据库 secret

apiVersion: v1
kind: Secret
metadata:
  name: system-database
stringData:
  URL: "oracle-enhanced://{DB_USER}:{DB_PASSWORD}@{DB_HOST}:{DB_PORT}/{DB_NAME}"
  ORACLE_SYSTEM_PASSWORD: "{SYSTEM_PASSWORD}"
type: Opaque

注意
  • Oracle system 用户以系统权限执行命令。详情包括在此GitHub 仓库中。在数据库中初始化表时,可以在 Oracle Database initializer 中执行最新的操作。其他命令可能未列在这些链接中。
  • 当有要运行的模式迁移时,也需要升级 system 用户,因此可能会执行前面链接中包括的其他命令。
  • 免责声明:包括在此处的外部网络链接仅为方便用户而提供。红帽没有审阅链接的内容,并不对其内容负责。包含任何指向外部网站的链接并不表示红帽认可该网站或其实体、产品或服务。您同意红帽对因您使用(或依赖)外部网站或内容而导致的任何损失或费用不承担任何责任。

2.8.2.4. Zync 数据库 secret

在 zync 数据库设置中,当启用 High Availability 时,如果也启用了 externalZyncDatabaseEnabled 字段,用户必须预先创建名为 zync 的 secret。然后,使用 DATABASE_URLDATABASE_PASSWORD 字段设置 zync,其值指向外部数据库。外部数据库必须处于高可用性模式。请参见以下示例:

apiVersion: v1
kind: Secret
metadata:
  name: zync
stringData:
  DATABASE_URL: postgresql://<zync-db-user>:<zync-db-password>@<zync-db-host>:<zync-db-port>/zync_production
  ZYNC_DATABASE_PASSWORD: <zync-db-password>
type: Opaque

2.8.2.5. 用于部署 3scale 的 APIManager 自定义资源

注意
  • 当启用 highAvailability 时,您必须预先创建 backend-redissystem-redissystem-database secret。
  • 当您启用 highAvailabilityexternalZyncDatabaseEnabled 字段时,您必须预先创建 zync 数据库 secret。

    • 对于 system-database,仅选择要外部化的数据库。

APIManager 自定义资源的配置将取决于您的 3scale 部署外部您选择的数据库。

如果您的后端 Redis、系统 Redis 和系统数据库将在 3scale 外部,APIManager 自定义资源必须将 highAvailability 设置为 true。请参见以下示例:

apiVersion: apps.3scale.net/v1alpha1
kind: APIManager
metadata:
  name: example-apimanager
spec:
  wildcardDomain: lvh.me
  highAvailability:
    enabled: true

如果您的 zync 数据库将是外部,APIManager 自定义资源必须将 highAvailability 设置为 true,并且 externalZyncDatabaseEnabled 还必须设置为 true。请参见以下示例:

apiVersion: apps.3scale.net/v1alpha1
kind: APIManager
metadata:
  name: example-apimanager
spec:
  wildcardDomain: lvh.me
  highAvailability:
    enabled: true
    externalZyncDatabaseEnabled: true

2.8.3. Amazon Simple Storage Service 3scale Filestorage 安装

以下示例演示了使用 Amazon Simple Storage Service(Amazon S3)而不是持久性卷声明(PVC)的 3scale FileStorage

在创建 APIManager 自定义资源以部署 3scale 之前,需要使用 openshift secret 提供 S3 服务的连接设置。

2.8.3.1. Amazon S3 secret

在以下示例中,Secret 名称可以是任何人,因为它将在 APIManager 自定义资源中引用。

kind: Secret
metadata:
  creationTimestamp: null
  name: aws-auth
stringData:
  AWS_ACCESS_KEY_ID: 123456
  AWS_SECRET_ACCESS_KEY: 98765544
  AWS_BUCKET: mybucket.example.com
  AWS_REGION: eu-west-1
type: Opaque

最后,创建 APIManager 自定义资源来部署 3scale。

apiVersion: apps.3scale.net/v1alpha1
kind: APIManager
metadata:
  name: example-apimanager
spec:
  wildcardDomain: lvh.me
  system:
    fileStorage:
      simpleStorageService:
        configurationSecretRef:
          name: aws-auth
注意

Amazon S3 区域和 Amazon S3 存储桶设置直接在 APIManager 自定义资源中提供。Amazon S3 secret 名称直接在 APIManager 自定义资源中提供。

检查 APIManager SystemS3Spec 供参考。

2.8.4. PostgreSQL 安装

MySQL 内部关系数据库是默认的部署。此部署配置可以被覆盖来改用 PostgreSQL。

apiVersion: apps.3scale.net/v1alpha1
kind: APIManager
metadata:
  name: example-apimanager
spec:
  wildcardDomain: lvh.me
  system:
    database:
      postgresql: {}

检查 APIManager DatabaseSpec 以了解参考。

2.8.5. 在组件级别自定义计算资源要求

通过 APIManager 自定义资源属性自定义 3scale 解决方案中的 Kubernetes 计算资源要求。这样做可自定义分配给特定 APIManager 组件的计算资源要求,即 CPU 和内存。

以下示例概述了如何自定义 system-master 的 system-provider 容器、backend-listenerzync-database 的计算资源要求:

apiVersion: apps.3scale.net/v1alpha1
kind: APIManager
metadata:
  name: example-apimanager
spec:
  backend:
    listenerSpec:
      resources:
        requests:
          memory: "150Mi"
          cpu: "300m"
        limits:
          memory: "500Mi"
          cpu: "1000m"
  system:
    appSpec:
      providerContainerResources:
        requests:
          memory: "111Mi"
          cpu: "222m"
        limits:
          memory: "333Mi"
          cpu: "444m"
  zync:
    databaseResources:
      requests:
        memory: "111Mi"
        cpu: "222m"
      limits:
        memory: "333Mi"
        cpu: "444m"

其他资源

如需有关如何指定组件级别自定义资源要求的更多信息,请参阅 APIManager CRD 引用

2.8.5.1. 默认 APIManager 组件计算资源

当您将 APIManager spec.resourceRequirementsEnabled 属性配置为 true 时,会为 APIManager 组件设置默认计算资源。

下表中显示了为 APIManager 组件设置的特定计算资源默认值。

2.8.5.1.1. CPU 和内存单元

下表说明了您将在计算资源默认值表中找到的单元。如需有关 CPU 和内存单元的更多信息,请参阅管理容器的资源

资源单元解释

  • m - milliCPU 或 millicore
  • Mi - mebibytes
  • Gi - gibibyte
  • G - gigabyte

表 2.2. 计算资源默认值

组件CPU 请求CPU 限值内存请求内存限值

system-app 的 system-master

50m

1000m

600Mi

800Mi

system-app 的 system-provider

50m

1000m

600Mi

800Mi

system-app 的 system-developer

50m

1000m

600Mi

800Mi

system-sidekiq

100m

1000m

500Mi

2Gi

system-sphinx

80m

1000m

250Mi

512Mi

system-redis

150m

500m

256Mi

32Gi

system-mysql

250m

无限制

512Mi

2Gi

system-postgresql

250m

无限制

512Mi

2Gi

backend-listener

500m

1000m

550Mi

700Mi

backend-worker

150m

1000m

50Mi

300Mi

backend-cron

50m

150m

40Mi

80Mi

backend-redis

1000m

2000m

1024Mi

32Gi

apicast-production

500m

1000m

64Mi

128Mi

apicast-staging

50m

100m

64Mi

128Mi

zync

150m

1

250M

512Mi

zync-que

250m

1

250M

512Mi

zync-database

50m

250m

250M

2G

2.8.6. 组件级别的自定义节点关联性和容限

在 Red Hat 3scale API Management 中自定义 Kubernetes 关联性容限APIManager 自定义资源属性用于定制一个安装中的不同 3scale 组件如何调度到 Kubernetes 节点。

以下示例为后端设置自定义节点关联性。它还为 system-memcached 设置监听程序和自定义容限:

apiVersion: apps.3scale.net/v1alpha1
kind: APIManager
metadata:
  name: example-apimanager
spec:
  backend:
    listenerSpec:
      affinity:
        nodeAffinity:
          requiredDuringSchedulingIgnoredDuringExecution:
            nodeSelectorTerms:
            - matchExpressions:
              - key: "kubernetes.io/hostname"
                operator: In
                values:
                - ip-10-96-1-105
              - key: "beta.kubernetes.io/arch"
                operator: In
                values:
                - amd64
  system:
    memcachedTolerations:
    - key: key1
      value: value1
      operator: Equal
      effect: NoSchedule
    - key: key2
      value: value2
      operator: Equal
      effect: NoSchedule

其他资源

如需与关联性和容限相关的完整属性列表,请参阅 APIManager CDR 参考

2.8.7. 协调

安装 3scale 后,3scale 操作器将启用更新自定义资源中的一组给定参数,以修改系统配置选项。可以通过 热交换 (即,不停止或关闭系统)进行修改。

并非所有 APIManager 自定义资源定义(CRD)的参数都是可协调的。

以下是可协调参数列表:

2.8.7.1. Resources

所有 3scale 组件的资源限制和请求.

apiVersion: apps.3scale.net/v1alpha1
kind: APIManager
metadata:
  name: example-apimanager
spec:
  ResourceRequirementsEnabled: true/false

2.8.7.2. 后端副本

后端 组件 pod 数量。

apiVersion: apps.3scale.net/v1alpha1
kind: APIManager
metadata:
  name: example-apimanager
spec:
  backend:
    listenerSpec:
      replicas: X
    workerSpec:
      replicas: Y
    cronSpec:
      replicas: Z

2.8.7.3. APIcast 副本

APIcast staging 和生产组件 pod 数量。

apiVersion: apps.3scale.net/v1alpha1
kind: APIManager
metadata:
  name: example-apimanager
spec:
  apicast:
    productionSpec:
      replicas: X
    stagingSpec:
      replicas: Z

2.8.7.4. 系统副本

系统 应用程序和系统 sidekiq 组件 pod 数量

apiVersion: apps.3scale.net/v1alpha1
kind: APIManager
metadata:
  name: example-apimanager
spec:
  system:
    appSpec:
      replicas: X
    sidekiqSpec:
      replicas: Z

2.8.7.5. Zync 副本

Zync app 和 que 组件 pod 数量

apiVersion: apps.3scale.net/v1alpha1
kind: APIManager
metadata:
  name: example-apimanager
spec:
  zync:
    appSpec:
      replicas: X
    queSpec:
      replicas: Z

2.9. 常见 3scale 安装问题的故障排除

这部分包含常见安装问题列表,并为它们解决提供指导。

2.9.1. 以前的部署导致存在脏的持久性卷声明

问题

之前的部署尝试导致脏的持久性卷声明(PVC),从而导致 MySQL 容器无法启动。

原因

在 OpenShift 中删除项目不会清理与其关联的 PVC。

解决方案

流程

  1. 使用 oc get pvc 命令查找包含错误 MySQL 数据的 PVC:

    # oc get pvc
    NAME                    STATUS    VOLUME    CAPACITY   ACCESSMODES   AGE
    backend-redis-storage   Bound     vol003    100Gi      RWO,RWX       4d
    mysql-storage           Bound     vol006    100Gi      RWO,RWX       4d
    system-redis-storage    Bound     vol008    100Gi      RWO,RWX       4d
    system-storage          Bound     vol004    100Gi      RWO,RWX       4d
  2. 点 OpenShift UI 中的 cancel 部署,以停止 system-mysql 容器集的部署。
  3. 删除 MySQL 路径下的所有内容,以清理卷。
  4. 启动新的 system-mysql 部署。

2.9.2. 经过身份验证的用户 registry 的错误或缺少凭证

问题

Pod 没有启动。镜像流显示以下错误:

! error: Import failed (InternalError): ...unauthorized: Please login to the Red Hat Registry

原因

在 OpenShift 4.x 上安装 3scale 时,OpenShift 无法启动 pod,因为 ImageStreams 无法拉取它们引用的镜像。这是因为 pod 无法针对它们所指向的 registry 进行身份验证。

解决方案

流程

  1. 键入以下命令以验证容器 registry 身份验证的配置:

    $ oc get secret
    • 如果 secret 存在,您会在终端中看到以下输出:

      threescale-registry-auth          kubernetes.io/dockerconfigjson        1         4m9s
    • 但是,如果没有看到输出结果,您必须执行以下操作:
  2. 创建 registry 服务帐户时,使用之前设置的凭证来创建您的 secret。
  3. 使用在 OpenShift 中配置 registry 身份验证的步骤,替换 oc create secret 命令中的 <your-registry-service-account-username> and <your-registry-service-account-password>
  4. 在与 APIManager 资源相同的命名空间中生成 threescale-registry-auth secret。您必须在 <project-name> 中运行以下命令:

    oc project <project-name>
    oc create secret docker-registry threescale-registry-auth \
      --docker-server=registry.redhat.io \
      --docker-username="<your-registry-service-account-username>" \
      --docker-password="<your-registry-service-account-password>"
      --docker-email="<email-address>"
  5. 删除并重新创建 APIManager 资源:

    $ oc delete -f apimanager.yaml
    apimanager.apps.3scale.net "example-apimanager" deleted
    
    $ oc create -f apimanager.yaml
    apimanager.apps.3scale.net/example-apimanager created

验证

  1. 键入以下命令,以确认部署的状态为 StartingReady :pod 会开始生成:

    $ oc describe apimanager
    (...)
    Status:
      Deployments:
        Ready:
          apicast-staging
          system-memcache
          system-mysql
          system-redis
          zync
          zync-database
          zync-que
        Starting:
          apicast-production
          backend-cron
          backend-worker
          system-sidekiq
          system-sphinx
        Stopped:
          backend-listener
          backend-redis
          system-app
  2. 键入以下命令以查看每个 pod 的状态:

    $ oc get pods
    NAME                               READY   STATUS             RESTARTS   AGE
    3scale-operator-66cc6d857b-sxhgm   1/1     Running            0          17h
    apicast-production-1-deploy        1/1     Running            0          17m
    apicast-production-1-pxkqm         0/1     Pending            0          17m
    apicast-staging-1-dbwcw            1/1     Running            0          17m
    apicast-staging-1-deploy           0/1     Completed          0          17m
    backend-cron-1-deploy              1/1     Running            0          17m

2.9.3. 从 Docker registry 中拉取错误

问题

在安装过程中出现以下错误:

svc/system-redis - 1EX.AMP.LE.IP:6379
  dc/system-redis deploys docker.io/rhscl/redis-32-rhel7:3.2-5.3
    deployment #1 failed 13 minutes ago: config change

原因

OpenShift 通过发出 docker 命令来搜索和调取容器镜像。此命令引用 docker.io Docker registry,而不是 registry.redhat.io 红帽生态系统目录。

当系统包含 Docker 容器化环境的意外版本时,会出现这种情况。

解决方案

2.9.4. 在本地挂载持久性卷时 MySQL 的权限问题

问题

system-msql pod 崩溃且不部署,从而导致其他系统依赖它失败部署。pod 日志显示以下错误:

[ERROR] Cannot start server : on unix socket: Permission denied
[ERROR] Do you already have another mysqld server running on socket: /var/lib/mysql/mysql.sock ?
[ERROR] Aborting

原因

MySQL 进程启动时不正确的用户权限。

解决方案

流程

  1. 用于持久性卷的目录 MUST 具有 root 组的写入权限。对 root 用户具有读写权限不够,因为 MySQL 服务以 root 组中的不同用户身份运行。以 root 用户身份执行以下命令:

    chmod -R g+w /path/for/pvs
  2. 执行以下命令以防止 SElinux 阻止访问:

    chcon -Rt svirt_sandbox_file_t /path/for/pvs

2.9.5. 无法上传徽标或图像

问题

无法上传徽标 - system-app 日志显示以下错误:

Errno::EACCES (Permission denied @ dir_s_mkdir - /opt/system/public//system/provider-name/2

原因

OpenShift 无法写入持久卷。

解决方案

流程

确保您的持久卷可由 OpenShift 写入。它应归 root 组所有,并且可写入组。

2.9.6. 测试在 OpenShift 中无法正常工作的调用

问题

测试调用在创建新服务和 OpenShift 上的路由后无法正常工作。通过 curl 直接调用也失败,带有 service not available 信息。

原因

3scale 默认需要 HTTPS 路由,并且 OpenShift 路由不受保护。

解决方案

流程

确保 OpenShift 路由器设置中点击了 安全路由 复选框。

2.9.7. 来自 3scale 的一个不同项目上部署 APIcast 失败

问题

APIcast 部署失败(pod 没有变为蓝色)。您在日志中看到以下错误:

update acceptor rejected apicast-3: pods for deployment "apicast-3" took longer than 600 seconds to become ready

您在 pod 中看到以下错误:

Error synching pod, skipping: failed to "StartContainer" for "apicast" with RunContainerError: "GenerateRunContainerOptions: secrets \"apicast-configuration-url-secret\" not found"

原因

该机密没有正确设置。

解决方案

流程

使用 APIcast v3 创建 secret 时,指定 apicast-configuration-url-secret

oc create secret generic apicast-configuration-url-secret --from-literal=password=https://<ACCESS_TOKEN>@<TENANT_NAME>-admin.<WILDCARD_DOMAIN>

第 3 章 安装 APIcast

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

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

先决条件

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

  • 您需要一个正常工作的 3scale On-Premises 实例。

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

3.1. APIcast 部署选项

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

  • 嵌入式 APIcast :默认情况下,两个 APIcast 网关(staging 和 production)随 3scale API 管理安装一同提供。它们预先配置好,随时开箱即用。
  • 自我管理的 APIcast :您可以随时随地部署 APIcast。以下是部署 APIcast 的几个推荐选项:

3.2. APIcast 环境

默认情况下,当您创建 3scale 帐户时,您将在两个不同的环境中获取嵌入式 APIcast:

  • Staging:仅在配置和测试 API 集成时使用。当您确认您的设置按预期工作时,您可以选择将其部署到生产环境中。OpenShift 模板设置 Staging APIcast 的参数,以便在每次 API 调用上重新载入配置(APICAST_CONFIGURATION_LOADER: lazy,APICAST_CONFIGURATION_CACHE):0).快速测试 APIcast 配置中的更改非常有用。
  • Production:此环境专用于生产环境。在 OpenShift 模板中为 Production APIcast 设置以下参数:APICAST_CONFIGURATION_LOADER: boot,APICAST_CONFIGURATION_CACHE:300.这意味着,在 APIcast 启动时将完全加载配置,并将缓存 300 秒(5 分钟)。5 分钟后将重新加载配置。这意味着,当您将配置提升到生产环境时,可能需要 5 分钟才能应用,除非您触发新的 APIcast 部署。

3.3. 配置集成设置

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

先决条件

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

流程

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

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

3.4. 配置服务

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

本节将指导您配置服务:

3.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"
      }

3.4.2. 配置身份验证设置

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

表 3.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:身份验证失败、缺少身份验证和不匹配。

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

响应代码响应正文

403

身份验证失败

403

缺少身份验证参数

404

没有匹配的映射规则

429

超过用量限制

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

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

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

主机

字符串

N/A

路由到网关的域名

tls

[]extensions.IngressTLS

N/A

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.7. 对 APIcast 的 Websocket 协议支持

红帽 3scale API 管理在 APIcast 网关中支持 WebSocket 协议连接到后端 API。

如果您计划实施 WebSocket 协议,则需要考虑以下列表:

  • WebSocket 协议不支持 JSON Web Token(JWT)。
  • WebSocket 标准不允许额外的标题。
  • WebSocket 协议不属于 HTTP/2 标准。

3.7.1. Websocket 协议支持

APIcast 配置策略链如下:

"policy_chain": [
  { "name": "apicast.policy.websocket" },
  { "name": "apicast.policy.apicast" }
],

API 后端可以定义为 http[s]`ws[s]

3.8. APIcast 网关中的 HTTP/2

红帽 3scale API 管理为 HTTP/2 和远程过程调用(gRPC)连接提供 APIcast 网关支持。HTTP/2 协议控制实现了 APIcast 和 API 后端之间的数据通信。

注意
  • 您不能使用 api_key 授权。改为使用 JSON Web Token(JWT)或标头。
  • gRPC 端点终止传输层安全(TLS)。
  • gRPC 策略(HTTP/2)必须高于策略链中的 APIcast 策略。

3.8.1. HTTP/2 协议支持

使用 HTTP/2 终止时,APICast 启用的 HTTP/2 和后端可以是 HTTP/1.1 纯文本或 TLS。

在使用策略的 HTTP/2 端点中,有一些限制:

  • 如果此策略无法正常工作,端点需要侦听 TLS。
  • 只有在启用了 TLS 策略时,gRPC 完整流才会正常工作。

APIcast 配置策略链如下:

"policy_chain": [
  { "name": "apicast.policy.grpc" },
  { "name": "apicast.policy.apicast" }
],

3.9. 其他资源

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

第 4 章 在 Red Hat OpenShift 上运行 APIcast

本教程介绍了如何在 Red Hat OpenShift 中部署 APIcast API 网关。

先决条件

  • 您必须根据 第 3 章 安装 APIcast 在 Red Hat 3scale API 管理门户中配置 APIcast。
  • 确保将 自助管理的网关 选为集成设置中的部署选项。
  • 您应当已将暂存和生产环境都配置为继续操作。

要在 Red Hat OpenShift 上运行 APIcast,请执行以下部分中所述的步骤:

4.1. 设置 Red Hat OpenShift

如果您已经有一个正在运行的 OpenShift 集群,您可以跳过本节。否则,继续阅读:

对于生产环境,您可以按照 OpenShift 安装的说明进行操作

在本教程中,将通过以下命令安装 OpenShift 集群:

  • Red Hat Enterprise Linux (RHEL) 7
  • Docker 容器化环境 v1.10.3
  • OpenShift Origin 命令行界面(CLI)- v1.3.1

使用以下部分来设置 Red Hat OpenShift:

4.1.1. 安装 Docker 容器化环境

红帽提供的 Docker 格式容器镜像作为 RHEL 中的 Extras 频道的一部分发布。要启用附加软件仓库,您可以使用 Subscription Manager 或 yum config Manager。详情请查看 RHEL 产品文档

对于部署在 AWS EC2 实例上的 RHEL 7,您将使用以下说明:

流程

  1. 列出所有软件仓库:

    sudo yum repolist all
  2. 查找并启用 *-extras 存储库:

    sudo yum-config-manager --enable rhui-REGION-rhel-server-extras
  3. 安装 Docker 格式的容器镜像:

    sudo yum install docker docker-registry
  4. 通过在 /etc/sysconfig/docker 文件中添加或取消注释以下行来添加不安全的 registry 172.30.0.0/16

    INSECURE_REGISTRY='--insecure-registry 172.30.0.0/16'
  5. 启动 Docker 服务:

    sudo systemctl start docker
  6. 使用以下命令验证容器服务是否正在运行:

    sudo systemctl status docker

4.1.2. 启动 OpenShift 集群

要启动 OpenShift 集群,请执行以下操作:

流程

  1. OpenShift 发行页面 下载客户端工具的最新稳定版本(openshift-origin-client-tools-VERSION-linux-64bit.tar.gz),并将从存档中提取的 Linux oc 二进制文件放在 PATH 中。

    注意

    docker 命令以 root 用户身份运行,因此您需要使用 root 特权运行任何 oc 或 docker 命令。

  2. 打开终端,该用户有运行 docker 命令的权限并运行:

    oc cluster up

    在输出底部,您可以找到有关部署的集群的信息:

        -- Server Information ...
          OpenShift server started.
          The server is accessible via web console at:
          https://172.30.0.112:8443
    
          You are logged in as:
            User:     developer
            Password: developer
    
          To login as administrator:
            oc login -u system:admin
  3. 注意分配给您的 OpenShift 服务器的 IP 地址。您将在教程中将其指代为 OPENSHIFT-SERVER-IP

4.1.3. 在远程服务器上设置 OpenShift 集群(可选)

如果要在远程服务器上部署 OpenShift 集群,则需要在启动集群时明确指定公共主机名和路由后缀,以便您可以远程访问 OpenShift Web 控制台。

例如,如果您要在 AWS EC2 实例上部署,您应该指定以下选项:

oc cluster up --public-hostname=ec2-54-321-67-89.compute-1.amazonaws.com --routing-suffix=54.321.67.89.xip.io

其中 ec2-54-321-67-89.compute-1.amazonaws.com 是公共域,而 54.321.67.89 是实例的 IP。然后,您将可以访问位于 https://ec2-54-321-67-89.compute-1.amazonaws.com:8443 的 OpenShift Web 控制台。

4.2. 使用 OpenShift 模板部署 APIcast

注意
  • 在使用模板时,您只能在 OpenShift Container Platform(OCP) 3.11 上部署 APIcast。
  • 基于 Operator 的安装仅支持 OCP 版本 4.1 和 4.2。
  • 有关支持配置的更多信息,请参阅 Red Hat 3scale API 管理支持的配置 页面。

使用以下内容来部署 APIcast 取消 OpenShift 模板:

流程

  1. 默认情况下,您以 developer 用户身份登录,并可继续下一步。

    否则,请从您在上一步中下载和安装的 OpenShift 客户端工具使用 oc login 命令登录 OpenShift。默认登录凭证为 username = "developer"password = "developer":

    oc login https://OPENSHIFT-SERVER-IP:8443

    您应当会在输出中看到 Login successful.

  2. 创建您的项目。本例设置显示名为 gateway

    oc new-project "3scalegateway" --display-name="gateway" --description="3scale gateway demo"

    响应应如下所示:

    Now using project "3scalegateway" on server "https://172.30.0.112:8443"

    忽略命令提示符处文本输出中的建议后续步骤,再继续下面的下一步。

  3. 通过将 <access_token><domain> 替换为您自己的凭证来创建新 secret 来引用项目。有关 <access_token><domain> 的更多信息,请参阅下方。

    oc create secret generic apicast-configuration-url-secret --from-literal=password=https://<access_token>@<admin_portal_domain>  --type=kubernetes.io/basic-auth

    这里的 <access_token> 是 3scale 帐户的 访问令牌<domain>-admin.3scale.net 是 3scale 管理门户的 URL。

    响应应如下所示:

    secret/apicast-configuration-url-secret
  4. 从模板为您的 APIcast 网关创建一个应用程序,并启动部署:

    oc new-app -f https://raw.githubusercontent.com/3scale/3scale-amp-openshift-templates/2.8.0.GA/apicast-gateway/apicast.yml

    您应该在输出的底部看到以下信息:

        --> Creating resources with label app=3scale-gateway ...
            deploymentconfig "apicast" created
            service "apicast" created
        --> Success
            Run 'oc status' to view your app.

4.3. 通过 OpenShift 控制台创建路由

要通过 OpenShift 控制台创建路由,请执行以下操作:

流程

  1. 在浏览器中为 OpenShift 集群打开 Web 控制台:

    https://OPENSHIFT-SERVER-IP:8443/console/

    如果在远程服务器上启动 OpenShift 集群,请使用 --public-hostname 中指定的值,而不是 OPENSHIFT-SERVER-IP

    您将看到 OpenShift 的登录屏幕。

    注意

    您可能会收到有关不受信任的网站的警告。这是正常的,因为您要尝试通过安全协议访问 Web 控制台,而无需配置有效证书。虽然您应该在生产环境中避免这种情况,但对于此测试设置,您可以继续操作并为此地址创建一个例外。

  2. 使用在 Setting Red Hat OpenShift 部分中创建或获取的开发人员凭据登录。

    您将看到项目列表,包括上面通过命令行创建的 gateway 项目。如果没有看到您的网关项目,您可能用其他用户创建它,并且需要将策略角色分配给此用户。

  3. gateway 链接,您将看到 概述 选项卡。

    OpenShift 下载了 APIcast 的代码,并启动了部署。您可能会在部署进行时看到消息 Deployment #1 running

    构建完成后,用户界面(UI)会刷新并显示 OpenShift 启动的 APIcast (1 pod)实例,如模板中定义的。

    在启动时,每个 APIcast 实例都会使用 3scale 管理门户的 Integration 页面中提供的设置从 3scale 下载所需的配置。

    OpenShift 将维护两个 APIcast 实例,并监控这两者的健康状态;任何不健康的 APIcast 实例将自动替换为新的实例。

  4. 为了允许您的 APIcast 实例接收流量,您需要创建一个路由。首先点 Create Route

    Public Base URL 部分(不带 http:// 且不带端口)部分输入您在 3scale 中设置的同一主机,如 gateway.openshift.demo。然后 单击创建按钮

    对于您定义的每 3scale 产品,您必须创建一个新路由。

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

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

注意

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

  • RHEL 7.7
  • Docker 1.13.1

先决条件

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

5.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 文档:

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

要运行 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-rhel8:3scale2.9
  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-rhel8:3scale2.9

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

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

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

5.2.2. 测试 APIcast

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

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

注意

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

其他资源

5.3. 其他资源

第 6 章 在 Podman 上部署 APIcast

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

注意

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

  • RHEL 8.x
  • Podman 1.4.2

先决条件

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

6.1. 安装 Podman 容器环境

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

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

流程

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

    sudo dnf install podman

其他资源

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

6.2. 运行 Podman 环境

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

流程

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

    podman pull registry.redhat.io/3scale-amp2/apicast-gateway-rhel8:3scale2.9
  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.9

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

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

6.2.1. 使用 Podman 测试 APIcast

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

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

注意

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

6.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\":

6.4. 其他资源

第 7 章 在 OpenShift 上安装 3scale Operator

注意

3scale 支持 OpenShift Container Platform(OCP)的最后两个通用版本(GA)。如需更多信息,请参阅 Red Hat 3scale API 管理支持的配置 页面。

本文档演示了如何:

  • 创建新项目。
  • 部署红帽 3scale API 管理实例。
  • 在项目中创建 threescale-registry-auth 机密。
  • 通过 Operator Lifecycle Manager(OLM)安装 3scale Operator。
  • 部署 Operator 后,部署自定义资源。

先决条件

  • 使用具有管理员权限的帐户访问受支持的 OpenShift Container Platform 4 集群版本。

警告

在另一个新创建的空项目中部署 3scale 操作器和自定义资源定义(CRD)。如果您将其部署到包含基础架构的现有项目中,则可能会更改或删除现有的元素。

要在 OpenShift 上安装 3scale 操作器,请执行以下部分中所述的步骤:

7.1. 创建新的 OpenShift 项目

此流程说明了如何创建名为 3scale-project 的新 OpenShift 项目。将此项目名称替换为您自己的项目名称。

流程

要创建新 OpenShift 项目,请执行以下操作:

  • 使用字母数字字符和短划线表示有效的名称。例如,运行以下命令来创建 3scale-project

    oc new-project 3scale-project

这会创建新的 OpenShift 项目,其中将安装 operator、APIManager 自定义资源(CR)和 Capabilities 自定义资源。Operator 通过该项目中的 OLM 管理自定义资源。

7.2. 使用 OLM 安装和配置 3scale Operator

使用 Operator Lifecycle Manager(OLM)通过 OCP 控制台中的 OperatorHub 在 OpenShift Container Platform(OCP)4.3 集群上安装 3scale 操作器。

注意

流程

  1. 在 OpenShift Container Platform 控制台中,使用具有管理员特权的帐户登录。
  2. 菜单结构取决于您使用的 OpenShift 版本:

    • Operators > OperatorHub
  3. Filter by keyword 框中,键入 3scale operator 来查找 3scale 运算符。
  4. 点 3scale operator。这时会显示 Operator 信息。
  5. 阅读有关 Operator 的信息,再点 InstallCreate Operator Subscription 页面会打开。
  6. Create Operator Subscription 页面中,接受所有默认选择并点 Subscribe

    注意

    Operator 仅在您选择的集群上的特定单一命名空间中可用。

    此时会显示 3scale-operator 详情页面,您可以在其中看到 Subscription Overview

  7. 确认订阅 升级状态 显示为 Up to date
  8. 验证 3scale Operator ClusterServiceVersion(CSV)是否已显示,Operator 的 Status 最终会在您在 创建新 OpenShift 项目中定义的项目中 解析为 InstallSucceeded

    • Operators > Installed Operators。在这种情况下,成功安装将注册 APIManager CRD,以及与 OpenShift API 服务器 中 Operator Capabilities 功能相关的 CRD。
  9. 成功安装后,通过 oc get 查询 CRD 定义的资源类型。

    1. 例如,要验证 APIManager CRD 是否已正确注册,请执行以下命令:

      oc get apimanagers
  10. 您应该看到以下输出:

    No resources found.

除了指定的步骤外,在受限网络中使用 OCP 时,创建一个在 3scale 开发人员门户中使用的允许域的列表。请考虑以下示例:

  • 您打算添加到开发人员门户的任何链接。
  • 通过第三方 SSO 提供程序(如 GitHub)进行 SSO 集成.
  • 计费。
  • 触发外部 URL 的 Webhook。

7.2.1. 在断开连接的环境中的限制

以下列表概述了 3scale 2.9 在断开连接的环境中的当前限制:

  • GitHub 登录 Developer Portal 不可用。
  • 支持链接不可用。
  • 到外部文档的链接无法正常运行。
  • Developer Portal 中的 OpenAPI 规范(OAS)验证器不正常运行,会影响外部服务的链接。
  • ActiveDocs 的产品 概述 页面中,到 OAS 的链接不起作用。

    • 在创建新的 ActiveDocs 规格时,还需要检查 Skip swagger 验证选项。

其他资源

第 8 章 3scale 高可用性和评估模板

本文档描述了红帽 3scale API 管理 2.9 安装所使用的高可用性评估模板。

先决条件

  • 您需要有一个可用的 OpenShift 集群来部署高可用性和评估模板的元素。
重要

3scale 高可用性和评估模板只是一个技术预览功能。技术预览功能不受红帽产品服务等级协议(SLA)支持,且功能可能并不完整。红帽不推荐在生产环境中使用它们。这些技术预览功能可以使用户提早试用新的功能,并有机会在开发阶段提供反馈意见。有关红帽技术预览功能支持范围的更多信息,请参阅技术预览功能支持范围

要部署高可用性和评估模板,请执行以下部分中所述的步骤:

8.1. 高可用性模板

High Availability(HA)模板允许您为关键数据库设置 HA。

先决条件

  • 在部署 HA 模板之前,您必须部署和配置外部数据库,并使用负载均衡端点在 HA 配置中配置它们。

使用 HA 模板

对于 HA,名为 amp-ha-tech-preview.yml 的模板允许您将关键数据库部署到 OpenShift 外部。这不包括:

  • Memcached
  • Sphinx
  • Zync

标准 amp.yml 模板和 amp-ha-tech-preview.yml 之间的区别包括:

  • 删除以下元素:

    • backend-redis 及其相关组件
    • system-redis 及其相关组件
    • system-mysql 及其相关组件
    • redis 和 MySQL 相关 ConfigMap
    • MYSQL_IMAGE, REDIS_IMAGE, MYSQL_USER, MYSQL_ROOT_PASSWORD 参数
  • 默认情况下,将非数据库 DeploymentConfig 对象类型的副本数从 1 增加到 2。
  • 添加以下强制参数,以便您控制外部数据库的位置:

    • BACKEND_REDIS_STORAGE_ENDPOINT
    • BACKEND_REDIS_QUEUES_ENDPOINT
    • SYSTEM_REDIS_URL
    • APICAST_STAGING_REDIS_URL
    • APICAST_PRODUCTION_REDIS_URL
    • SYSTEM_DATABASE_URL

使用 amp-ha-tech-preview.yml,您需要通过新增的强制参数从集群中配置数据库连接(不包括 system-memcachezync-databasesystem-sphinx )。端点需要数据库负载均衡的连接字符串,包括身份验证信息。另外,对于非数据库部署,pod 副本数默认增加到 2,以在应用级别具有冗余性。

8.1.1. 为高可用性设置 RWX_STORAGE_CLASS

ReadWriteMany(RWX) PersistentVolumeClaims(PVC)使用存储类 RWX_STORAGE_CLASS。

必需 :false

null

  • 将此设置为 null 会向 OpenShift 发出信号,指出您希望该存储类自动发现(无值)。
  • 如果将其设置为空字符串或没有默认值,它会向 OpenShift 发送信号,表示您希望字符串存储为空。这是无效的设置。

8.2. 评估模板

出于评估目的,有一个名为 amp-eval-tech-preview.yml 的模板,模板可在无资源请求或限制的情况下部署 3scale 环境。

与 standard amp.yml 模板相比,唯一功能区别在于已删除资源限制和请求。这意味着,在此版本中,CPU 和内存级别的 pod 上已删除了最低硬件要求。此模板仅用于评估、测试和开发目的,因为它尝试使用给定的硬件资源以最佳的方式部署组件。

第 9 章 对 3scale 的 redis 高可用性(HA)支持

重要

红帽官方不支持为零停机时间设置 Redis、为 3scale 配置后端组件或 Redis 数据库复制和分片。其内容仅供参考。另外,3scale 不支持 Redis 集群模式

OpenShift 容器平台(OCP)为大多数组件提供高可用性(HA)。如需更多信息,请参阅 OpenShift Container Platform 3.11 第 30 章。高可用性

红帽 3scale API 管理中的 HA 数据库组件包括:

  • backend-redis :用于统计存储和临时作业存储。
  • system-redis :为 3scale 的后台作业提供临时存储,也用作 system-app pod 的 Ruby 处理的消息总线。

backend-redissystem-dis 都可以与 Redis Sentinel 和 Redis Enterprise 支持的 Redis 高可用性变体一起工作。

如果 Redis pod 进入停止状态,或者 OpenShift Container Platform 停止它,则会自动创建新的 pod。持久存储将恢复数据,以便 pod 继续工作。在这些情况下,新容器集启动时会出现少量停机时间。这是因为 Redis 中不支持多主设置的限制。您可以通过在已部署 Redis 的所有节点上预安装 Redis 镜像来缩短停机时间。这将加快 pod 重启时间。

为零停机时间设置 Redis,并为 3scale 配置后端组件:

先决条件

  • 具有管理员角色的 3scale 帐户。

9.1. 为零停机时间设置 Redis

以 3scale 管理员身份,如果您不需要停机,请在 OCP 外部配置 Redis。使用 3scale pod 的配置选项进行设置的方法有几种:

  • 设置您自己的自助管理的 Redis
  • 使用 Redis Sentinel:参考 Redis Sentinel 文档
  • redis 作为服务提供:

    例如:

    • Amazon ElastiCache
    • redis Labs
注意

红帽不支持上述服务。提及任何此类服务并不意味着红帽认可这些产品或服务。您同意,由于您使用(或依赖)任何外部内容而可能导致的任何损失或费用,红帽不承担任何责任。

9.2. 为 3scale 配置后端组件

作为 3scale 管理员,在以下部署配置中为 后端组件环境变量配置 Redis HA(failover):backend-cronbackend-listenerbackend-worker。这些配置是 3scale 中红帽 HA 所必需的。

注意

如果要将 Redis 与 sendinel 一起使用,您必须使用所有字段创建 system-redis secret,以便在部署 3scale 前配置您要指向的 Redis。从 3scale 开始,这些字段在后端中不作为参数提供。

9.2.1. 创建 backend-redissystem-redis secret

按照以下步骤相应地创建 backend-redissystem-redis secret:

9.2.2. 为 HA 部署 3scale 的新安装

  1. 使用以下字段创建 backend-redissystem-redis secret:

    backend-redis

    REDIS_QUEUES_SENTINEL_HOSTS
    REDIS_QUEUES_SENTINEL_ROLE
    REDIS_QUEUES_URL
    REDIS_STORAGE_SENTINEL_HOSTS
    REDIS_STORAGE_SENTINEL_ROLE
    REDIS_STORAGE_URL

    system-redis

    MESSAGE_BUS_NAMESPACE
    MESSAGE_BUS_SENTINEL_HOSTS
    MESSAGE_BUS_SENTINEL_ROLE
    MESSAGE_BUS_URL
    NAMESPACE
    SENTINEL_HOSTS
    SENTINEL_ROLE
    URL

    • 当使用 sendinels 为 Redis 配置时,backend-redissystem-redis 中的对应 URL 字段以 redis://[:redis-password@]redis-group[/db]' 格式引用 Redis 组,其中 [x] 表示可选元素 xredis-passwordredis-groupdb 是变量。

      示例

      redis://:redispwd@mymaster/5

    • SENTINEL_HOSTS 字段采用以下格式以逗号分隔:

      redis://:sentinel-password@sentinel-hostname-or-ip:port
      • 对于列表的每个元素,[x] 表示可选元素 xsendinel-passwordfinel-hostname-or-ipport 是相应地替换的变量:

        示例

        :sentinelpwd@123.45.67.009:2711,:sentinelpwd@other-sentinel:2722

    • SENTINEL_ROLE 字段为 masterslave 字段。
  2. 使用最新版本模板,部署 3scale,如 OpenShift 在 OpenShift 上部署 3scale 所示。

    1. 忽略因为 backend-redis system-redis 已存在的错误。

9.2.3. 将 3scale 的非 HA 部署迁移到 HA

  1. 使用所有字段编辑 backend-redissystem-redis secret,如 部署 3scale 为 HA 所示。
  2. 确保为后端容器集定义了以下 backend-redis 环境变量。

    name: BACKEND_REDIS_SENTINEL_HOSTS
      valueFrom:
        secretKeyRef:
          key: REDIS_STORAGE_SENTINEL_HOSTS
          name: backend-redis
    name: BACKEND_REDIS_SENTINEL_ROLE
      valueFrom:
        secretKeyRef:
          key: REDIS_STORAGE_SENTINEL_ROLE
          name: backend-redis
  3. 确保为 system-(app|sidekiq|sphinx) pod 定义了以下 system-redis 环境变量。

    name: REDIS_SENTINEL_HOSTS
      valueFrom:
        secretKeyRef:
          key: SENTINEL_HOSTS
          name: system-redis
    name: REDIS_SENTINEL_ROLE
      valueFrom:
        secretKeyRef:
          key: SENTINEL_ROLE
          name: system-redis
    name: MESSAGE_BUS_REDIS_SENTINEL_HOSTS
      valueFrom:
        secretKeyRef:
          key: MESSAGE_BUS_SENTINEL_HOSTS
          name: system-redis
    name: MESSAGE_BUS_REDIS_SENTINEL_ROLE
      valueFrom:
        secretKeyRef:
          key: MESSAGE_BUS_SENTINEL_ROLE
          name: system-redis
  4. 继续执行说明以使用模板升级 3scale

9.2.3.1. 使用 Redis Enterprise

  1. 在 OpenShift 中使用 Redis Enterprise,具有三个不同的 redis-enterprise 实例:

    1. 编辑 system-redis secret:

      1. 将不同的值设置为 MESSAGE_BUS_NAMESPACENAMESPACE
      2. URLMESSAGE_BUS_URL 设置为同一数据库。
    2. backend-redis 中的后端数据库设置为 REDIS_QUEUES_URL
    3. 将第三个数据库设置为 backend-redisREDIS_STORAGE_URL

9.2.3.2. 使用 Redis Sentinel

  1. 使用 Redis Sentinel,具有三个或四个不同的 Redis 数据库:

    1. 编辑 system-redis secret:

      1. 将不同的值设置为 MESSAGE_BUS_NAMESPACENAMESPACE
      2. URLMESSAGE_BUS_URL 设置为正确的 Redis 组,例如: redis://:redispwd@mymaster/5
      3. SENTINEL_HOSTSMESSAGE_BUS_SENTINEL_HOSTS 设置为以逗号分隔的主机和端口列表,例如: :sentinelpwd@123.45.67.009:2711,:sentinelpwd@other-sentinel:2722
      4. SENTINEL_ROLEMESSAGE_BUS_SENTINEL_ROLE 设置为 master
  2. 使用以下值为后端设置 backend-redis secret:

    • REDIS_QUEUES_URL
    • REDIS_QUEUES_SENTINEL_ROLE
    • REDIS_QUEUES_SENTINEL_HOSTS
  3. 将第三个数据库中的变量设置为如下:

    • REDIS_STORAGE_URL
    • REDIS_STORAGE_SENTINEL_ROLE
    • REDIS_STORAGE_SENTINEL_HOSTS

备注

  • system-appsystem-sidekiq 组件直接连接到 后端 Redis 以检索统计信息。

    • 从 3scale 2.7 开始,使用发送时这些系统组件也可以连接到 后端 Redis(存储)。
  • system-appsystem-sidekiq 组件 仅使用 backend-redis 存储,而不使用 backend-redis 队列。

    • 对系统组件所做的更改支持带有 sendinels 的 backend-redis 存储。

9.3. 重新删除数据库分片和复制

分片有时称为分区,可将大型数据库隔离为称为分片的较小数据库。通过复制,您的数据库使用托管在独立计算机上的同一数据集的副本进行设置。

分片

分片有助于添加更多领导实例,当您有如此多的数据并不适用于单个数据库中,或者 CPU 负载接近 100% 时,这也会很有用。

使用 Red Hat is HA for 3scale 时,以下两个原因是分片非常重要的原因:

  • 拆分和扩展大量数据,并调整特定索引的分片数量,以帮助避免瓶颈。
  • 跨不同节点分布操作,因此可以提高性能,例如当多台机器处理同一个查询时。

禁用集群模式的 Redis 数据库分片的三个主要解决方案是:

  • Amazon ElastiCache
  • 通过 Redis 发送的标准 Redis
  • redis Enterprise

复制

redis 数据库复制通过在不同机器之间复制您的数据集来确保冗余性。通过利用复制功能,您可以在领导机停机时让 Redis 保持工作。然后,从单个实例(领导)中拉取数据,以确保高可用性。

通过适用于 3scale 的 HA,数据库复制可确保主分片的高可用性副本。操作原则包括:

  • 当主分片失败时,副本分片将自动提升到新的主分片。
  • 恢复原始主分片后,它会自动成为新主分片的副本分片。

Redis 数据库复制的三个主要解决方案是:

  • redis Enterprise
  • Amazon ElastiCache
  • 通过 Redis 发送的标准 Redis

使用 twemproxy 进行分片

对于 Amazon ElastiCache 和 Standard Redis,分片涉及基于密钥分割数据。您需要给定特定密钥的代理组件知道要查找的分片,如 twemproxytwemproxy 也称为 nutcracker,它是一个适用于 Redis 协议的轻量级代理解决方案,它根据特定的密钥或服务器映射找到分配给它们的分片。使用 twemproxy 在 Amazon ElastiCache 或 Standard Redis 实例中添加分片功能具有以下优点:

  • 在多个服务器间自动分片数据的功能。
  • 支持多种哈希模式,支持一致的散列和发行版。
  • 在多个实例中运行的能力,允许客户端连接到第一个可用的代理服务器。
  • 减少与后端上缓存名称服务器的连接数量。
注意

redis Enterprise 使用自己的代理,因此不需要 twemproxy

其他资源

9.4. 附加信息

第 10 章 配置外部 MySQL 数据库

本指南提供有关将 MySQL 数据库外部化 第 8 章 3scale 高可用性和评估模板 的信息。这可以通过使用默认 amp.yml 文件来完成。当使用默认的 system-mysql 容器集存在多个基础架构问题(如网络或文件系统)时,这非常有用。

这种方法和 第 8 章 3scale 高可用性和评估模板 中的区别在于,如果 Red Hat 3scale API 管理最初使用默认 amp.yml 模板,这为外部化 MySQL 数据库提供了一种方法。

注意

红帽支持使用外部 MySQL 数据库的 3scale 配置。但是,数据库本身不在支持范围之内。

先决条件

要为高可用性(HA)配置外部 MySQL 数据库,请执行以下部分中所述的步骤:

10.1. 外部 MySQL 数据库限制

外部化 MySQL 数据库的过程存在一些限制:

3scale 内部内部版本

它仅在 3scale 的 2.5 个内部版本和 2.6 内部部署版本中进行测试并验证。

MySQL 数据库用户

URL 必须为以下格式:

<database_scheme>://<admin_user>:<admin_password>@<database_host>/<database_name>

<admin_user> 必须是外部数据库中的现有用户,具有 <database_name> 逻辑数据库的完整权限。<database_name> 必须是外部数据库中已存在的逻辑数据库。

MySQL 主机

使用来自外部 MySQL 数据库的 IP 地址,而不是 主机名,否则不会解析。例如,使用 1.1.1.1 而不是 mysql.mydomain.com

10.2. 外部化 MySQL 数据库

使用以下步骤,将 MySQL 数据库完全外部化。

警告

这将在进程持续期间导致环境中的停机。

流程

  1. 登录到托管 3scale On-premises 实例的 OpenShift 节点,并更改到其项目:

    oc login -u <user> <url>
    oc project <3scale-project>

    <user><url><3scale-project> 替换为您自己的凭证和项目名称。

  2. 按照下方的步骤,按照所示的顺序缩减所有 pod。这将避免丢失数据。

    停止 3scale 内部部署

    从 OpenShift Web 控制台或命令行界面(CLI),按以下顺序将所有部署配置缩减为零副本:

    • apicast-wildcard-routerzync 适用于 3scale 2.6 之前的版本,zync-quezync 适用于 3scale 2.6 和以上版本。
    • apicast-stagingapicast-production
    • system-sidekiqbackend-cronsystem-sphinx.

      • 3scale 2.3 包括 system-resque
    • system-app
    • backend-listenerbackend-worker
    • backend-redissystem-memcachesystem-mysqlsystem-rediszync-database.

      以下示例演示了如何在 CLI 中为 apicast-wildcard-routerzync 执行此操作 :

      oc scale dc/apicast-wildcard-router --replicas=0
      oc scale dc/zync --replicas=0
      注意

      可以同时缩减每个步骤的部署配置。例如,您可以将 apicast-wildcard-routerzync 一起缩减。但是,最好等待每个步骤中的 pod 终止,然后再缩减后续 pod。3scale 实例将完全无法访问,直到它被完全启动。

  3. 要确认 3scale 项目上没有运行任何 pod,请使用以下命令:

    oc get pod

    命令应返回 No resources found

  4. 使用以下命令再次扩展数据库级别的 pod:

    oc scale dc/{backend-redis,system-memcache,system-mysql,system-redis,zync-database} --replicas=1
  5. 确保您可以通过 system-mysql pod 登录外部 MySQL 数据库,然后继续后续步骤:

    oc rsh system-mysql-<system_mysql_pod_id>
    mysql -u root -p -h <host>
    • <system_mysql_pod_id>:system-mysql 容器集的标识符。
    • 用户应当始终为 root。如需更多信息,请参阅 外部 MySQL 数据库限制

      1. CLI 现在将显示 mysql>。键入 exit,然后按 返回。在下一提示中再次键入 exit 以 返回到 OpenShift 节点控制台。
  6. 使用以下命令执行完整的 MySQL 转储:

    oc rsh system-mysql-<system_mysql_pod_id> /bin/bash -c "mysqldump -u root --single-transaction --routines --triggers --all-databases" > system-mysql-dump.sql
    • <system_mysql_pod_id> 替换为您唯一的 system-mysql pod ID
    • 验证 system-mysql-dump.sql 是否包含有效的 MySQL 级别转储,如下例所示:

      $ head -n 10 system-mysql-dump.sql
      -- MySQL dump 10.13  Distrib 5.7.24, for Linux (x86_64)
      --
      -- Host: localhost    Database:
      -- ------------------------------------------------------
      -- Server version   5.7.24
      
      /*!40101 SET @OLD_CHARACTER_SET_CLIENT=@@CHARACTER_SET_CLIENT */;
      /*!40101 SET @OLD_CHARACTER_SET_RESULTS=@@CHARACTER_SET_RESULTS */;
      /*!40101 SET @OLD_COLLATION_CONNECTION=@@COLLATION_CONNECTION */;
      /*!40101 SET NAMES utf8 */;
  7. 缩减 system-mysql pod,并保留为 0(零)副本:

    oc scale dc/system-mysql --replicas=0
  8. 查找与 URL mysql2://root:<password>@<host>/system 等效的 base64,相应地替换 <password><host>

    echo "mysql2://root:<password>@<host>/system" | base64
  9. 在远程 MySQL 数据库上创建默认的 'user'@'%'。它只需要具有 SELECT 特权。找到它的 base64 对等信息:

    echo "user" | base64
    echo "<password>" | base64
    • 将 <password> 替换为 'user'@'%' 的密码。
  10. 执行备份并编辑 OpenShift secret system-database

    oc get secret system-database -o yaml > system-database-orig.bkp.yml
    oc edit secret system-database
    • URL :使用 [step-8] 中的值替换它。
    • DB_USERDB_PASSWORD :将上一步中的值用于这两者。
  11. system-mysql-dump.sql 发送到远程数据库服务器,并将转储导入到其中。使用命令导入它:
  12. 使用以下命令将 system-mysql-dump.sql 发送到远程数据库服务器,并将转储导入到服务器:

    mysql -u root -p < system-mysql-dump.sql
  13. 确保创建了名为 system 的新数据库:

    mysql -u root -p -se "SHOW DATABASES"
  14. 使用以下说明启动 3scale 内部部署,以正确顺序扩展所有 pod。

    启动 3scale 内部部署

    • backend-redissystem-memcachesystem-mysqlsystem-rediszync-database.
    • backend-listenerbackend-worker
    • system-app
    • system-sidekiqbackend-cronsystem-sphinx

      • 3scale 2.3 包括 system-resque
    • apicast-stagingapicast-production
    • apicast-wildcard-routerzync 适用于 3scale 2.6 之前的版本,zync-quezync 适用于 3scale 2.6 和以上版本。

      以下示例演示了如何在 CLI 中为 backend-redissystem-memcachesystem-mysqlsystem-rediszync-database 执行此操作 :

      oc scale dc/backend-redis --replicas=1
      oc scale dc/system-memcache --replicas=1
      oc scale dc/system-mysql --replicas=1
      oc scale dc/system-redis --replicas=1
      oc scale dc/zync-database --replicas=1

      system-app pod 现在应该已启动并运行,且没有任何问题。

  15. 验证后,按照所示的顺序扩展其他容器集。
  16. 备份 system-mysql DeploymentConfig 对象。您可以在几分钟后删除所有内容,确定一切运行正常。如果将来再次执行此步骤,删除 system-mysql DeploymentConfig 可避免以后出现混淆。

10.3. 回滚

如果 system-app pod 没有完全在线,并且其根本原因在第 14 步 后无法决定或解决,请执行回滚步骤。

  1. 使用来自 system-database-orig.bkp.yml 的原始值编辑 system-database。请参阅 [step-10]:

    oc edit secret system-database

    URLDB_USERDB_PASSWORD 替换为其原始值。

  2. 缩减所有容器集,然后再次向上扩展,包括 system-mysqlsystem-app pod 和在启动后启动的其他 pod 应启动并再次运行。运行以下命令确认所有 pod 都已备份并正在运行:

    oc get pods -n <3scale-project>

10.4. 附加信息

第 11 章 使用 Oracle 数据库设置 3scale 系统镜像

注意
  • 只有在您执行基于模板的 3scale 安装时,OpenShift Container Platform(OCP) 3.11 才支持 Oracle 数据库。
  • 当您执行只有 3scale 的 operator 安装时,OCP 版本 4.2 和 4.3 不支持 Oracle Database。
  • 有关支持配置的更多信息,请参阅 Red Hat 3scale API 管理支持的配置 页面。

本节介绍红帽 3scale API 管理管理员如何使用 Oracle 数据库设置 3scale 系统镜像。默认情况下,3scale 2.9 的组件称为系统,它将配置数据存储在 MySQL 数据库中。您可以覆盖默认数据库,并将信息存储在外部 Oracle 数据库中。按照本章中的步骤,使用您自己的 Oracle 数据库客户端二进制文件构建自定义系统容器镜像,并将 3scale 部署到 OpenShift。

先决条件

以下 Oracle 软件组建的一个支持的版本

  • Oracle Instant 客户端软件包:Basic 或 Basic Light
  • Oracle Instant 客户端软件包:SDK
  • Oracle Instant 客户端软件包:ODBC

3scale 2.9 和 2.9.1 的 Oracle 12c 示例软件包

  • Oracle Instant Client Package - Basic: instantclient-basic-linux.x64-12.2.0.1.0.zip 或 instantclient-basiclite-linux.x64-12.2.0.1.0.zip
  • Oracle Instant Client Package - SDK: instantclient-sdk-linux.x64-12.2.0.1.0.zip
  • Oracle Instant Client Package - ODBC: instantclient-odbc-linux.x64-12.2.0.1.0-2.zip

3scale 2.9.1 的 Oracle 19c 示例软件包

  • Oracle Instant Client Package - Basic 或 Basic Light: instantclient-basic-linux.x64-19.8.0.0.0dbru.zip or instantclient-basiclite-linux.x64-19.8.0.0.0dbru.zip
  • Oracle Instant Client Package - SDK: instantclient-sdk-linux.x64-19.8.0.0.0dbru.zip
  • Oracle Instant Client Package - ODBC: instantclient-odbc-linux.x64-19.8.0.0.0dbru.zip

要使用 和 Oracle Database 设置 3scale 系统镜像,请执行以下部分中所述的步骤:

11.1. 准备 Oracle 数据库

本节介绍准备 Oracle 数据库的步骤。

先决条件

  • 可以从 OpenShift cluster 访问的一个 Oracle Database 的支持版本
  • 访问 Oracle Database system 用户以获取安装过程。

流程

  1. 创建新数据库。

    要使用 Oracle 数据库配置 3scale,请使用以下设置:

    ALTER SYSTEM SET max_string_size=extended SCOPE=SPFILE;
  2. 收集数据库详细信息。

    3scale 配置需要以下信息:

    • Oracle 数据库 URL 地址。
    • Oracle 数据库。服务名称
    • Oracle Database system 密码。

      DATABASE_URL 参数必须遵循以下格式: oracle-enhanced://${user}:${password}@${host}:${port}/${database}

示例

DATABASE_URL="oracle-enhanced://user:password@my-oracle-database.com:1521/threescalepdb"

其他资源

  • 有关在 Oracle 数据库中创建新数据库的详情,请查看 Oracle 文档

11.2. 构建系统镜像

本节提供构建系统镜像的步骤。

先决条件

流程

  1. 从 GitHub 存储库克隆 3scale 的 OpenShift 模板。使用以下命令:

    $ git clone --branch 2.9.1.GA https://github.com/3scale/3scale-amp-openshift-templates.git
  2. 将您的 Oracle Database Instant 客户端软件包文件放在 3scale-amp-openshift-templates/amp/system-oracle/oracle-client-files 目录中。
  3. 下载 3scale 2.9 amp.yml 模板。
  4. 使用 -f 选项运行 oc new-app 命令并指定 build.yml OpenShift 模板:

    $ oc new-app -f build.yml
  5. 使用 -f 选项运行 oc new-app 命令以指示 amp.yml OpenShift 模板,并使用 -p 选项指定带有 OpenShift 集群域的 WILDCARD_DOMAIN 参数:

    $ oc new-app -f amp.yml -p WILDCARD_DOMAIN=mydomain.com
  6. 输入以下 oc patch 命令,将 SYSTEM_PASSWORD 替换为您在准备 Oracle 数据库中设置的 Oracle Database system 密码:

    $ oc patch dc/system-app -p '[{"op": "add", "path": "/spec/strategy/rollingParams/pre/execNewPod/env/-", "value": {"name": "ORACLE_SYSTEM_PASSWORD", "value": "SYSTEM_PASSWORD"}}]' --type=json
    
    $ oc patch dc/system-app -p '{"spec": {"strategy": {"rollingParams": {"post":{"execNewPod": {"env": [{"name": "ORACLE_SYSTEM_PASSWORD", "value": "SYSTEM_PASSWORD"}]}}}}}}'
  7. 输入以下命令,替换 DATABASE_URL 以指向在准备 Oracle 数据库中指定的 Oracle 数据库

    $ oc patch secret/system-database -p '{"stringData": {"URL": "DATABASE_URL"}}'
  8. 输入 oc start-build 命令以构建新系统镜像:

    $ oc start-build 3scale-amp-system-oracle --from-dir=.
  9. 等待构建完成。要查看构建的状态,请运行以下命令:

    $ oc get build <build-name> -o jsonpath="{.status.phase}"
    1. 等待构建处于 Complete 状态。

11.2.1. 更新 ImageChange 触发器

更新使用系统镜像的 DeploymentConfig 的 ImageChange 触发器,以便它们使用基于 Oracle 的新系统镜像。

先决条件

流程

  1. 将当前的 3scale 发行版本保存到环境变量中:

    $ export THREESCALE_RELEASE=2.9
  2. 更新 system-app ImageChange 触发器:

    $ oc set triggers dc/system-app --from-image=amp-system:${THREESCALE_RELEASE} --containers=system-master,system-developer,system-provider --remove
    
    $ oc set triggers dc/system-app --from-image=amp-system:${THREESCALE_RELEASE}-oracle --containers=system-master,system-developer,system-provider

    这会触发 system-app DeploymentConfig 的重新部署。等待它重新部署,其对应的新容器集就绪,并且旧的容器集已停止。

  3. 更新 system-sidekiq ImageChange 触发器:

    $ oc set triggers dc/system-sidekiq --from-image=amp-system:${THREESCALE_RELEASE} --containers=system-sidekiq,check-svc --remove
    
    $ oc set triggers dc/system-sidekiq --from-image=amp-system:${THREESCALE_RELEASE}-oracle --containers=system-sidekiq,check-svc

    这会触发 system-sidekiq DeploymentConfig 的重新部署。等待它重新部署,其对应的新容器集就绪,并且旧的容器集已停止。

  4. 更新 system-sphinx ImageChange 触发器:

    $ oc set triggers dc/system-sphinx --from-image=amp-system:${THREESCALE_RELEASE} --containers=system-sphinx,system-master-svc --remove
    
    $ oc set triggers dc/system-sphinx --from-image=amp-system:${THREESCALE_RELEASE}-oracle --containers=system-sphinx,system-master-svc

    这会触发 system-sphinx DeploymentConfig 的重新部署。等待它重新部署,其对应的新容器集就绪,并且旧的容器集已停止。

其他资源

有关 3scale 和 Oracle 数据库支持的更多信息,请参阅 Red Hat 3scale API 管理支持的配置