操作 3scale
如何自动部署、扩展您的环境并对问题进行故障排除
摘要
让开源更具包容性
红帽致力于替换我们的代码、文档和 Web 属性中存在问题的语言。我们从这四个术语开始：master、slave、黑名单和白名单。由于此项工作十分艰巨，这些更改将在即将推出的几个发行版本中逐步实施。详情请查看我们的 CTO Chris Wright 信息。
第 1 章 3scale 操作和扩展
本文档不适用于笔记本电脑或类似最终用户设备的本地安装。
本节论述了红帽 3scale API 管理 2.10 安装的操作和扩展任务。
先决条件
- 在 受支持的 OpenShift 版本 上安装并最初配置 3scale On-Premises 实例。
要执行 3scale 操作和扩展任务，请执行以下小节中所述的步骤：
1.1. 重新部署 APIcast
您可以通过 3scale 管理门户测试和提升系统更改。
先决条件
- 3scale 内部部署的实例。
- 您已选择了 APIcast 部署方法。
默认情况下，OpenShift 上的 APIcast 部署（嵌入式部署和其他 OpenShift 集群中）已配置为允许您通过 3scale 管理门户发布对您的暂存和生产网关的更改。
在 OpenShift 中重新部署 APIcast：
步骤
- 进行系统更改.
- 在管理门户中，部署 暂存和测试。
- 在管理门户中，将 提升到生产。
默认情况下，APIcast 每 5 分钟检索并发布升级的更新一次。
如果您在 Docker 容器化环境或原生安装中使用 APIcast，请配置暂存和生产网关，并指示网关检索已发布更改的频率。在配置了 APIcast 网关后，您可以通过 3scale 管理门户重新部署 APIcast。
要在 Docker 容器化环境或原生安装上重新部署 APIcast：
步骤
- 配置 APIcast 网关并将其连接到 3scale 内部。
- 进行系统更改.
- 在管理门户中，部署 暂存和测试。
- 在管理门户中，将 提升到生产。
APIcast 以配置的频率检索并发布升级的更新。
1.2. 扩展内部 3scale
随着 APIcast 部署的增长，您可能需要增加可用的存储量。如何扩展存储取决于您用于持久性存储的文件系统类型。
如果使用网络文件系统(NFS)，使用以下命令扩展持久性卷(PV)：
oc edit pv <pv_name>
如果使用任何其他存储方法，则必须使用以下部分中列出的方法之一手动扩展持久性卷。
1.2.1. 方法 1：备份和交换持久性卷
步骤
- 备份现有持久性卷中的数据。
- 创建并附加一个目标持久性卷，按照您的新大小要求扩展。
-
创建预绑定持久性卷声明，指定：使用
volumeName字段的新 PVC(PersistentVolumeClaim)和持久性卷名称的大小。 - 将备份中的数据恢复到新创建的 PV。
使用新 PV 的名称修改部署配置：
oc edit dc/system-app
- 验证您的新 PV 已配置且正常工作。
- 删除您之前的 PVC 以释放其声明的资源。
1.2.2. 方法 2：备份和重新部署 3scale
步骤
- 备份现有持久性卷中的数据。
- 关闭 3scale pod。
- 创建并附加一个目标持久性卷，按照您的新大小要求扩展。
- 将备份中的数据恢复到新创建的 PV。
创建预绑定持久性卷声明。指定：
- 新 PVC 的大小
-
使用
volumeName字段的持久性卷名称。
- 部署您的 amp.yml。
- 验证您的新 PV 已配置且正常工作。
- 删除您之前的 PVC 以释放其声明的资源。
1.2.3. 扩展性能
扩展性能是通过 pod 总数实现的。硬件资源越多，部署的 pod 越多。
使用以下命令，通过 pod 数量扩展性能：
oc scale dc dc-name --replicas=X
1.2.4. 配置 3scale 内部部署
为 3scale 扩展的关键部署配置有：
- APIcast 生产
- 后端监听程序
- 后端 worker
1.2.4.1. 通过 OCP 命令行界面扩展
通过 OpenShift Container Platform(OCP)命令行界面(CLI)，您可以扩展或缩减部署配置。
要扩展特定的部署配置，请使用：
使用以下命令扩展 APIcast 产品部署配置：
oc scale dc apicast-production --replicas=X
使用以下命令扩展后端监听程序部署配置：
oc scale dc backend-listener --replicas=Y
使用以下命令扩展后端 worker 部署配置：
oc scale dc backend-worker --replicas=Z
1.2.4.2. 垂直和横向硬件扩展
您可以通过添加资源来提高 OpenShift 上 3scale 部署的性能。您可以将更多计算节点作为 pod 添加到 OpenShift 集群，作为横向扩展，或者以垂直扩展形式将更多资源分配给现有计算节点。
横向扩展
您可以将更多计算节点作为容器集添加到 OpenShift 中。如果额外的计算节点与集群中的现有节点匹配，则不必重新配置任何环境变量。
垂直扩展
您可以为现有计算节点分配更多资源。如果分配更多资源，您必须在 pod 中添加额外的进程来提高性能。
在 3scale 部署中避免使用具有不同规格和配置的计算节点。
1.2.4.3. 扩展路由器
随着流量的增加，确保您的红帽 OCP 路由器可以正确处理请求。如果您的路由器正在限制请求的吞吐量，您必须扩展路由器节点。
1.3. 操作故障排除
本节介绍如何配置 3scale 审计日志记录以在 OpenShift 上显示，以及如何访问 OpenShift 上的 3scale 日志和作业队列。
1.3.1. 在 OpenShift 上配置 3scale 审计日志记录
这可让所有日志位于一个位置，供 Elasticsearch、Fluentd 和 Kibana(EFK)日志工具查询。这些工具提高了对 3scale 配置所做的更改的可见性，以及进行了这些更改的时间。例如，这包括对计费、应用程序计划、API 配置等的更改。
先决条件
- 3scale 2.10 部署.
步骤
配置审计日志记录到 stdout，以将所有应用日志转发到标准 OpenShift 容器集日志。
些注意事项：
-
默认情况下，当 3scale 内部部署 3scale 时，审计日志记录
被禁用，您需要配置此功能才能完全正常工作。 -
3scale 托管不提供审计日志记录到
stdout。
1.3.2. 启用审计日志记录
3scale 使用 features.yml 配置文件来启用一些全局功能。要将审计日志记录启用到 stdout，您必须从 ConfigMap 挂载此文件，以替换默认的 文件。依赖于 features.yml 的 OpenShift pod 是 system-app 和 system-sidekiq。
先决条件
- 您必须在 OpenShift 上具有集群管理员访问权限。
步骤
输入以下命令将审计日志记录启用到
stdout：oc patch configmap system -p '{"data": {"features.yml": "features: &default\n logging:\n audits_to_stdout: true\n\nproduction:\n <<: *default\n"}}'导出以下环境变量：
export PATCH_SYSTEM_VOLUMES='{"spec":{"template":{"spec":{"volumes":[{"emptyDir":{"medium":"Memory"},"name":"system-tmp"},{"configMap":{"items":[{"key":"zync.yml","path":"zync.yml"},{"key":"rolling_updates.yml","path":"rolling_updates.yml"},{"key":"service_discovery.yml","path":"service_discovery.yml"},{"key":"features.yml","path":"features.yml"}],"name":"system"},"name":"system-config"}]}}}}'输入以下命令将更新的部署配置应用到相关的 OpenShift pod:
oc patch dc system-app -p $PATCH_SYSTEM_VOLUMES oc patch dc system-sidekiq -p $PATCH_SYSTEM_VOLUMES
1.3.3. 配置 EFK 日志
当您启用了审计日志记录到 stdout 将 3scale 应用日志转发到 OpenShift 后，您可以使用 EFK 日志工具来监控 3scale 应用。
有关如何在 OpenShift 中配置 EFK 日志的详情，请参考以下内容：
1.3.4. 访问日志
每个组件的部署配置都包含用于访问和异常的日志。如果您在部署时遇到问题，请检查这些日志以了解详细信息。
按照以下步骤访问 3scale 中的日志：
步骤
查找您要日志的 pod 的 ID：
oc get pods
输入
oc logs和所选 pod 的 ID：oc logs <pod>
系统 pod 有两个容器，各自具有单独的日志。要访问容器的日志，请使用 system-
provider和system-developerpod 指定--container参数：oc logs <pod> --container=system-provider oc logs <pod> --container=system-developer
1.3.5. 检查作业队列
作业队列包含从 系统侧kiq pod 发送的信息日志。使用这些日志来检查集群是否正在处理数据。您可以使用 OpenShift CLI 查询日志：
oc get jobs
oc logs <job>
1.3.6. 防止单调增长
为防止单例增长，3scale 默认调度 3scale 调度，自动清除以下表：
- user_sessions - 清理每周触发一次，可删除超过两周的记录。
- 审计 - 每天触发一次清理，删除超过 3 个月的记录。
- log_entries - 每天清理一次，删除超过 6 个月的记录。
- event_store_events - 清理每周触发一次，删除超过一周的记录。
除以上列出的表外，下表需要数据库管理员手动清除：
- alerts
表 1.1. SQL 清除命令
| 数据库类型 | SQL 命令 |
|---|---|
| MySQL |
DELETE FROM alerts WHERE timestamp < NOW() - INTERVAL 14 DAY; |
| PostgreSQL |
DELETE FROM alerts WHERE timestamp < NOW() - INTERVAL '14 day'; |
| Oracle |
DELETE FROM alerts WHERE timestamp <= TRUNC(SYSDATE) - 14; |
对于本节中未指定的其他表，数据库管理员必须手动清理系统不会自动清除的表。
第 2 章 监控 3scale
Prometheus 是专为存储历史数据和监控大型可扩展系统而构建的容器原生软件。它在延长时间内收集数据，而不仅仅是针对当前运行的会话。Prometheus 中的警报规则由 Alertmanager 管理。
您可以使用 Prometheus 和 Alertmanager 监控并存储 3scale 数据，以便您可以使用图形工具（如 Grafana ）来视觉化和运行数据查询。
Prometheus 是一个开源系统监控工具包，Grafana 是一个开源仪表板工具包。红帽对 Prometheus 和 Grafana 的支持仅限于红帽产品文档中提供的配置建议。
3scale 操作器允许您使用现有的 Prometheus 和 Grafana 操作器安装来监控 3scale 使用情况和资源。
3scale 操作器创建监控资源，但不会阻止修改这些资源。
先决条件
- 已安装 3scale 操作器。
Prometheus Operator 已安装在集群中。Prometheus operator 是一个用于创建和管理 Prometheus 实例的操作器。它提供了 3scale 监控所需的
Prometheus自定义资源定义。以下 Prometheus operator 和镜像版本使用 3scale 测试：
-
Prometheus operator
v0.37.0 -
Prometheus image:
quay.io/prometheus/prometheus:v2.16.0
-
Prometheus operator
Grafana Operator 在集群中安装。Grafana Operator 是一个用于创建和管理 Grafana 实例的操作器。它提供了 3scale 监控所需的
GrafanaDashboard自定义资源定义。以下 Grafana operator 和镜像版本使用 3scale 测试：
-
Grafana operator
v3.6.0 -
Grafana 镜像：
registry.hub.docker.com/grafana/grafana:7.1.1
-
Grafana operator
如果您的集群在互联网上公开，请确保保护 Prometheus 和 Grafana 服务。
本节论述了如何启用对 3scale 实例的监控，以便您可以查看 Grafana 仪表板。
2.1. 为 3scale 启用监控
要监控 3scale，您必须通过设置 APIManager 自定义资源来启用监控。
步骤
通过将 3scale 部署 YAML 的
spec.monitoring.enabled参数设置为true，将 3scale 配置为启用监控。例如：.创建名为
3scale-monitoring.yml的 APIManager 自定义资源来启用监控：apiVersion: apps.3scale.net/v1alpha1 kind: APIManager metadata: name: apimanager1 spec: wildcardDomain: example.com monitoring: enabled: true登录您的 OpenShift 集群。您必须以具有 edit 集群角色的用户身份在 3scale 的 OpenShift 项目中（如
cluster-admin）登录。oc login
切换到 3scale 项目。
oc project <project_name>
部署自定义资源：
$ oc apply -f 3scale-monitoring.yml
其他资源
- 有关使用操作器配置 3scale 的更多信息，请参阅使用操作器在 OpenShift 上 3scale 的部署配置选项指南。
2.2. 配置 Prometheus 以监控 3scale
您必须使用 Prometheus 自定义资源部署和配置 Prometheus，以启用 3scale 的监控。
确保正确设置了权限，如 Prometheus 文档 所述。
步骤
根据您要监控集群中的所有资源还是仅 3scale 资源，按如下所示部署 Prometheus 自定义资源：
要监控集群中的所有资源，请将
spec.podMonitorSelector属性设置为{}，并将spec.ruleSelector属性设置为{}。例如，应用以下自定义资源：apiVersion: monitoring.coreos.com/v1 kind: Prometheus metadata: name: example spec: podMonitorSelector: {} ruleSelector: {}如果您在同一 OpenShift 项目中部署了 3scale 和 Prometheus operator，并假设
APP_LABEL的值被设置为默认的3scale-api-management，请按照以下步骤监控 3scale 资源：将
spec.podMonitorSelector属性设置为：podMonitorSelector: matchExpressions: - key: app operator: In values: - 3scale-api-management将
spec.ruleSelector属性设置为：matchExpressions: - key: app operator: In values: - 3scale-api-management例如，应用以下自定义资源：
apiVersion: monitoring.coreos.com/v1 kind: Prometheus metadata: name: example spec: podMonitorSelector: matchExpressions: - key: app operator: In values: - 3scale-api-management ruleSelector: matchExpressions: - key: app operator: In values: - 3scale-api-management
如果您在不同的 OpenShift 项目中部署了 3scale 和 Prometheus operator，请按照以下步骤监控 3scale 资源：
-
为 OpenShift 项目添加标签，其中 3scale 使用
MYLABELKEY=MYLABELVALUE部署 使用
podMonitorNamespaceSelector过滤器选择 3scale pod。例如，应用以下自定义资源：apiVersion: monitoring.coreos.com/v1 kind: Prometheus metadata: name: example spec: podMonitorSelector: {} ruleSelector: {} podMonitorNamespaceSelector: matchExpressions: - key: MYLABELKEY operator: In values: - MYLABELVALUE
-
为 OpenShift 项目添加标签，其中 3scale 使用
为确保仪表板和警报按预期工作，您必须执行以下操作之一来包含 Kubernetes 指标 （即 kube-state-metrics ）：
- 将 Prometheus 实例与集群默认 Prometheus 实例相结合。
- 配置您自己的提取任务，以从 kubelet、etcd 和其它数据获取指标。
其他资源
- 有关 Prometheus 的更多信息，请参阅 Prometheus 文档。
2.3. 配置 Grafana 来监控 3scale
您必须配置 Grafana 来启用 3scale 的监控。
步骤
通过覆盖
app=3scale-api-management标签，确保将Grafana 服务配置为监控 GrafanaDashboards资源。例如，应用以下自定义资源：apiVersion: integreatly.org/v1alpha1 kind: Grafana metadata: name: grafana spec: dashboardLabelSelector: - matchExpressions: - key: app operator: In values: - 3scale-api-management由 3scale Operator 创建的 Grafana 仪表板被标记为如下：
app: 3scale-api-management monitoring-key: middleware
-
如果 Grafana Operator 安装在 3scale 以外的命名空间中，请将其配置为使用
--namespaces 或 --scan-alloperator 标记来监控命名空间外的资源。如需有关 operator 标记的更多信息，请参阅 Grafana 文档。 创建类型为
prometheus的GrafanaDataSource自定义资源，以便在 Grafana 中提供 Prometheus 数据。例如：apiVersion: integreatly.org/v1alpha1 kind: GrafanaDataSource metadata: name: prometheus spec: name: middleware datasources: - name: Prometheus type: prometheus access: proxy url: http://prometheus-operated:9090 isDefault: true version: 1 editable: true jsonData: timeInterval: "5s"其中
http://prometheus-operated:9090是 Prometheus 路由。- 确保正确设置了权限，如 Grafana 文档中的 所述。
其他资源
- 如需有关 Grafana 的更多信息，请参阅 Grafana 文档。
2.4. 查看 3scale 的指标
配置 3scale、Prometheus 和 Grafana 后，您可以查看本节中描述的指标。
步骤
- 登录到 Grafana 控制台。
检查您可以查看以下指标：
- 安装 3scale 的 pod 和命名空间级别的 Kubernetes 资源
- APIcast 暂存
- APIcast Production
- 后端 worker
- 后端监听程序
- System
- Zync
2.5. 3scale 公开给 Prometheus 的系统指标
您可以将以下端口配置为将 3scale 系统 Pod 与 Prometheus 端点搭配使用，以公开指标。
表 2.1. 3scale 系统端口
| system-app | 端口 |
|---|---|
|
| 9394 |
|
| 9395 |
|
| 9396 |
| system-sidekiq | 端口 |
|---|---|
|
| 9394 |
端点只能由内部访问：
http://${service}:${port}/metrics例如：
http://system-developer:9394/metrics
其他资源
- 有关监控 APIcast 的详情，请参考 向 Prometheus 公开 3scale APIcast Metrics。
- 有关保护 Prometheus 安全性的详情，请查看 Prometheus 安全 文档。
- 有关保护 Grafana 的详情，请查看 权限 和安全 Grafana 文档。
第 3 章 使用 Webhook 进行 3scale 自动化
Webhook 是一种有助于自动化的功能，也可用于根据 3scale 中发生的事件集成其他系统。当 3scale 系统中发生指定事件时，应用程序会收到 Webhook 信息。例如，通过配置 webhook，您可以使用新帐户注册的数据来填充开发人员门户。
3.1. Webhook 概述
Webhook 是一个自定义 HTTP 回调，它被从 Webhook 配置窗口中的可用事件选择来触发。发生这些事件时，3scale 系统会为 webhook 部分指定的 URL 地址生成 HTTP 或 HTTPS 请求。使用 Webhook，您可以将监听器配置为调用一些所需的行为，如事件跟踪。
Webhook 的格式始终相同。它使用以下结构的 XML 文档在端点中记录：
<?xml version="1.0" encoding="UTF-8"?>
<event>
<type>application</type>
<action>updated</action>
<object>
THE APPLICATION OBJECT AS WOULD BE RETURNED BY A GET ON THE ACCOUNT MANAGEMENT
API
</object>
</event>每个元素提供信息：
-
<type>:为您提供事件的主题，如应用、帐户 等等。 -
<action>:使用 更新、创建、删除 等值指定已完成的操作。 -
<object>:构成 XML 对象本身，其格式与帐户管理 API 返回的格式相同。要进行检查，您可以使用我们的互动 ActiveDocs。
如果您需要保证 3scale 发布 Webhook，请公开 HTTPS webhook URL，并在 3scale 中的 webhook 声明中添加自定义参数。例如： https://your-webhook-endpoint?someSecretParameterName=someSecretParameterValue。决定参数名称和值。然后，在 Webhook 端点中检查是否存在此参数值。
3.2. 配置 webhook
步骤
- 进入 Account Settings > integratione > Webhooks。帐户 设置是窗口右上角的齿轮图标。
指明 Webhook 的行为。有两个选项：
- Webhook 已启用 ：选中此复选框启用或禁用 Webhook。
管理门户中的操作也会触发 Webhook ：选择此复选框在事件发生时触发 Webhook。请考虑以下几点：
- 在调用配置了触发事件的内部 3scale API 时，请使用访问令牌，而不是供应商密钥。
- 如果您保留这个复选框，则只有 Developer Portal 触发器 Webhook 中的操作。
- 指定在所选事件触发时通知的 URL 地址。
- 选择将触发回调的事件到指定的 URL 地址。
配置完设置后，点 Update webhook 设置 保存您的更改。
3.3. Webhook 故障排除
如果您遇到侦听端点中断，您可以恢复失败的交付。如果您的端点使用 200 代码响应，则 3scale 将考虑发送 Webhook。否则，它将重试 5 次，间隔为 60 秒。在处于中断状态或定期恢复后，您应运行检查，以及是否有适用的清理队列。您可以在 ActiveDocs 中找到有关以下方法的更多信息：
- Webhook 列表失败
- Webhook 删除失败
第 4 章 3scale toolbox
3scale toolbox 是一个 Ruby 客户端，可让您从命令行管理 3scale 产品。
3scale 文档中有有关安装 3scale toolbox、支持的 toolbox 命令、服务、计划、SSL 和 TLS 故障排除问题的信息。如需了解更多详细信息，请参阅以下部分之一：
- 第 4.1 节 “安装 toolbox”
- 第 4.2 节 “支持的 toolbox 命令”
- 第 4.3 节 “导入服务”
- 第 4.4 节 “复制服务”
- 第 4.5 节 “仅复制服务设置”
- 第 4.6 节 “导入 OpenAPI 定义”
- 第 4.7 节 “管理远程访问凭证”
- 第 4.8 节 “创建应用程序计划”
- 第 4.9 节 “创建指标”
- 第 4.10 节 “创建方法”
- 第 4.11 节 “创建服务”
- 第 4.12 节 “创建 ActiveDocs”
- 第 4.13 节 “列出代理配置”
- 第 4.14 节 “复制策略 registry”
- 第 4.15 节 “列出应用”
- 第 4.16 节 “复制 API 后端”
- 第 4.17 节 “SSL 和 TLS 故障排除”
4.1. 安装 toolbox
官方支持的安装 3scale toolbox 的方法是使用 3scale toolbox 容器镜像。
4.1.1. 安装 toolbox 容器镜像
本节介绍如何安装 toolbox 容器镜像。
先决条件
- 请参阅 Red Hat Ecosystem Catalog 中的 3scale toolbox 镜像。
- 您必须有一个红帽 registry 服务帐户。
- 本主题中的示例假定您已安装了 Podman。
步骤
登录到红帽生态系统目录：
$ podman login registry.redhat.io Username: ${REGISTRY-SERVICE-ACCOUNT-USERNAME} Password: ${REGISTRY-SERVICE-ACCOUNT-PASSWORD} Login Succeeded!拉取 toolbox 容器镜像：
$ podman pull registry.redhat.io/3scale-amp2/toolbox-rhel7:3scale2.10
验证安装：
$ podman run registry.redhat.io/3scale-amp2/toolbox-rhel7:3scale2.10 3scale help
4.1.2. 安装不支持的 toolbox 版本
步骤
-
您可以通过 从 GitHub 下载并安装 latest.
rpm、.deb、.msi或.pkg文件，在 Fedora Linux、Ubuntu Linux、 Windows 或 macOS 上安装不支持的 toolbox 版本。
其他资源
- 有关使用 OpenShift、Podman 或 Docker 安装 toolbox 镜像的详情，请查看在 Red Hat Ecosystem Catalog 中获取镜像的说明。
-
另请参阅在 Kubernetes 上安装 3scale toolbox 的说明。您必须使用正确的镜像名称和
oc命令，而不是 OpenShift 上的kubectl。
4.2. 支持的 toolbox 命令
使用 3scale toolbox 使用命令行工具(CLI)管理您的 API。
update 命令已弃用，并由 copy 命令替代。不支持使用已弃用的命令。
支持以下命令：
COMMANDS
account account super command
activedocs activedocs super command
application application super command
application-plan application-plan super command
backend backend super command
copy copy super command
help print help
import import super command
method method super command
metric metric super command
policy-registry policy-registry super command
product product super command
proxy-config proxy-config super command
remote remotes super command
service services super command
update [DEPRECATED] update super command
OPTIONS
-c --config-file=<value> 3scale toolbox configuration file
(default: $HOME/.3scalerc.yaml)
-h --help show help for this command
-k --insecure Proceed and operate even for server
connections otherwise considered insecure
-v --version Prints the version of this command
--verbose Verbose mode4.3. 导入服务
通过按照以下指定顺序指定以下字段，从 CSV 文件中导入服务。在 CSV 文件中包含这些标头：
service_name,endpoint_name,endpoint_http_method,endpoint_path,auth_mode,endpoint_system_name,type
您需要以下信息：
-
3scale admin 帐户：
{3SCALE_ADMIN} 运行 3scale 实例的域：
{DOMAIN_NAME}- 如果您使用的是托管 APICast，这是 3scale.net
-
您的帐户的访问密钥：{
ACCESS_KEY} -
服务的 CSV 文件，例如：example
/import_example.csv
运行以下命令导入服务：
示例
$ podman run -v $PWD/examples/import_example.csv:/tmp/import_example.csv registry.redhat.io/3scale-amp2/toolbox-rhel7:3scale2.10 3scale import csv --destination=https://{ACCESS_KEY}@{3SCALE_ADMIN}-admin.{DOMAIN_NAME} --file=/tmp/import_example.csv
本例使用 Podman 卷在容器中挂载资源文件。它假定该文件位于当前的 $PWD 文件夹中。
4.4. 复制服务
基于同一帐户或其他帐户中的现有服务创建新服务。复制服务时，也会复制相关的 ActiveDocs。
您需要以下信息：
-
要复制的服务 id：
{SERVICE_ID} -
3scale admin 帐户：
{3SCALE_ADMIN} 运行 3scale 实例的域：
{DOMAIN_NAME}- 如果您使用的是托管 APICast，这是 3scale.net
-
您的帐户的访问密钥：{
ACCESS_KEY} -
如果要复制到其他帐户，目标帐户的访问密钥：
{DEST_KEY} -
新服务的名称：
{NEW_NAME}
示例
$ podman run registry.redhat.io/3scale-amp2/toolbox-rhel7:3scale2.10 3scale copy service {SERVICE_ID} --source=https://{ACCESS_KEY}@{3SCALE_ADMIN}-admin.{DOMAIN_NAME} --destination=https://{DEST_KEY}@{3SCALE_ADMIN}-admin.{DOMAIN_NAME} --target_system_name={NEW_NAME}
如果要复制的服务具有自定义策略，请确保它们对应的自定义策略定义已存在于要复制该服务的目标中。要了解更多有关复制自定义策略定义的信息，请查看复制策略 registry
4.5. 仅复制服务设置
您可以批量复制和更新服务及代理设置、指标、方法、应用计划、应用计划限制，以及将规则从服务映射到其他现有服务。
您需要以下信息：
-
要复制的服务 id：
{SERVICE_ID} -
目标的服务 ID：
{DEST_ID} -
3scale admin 帐户：
{3SCALE_ADMIN} 运行 3scale 实例的域：
{DOMAIN_NAME}- 如果您使用的是托管 APICast，这是 3scale.net
-
您的帐户的访问密钥：{
ACCESS_KEY} -
目标帐户的访问密钥：
{DEST_KEY}
另外，您可以使用可选标志：
-
用于在复制前删除现有目标服务映射规则的
-f标志。 -
用于仅将规则复制到目标服务的
-r标志。
update 命令已弃用，并由 copy 命令替代。不支持使用已弃用的命令。
以下示例命令从一个服务批量更新到另一个现有服务：
$ podman run registry.redhat.io/3scale-amp2/toolbox-rhel7:3scale2.10 3scale update [opts] service --source=https://{ACCESS_KEY}@{3SCALE_ADMIN}-admin.{DOMAIN_NAME} --destination=https://{DEST_KEY}@{3SCALE_ADMIN}-admin.{DOMAIN_NAME} {SERVICE_ID} {DEST_ID}4.6. 导入 OpenAPI 定义
要创建新服务或更新现有服务，您可以从本地文件或 URL 导入 OpenAPI 定义。导入的默认服务名称由 OpenAPI 定义中的 info.title 指定。但是，您可以使用 --target_system_name=<NEW NAME> 覆盖 此服务名称。这将更新服务名称（如果已存在），或者创建新的服务名称（如果不存在）。
导入 openapi 命令的格式如下：
3scale import openapi [opts] -d=<destination> <specification>
OpenAPI <specification> 可以是以下之一：
-
/path/to/your/definition/file.[json|yaml|yml] -
http[s]://domain/resource/path.[json|yaml|yml]
示例
$ podman run registry.redhat.io/3scale-amp2/toolbox-rhel7:3scale2.10 3scale import openapi [opts] -d=https://{DEST_KEY}@{3SCALE_ADMIN}-admin.{DOMAIN_NAME} my-test-api.json
命令选项
导入 openapi 命令选项包括：
-d --destination=<value>-
3scale 目标实例格式：
http[s]://<authentication>@3scale_domain。 -t --target_system_name=<value>- 3scale 目标系统名称.
--backend-api-secret-token=<value>- API 网关向后端 API 发送的自定义机密令牌。
--backend-api-host-header=<value>- API 网关向后端 API 发送的自定义主机标头。
如需了解更多选项，请参阅 3scale import openapi --help 命令。
OpenAPI 导入规则
导入 OpenAPI 定义时应用以下规则：
- 定义验证为 OpenAPI 2.0 或 OpenAPI 3.0。
- 3scale 产品中的所有映射规则都会被删除。
-
要替换，所有方法名称都必须与 OpenAPI 定义
操作中定义的方法相同。operationId使用精确的模式匹配。 - 仅修改 OpenAPI 定义中包含的方法。
-
仅存在于 OpenAPI 定义中的所有方法都附加到
Hits指标。 - 导入 OpenAPI 定义中的所有映射规则。您可以在 API > Integration 中查看它们。
-
支持的安全方案是
apiKey和oauth2，其中包含任何 OAuth 流类型。 OpenAPI 规格必须是以下之一：
- 可用路径中的文件名.
-
toolbox 可以从中下载内容的 URL。支持的方案是
http和https。 -
从
stdin标准输入流读取.这通过设置-值来控制。
虽然规范中没有安全要求，但该服务被视为 OpenAPI。toolbox 将添加一个 default_credentials 策略，如果还没有在策略链中，它也称为 anonymous_policy。default_credentials 策略将配置在可选参数 --default-credentials-userkey 中提供的 user key。
OpenAPI 3.0 限制
导入 OpenAPI 3.0 定义时会应用以下限制：
-
只有
servers列表中的第一个server.url元素解析为专用 URL。server.url元素的路径组件将用作 OpenAPI 的basePath属性。 - toolbox 不会解析操作对象中路径项和服务器中的服务器。
- 不支持安全方案对象中的多个流。
4.7. 管理远程访问凭证
为了便于使用远程 3scale 实例，您可以使用 3scale toolbox 定义远程 URL 地址和验证详情，以便在配置文件中访问这些远程实例。然后，您可以在任意 toolbox 命令中使用一个短名称来引用这些远程数据。
配置文件的默认位置为 $HOME/.3scalerc.yaml。但是，您可以使用 THREESCALE_CLI_CONFIG 环境变量或 --config-file <config_file> toolbox 选项指定另一个位置。
在添加远程访问凭证时，您可以指定 access_token 或 provider_key ：
-
http[s]://<access_token>@<3scale-instance-domain> -
http[s]://<provider_key>@<3scale-instance-domain>
4.7.1. 添加远程访问凭证
以下示例命令添加一个远程 3scale 实例，其短 <name> at <url>:
3scale remote add [--config-file <config_file>] <name> <url>
示例
$ podman run --name toolbox-container registry.redhat.io/3scale-amp2/toolbox-rhel7:3scale2.10 3scale remote add instance_a https://123456789@example_a.net $ podman commit toolbox-container toolbox
本例创建远程实例并提交容器以创建新镜像。然后，您可以使用包含的远程信息运行新镜像。例如，以下命令使用新镜像显示新添加的远程：
$ podman run toolbox 3scale remote list instance_a https://example_a.net 123456789
然后，其他 toolbox 命令可以使用新创建的镜像来访问添加的远程系统。这个示例使用名为 toolbox 的镜像而不是 registry.redhat.io/3scale-amp2/toolbox-rhel7:3scale2.10 的镜像。
在容器中存储 toolbox 的 secret 存在潜在的安全风险，例如，将容器与 secret 一起分发到其他用户或使用容器进行自动化时。在 OpenShift 中使用 Podman 或机密中的安全卷。
其他资源
有关使用 Podman 的更多详细信息，请参阅：
4.7.2. 列出远程访问凭证
以下示例命令演示了如何列出远程访问凭证：
3scale remote list [--config-file <config_file>]
此命令以以下格式显示添加的远程 3scale 实例列表： <name> < URL><authentication-key>:
示例
$ podman run <toolbox_image_with_remotes_added> 3scale remote list instance_a https://example_a.net 123456789 instance_b https://example_b.net 987654321
4.7.3. 删除远程访问凭证
以下示例命令演示了如何删除远程访问凭证：
3scale remote remove [--config-file <config_file>] <name>
这个命令使用简短 <name> 删除远程 3scale 实例：
示例
$ podman run <toolbox_image_with_remote_added> 3scale remote remove instance_a
4.7.4. 重命名远程访问凭证
以下示例命令演示了如何重命名远程访问凭证：
3scale remote rename [--config-file <config_file>] <old_name> <new_name>
这个命令使用简短的 <old_name> 将远程 3scale 实例重命名为 <new_name> ：
示例
$ podman run <toolbox_image_with_remote_added> 3scale remote rename instance_a instance_b
4.8. 创建应用程序计划
使用 3scale toolbox 在 Developer Portal 中创建、更新、列出、删除、显示或导出/导入应用程序计划。
4.8.1. 创建新应用程序计划
使用以下步骤创建新应用程序计划：
- 您必须提供应用计划名称。
-
要覆盖
system-name，请使用可选参数。 - 如果存在具有相同名称的应用计划，您将看到错误消息。
-
使用
--default标志，将应用计划设置为默认。 使用
--publish标志创建发布的应用计划。-
默认情况下，它将被
隐藏。
-
默认情况下，它将被
使用
--disabled标志创建禁用的应用程序计划。-
默认情况下将
启用它。
-
默认情况下将
服务位置参数是服务引用，可以是服务ID或 servicesystem_name。- toolbox 使用其中任一个。
以下命令创建新应用程序计划：
3scale application-plan create [opts] <remote> <service> <plan-name>
在创建应用程序计划时使用以下选项：
Options
--approval-required=<value> The application requires approval:
true or false
--cost-per-month=<value> Cost per month
--default Make the default application plan
--disabled Disable all methods and metrics in
the application plan
-o --output=<value> Output format on stdout:
one of json|yaml
-p --published Publish the application plan
--setup-fee=<value> Set-up fee
-t --system-name=<value> Set application plan system name
--trial-period-days=<value> The trial period in days
Options for application-plan
-c --config-file=<value> 3scale toolbox configuration file:
defaults to $HOME/.3scalerc.yaml
-h --help Print help for this command
-k --insecure Proceed and operate even for server
connections otherwise considered
insecure
-v --version Print the version of this command
--verbose Verbose mode4.8.2. 创建或更新应用程序计划
如果使用以下步骤创建新应用程序计划（如果不存在），或更新现有应用程序计划：
-
使用
--default标志更新默认应用计划。 -
使用
--publish标志，更新发布的应用计划。 -
使用
--hide标志更新隐藏的应用计划。 -
使用
--disabled标志更新禁用的应用程序计划。 -
使用
--enabled标志，更新启用的应用计划。
服务位置参数是服务引用，可以是服务ID或 servicesystem_name。- toolbox 使用其中任一个。
计划位置参数是计划引用，可以是计划id或 plansystem_name。- toolbox 使用其中任一个。
以下命令更新应用程序计划：
3scale application-plan create [opts] <remote> <service> <plan>
在更新应用程序计划时使用以下选项：
Options
--approval-required=<value> The application requires approval:
true or false
--cost-per-month=<value> Cost per month
--default Make the default application plan
--disabled Disable all methods and metrics in
the application plan
--enabled Enable the application plan
--hide Hide the application plan
-n --name=<value> Set the plan name
-o --output=<value> Output format on stdout:
one of json|yaml
-p --publish Publish the application plan
--setup-fee=<value> Set-up fee
--trial-period-days=<value> The trial period in days
Options for application-plan
-c --config-file=<value> 3scale toolbox configuration file:
defaults to $HOME/.3scalerc.yaml
-h --help Print help for this command
-k --insecure Proceed and operate even for server
connections otherwise considered
insecure
-v --version Print the version of this command
--verbose Verbose mode4.8.3. 列出应用计划
以下命令列出应用程序计划：
3scale application-plan list [opts] <remote> <service>
在列出应用程序计划时使用以下选项：
Options
-o --output=<value> Output format on stdout:
one of json|yaml
Options for application-plan
-c --config-file=<value> 3scale toolbox configuration file:
defaults to $HOME/.3scalerc.yaml
-h --help Print help for this command
-k --insecure Proceed and operate even for server
connections otherwise considered insecure
-v --version Print the version of this command
--verbose Verbose mode4.8.4. 显示应用程序计划
以下命令显示应用程序计划：
3scale application-plan show [opts] <remote> <service> <plan>
在显示应用程序计划时使用以下选项：
Options
-o --output=<value> Output format on stdout:
one of json|yaml
Options for application-plan
-c --config-file=<value> 3scale toolbox configuration file:
defaults to $HOME/.3scalerc.yaml
-h --help Print help for this command
-k --insecure Proceed and operate even for server
connections otherwise considered insecure
-v --version Print the version of this command
--verbose Verbose mode4.8.5. 删除应用程序计划
以下命令删除应用程序计划：
3scale application-plan delete [opts] <remote> <service> <plan>
在删除应用程序计划时使用以下选项：
Options for application-plan
-c --config-file=<value> 3scale toolbox configuration file:
defaults to $HOME/.3scalerc.yaml
-h --help Print help for this command
-k --insecure Proceed and operate even for server
connections otherwise considered insecure
-v --version Print the version of this command
--verbose Verbose mode4.8.6. 导出/导入应用程序计划
您可以将单个应用程序计划导出或导入到 yaml 内容。
注意以下几点：
- 包括应用计划中定义的限值。
- 包含在应用计划中定义的定价规则。
- 包括限制和定价规则所引用的指标/指标。
- 其中包含了应用计划中定义的功能。
-
服务可以通过
id或system_name引用。 -
应用计划可以通过
id或system_name引用。
4.8.6.1. 将应用计划导出到文件
以下命令导出应用程序计划：
3scale application-plan export [opts] <remote> <service_system_name> <plan_system_name>
示例
$ podman run -u root -v $PWD:/tmp registry.redhat.io/3scale-amp2/toolbox-rhel7:3scale2.10 3scale application-plan export --file=/tmp/plan.yaml remote_name service_name plan_name
本例使用 Podman 卷将输出结果中的导出文件挂载到当前的 $PWD 文件夹。
特定于 export 命令：
- 对远程服务和应用计划进行只读操作.
命令输出可以是
stdout或 file。-
如果没有由
-f选项指定，则默认情况下，yaml内容将写入stdout。
-
如果没有由
在导出应用程序计划时使用以下选项：
Options
-f --file=<value> Write to file instead of stdout
Options for application-plan
-c --config-file=<value> 3scale toolbox configuration file:
defaults to $HOME/.3scalerc.yaml
-h --help Print help for this command
-k --insecure Proceed and operate even for server
connections otherwise considered insecure
-v --version Print the version of this command
--verbose Verbose mode4.8.6.2. 从文件导入应用计划
以下命令导入应用程序计划：
3scale application-plan import [opts] <remote> <service_system_name>
示例
$ podman run -v $PWD/plan.yaml:/tmp/plan.yaml registry.redhat.io/3scale-amp2/toolbox-rhel7:3scale2.10 3scale application-plan import --file=/tmp/plan.yaml remote_name service_name
本例使用 Podman 卷从当前的 $PWD 文件夹挂载容器中导入的文件。
4.8.6.3. 从 URL 导入应用计划
3scale application-plan import -f http[s]://domain/resource/path.yaml remote_name service_name
特定于导入命令：
命令输入内容可以
stdin、file 或 URL 格式。-
如果没有由
-f选项指定，默认情况下，yaml内容将从stdin 中读取。
-
如果没有由
- 如果无法在远程服务中找到应用计划，它将被创建。
可选的 param
-p，--plan，用于覆盖远程目标应用程序计划id或system_name。-
如果没有通过
-p选项指定，默认情况下，应用程序计划将由计划属性system_name fromyaml内容引用。
-
如果没有通过
- 将创建在远程服务中没有的 yaml 内容中的任何指标或方法。
导入应用程序计划时使用以下选项：
Options
-f --file=<value> Read from file or URL instead of
stdin
-p --plan=<value> Override application plan reference
Options for application-plan
-c --config-file=<value> 3scale toolbox configuration file:
defaults to $HOME/.3scalerc.yaml
-h --help Print help for this command
-k --insecure Proceed and operate even for server
connections otherwise considered
insecure
-v --version Print the version of this command
--verbose Verbose mode4.9. 创建指标
使用 3scale toolbox 在 Developer Portal 中创建、更新、列出和删除指标。
使用以下步骤创建指标：
- 您必须提供指标名称。
-
要覆盖
system-name，请使用可选参数。 - 如果存在相同名称的指标，您将看到错误消息。
使用--disabled 标志创建禁用的指标。-
默认情况下将
启用它。
-
默认情况下将
服务位置参数是服务引用，可以是服务ID或 servicesystem_name。- toolbox 使用其中任一个。
以下命令创建指标：
3scale metric create [opts] <remote> <service> <metric-name>
在创建指标时请使用以下选项：
Options
--description=<value> Set a metric description
--disabled Disable this metric in all application
plans
-o --output=<value> Output format on stdout:
one of json|yaml
-t --system-name=<value> Set the application plan system name
--unit=<value> Metric unit: default hit
Options for metric
-c --config-file=<value> 3scale toolbox configuration file:
defaults to $HOME/.3scalerc.yaml
-h --help Print help for this command
-k --insecure Proceed and operate even for server
connections otherwise considered insecure
-v --version Print the version of this command
--verbose Verbose mode4.9.1. 创建或更新指标
如果新的指标不存在，请使用以下步骤创建新指标，或更新现有指标：
- 如果存在相同名称的指标，您将看到错误消息。
-
使用--disabled 标志更新禁用的指标。 -
使用
--enabled标志更新为启用的指标。
服务位置参数是服务引用，可以是服务ID或 servicesystem_name。- toolbox 使用其中任一个。
指标位置参数是指标引用，可以是指标ID或指标system_name。- toolbox 使用其中任一个。
以下命令更新了指标：
3scale metric apply [opts] <remote> <service> <metric>
在更新指标时请使用以下选项：
Options
--description=<value> Set a metric description
--disabled Disable this metric in all application
plans
--enabled Enable this metric in all application
plans
-n --name=<value> This will set the metric name
--unit=<value> Metric unit: default hit
-o --output=<value> Output format on stdout:
one of json|yaml
Options for metric
-c --config-file=<value> 3scale toolbox configuration file:
defaults to $HOME/.3scalerc.yaml
-h --help Print help for this command
-k --insecure Proceed and operate even for server
connections otherwise considered insecure
-v --version Print the version of this command
--verbose Verbose mode4.9.2. 列出指标
以下命令列出了指标：
3scale metric list [opts] <remote> <service>
在列出指标时请使用以下选项：
Options
-o --output=<value> Output format on stdout:
one of json|yaml
Options for metric
-c --config-file=<value> 3scale toolbox configuration file:
defaults to $HOME/.3scalerc.yaml
-h --help Print help for this command
-k --insecure Proceed and operate even for server
connections otherwise considered insecure
-v --version Print the version of this command
--verbose Verbose mode4.9.3. 删除指标
以下命令删除指标：
3scale metric delete [opts] <remote> <service> <metric>
在删除指标时请使用以下选项：
Options for metric
-c --config-file=<value> 3scale toolbox configuration file:
defaults to $HOME/.3scalerc.yaml
-h --help Print help for this command
-k --insecure Proceed and operate even for server
connections otherwise considered insecure
-v --version Print the version of this command
--verbose Verbose mode4.10. 创建方法
使用 3scale toolbox 在 Developer Portal 中创建、应用、列出和删除方法。
4.10.1. 创建方法
使用以下步骤创建方法：
- 您必须提供方法名称。
-
要覆盖
system-name，请使用可选参数。 - 如果存在具有相同名称的方法，您将看到错误消息。
通过
--disabled标志创建禁用的方法。-
默认情况下将
启用它。
-
默认情况下将
服务位置参数是服务引用，可以是服务ID或 servicesystem_name。- toolbox 使用其中任一个。
以下命令创建一个方法：
3scale method create [opts] <remote> <service> <method-name>
在创建方法时使用以下选项：
Options
--description=<value> Set a method description
--disabled Disable this method in all
application plans
-o --output=<value> Output format on stdout:
one of json|yaml
-t --system-name=<value> Set the method system name
Options for method
-c --config-file=<value> 3scale toolbox configuration file:
defaults to $HOME/.3scalerc.yaml
-h --help Print help for this command
-k --insecure Proceed and operate even for server
connections otherwise considered insecure
-v --version Print the version of this command
--verbose Verbose mode4.10.2. 创建或更新方法
如果方法不存在，请使用以下步骤创建新方法，或更新现有的方法：
- 如果存在具有相同名称的方法，命令将返回错误消息。
-
使用
--disabled 标志更新为禁用的方法。 -
使用
--enabled 标志将 更新为启用的方法。
服务位置参数是服务引用，可以是服务ID或 servicesystem_name。- toolbox 使用其中任一个。
方法位置参数是方法引用，可以是方法id或方法system_name。- toolbox 使用其中任一个。
以下命令更新方法：
3scale method apply [opts] <remote> <service> <method>
在更新方法时使用以下选项：
Options
--description=<value> Set a method description
--disabled Disable this method in all
application plans
--enabled Enable this method in all
application plans
-n --name=<value> Set the method name
-o --output=<value> Output format on stdout:
one of json|yaml
Options for method
-c --config-file=<value> 3scale toolbox configuration file:
defaults to $HOME/.3scalerc.yaml
-h --help Print help for this command
-k --insecure Proceed and operate even for server
connections otherwise considered insecure
-v --version Print the version of this command
--verbose Verbose mode4.10.3. 列出方法
以下命令列出方法：
3scale method list [opts] <remote> <service>
在列出方法时使用以下选项：
Options
-o --output=<value> Output format on stdout:
one of json|yaml
Options for method
-c --config-file=<value> 3scale toolbox configuration file:
defaults to $HOME/.3scalerc.yaml
-h --help Print help for this command
-k --insecure Proceed and operate even for server
connections otherwise considered insecure
-v --version Print the version of this command
--verbose Verbose mode4.10.4. 删除方法
以下命令删除方法：
3scale method delete [opts] <remote> <service> <metric>
在删除方法时使用以下选项：
Options for method
-c --config-file=<value> 3scale toolbox configuration file:
defaults to $HOME/.3scalerc.yaml
-h --help Print help for this command
-k --insecure Proceed and operate even for server
connections otherwise considered insecure
-v --version Print the version of this command
--verbose Verbose mode4.11. 创建服务
使用 3scale toolbox 在 Developer Portal 中创建、应用、列出、显示或删除服务。
4.11.1. 创建新服务
以下命令创建新服务：
3scale service create [options] <remote> <service-name>
在创建服务时使用以下选项：
Options
-a --authentication-mode=<value> Specify authentication mode of
the service:
- '1' for API key
- '2' for App Id/App Key
- 'oauth' for OAuth mode
- 'oidc' for OpenID Connect
-d --deployment-mode=<value> Specify the deployment mode of
the service
--description=<value> Specify the description of the
service
-o --output=<value> Output format on stdout:
one of json|yaml
-s --system-name=<value> Specify the system-name of the
service
--support-email=<value> Specify the support email of the
service
Options for service
-c --config-file=<value> 3scale toolbox configuration file:
defaults to $HOME/.3scalerc.yaml
-h --help Print help for this command
-k --insecure Proceed and operate even for
server connections otherwise
considered insecure
-v --version Print the version of this command
--verbose Verbose mode4.11.2. 创建或更新服务
如果新服务不存在，请使用以下内容创建新服务，或更新现有服务：
service-id_or_system-name位置参数是服务引用。-
它可以是服务
ID，也可以是 servicesystem_name。 - toolbox 将自动找出这一点。
-
它可以是服务
-
此命令是
幂等的。
以下命令更新服务：
3scale service apply <remote> <service-id_or_system-name>
在更新服务时使用以下选项：
Options
-a --authentication-mode=<value> Specify authentication mode of
the service:
- '1' for API key
- '2' for App Id/App Key
- 'oauth' for OAuth mode
- 'oidc' for OpenID Connect
-d --deployment-mode=<value> Specify the deployment mode of
the service
--description=<value> Specify the description of the
service
-n --name=<value> Specify the name of the metric
--support-email=<value> Specify the support email of the
service
-o --output=<value> Output format on stdout:
one of json|yaml
Options for services
-c --config-file=<value> 3scale toolbox configuration file:
defaults to $HOME/.3scalerc.yaml
-h --help Print help for this command
-k --insecure Proceed and operate even for
server connections otherwise
considered insecure
-v --version Print the version of this command
--verbose Verbose mode4.11.3. 列出服务
以下命令列出服务：
3scale service list <remote>
在列出服务时使用以下选项：
Options
-o --output=<value> Output format on stdout:
one of json|yaml
Options for services
-c --config-file=<value> 3scale toolbox configuration file:
defaults to $HOME/.3scalerc.yaml
-h --help Print help for this command
-k --insecure Proceed and operate even for server
connections otherwise considered insecure
-v --version Print the version of this command
--verbose Verbose mode4.11.4. 显示服务
以下命令显示服务：
3scale service show <remote> <service-id_or_system-name>
在显示服务时使用以下选项：
Options
-o --output=<value> Output format on stdout:
one of json|yaml
Options for services
-c --config-file=<value> 3scale toolbox configuration file:
defaults to $HOME/.3scalerc.yaml
-h --help Print help for this command
-k --insecure Proceed and operate even for server
connections otherwise considered insecure
-v --version Print the version of this command
--verbose Verbose mode4.11.5. 删除服务
以下命令删除服务：
3scale service delete <remote> <service-id_or_system-name>
在删除服务时使用以下选项：
Options for services
-c --config-file=<value> 3scale toolbox configuration file:
defaults to $HOME/.3scalerc.yaml
-h --help Print help for this command
-k --insecure Proceed and operate even for server
connections otherwise considered insecure
-v --version Print the version of this command
--verbose Verbose mode4.12. 创建 ActiveDocs
使用 3scale toolbox 在 Developer Portal 中创建、更新、列出或删除 ActiveDocs。
4.12.1. 创建新的 ActiveDocs
要从 API 定义创建一个新的 ActiveDocs，符合 OpenAPI 规格：
将 API 定义添加到 3scale，选择性地为其指定名称：
3scale activedocs create <remote> <activedocs-name> <specification>
ActiveDocs 的 OpenAPI 规格是必需的，且必须是以下值之一：
- 可用路径中的文件名.
-
toolbox 可以从中下载内容的 URL。支持的方案是
http和https。 从
stdin标准输入流读取.这通过设置-值来控制。在创建 ActiveDocs 时使用以下选项：
Options -d --description=<value> Specify the description of the ActiveDocs -i --service-id=<value> Specify the Service ID associated to the ActiveDocs -o --output=<value> Output format on stdout: one of json|yaml -p --published Specify to publish the ActiveDocs on the Developer Portal. Otherwise it is hidden. -s --system-name=<value> Specify the system-name of the ActiveDocs --skip-swagger-validations Specify to skip validation of the Swagger specification Options for ActiveDocs -c --config-file=<value> toolbox configuration file. Defaults to $HOME/.3scalerc.yaml -h --help Print help for this command -k --insecure Proceed and operate even for server connections otherwise considered insecure -v --version Print the version of this command --verbose Verbose mode
- 在 Developer Portal 中发布该定义。
4.12.2. 创建或更新 ActiveDocs
使用以下命令创建新的 ActiveDocs（如果不存在），或者使用新的 API 定义更新现有 ActiveDocs：
3scale activedocs apply <remote> <activedocs_id_or_system_name>
在更新 ActiveDocs 时使用以下选项：
Options
-d --description=<value> Specify the description of the
ActiveDocs
--hide Specify to hide the ActiveDocs
on the Developer Portal
-i --service-id=<value> Specify the Service ID associated
to the ActiveDocs
-o --output=<value> Output format on stdout:
one of json|yaml
--openapi-spec=<value> Specify the Swagger specification.
Can be a file, a URL or '-' to read
from stdin. This is a mandatory
option when applying the ActiveDoc
for the first time.
-p --publish Specify to publish the ActiveDocs
on the Developer Portal. Otherwise
it is hidden
-s --name=<value> Specify the name of the ActiveDocs
--skip-swagger-validations=<value> Specify whether to skip validation
of the Swagger specification: true
or false. Defaults to true.
Options for ActiveDocs
-c --config-file=<value> 3scale toolbox configuration file:
defaults to $HOME/.3scalerc.yaml
-h --help Print help for this command
-k --insecure Proceed and operate even for server
connections otherwise considered
insecure
-v --version Print the version of this command
--verbose Verbose mode
activedocs 应用 --skip-swagger-validations 的行为在 3scale 2.8 中 更改。您可能需要使用 activedocs apply 更新现有脚本。在以前的版本中，如果您没有在每个 activedocs apply 命令中指定这个选项，则不会跳过验证。现在，--skip-swagger-validations 默认为 true。
4.12.3. 列出 ActiveDocs
使用以下命令在 Developer Portal 中获取有关所有 ActiveDocs 的信息，包括：
- id
- name
- 系统名称
- description
- 发布（这意味着可以在开发人员门户中显示）
- 创建日期
- 最新更新日期
以下命令列出所有定义的 ActiveDocs：
3scale activedocs list <remote>
在列出 ActiveDocs 时请使用以下选项：
Options
-o --output=<value> Output format on stdout:
one of json|yaml
-s --service-ref=<value> Filter the ActiveDocs by service
reference
Options for ActiveDocs
-c --config-file=<value> 3scale toolbox configuration file:
defaults to $HOME/.3scalerc.yaml
-h --help Print help for this command
-k --insecure Proceed and operate even for server
connections otherwise considered insecure
-v --version Print the version of this command
--verbose Verbose mode4.12.4. 删除 ActiveDocs
以下命令删除 ActiveDocs：
3scale activedocs delete <remote> <activedocs-id_or-system-name>
在删除 ActiveDocs 时使用以下选项：
Options for ActiveDocs
-c --config-file=<value> 3scale toolbox configuration file:
defaults to $HOME/.3scalerc.yaml
-h --help Print help for this command
-k --insecure Proceed and operate even for server
connections otherwise considered insecure
-v --version Print the version of this command
--verbose Verbose mode4.13. 列出代理配置
使用 3scale toolbox 列出、显示并在 Developer Portal 中提升所有定义的代理配置。
以下命令列出代理配置：
3scale proxy-config list <remote> <service> <environment>
在列出代理配置时请使用以下选项：
Options
-o --output=<value> Output format on stdout:
one of json|yaml
Options for proxy-config
-c --config-file=<value> 3scale toolbox configuration file:
defaults to $HOME/.3scalerc.yaml
-h --help Print help for this command
-k --insecure Proceed and operate even for server
connections otherwise considered insecure
-v --version Print the version of this command
--verbose Verbose mode4.13.1. 显示代理配置
以下命令显示代理配置：
3scale proxy-config show <remote> <service> <environment>
在显示代理配置时请使用以下选项：
Options
--config-version=<value> Specify the proxy configuration version.
If not specified, defaults to latest
-o --output=<value> Output format on stdout:
one of json|yaml
Options for proxy-config
-c --config-file=<value> 3scale toolbox configuration file:
defaults to $HOME/.3scalerc.yaml
-h --help Print help for this command
-k --insecure Proceed and operate even for server
connections otherwise considered
insecure
-v --version Print the version of this command
--verbose Verbose mode4.13.2. 提升代理配置
以下命令将最新的暂存代理配置提升到生产环境：
3scale proxy-config promote <remote> <service>
在将最新的暂存代理配置提升到生产环境时，请使用以下选项：
Options for proxy-config
-c --config-file=<value> 3scale toolbox configuration file:
defaults to $HOME/.3scalerc.yaml
-h --help Print help for this command
-k --insecure Proceed and operate even for server
connections otherwise considered insecure
-v --version Print the version of this command
--verbose Verbose mode4.14. 复制策略 registry
在以下情况下，使用 toolbox 命令将策略 registry 从 3scale 源帐户复制到目标帐户：
- 目标帐户中正在创建缺少的自定义策略。
- 目标帐户中正在更新匹配的自定义策略。
- 此 copy 命令具有幂等性。
- 缺少的自定义策略定义为源帐户中存在的自定义策略，且不存在于帐户租户中。
- 匹配自定义策略定义为源和目标帐户中存在的自定义策略。
以下命令复制策略 registry：
3scale policy-registry copy [opts] <source_remote> <target_remote>
Option for policy-registry
-c --config-file=<value> 3scale toolbox configuration file:
defaults to $HOME/.3scalerc.yaml
-h --help Print help for this command
-k --insecure Proceed and operate even for server
connections otherwise considered insecure
-v --version Print the version of this command
--verbose Verbose mode4.15. 列出应用
使用 3scale toolbox 列出、创建、显示、应用或删除应用程序开发人员门户。
以下命令列出应用程序：
3scale application list [opts] <remote>
在列出应用程序时使用以下选项：
OPTIONS
--account=<value> Filter by account
-o --output=<value> Output format on stdout:
one of json|yaml
--plan=<value> Filter by application plan. Service
option required.
--service=<value> Filter by service
OPTIONS FOR APPLICATION
-c --config-file=<value> 3scale toolbox configuration file:
defaults to $HOME/.3scalerc.yaml
-h --help Print help for this command
-k --insecure Proceed and operate even for server
connections otherwise considered insecure
-v --version Print the version of this command
--verbose Verbose mode4.15.1. 创建应用程序
使用 create 命令创建与给定 3scale 帐户和应用计划相关联的一个应用。
所需的位置参数如下：
-
<service>参考.它可以是服务ID，也可以是 servicesystem_name。 <account>参考.它可以是以下之一：-
帐户
ID -
帐户管理员用户
的用户名、电子邮件或user_id -
provider_key
-
帐户
-
<application plan>参考。它可以是计划ID，也可以是计划system_name。 -
<name>应用程序名称。
以下命令创建应用程序：
3scale application create [opts] <remote> <account> <service> <application-plan> <name>
在创建应用程序时使用以下选项：
OPTIONS
--application-id=<value> App ID or Client ID (for OAuth and
OpenID Connect authentication modes)
of the application to be created.
--application-key=<value> App Key(s) or Client Secret (for OAuth
and OpenID Connect authentication
modes) of the application created.
--description=<value> Application description
-o --output=<value> Output format on stdout:
one of json|yaml
--redirect-url=<value> OpenID Connect redirect url
--user-key=<value> User Key (API Key) of the application
to be created.
OPTIONS FOR APPLICATION
-c --config-file=<value> 3scale toolbox configuration file:
defaults to $HOME/.3scalerc.yaml
-h --help Print help for this command
-k --insecure Proceed and operate even for server
connections otherwise considered insecure
-v --version Print the version of this command
--verbose Verbose mode4.15.2. 显示应用程序
以下命令显示应用程序：
3scale application show [opts] <remote> <application>
应用程序参数允许：
-
user_key- API 密钥 -
App_id- 来自 app_id/app_key 对或 OAuth 和 OpenID Connect (OIDC)验证模式 的客户端 ID -
应用程序内部
ID
OPTIONS
-o --output=<value> Output format on stdout:
one of json|yaml
OPTIONS FOR APPLICATION
-c --config-file=<value> 3scale toolbox configuration file:
defaults to $HOME/.3scalerc.yaml
-h --help Print help for this command
-k --insecure Proceed and operate even for server
connections otherwise considered insecure
-v --version Print the version of this command
--verbose Verbose mode4.15.3. 创建或更新应用程序
如果新应用程序不存在，或更新现有应用程序，使用以下命令创建新应用程序：
3scale application apply [opts] <remote> <application>
应用程序参数允许：
-
user_key- API 密钥 -
App_id- 来自 app_id/app_key 对或 OAuth 和 OIDC 验证模式 的客户端 ID -
应用程序内部
ID 如果未找到应用程序且需要创建应用程序，则需要
帐户可选参数。它可以是以下之一：-
帐户
ID -
3scale 帐户管理员用户
的用户名、电子邮件或user_id -
provider_key
-
帐户
-
名称不能用作唯一标识符，因为应用名称在 3scale 中不唯一。 -
使用
--resume 标志恢复暂停的应用。 -
暂停应用 - 将状态更改为通过
--suspend标志暂停。
在更新应用程序时使用以下选项：
OPTIONS
--account=<value> Application's account. Required when
creating
--application-key=<value> App Key(s) or Client Secret (for OAuth
and OpenID Connect authentication
modes) of the application to be
created. Only used when application
does not exist.
--description=<value> Application description
--name=<value> Application name
-o --output=<value> Output format on stdout:
one of json|yaml
--plan=<value> Application's plan. Required when
creating.
--redirect-url=<value> OpenID Connect redirect url
--resume Resume a suspended application
--service=<value> Application's service. Required when
creating.
--suspend Suspends an application (changes the
state to suspended)
--user-key=<value> User Key (API Key) of the application
to be created.
OPTIONS FOR APPLICATION
-c --config-file=<value> 3scale toolbox configuration file:
defaults to $HOME/.3scalerc.yaml
-h --help Show help for this command
-k --insecure Proceed and operate even for server
connections otherwise considered insecure
-v --version Print the version of this command
--verbose Verbose mode.4.15.4. 取消应用程序
以下命令删除应用程序：
3scale application delete [opts] <remote> <application>
应用程序参数允许：
-
user_key- API 密钥 -
App_id- 来自 app_id/app_key 对或 OAuth 和 OIDC 验证模式 的客户端 ID -
应用程序内部
ID
4.16. 复制 API 后端
在指定的 3scale 系统上创建指定源 API 后端的副本。默认情况下，目标系统首先使用源后端系统名称搜索：
- 如果没有找到带有所选系统名称的后端，则会创建它。
- 如果找到带有所选系统名称的后端，则会更新它。仅创建缺少的组件，如指标、方法或映射规则。
您可以使用 --target_system_name 选项覆盖系统名称。
复制的组件
复制以下 API 后端组件：
- 指标
- 方法
- 映射规则
步骤
输入以下命令复制 API 后端：
3scale backend copy [opts] -s <source_remote> -d <target_remote> <source_backend>
指定的 3scale 实例可以是远程名称或 URL。
注意您只能为每个命令复制单个 API 后端。您可以使用多个 命令复制多个后端。您可以通过指定不同的
--target_system_name 名称来多次复制同一后端。
在复制 API 后端时使用以下选项：
Options
-d --destination=<value> 3scale target instance: URL or
remote name (required).
-s --source=<value> 3scale source instance: URL or
remote name (required).
-t --target_system_name=<value> Target system name: defaults to
source system name.
+ 以下示例命令演示了如何通过指定不同的 --target_system_name 名称 来多次复制 API 后端：
+
$ podman run registry.redhat.io/3scale-amp2/toolbox-rhel7:3scale2.10 3scale backend copy [-t target_system_name] -s 3scale1 -d 3scale2 api_backend_01
4.16.1. 复制 API 产品
在目标 3scale 系统上创建指定源 API 产品的副本。默认情况下，源 API 产品系统名称首先搜索目标系统：
-
如果没有找到具有所选
system-name的产品，则会创建它。 -
如果找到具有所选
system-name的产品，则会更新它。仅创建缺少的组件，如指标、方法、映射规则和其他配置。
您可以使用 --target_system_name 选项覆盖系统名称。
复制的组件
复制以下 API 产品组件：
- 配置和设置
- 指标和方法
- 映射规则
- 应用程序计划、定价规则和限值
- 应用程序用量规则
- 策略（policy）
- 后端
- ActiveDocs
步骤
输入以下命令复制 API 产品：
3scale product copy [opts] -s <source_remote> -d <target_remote> <source_product>
指定的 3scale 实例可以是远程名称或 URL。
注意您只能为每个命令复制单个 API 产品。您可以使用多个 命令复制多个产品。您可以通过指定不同的
--target_system_name 名称来多次复制同一产品。
在复制 API 产品时请使用以下选项：
Options
-d --destination=<value> 3scale target instance: URL or
remote name (required).
-s --source=<value> 3scale source instance: URL or
remote name (required).
-t --target_system_name=<value> Target system name: defaults to
source system name.
+ 以下示例命令演示了如何通过指定不同的 --target_system_name 名称 来多次复制 API 产品：
+
$ podman run registry.redhat.io/3scale-amp2/toolbox-rhel7:3scale2.10 3scale product copy [-t target_system_name] -s 3scale1 -d 3scale2 my_api_product_01
4.17. SSL 和 TLS 故障排除
本节介绍如何解决安全套接字层/交易层安全性(SSL/TLS)的问题。
如果您遇到与自签名 SSL 证书相关的问题，您可以下载和使用远程主机证书，如本节所述。例如，典型的错误包括 SSL 证书问题： 。
自签名证书或 证书链中的自签名证书
步骤
使用
openssl下载远程主机证书。例如：$ echo | openssl s_client -showcerts -servername self-signed.badssl.com -connect self-signed.badssl.com:443 2>/dev/null | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > self-signed-cert.pem
确保证书使用
curl正常工作。例如：$ SSL_CERT_FILE=self-signed-cert.pem curl -v https://self-signed.badssl.com
如果证书正常工作，您将不再获得 SSL 错误。如果证书无法正常工作，请尝试使用
-k选项（或其长形式--insecure）运行curl命令。这表示即使对于其他被视为不安全的服务器连接也一样希望继续。将
SSL_CERT_FILE环境变量添加到3scale命令。例如：$ podman run --env "SSL_CERT_FILE=/tmp/self-signed-cert.pem" -v $PWD/self-signed-cert.pem:/tmp/self-signed-cert.pem egistry.redhat.io/3scale-amp2/toolbox-rhel7:3scale2.10 3scale service list https://{ACCESS_KEY}@{3SCALE_ADMIN}-admin.{DOMAIN_NAME}本例使用 Podman 卷在容器中挂载证书文件。它假定该文件位于当前的
$PWD文件夹中。另一种方法是使用 3scale toolbox 镜像作为基础镜像创建您自己的 toolbox 镜像，然后安装您自己的可信证书存储。
其他资源
- 有关 SSL 证书的详情，请查看 Red Hat Certificate System 文档。
- 有关 Podman 的详情，请参阅在 Red Hat Enterprise Linux 8 上构建、运行和管理 Linux 容器。
第 5 章 在 3scale 中映射 API 环境
API 提供程序提供对通过 3scale 管理门户管理的 API 的访问权限。然后，您可以在许多环境中部署 API 后端。API 后端环境包括以下：
- 用于开发、质量保证(QA)、登台和生产的不同环境。
- 用于管理其自身 API 后端组的团队或部门的不同环境。
红帽 3scale API 管理产品代表 API 的单一 API 或子集，但也可用于映射和管理不同的 API 后端环境。
要了解为您的 3scale 产品映射 API 环境的信息，请查看以下部分：
5.1. 每个环境的产品
此方法为每个 API 后端环境使用单独的 3scale 产品。在每个产品中，配置生产网关和暂存网关，以便能够像使用 API 后端一样安全地测试并提升对网关配置的更改。
Production Product => Production Product APIcast gateway => Production Product API upstream Staging Product => Staging Product APIcast gateway => Staging Product API upstream
为 API 后端环境配置产品，如下所示：
- 使用环境 API 后端的基础 URL 创建 后端。
- 使用 后端路径 / 将后端添加到 环境的产品中。
开发环境
创建开发后端
- name：dev
- 私有基础 URL:API 后端的 URL
创建 Dev 产品
-
生产公共基本 URL：https://dev-api-backend.yourdomain.com
-
暂存公共基本 URL：https://dev-api-backend.yourdomain.com
- 使用 后端路径 /添加 Dev 后端.
-
生产公共基本 URL：https://dev-api-backend.yourdomain.com
QA 环境
创建 QA 后端
- name：QA
- 私有基础 URL:API 后端的 URL
创建 QA 产品
-
生产公共基本 URL：https://qa-api-backend.yourdomain.com
-
暂存公共基本 URL：https://qa-api-backend.yourdomain.com
- 使用 后端路径 /添加 QA 后端.
-
生产公共基本 URL：https://qa-api-backend.yourdomain.com
生产环境
创建生产后端
- name：prod
- 私有基础 URL:API 后端的 URL
创建生产产品
-
生产公共基本 URL：https://prod-api-backend.yourdomain.com
-
暂存公共基本 URL：https://prod-api-backend.yourdomain.com
- 使用 后端路径 /添加生产 后端
-
生产公共基本 URL：https://prod-api-backend.yourdomain.com
其他资源
- 如需有关 3scale 产品的更多信息，请参阅 3scale 的首个步骤。
5.2. 3scale 内部部署实例
对于 3scale 内部部署实例，有多种方式可以设置 3scale 来管理 API 后端环境。
- 每个 API 后端环境有一个单独的 3scale 实例
- 使用 多租户 功能的 3scale 实例
5.2.1. 每个环境隔离 3scale 实例
在这种方法中，为每个 API 后端环境部署一个单独的 3scale 实例。这种架构的优势在于每个环境都将相互隔离，因此没有共享的数据库或其他资源。例如，在一个环境中进行的任何负载测试都不会影响其他环境中的资源。
如前文所述，这种分离安装具有优势，但需要更多运营资源和维护。OpenShift 管理控制台中需要这些额外的资源，而不一定在 3scale 层上。
5.2.2. 每个环境隔离 3scale 租户
在这个方法中使用了一个 3scale 实例，但多租户功能用于支持多个 API 后端。
有两个选项：
- 在单个租户内，创建环境和 3scale 产品之间的 1 到 1 到 1 个映射。
根据需要，在每个租户具有一个或多个产品的环境和租户之间创建一个 1 到 1 的映射。
- 将有三个与 API 后端环境对应的租户，即 dev-tenant、qa-tenant、prod-tenant。这种方法的优点在于，它允许环境的逻辑分割，但使用共享的物理资源。
最终，在将 API 环境映射到具有多个租户的单一安装的最佳策略时，需要考虑共享的物理资源。
5.3. 3scale 混合方法
3scale 内部部署实例 中描述的方法可以组合使用。例如：
- 用于生产环境的独立 3scale 实例
- 单独的 3scale 实例，为 dev 和 qa 中的非生产环境提供单独的租户。
5.4. 3scale 使用 APIcast 网关
对于 3scale 内部部署实例，有两个替代方案可用来设置 3scale 来管理 API 后端环境：
- 每个 3scale 安装附带两个内置 APIcast 网关，供暂存和生产使用。
- 将 额外的 APIcast 网关部署到运行 3scale 的 OpenShift 集群。
5.4.1. APIcast 内置默认网关
使用 APIcast 内置网关时，将自动处理使用带有 API cast 网关 3scale 中描述的方法配置的 API 后端。当 3scale Master Admin 添加租户时，将为 production 和暂存内置 APIcast 网关中的租户创建一个路由。请参阅 了解多租户子域
-
<API_NAME>-<TENANT_NAME>-apicast.staging.<WILDCARD_DOMAIN> -
<API_NAME>-<TENANT_NAME>-apicast.production.<WIDLCARD_DOMAIN>
因此，映射到不同租户的每个 API 后端环境都会获得自己的路由。例如：
-
Dev
<API_NAME>-dev-apicast.staging.<WILDCARD_DOMAIN> -
QA
<API_NAME>-qa-apicast.staging.<WILDCARD_DOMAIN> -
prod
<API_NAME>-prod-apicast.staging.<WILDCARD_DOMAIN>
5.4.2. 额外的 APIcast 网关
额外的 APIcast 网关是部署到与 3scale 实例所运行 集群不同的 OpenShift 集群上。设置和使用其他 APIcast 网关的方法不止一种。启动 APIcast 使用的环境变量变量变量 THREESCALE_PORTAL_ENDPOINT 的值取决于如何设置额外的 APIcast 网关。
单独的 APIcast 网关可用于每个 API 后端环境。例如：
DEV_APICAST -> DEV_TENANT ; DEV_APICAST started with THREESCALE_PORTAL_ENDPOINT = admin portal for DEV_TENANT QA_APICAST -> QA_TENANT ; QA_APICAST started with THREESCALE_PORTAL_ENDPOINT = admin portal for QA_APICAST PROD_APICAST -> PROD_TENANT ; PROD_APICAST started with THREESCALE_PORTAL_ENDPOINT = admin portal for PROD_APICAST
The THREESCALE_PORTAL_ENDPOINT 由 APIcast 用于下载配置。映射到 API 后端环境的每一租户都使用单独的 APIcast 网关。The THREESCALE_PORTAL_ENDPOINT 设置为租户的管理门户，其中包含特定于该 API 后端环境的所有产品配置。
单个 APIcast 网关可用于多个 API 后端环境。在本例中，THREESCALE_PORTAL_ENDPOINT 设置为 主管理门户。
第 6 章 使用 3scale toolbox 自动执行 API 生命周期
本主题介绍了红帽 3scale API 管理的 API 生命周期的概念，并演示了 API 供应商如何使用 3scale toolbox 命令使用 Jenkins 持续集成/持续部署(CI/CD)管道自动执行部署阶段。它描述了如何部署示例 Jenkins CI/CD 管道、如何使用 3scale 共享库创建自定义 Jenkins 管道以及如何从头开始创建自定义管道：
6.1. API 生命周期阶段概述
API 生命周期描述了在创建 API 时需要的所有活动，直到它被弃用。3scale 可让 API 供应商执行完整的 API 生命周期管理。本节解释了 API 生命周期中的每个阶段，并描述了其目标和预期结果。
下图显示了左侧基于 API 供应商的阶段，以及右侧基于 API 使用者的阶段：
红帽目前支持 API 供应商周期的设计、实施、部署和管理阶段以及 API 消费者周期的所有阶段。
6.1.1. API 供应商周期
API 提供程序周期阶段基于指定、开发和部署 API。下文描述了每个阶段的目标和结果：
表 6.1. API 供应商生命周期阶段
| Stage | 目标 | 结果 |
|---|---|---|
| 1.策略 | 确定 API 的公司战略，包括目标、资源、目标市场、时间线和制定计划。 | 制定企业战略的清晰计划以实现目标。 |
| 2.设计 | 提前创建 API 合同，以中断项目之间的依赖关系、收集反馈并缩短风险和上市时间（例如，使用 Apicurio Studio）。 | 以使用者为中心的 API 合同定义可通过 API 交换的消息。API 用户提供了反馈。 |
| 3.Mock | 进一步指定使用真实示例和载荷的 API 合同，供 API 用户用来开始实施。 | 模拟 API 是实时的，返回真实示例。API 合同附带示例。 |
| 4.测试 | 进一步指定具有可用于测试所开发的 API API 的业务预期的 API 合同。 | 创建一组验收测试。API 文档已根据业务预期完成。 |
| 5.实施 | 使用红帽 Fuse 或您选择的开发语言等集成框架实施 API。确保实施与 API 合同匹配。 | API 已被实施。如果需要自定义 API 管理功能，还会开发 3scale APIcast 策略。 |
| 6.deploy | 使用带有 3scale toolbox 的 CI/CD 管道自动执行 API 集成、测试、部署和管理。 | CI/CD 管道以自动化方式集成、测试、部署和管理 API 到生产环境。 |
| 7.安全 | 确保 API 的安全（例如，使用安全开发实践和自动安全测试）。 | 制定安全指南、流程和门。 |
| 8.管理 | 大规模管理环境、版本控制、弃用和停用之间的 API 提升。 | 进程和工具已经到位，可以大规模管理 API（例如，语义版本控制以防止破坏对 API 的更改）。 |
6.1.2. API 使用者周期
API 消费者周期阶段基于提升、分发和调整 API 以供使用。下文描述了每个阶段的目标和结果：
表 6.2. API 消费者生命周期阶段
| Stage | 目标 | 结果 |
|---|---|---|
| 9.发现 | 将 API 提升给第三方开发人员、合作伙伴和内部用户。 | 开发人员门户是实时的，最新的文档会持续推送到此开发人员门户（例如，使用 3scale ActiveDocs）。 |
| 10.Development | 指导并允许第三方开发人员、合作伙伴和内部用户基于 API 开发应用程序。 | 开发人员门户包括最佳实践、指南和建议。API 开发人员有权访问模拟和测试端点来开发他们的软件。 |
| 11.使用 | 大规模处理不断增加的 API 用户并管理 API 使用者。 | 分阶段的应用计划可供消费，并持续推动最新的价格和限制。API 用户可以从 CI/CD 管道集成 API 密钥或客户端 ID/secret 生成。 |
| 12.monitor | 收集有关 API 健康、质量和开发人员参与情况（例如，时间到第一个 Hello World！）的指标。 | 建立了监控系统。仪表板显示 API 的 KPI（例如，正常运行时间、每分钟请求数、延迟等）。 |
| 13.monetize | 按规模驱动新的地区（此阶段是可选的）。 | 例如，针对大量小型 API 用户时，启用货币化，并且用户按照使用情况自动计费。 |
6.2. 部署示例 Jenkins CI/CD 管道
使用 3scale toolbox 的 API 生命周期自动化侧重于 API 生命周期的部署阶段，并可让您使用 CI/CD 管道来自动化 API 管理解决方案。本节介绍如何部署调用 3scale toolbox 的示例 Jenkins 管道：
6.2.1. Jenkins CI/CD 管道示例
以下示例在 Red Hat Integration 存储库中提供，作为如何为 API 生命周期自动化创建和部署 Jenkins 管道的示例：
表 6.3. Jenkins 共享库管道示例
| 管道示例 | 目标环境 | 安全性 |
|---|---|---|
| 3scale Hosted | API 密钥 | |
| 3scale 托管和 3scale 内部部署，APIcast 自我管理 | 无 | |
| 3scale 托管和 3scale 内部部署，APIcast 自我管理 | OpenID Connect(OIDC) | |
| 3scale 在开发、测试和生产上托管，APIcast 自我管理 | API 密钥 | |
| 3scale 在开发、测试和生产上托管，APIcast 自我管理 | API 密钥、无、OIDC |
这些示例使用 3scale Jenkins 共享库调用 3scale toolbox 来演示关键 API 管理功能。执行本主题中的设置步骤后，您可以使用 红帽集成存储库中为各个示例用例 提供的 OpenShift 模板来安装管道。
示例管道和应用程序仅作为示例提供。红帽完全支持底层 API、CLI 和其他示例管道利用的接口。您对管道所做的任何修改都不受红帽直接支持。
6.2.2. 设置 3scale Hosted 环境
所有 Jenkins CI/CD 管道示例都需要设置 3scale Hosted 环境。
SaaS - API 键、多环境和 Semantic 版本管道 仅使用 3scale Hosted。混合 - 开放 和混合 - OIDC 管道也使用 3scale 内部部署。另 请参阅设置 3scale 内部环境。
先决条件
- 您必须有一个 Linux 工作站。
- 您必须有一个 3scale 托管环境。
您必须有一个 OpenShift 3.11 集群。OpenShift 4 目前不受支持。
- 有关支持配置的更多信息，请参阅 Red Hat 3scale API 管理支持的配置 页面。
- 如 OpenShift 文档 中所述，确保 OpenShift 路由器上已启用了通配符路由。
步骤
- 登录您的 3scale 托管管理门户控制台。
- 生成对帐户管理 API 具有写入访问权限的新访问令牌。
保存生成的访问令牌以供以后使用。例如：
export SAAS_ACCESS_TOKEN=123...456
保存 3scale 租户的名称，以备以后使用。这是管理门户 URL 中
-admin.3scale.net前面的字符串。例如：export SAAS_TENANT=my_username
- 导航到管理门户 中的 Audience > Accounts > Listing。
- 单击 Developer。
保存 开发人员帐户 ID。这是
/buyers/accounts/后 URL 的最后一部分。例如：export SAAS_DEVELOPER_ACCOUNT_ID=123...456
6.2.3. 设置 3scale 内部环境
混合 - 开放和混合 - OIDC 示例 Jenkins CI/CD 管道只需要设置 3scale 内部环境。
如果要使用这些 混合 示例管道，您必须设置 3scale 内部部署环境和 3scale 托管环境。另请参阅 设置 3scale 托管环境。
先决条件
- 您必须有一个 Linux 工作站。
- 您必须有一个 3scale 内部环境。有关使用 OpenShift 中的模板安装 3scale 内部的详情，请参阅 3scale 安装文档。
您必须有一个 OpenShift 3.11 集群。OpenShift 4 目前不受支持。
- 有关支持配置的更多信息，请参阅 Red Hat 3scale API 管理支持的配置 页面。
- 如 OpenShift 文档 中所述，确保 OpenShift 路由器上已启用了通配符路由。
步骤
- 登录您的 3scale 内部管理门户控制台。
- 生成对帐户管理 API 具有写入访问权限的新访问令牌。
保存生成的访问令牌以供以后使用。例如：
export SAAS_ACCESS_TOKEN=123...456
保存 3scale 租户名称以供以后使用：
export ONPREM_ADMIN_PORTAL_HOSTNAME="$(oc get route system-provider-admin -o jsonpath='{.spec.host}')"定义通配符路由：
export OPENSHIFT_ROUTER_SUFFIX=app.openshift.test # Replace me! export APICAST_ONPREM_STAGING_WILDCARD_DOMAIN=onprem-staging.$OPENSHIFT_ROUTER_SUFFIX export APICAST_ONPREM_PRODUCTION_WILDCARD_DOMAIN=onprem-production.$OPENSHIFT_ROUTER_SUFFIX
注意您必须将
OPENSHIFT_ROUTER_SUFFIX的值设置为 OpenShift 路由器的后缀（如app.openshift.test）。将通配符路由添加到现有的 3scale 内部实例中：
oc create route edge apicast-wildcard-staging --service=apicast-staging --hostname="wildcard.$APICAST_ONPREM_STAGING_WILDCARD_DOMAIN" --insecure-policy=Allow --wildcard-policy=Subdomain oc create route edge apicast-wildcard-production --service=apicast-production --hostname="wildcard.$APICAST_ONPREM_PRODUCTION_WILDCARD_DOMAIN" --insecure-policy=Allow --wildcard-policy=Subdomain
- 导航到管理门户 中的 Audience > Accounts > Listing。
- 单击 Developer。
保存 开发人员帐户 ID。这是
/buyers/accounts/后 URL 的最后一部分：export ONPREM_DEVELOPER_ACCOUNT_ID=5
6.2.4. 为 OpenID Connect 部署红帽单点登录
如果您使用 混合 - OpenID Connect(OIDC) 或 Semantic 版本示例 管道，请执行本节中的步骤以使用 3scale 部署红帽单点登录(RH-SSO)。这是 OIDC 身份验证所需要的，在两个样本中使用。
步骤
按照 RH-SSO 文档中所述，部署 RH-SSO 7.3。
以下示例命令提供了一个简短概述：
oc replace -n openshift --force -f https://raw.githubusercontent.com/jboss-container-images/redhat-sso-7-openshift-image/sso73-dev/templates/sso73-image-stream.json oc replace -n openshift --force -f https://raw.githubusercontent.com/jboss-container-images/redhat-sso-7-openshift-image/sso73-dev/templates/sso73-x509-postgresql-persistent.json oc -n openshift import-image redhat-sso73-openshift:1.0 oc policy add-role-to-user view system:serviceaccount:$(oc project -q):default oc new-app --template=sso73-x509-postgresql-persistent --name=sso -p DB_USERNAME=sso -p SSO_ADMIN_USERNAME=admin -p DB_DATABASE=sso
保存 RH-SSO 安装的主机名，以便稍后使用：
export SSO_HOSTNAME="$(oc get route sso -o jsonpath='{.spec.host}')"- 按照 3scale 开发人员门户文档中所述，为 3scale 配置 RH-SSO。
保存 realm 名称、客户端 ID 和客户端 secret 以供以后使用：
export REALM=3scale export CLIENT_ID=3scale-admin export CLIENT_SECRET=123...456
6.2.5. 安装 3scale toolbox 并启用访问
本节论述了如何安装 toolbox、创建远程 3scale 实例，以及置备用于访问管理门户的 secret。
步骤
- 如 3scale toolbox 中所述，在本地安装 3scale toolbox。
运行适当的 toolbox 命令创建 3scale 远程实例：
3scale Hosted
3scale remote add 3scale-saas "https://$SAAS_ACCESS_TOKEN@$SAAS_TENANT-admin.3scale.net/"
3scale On-premises
3scale remote add 3scale-onprem "https://$ONPREM_ACCESS_TOKEN@$ONPREM_ADMIN_PORTAL_HOSTNAME/"
运行以下命令来置备包含 3scale 管理门户和访问令牌的 secret：
oc create secret generic 3scale-toolbox -n "$TOOLBOX_NAMESPACE" --from-file="$HOME/.3scalerc.yaml"
6.2.6. 部署 API 后端
本节介绍如何部署示例管道提供的示例 API 后端。在创建和部署自己的管道时，您可以根据需要替换您自己的 API 后端
步骤
部署示例 Beer Catalog API 后端，以便与以下示例搭配使用：
-
SaaS - API 密钥 -
混合 - 开放 混合 - OIDCoc new-app -n "$TOOLBOX_NAMESPACE" -i openshift/redhat-openjdk18-openshift:1.4 https://github.com/microcks/api-lifecycle.git --context-dir=/beer-catalog-demo/api-implementation --name=beer-catalog oc expose -n "$TOOLBOX_NAMESPACE" svc/beer-catalog
-
保存 Beer Catalog API 主机名以供以后使用：
export BEER_CATALOG_HOSTNAME="$(oc get route -n "$TOOLBOX_NAMESPACE" beer-catalog -o jsonpath='{.spec.host}')"部署示例 Red Hat Event API 后端，以便与以下示例搭配使用：
-
多环境 语义版本oc new-app -n "$TOOLBOX_NAMESPACE" -i openshift/nodejs:10 'https://github.com/nmasse-itix/rhte-api.git#085b015' --name=event-api oc expose -n "$TOOLBOX_NAMESPACE" svc/event-api
-
保存 Event API 主机名供以后使用：
export EVENT_API_HOSTNAME="$(oc get route -n "$TOOLBOX_NAMESPACE" event-api -o jsonpath='{.spec.host}')"
6.2.7. 部署自我管理的 APIcast 实例
本节用于 3scale 托管环境中的 APIcast 自我管理实例。它应用到除 SaaS - API 密钥 以外的所有示例管道。
步骤
定义通配符路由：
export APICAST_SELF_MANAGED_STAGING_WILDCARD_DOMAIN=saas-staging.$OPENSHIFT_ROUTER_SUFFIX export APICAST_SELF_MANAGED_PRODUCTION_WILDCARD_DOMAIN=saas-production.$OPENSHIFT_ROUTER_SUFFIX
在项目中部署 APIcast 自我管理实例：
oc create secret generic 3scale-tenant --from-literal=password=https://$SAAS_ACCESS_TOKEN@$SAAS_TENANT-admin.3scale.net oc create -f https://raw.githubusercontent.com/3scale/apicast/v3.5.0/openshift/apicast-template.yml oc new-app --template=3scale-gateway --name=apicast-staging -p CONFIGURATION_URL_SECRET=3scale-tenant -p CONFIGURATION_CACHE=0 -p RESPONSE_CODES=true -p LOG_LEVEL=info -p CONFIGURATION_LOADER=lazy -p APICAST_NAME=apicast-staging -p DEPLOYMENT_ENVIRONMENT=sandbox -p IMAGE_NAME=registry.redhat.io/3scale-amp2/apicast-gateway-rhel8:3scale2.10 oc new-app --template=3scale-gateway --name=apicast-production -p CONFIGURATION_URL_SECRET=3scale-tenant -p CONFIGURATION_CACHE=60 -p RESPONSE_CODES=true -p LOG_LEVEL=info -p CONFIGURATION_LOADER=boot -p APICAST_NAME=apicast-production -p DEPLOYMENT_ENVIRONMENT=production -p IMAGE_NAME=registry.redhat.io/3scale-amp2/apicast-gateway-rhel8:3scale2.10 oc scale dc/apicast-staging --replicas=1 oc scale dc/apicast-production --replicas=1 oc create route edge apicast-staging --service=apicast-staging --hostname="wildcard.$APICAST_SELF_MANAGED_STAGING_WILDCARD_DOMAIN" --insecure-policy=Allow --wildcard-policy=Subdomain oc create route edge apicast-production --service=apicast-production --hostname="wildcard.$APICAST_SELF_MANAGED_PRODUCTION_WILDCARD_DOMAIN" --insecure-policy=Allow --wildcard-policy=Subdomain
6.2.8. 安装和部署示例管道
设置所需的环境后，您可以使用 红帽集成存储库中为各个示例用例提供的 OpenShift 模板来安装和部署示例 管道。例如，本节仅显示 SaaS - API 密钥 示例。
步骤
使用提供的 OpenShift 模板安装 Jenkins 管道：
oc process -f saas-usecase-apikey/setup.yaml \ -p DEVELOPER_ACCOUNT_ID="$SAAS_DEVELOPER_ACCOUNT_ID" \ -p PRIVATE_BASE_URL="http://$BEER_CATALOG_HOSTNAME" \ -p NAMESPACE="$TOOLBOX_NAMESPACE" |oc create -f -按如下方式部署示例：
oc start-build saas-usecase-apikey
6.2.9. 3scale toolbox 的 API 生命周期自动化的限制
这个版本有以下限制：
- OpenShift 支持
- OpenShift 3.11 仅支持示例管道。OpenShift 4 目前不受支持。有关支持配置的更多信息，请参阅 Red Hat 3scale API 管理支持的配置 页面。
- 更新应用程序
-
您可以将
3scale 应用程序应用toolbox 命令用于创建和更新应用程序。创建命令支持帐户、计划、服务和应用程序键。 - 更新命令不支持对帐户、计划或服务的更改。如果传递了更改，则会触发管道，不会显示任何错误，但不会更新这些字段。
-
您可以将
- 复制服务
-
当使用
3scale copy servicetoolbox 命令复制带有自定义策略的服务时，您必须首先单独复制自定义策略。
6.3. 使用 3scale Jenkins 共享库创建管道
本节提供创建使用 3scale toolbox 的自定义 Jenkins 管道的最佳实践。它解释了如何在 Groovy 中编写 Jenkins 管道，该管道使用 3scale Jenkins 共享库根据示例应用程序调用 toolbox。如需了解更多详细信息，请参阅 Jenkins 共享库。
红帽支持红帽集成存储库中提供的 Jenkins 管道示例。
对这些管道所做的任何修改都不受红帽直接支持。不支持您为环境创建的自定义管道。
先决条件
- 部署示例 Jenkins CI/CD 管道.
- 您的 API 必须具有 OpenAPI 规格文件。例如，您可以使用 Apicurio Studio 生成此操作。
步骤
将以下内容添加到 Jenkins 管道的开头，以引用管道的 3scale 共享库：
#!groovy library identifier: '3scale-toolbox-jenkins@master', retriever: modernSCM([$class: 'GitSCMSource', remote: 'https://github.com/rh-integration/3scale-toolbox-jenkins.git'])声明一个全局变量来存放
三个scaleService对象，以便您可以在管道的不同阶段使用它。def service = null
使用所有相关信息创建
ThreescaleService：stage("Prepare") { service = toolbox.prepareThreescaleService( openapi: [ filename: "swagger.json" ], environment: [ baseSystemName: "my_service" ], toolbox: [ openshiftProject: "toolbox", destination: "3scale-tenant", secretName: "3scale-toolbox" ], service: [:], applications: [ [ name: "my-test-app", description: "This is used for tests", plan: "test", account: "<CHANGE_ME>" ] ], applicationPlans: [ [ systemName: "test", name: "Test", defaultPlan: true, published: true ], [ systemName: "silver", name: "Silver" ], [ artefactFile: "https://raw.githubusercontent.com/my_username/API-Lifecycle-Mockup/master/testcase-01/plan.yaml"], ] ) echo "toolbox version = " + service.toolbox.getToolboxVersion() }-
OpenAPI.filename是包含 OpenAPI 规范的文件的路径。 -
environment.baseSystemName用于根据 OpenAPI 规格info.version中的 environment.environmentName和 API 主要版本计算最终system_name。 -
toolbox.openshiftProject是创建 Kubernetes 作业的 OpenShift 项目。 -
toolbox.secretName是包含 3scale toolbox 配置文件的 Kubernetes secret 的名称，如 安装 3scale toolbox 并启用访问权限 所示。 -
toolbox.destination是 3scale toolbox 远程实例的名称。 -
applicationPlans是使用 a.yaml文件或提供应用程序计划属性详情创建的应用程序计划列表。
-
添加一个管道阶段来在 3scale 中置备服务：
stage("Import OpenAPI") { service.importOpenAPI() echo "Service with system_name ${service.environment.targetSystemName} created !" }添加一个阶段来创建应用程序计划：
stage("Create an Application Plan") { service.applyApplicationPlans() }添加全局变量和阶段来创建测试应用程序：
stage("Create an Application") { service.applyApplication() }添加阶段来运行集成测试。使用 APIcast Hosted 实例时，您必须获取代理定义来提取暂存公共 URL：
stage("Run integration tests") { def proxy = service.readProxy("sandbox") sh """set -e +x curl -f -w "ListBeers: %{http_code}\n" -o /dev/null -s ${proxy.sandbox_endpoint}/api/beer -H 'api-key: ${service.applications[0].userkey}' curl -f -w "GetBeer: %{http_code}\n" -o /dev/null -s ${proxy.sandbox_endpoint}/api/beer/Weissbier -H 'api-key: ${service.applications[0].userkey}' curl -f -w "FindBeersByStatus: %{http_code}\n" -o /dev/null -s ${proxy.sandbox_endpoint}/api/beer/findByStatus/ available -H 'api-key: ${service.applications[0].userkey}' """ }添加一个阶段来将 API 提升到生产环境：
stage("Promote to production") { service.promoteToProduction() }
6.4. 使用 Jenkinsfile 创建管道
本节提供在使用 3scale toolbox 的 Groovy 中从头开始编写自定义 Jenkinsfile 的最佳实践。
红帽支持红帽集成存储库中提供的 Jenkins 管道示例。
对这些管道所做的任何修改都不受红帽直接支持。不支持您为环境创建的自定义管道。本节仅供参考。
先决条件
- 部署示例 Jenkins CI/CD 管道.
- 您的 API 必须具有 OpenAPI 规格文件。例如，您可以使用 Apicurio Studio 生成此操作。
步骤
编写一个工具函数来调用 3scale toolbox。下面创建一个运行 3scale toolbox 的 Kubernetes 作业：
#!groovy def runToolbox(args) { def kubernetesJob = [ "apiVersion": "batch/v1", "kind": "Job", "metadata": [ "name": "toolbox" ], "spec": [ "backoffLimit": 0, "activeDeadlineSeconds": 300, "template": [ "spec": [ "restartPolicy": "Never", "containers": [ [ "name": "job", "image": "registry.redhat.io/3scale-amp2/toolbox-rhel7:3scale2.10", "imagePullPolicy": "Always", "args": [ "3scale", "version" ], "env": [ [ "name": "HOME", "value": "/config" ] ], "volumeMounts": [ [ "mountPath": "/config", "name": "toolbox-config" ], [ "mountPath": "/artifacts", "name": "artifacts" ] ] ] ], "volumes": [ [ "name": "toolbox-config", "secret": [ "secretName": "3scale-toolbox" ] ], [ "name": "artifacts", "configMap": [ "name": "openapi" ] ] ] ] ] ] ] kubernetesJob.spec.template.spec.containers[0].args = args sh "rm -f -- job.yaml" writeYaml file: "job.yaml", data: kubernetesJob sh """set -e oc delete job toolbox --ignore-not-found sleep 2 oc create -f job.yaml sleep 20 # Adjust the sleep duration to your server velocity """ def logs = sh(script: "set -e; oc logs -f job/toolbox", returnStdout: true) echo logs return logs }Kubernetes 对象模板
此功能使用 Kubernetes 对象模板来运行 3scale toolbox，您可以根据您的需要进行调整。它设置 3scale toolbox CLI 参数，并将生成的 Kubernetes 作业定义写入 YAML 文件，清理之前运行 toolbox，创建 Kubernetes 作业并等待：
-
您可以将等待持续时间调整到服务器速度，以匹配 Pod
在 Created和Running 状态之间过渡所需的时间。您可以使用轮询循环来优化此步骤。 -
OpenAPI 规格文件从名为
openapi 的。ConfigMap获取 -
3scale 管理门户主机名和访问令牌是从名为
3scale-toolbox的 secret 获取的，如 安装 3scale toolbox 并启用访问权限 所示。 -
ConfigMap将由管道在第 3 步中创建。但是，该 secret 已在管道外部置备，并受基于角色的访问控制(RBAC)的约束，以提高安全性。
-
您可以将等待持续时间调整到服务器速度，以匹配 Pod
在 Jenkins 管道阶段定义要用于 3scale toolbox 的全局环境变量。例如：
3scale Hosted
def targetSystemName = "saas-apikey-usecase" def targetInstance = "3scale-saas" def privateBaseURL = "http://echo-api.3scale.net" def testUserKey = "abcdef1234567890" def developerAccountId = "john"
3scale On-premises
使用自我管理的 APIcast 或 3scale 内部安装时，您必须再声明两个变量：
def publicStagingBaseURL = "http://my-staging-api.example.test" def publicProductionBaseURL = "http://my-production-api.example.test"
这些变量如下所述：
-
targetSystemName:要创建的服务的名称。 -
targetInstance:这与 安装 3scale toolbox 并启用访问权限时创建的 3scale 远程实例的名称匹配。 -
privateBaseURL:API 后端的端点主机。 -
testUserKey:用于运行集成测试的用户 API 密钥。可以像所示一样硬编码，或者从 HMAC 功能生成。 -
DeveloperAccountId：在其中创建测试应用的目标帐户的 ID。 -
publicStagingBaseURL:要创建的服务的公共暂存基础 URL。 -
publicProductionBaseURL:要创建的服务的公共生产基础 URL。
-
添加 pipeline 阶段来获取 OpenAPI 规格文件，并将它作为
ConfigMap在 OpenShift 中置备，如下所示：node() { stage("Fetch OpenAPI") { sh """set -e curl -sfk -o swagger.json https://raw.githubusercontent.com/microcks/api-lifecycle/master/beer-catalog-demo/api-contracts/beer-catalog-api-swagger.json oc delete configmap openapi --ignore-not-found oc create configmap openapi --from-file="swagger.json" """ }添加一个使用 3scale toolbox 将 API 导入到 3scale 的管道阶段：
3scale Hosted
stage("Import OpenAPI") { runToolbox([ "3scale", "import", "openapi", "-d", targetInstance, "/artifacts/swagger.json", "--override-private-base-url=${privateBaseURL}", "-t", targetSystemName ]) }3scale On-premises
使用自我管理的 APIcast 或 3scale 内部安装时，还必须指定公共暂存和生产基本 URL 的选项：
stage("Import OpenAPI") { runToolbox([ "3scale", "import", "openapi", "-d", targetInstance, "/artifacts/swagger.json", "--override-private-base-url=${privateBaseURL}", "-t", targetSystemName, "--production-public-base-url=${publicProductionBaseURL}", "--staging-public-base-url=${publicStagingBaseURL}" ]) }添加使用 toolbox 创建 3scale 应用程序计划和应用程序的管道阶段：
stage("Create an Application Plan") { runToolbox([ "3scale", "application-plan", "apply", targetInstance, targetSystemName, "test", "-n", "Test Plan", "--default" ]) } stage("Create an Application") { runToolbox([ "3scale", "application", "apply", targetInstance, testUserKey, "--account=${developerAccountId}", "--name=Test Application", "--description=Created by Jenkins", "--plan=test", "--service=${targetSystemName}" ]) }stage("Run integration tests") { def proxyDefinition = runToolbox([ "3scale", "proxy", "show", targetInstance, targetSystemName, "sandbox" ]) def proxy = readJSON text: proxyDefinition proxy = proxy.content.proxy sh """set -e echo "Public Staging Base URL is ${proxy.sandbox_endpoint}" echo "userkey is ${testUserKey}" curl -vfk ${proxy.sandbox_endpoint}/beer -H 'api-key: ${testUserKey}' curl -vfk ${proxy.sandbox_endpoint}/beer/Weissbier -H 'api-key: ${testUserKey}' curl -vfk ${proxy.sandbox_endpoint}/beer/findByStatus/available -H 'api-key: ${testUserKey}' """ }添加使用 toolbox 将 API 提升到您的生产环境的阶段。
stage("Promote to production") { runToolbox([ "3scale", "proxy", "promote", targetInstance, targetSystemName ]) }
第 7 章 通过操作器配置和提供 3scale
本文档包含有关功能 3scale 操作器的信息，其中包括通过 OpenShift Container Platform(OCP)用户界面通过 3scale 操作器置备 3scale 服务和配置。
当使用 3scale 操作器在 3scale 中更新 API 配置时，自定义资源定义(CRD)是事实的来源。如果在 Admin 用户界面中进行更改，它们不会持久存在，最终会被 CRD 中的定义覆盖。
3scale 的功能操作器只是一个技术预览功能。技术预览功能不受红帽产品服务等级协议（SLA）支持，且功能可能并不完整。红帽不推荐在生产环境中使用它们。这些技术预览功能可以使用户提早试用新的功能，并有机会在开发阶段提供反馈意见。有关红帽技术预览功能支持范围的更多信息，请参阅技术预览功能支持范围。
本章包含有关操作器应用程序功能如何工作的详细信息，以及部署以下步骤：
- 您的第一个 3scale 产品和后端.
- 与功能相关的后端自定义资源。
- 与功能相关的产品自定义资源。
- 租户自定义资源。
另外，您还可以通过 3scale 操作器查找有关功能限制的信息。
7.1. 一般先决条件
对于 Operator 的配置和置备 3scale，这是所需的元素：
- 具有 3scale 2.10 On-Premises 实例管理员特权的用户帐户。
- 安装了 3scale 操作器。
OpenShift Container Platform 4，具有在 OpenShift 集群中具有管理员特权的用户帐户。
- 备注：OCP 4 支持仅使用操作器部署 3scale。
- 有关支持配置的更多信息，请参阅 Red Hat 3scale API 管理支持的配置 页面。
7.2. 通过 3scale 操作器的应用程序功能
3scale 操作器包含这些特性：
- 允许与红帽 3scale API 管理解决方案交互。
- 使用 OpenShift 中的自定义资源，以声明方式管理 3scale 应用。
下图显示了 3scale 实体和关系，它们有资格以声明性方式使用 OpenShift 自定义资源进行管理。产品包含一个或多个后端。在产品层面上，您可以配置应用程序、应用程序计划以及映射规则。在后端，您可以为每个后端设置指标、方法和映射规则。
3scale 操作器提供自定义资源定义及其关系，如下图中所示。
7.3. 部署第一个 3scale 产品和后端
在新创建的租户中使用 Openshift Container Platform，您将以最低的配置部署第一个 3scale 产品和后端。
先决条件
常规先决条件 中列出的安装要求与以下事项相同：
- 3scale 帐户可以在正常工作的 OpenShift 命名空间或远程安装中是本地的。
- 此帐户中所需的参数是 3scale Admin URL 地址和访问令牌。
步骤
使用 3scale 管理门户中的凭据，为 3scale 提供程序帐户创建一个机密。例如：
adminURL=https://3scale-admin.example.com和token=123456。oc create secret generic threescale-provider-account --from-literal=adminURL=https://3scale-admin.example.com --from-literal=token=123456
使用上游 API URL 配置 3scale 后端：
使用以下内容创建 YAML 文件：
apiVersion: capabilities.3scale.net/v1beta1 kind: Backend metadata: name: backend1 spec: name: "Operated Backend 1" systemName: "backend1" privateBaseURL: "https://api.example.com"
- 创建该文件后，操作员将确认步骤是否成功。
- 有关 Backend 自定义资源字段和可能值的详情，请参阅 后端 CRD 引用。
创建自定义资源：
oc create -f backend1.yaml
配置 3scale 产品：
使用应用到之前创建的后端的所有默认设置创建产品：
apiVersion: capabilities.3scale.net/v1beta1 kind: Product metadata: name: product1 spec: name: "OperatedProduct 1" systemName: "operatedproduct1" backendUsages: backend1: path: /- 创建该文件后，操作员将确认步骤是否成功。
- 有关产品自定义资源字段和可能值的详情，请参阅 产品 CRD 参考。
创建自定义资源：
oc create -f product1.yaml
创建的自定义资源将需要几秒钟时间来填充 3scale 实例。要确认何时同步资源，您可以选择以下方法之一：
- 验证对象的 status 字段。
使用
oc wait命令：oc wait --for=condition=Synced --timeout=-1s backend/backend1 oc wait --for=condition=Synced --timeout=-1s product/product1
7.6. 部署租户自定义资源
租户自定义资源也称为 Provider 帐户。
创建 APIManager 自定义资源表示要部署 3scale 的 Operator。默认 3scale 安装包括可供使用的默认租户。另外，您可以创建其他租户创建租户自定义资源对象。
先决条件
要在 3scale 实例中部署新租户，您需要一些准备步骤：
获取或创建 3scale master 凭证 secret：MASTER_SECRET
您只能使用 3scale master 帐户凭据（最好是访问令牌）来执行租户管理任务。您有以下选项：
-
如果租户资源是在与 3scale 相同的命名空间中创建的，则具有 master 帐户凭证的机密已创建好，它称为
system-seed。 如果没有在与 3scale 相同的命名空间中创建租户资源，请使用 master 帐户凭证创建一个 secret。在此命令中，机密的名称为可选。secret 名称将在租户自定义资源中使用：
oc create secret generic system-seed --from-literal=MASTER_ACCESS_TOKEN=<master access token>
-
如果租户资源是在与 3scale 相同的命名空间中创建的，则具有 master 帐户凭证的机密已创建好，它称为
创建新 secret 以存储新租户的 admin 帐户的密码：ADMIN_SECRET.在此命令中，机密的名称为可选。机密名称将在租户自定义资源中使用。
oc create secret generic ecorp-admin-secret --from-literal=admin_password=<admin password value>
获取 3scale master 帐户主机名：MASTER_HOSTNAME.当您使用操作器部署 3scale 时，master 帐户具有具有此模式的固定 URL：
master.${wildcardDomain}如果您可以访问安装 3scale 的命名空间，获得 master 帐户主机名：
oc get routes --field-selector=spec.to.name==system-master -o jsonpath="{.items[].spec.host}"
步骤
部署新的租户自定义资源：
apiVersion: capabilities.3scale.net/v1alpha1 kind: Tenant metadata: name: ecorp-tenant spec: username: admin systemMasterUrl: https://<MASTER_HOSTNAME> email: admin@ecorp.com organizationName: ECorp masterCredentialsRef: name: <MASTER_SECRET> passwordCredentialsRef: name: <ADMIN_SECRET*> tenantSecretRef: name: tenant-secret创建租户资源：
oc create -f <yaml-name>
- 此命令会在 3scale 解决方案中触发新租户的创建。
- 3scale 操作器将创建新机密，并将新租户凭据存储在机密中。
-
新租户
provider_key和admin 域 url将存储在机密中。 -
可以使用
tenantSecretRef租户规格键指定 secret 位置。
作为参考，这是创建的 secret 内容示例：
apiVersion: v1 kind: Secret metadata: name: tenant-secret type: Opaque stringData: adminURL: https://my3scale-admin.example.com:443 token: "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
有关租户自定义资源字段和可能值的详情，请参阅 Tenant CRD 参考。
7.7. 3scale 操作器的能力限制
在 Red Hat 3scale API Management 2.10 中，3scale Operator 带有以下功能限制：
- 无法协调后端自定义资源定义(CRD)：3scale 中的现有后端不会被删除。
- 不协调删除产品 CRD：3scale 中的现有产品不会被删除。
- 产品 CRD 不支持对管理和开发人员门户进行单点登录(SSO)身份验证。
- 产品 CRD 不支持 OpenID Connect 身份验证。
- ActiveDocs CRD 当前不可用。
- 网关策略 CRD 目前不可用。
- 产品 CRD 网关不支持响应自定义代码和错误
- 3scale 拥有 OAS3 的 operator CRD 不作为 3scale 产品配置的真实来源引用。
7.8. 其他资源
如需更多信息，请查看以下指南：
第 8 章 3scale 备份和恢复
本节为您提供了作为 Red Hat 3scale API 管理安装的管理员所需的信息：
- 为持久数据设置备份程序。
- 从持久数据的备份中执行恢复。
如果一个或多个 MySQL 数据库出现问题，您可以将 3scale 正确恢复到之前的操作状态。
8.1. 先决条件
- 3scale 2.10 实例.有关如何安装 3scale 的更多信息，请参阅在 OpenShift 上安装 3scale。
- jq:用于提取或转换 JSON 数据。
OpenShift Container Platform 4.x 用户帐户，在 OpenShift 集群中具有以下角色之一：
- cluster-admin
- admin
- 编辑
在 3scale 安装的命名空间中本地绑定了 edit 集群角色 的用户，可以执行备份和恢复过程。
以下小节包含有关持久性卷的信息，使用数据集、为持久数据设置备份程序，以及恢复系统数据库和 OpenShift secret：
8.2. 持久性卷和注意事项
持久性卷（PV）
- 由底层基础架构向集群提供的持久性卷(PV)。
- 集群外部的存储服务.这可以位于同一数据中心或其它位置。
注意事项
持久数据的备份和恢复过程因使用的存储类型而异。为确保备份和恢复保留数据一致性，仅备份数据库基础 PV 是不够的。例如，请勿只捕获部分写入和部分事务。改为使用数据库的备份机制。
数据的某些部分在不同的组件之间同步。个副本被视为数据集 的真实来源。另一个是不在本地修改的副本，但从 事实来源 同步。在这些情况下，在完成时，应恢复数据源，并从它同步的其他组件中复制。
8.3. 使用数据集
本节更详细地说明了不同持久存储中不同数据集、其用途、使用的存储类型，以及是否是 数据源。
3scale 部署的完整状态存储在以下 DeploymentConfig 对象及其 PV 中：
| Name | 描述 |
|---|---|
|
MySQL 数据库( | |
| 文件的卷 | |
|
redis 数据库( | |
|
redis 数据库( |
8.3.1. 定义 system-mysql
system-mysql 是一个关系数据库，存储在 3scale 管理控制台中有关用户、帐户、API、计划等的信息。
与服务相关的信息子集已同步到 后端 组件，存储在 backend-redis。system-mysql 是此信息 的真实来源。
8.3.2. 定义 system-storage
可以通过上传和读取所述静态文件的多个 pod 来水平扩展 系统，因此对 ReadWriteMany(RWX) PersistentVolume的需求
system-storage 存储要由 系统 组件读取和写入的文件。
它们分为两个类别：
-
系统组件运行时读取的配置文件 - 静态文件，如 HTML、CSS、JS，通过其 CMS 功能上传到系统，以便创建开发人员门户
可通过上传和读取上述静态文件来水平扩展 系统，因此对 ReadWriteMany(RWX) PersistentVolume 的需求。
8.3.3. 定义 backend-redis
backend-redis 包含由 后端 组件使用的多个数据集：
-
使用方法：这是
后端聚合的 API使用量信息。后端用于速率限制决策，系统则用于在 UI 或 API 中显示分析信息。 -
config ：这是关于服务、速率限制等的配置信息，它们通过内部 API 从
系统同步。这不是此信息 的真实来源，但系统和 system-mysql是. - 队列：这是由 worker 进程执行的后台作业队列。这些是临时的，会在处理后删除。
8.3.4. 定义 system-redis
system-redis 包含在后台处理作业的队列。这些是临时的，会在处理后删除。
8.4. 备份系统数据库
以下命令不按特定顺序运行，您可以根据需要使用这些命令来备份和归档系统数据库。
8.4.1. 备份 system-mysql
执行 MySQL 备份命令：
oc rsh $(oc get pods -l 'deploymentConfig=system-mysql' -o json | jq -r '.items[0].metadata.name') bash -c 'export MYSQL_PWD=${MYSQL_ROOT_PASSWORD}; mysqldump --single-transaction -hsystem-mysql -uroot system' | gzip > system-mysql-backup.gz8.4.2. 备份 system-storage
将 system-storage 文件归档到另一个存储中：
oc rsync $(oc get pods -l 'deploymentConfig=system-app' -o json | jq '.items[0].metadata.name' -r):/opt/system/public/system ./local/dir
8.4.3. 备份 backend-redis
从 redis 备份 dump.rdb 文件：
oc cp $(oc get pods -l 'deploymentConfig=backend-redis' -o json | jq '.items[0].metadata.name' -r):/var/lib/redis/data/dump.rdb ./backend-redis-dump.rdb
8.4.4. 备份 system-redis
从 redis 备份 dump.rdb 文件：
oc cp $(oc get pods -l 'deploymentConfig=system-redis' -o json | jq '.items[0].metadata.name' -r):/var/lib/redis/data/dump.rdb ./system-redis-dump.rdb
8.4.5. 备份 zync-database
备份 zync_production 数据库：
oc rsh $(oc get pods -l 'deploymentConfig=zync-database' -o json | jq -r '.items[0].metadata.name') bash -c 'pg_dump zync_production' | gzip > zync-database-backup.gz
8.4.6. 备份 OpenShift secret 和 ConfigMap
以下是 OpenShift secret 和 ConfigMap 的命令列表：
8.4.6.1. OpenShift secret
oc get secrets system-smtp -o json > system-smtp.json oc get secrets system-seed -o json > system-seed.json oc get secrets system-database -o json > system-database.json oc get secrets backend-internal-api -o json > backend-internal-api.json oc get secrets system-events-hook -o json > system-events-hook.json oc get secrets system-app -o json > system-app.json oc get secrets system-recaptcha -o json > system-recaptcha.json oc get secrets system-redis -o json > system-redis.json oc get secrets zync -o json > zync.json oc get secrets system-master-apicast -o json > system-master-apicast.json
8.4.6.2. ConfigMaps
oc get configmaps system-environment -o json > system-environment.json oc get configmaps apicast-environment -o json > apicast-environment.json
8.5. 恢复系统数据库
通过缩减 pod（如 system-app 或禁用路由）来阻止记录创建。
使用以下步骤恢复 OpenShift secret 和系统数据库：
8.5.1. 恢复基于模板的部署
使用以下步骤恢复基于模板的部署。
步骤
- 在创建部署模板前恢复 secret：
oc apply -f system-smtp.json
模板参数将从复制的 secret 和 configmap 中读取：
oc new-app --file /opt/amp/templates/amp.yml \ --param APP_LABEL=$(cat system-environment.json | jq -r '.metadata.labels.app') \ --param TENANT_NAME=$(cat system-seed.json | jq -r '.data.TENANT_NAME' | base64 -d) \ --param SYSTEM_DATABASE_USER=$(cat system-database.json | jq -r '.data.DB_USER' | base64 -d) \ --param SYSTEM_DATABASE_PASSWORD=$(cat system-database.json | jq -r '.data.DB_PASSWORD' | base64 -d) \ --param SYSTEM_DATABASE=$(cat system-database.json | jq -r '.data.URL' | base64 -d | cut -d '/' -f4) \ --param SYSTEM_DATABASE_ROOT_PASSWORD=$(cat system-database.json | jq -r '.data.URL' | base64 -d | awk -F '[:@]' '{print $3}') \ --param WILDCARD_DOMAIN=$(cat system-environment.json | jq -r '.data.THREESCALE_SUPERDOMAIN') \ --param SYSTEM_BACKEND_USERNAME=$(cat backend-internal-api.json | jq '.data.username' -r | base64 -d) \ --param SYSTEM_BACKEND_PASSWORD=$(cat backend-internal-api.json | jq '.data.password' -r | base64 -d) \ --param SYSTEM_BACKEND_SHARED_SECRET=$(cat system-events-hook.json | jq -r '.data.PASSWORD' | base64 -d) \ --param SYSTEM_APP_SECRET_KEY_BASE=$(cat system-app.json | jq -r '.data.SECRET_KEY_BASE' | base64 -d) \ --param ADMIN_PASSWORD=$(cat system-seed.json | jq -r '.data.ADMIN_PASSWORD' | base64 -d) \ --param ADMIN_USERNAME=$(cat system-seed.json | jq -r '.data.ADMIN_USER' | base64 -d) \ --param ADMIN_EMAIL=$(cat system-seed.json | jq -r '.data.ADMIN_EMAIL' | base64 -d) \ --param ADMIN_ACCESS_TOKEN=$(cat system-seed.json | jq -r '.data.ADMIN_ACCESS_TOKEN' | base64 -d) \ --param MASTER_NAME=$(cat system-seed.json | jq -r '.data.MASTER_DOMAIN' | base64 -d) \ --param MASTER_USER=$(cat system-seed.json | jq -r '.data.MASTER_USER' | base64 -d) \ --param MASTER_PASSWORD=$(cat system-seed.json | jq -r '.data.MASTER_PASSWORD' | base64 -d) \ --param MASTER_ACCESS_TOKEN=$(cat system-seed.json | jq -r '.data.MASTER_ACCESS_TOKEN' | base64 -d) \ --param RECAPTCHA_PUBLIC_KEY="$(cat system-recaptcha.json | jq -r '.data.PUBLIC_KEY' | base64 -d)" \ --param RECAPTCHA_PRIVATE_KEY="$(cat system-recaptcha.json | jq -r '.data.PRIVATE_KEY' | base64 -d)" \ --param SYSTEM_REDIS_URL=$(cat system-redis.json | jq -r '.data.URL' | base64 -d) \ --param SYSTEM_MESSAGE_BUS_REDIS_URL="$(cat system-redis.json | jq -r '.data.MESSAGE_BUS_URL' | base64 -d)" \ --param SYSTEM_REDIS_NAMESPACE="$(cat system-redis.json | jq -r '.data.NAMESPACE' | base64 -d)" \ --param SYSTEM_MESSAGE_BUS_REDIS_NAMESPACE="$(cat system-redis.json | jq -r '.data.MESSAGE_BUS_NAMESPACE' | base64 -d)" \ --param ZYNC_DATABASE_PASSWORD=$(cat zync.json | jq -r '.data.ZYNC_DATABASE_PASSWORD' | base64 -d) \ --param ZYNC_SECRET_KEY_BASE=$(cat zync.json | jq -r '.data.SECRET_KEY_BASE' | base64 -d) \ --param ZYNC_AUTHENTICATION_TOKEN=$(cat zync.json | jq -r '.data.ZYNC_AUTHENTICATION_TOKEN' | base64 -d) \ --param APICAST_ACCESS_TOKEN=$(cat system-master-apicast.json | jq -r '.data.ACCESS_TOKEN' | base64 -d) \ --param APICAST_MANAGEMENT_API=$(cat apicast-environment.json | jq -r '.data.APICAST_MANAGEMENT_API') \ --param APICAST_OPENSSL_VERIFY=$(cat apicast-environment.json | jq -r '.data.OPENSSL_VERIFY') \ --param APICAST_RESPONSE_CODES=$(cat apicast-environment.json | jq -r '.data.APICAST_RESPONSE_CODES') \ --param APICAST_REGISTRY_URL=$(cat system-environment.json | jq -r '.data.APICAST_REGISTRY_URL')
8.5.2. 恢复基于 Operator 的部署
使用以下步骤恢复基于 Operator 的部署。
步骤
- 在 OpenShift 上安装 3scale 操作器。
在创建 APIManager 资源前恢复 secret：
oc apply -f system-smtp.json oc apply -f system-seed.json oc apply -f system-database.json oc apply -f backend-internal-api.json oc apply -f system-events-hook.json oc apply -f system-app.json oc apply -f system-recaptcha.json oc apply -f system-redis.json oc apply -f zync.json oc apply -f system-master-apicast.json
在创建 APIManager 资源前恢复 ConfigMap：
oc apply -f system-environment.json oc apply -f apicast-environment.json
- 使用 APIManager 自定义资源部署 3scale。
8.5.3. 恢复 system-mysql
步骤
将 MySQL 转储复制到 system-mysql pod:
oc cp ./system-mysql-backup.gz $(oc get pods -l 'deploymentConfig=system-mysql' -o json | jq '.items[0].metadata.name' -r):/var/lib/mysql
解压缩备份文件：
oc rsh $(oc get pods -l 'deploymentConfig=system-mysql' -o json | jq -r '.items[0].metadata.name') bash -c 'gzip -d ${HOME}/system-mysql-backup.gz'恢复 MySQL DB 备份文件：
oc rsh $(oc get pods -l 'deploymentConfig=system-mysql' -o json | jq -r '.items[0].metadata.name') bash -c 'export MYSQL_PWD=${MYSQL_ROOT_PASSWORD}; mysql -hsystem-mysql -uroot system < ${HOME}/system-mysql-backup'
8.5.4. 恢复 system-storage
将备份文件恢复到 system-storage：
oc rsync ./local/dir/system/ $(oc get pods -l 'deploymentConfig=system-app' -o json | jq '.items[0].metadata.name' -r):/opt/system/public/system
8.5.5. 恢复 zync-database
恢复 zync-database 的具体方法取决于为 3scale 应用的部署类型。
8.5.5.1. 基于模板的部署
步骤
将 zync DeploymentConfig 缩减为 0 个 pod：
oc scale dc zync --replicas=0 oc scale dc zync-que --replicas=0
将 Zync 数据库转储复制到
zync-databasepod:oc cp ./zync-database-backup.gz $(oc get pods -l 'deploymentConfig=zync-database' -o json | jq '.items[0].metadata.name' -r):/var/lib/pgsql/
解压缩备份文件：
oc rsh $(oc get pods -l 'deploymentConfig=zync-database' -o json | jq -r '.items[0].metadata.name') bash -c 'gzip -d ${HOME}/zync-database-backup.gz'恢复 PostgreSQL DB 备份文件：
oc rsh $(oc get pods -l 'deploymentConfig=zync-database' -o json | jq -r '.items[0].metadata.name') bash -c 'psql -f ${HOME}/zync-database-backup'在以下命令中，通过将
${ZYNC_REPLICAS}替换为副本数来恢复到原始副本数：oc scale dc zync --replicas=${ZYNC_REPLICAS} oc scale dc zync-que --replicas=${ZYNC_REPLICAS}
8.5.5.2. 基于 Operator 的部署
按照 使用 Operator 部署 3scale 下的说明，特别是 部署 APIManager 自定义资源 以重新部署 3scale 实例。
步骤
通过将
${DEPLOYMENT_NAME}替换为您在创建 3scale 部署时定义的名称来存储副本数量：ZYNC_SPEC=`oc get APIManager/${DEPLOYMENT_NAME} -o json | jq -r '.spec.zync'`将 zync DeploymentConfig 缩减为 0 个 pod：
oc patch APIManager/${DEPLOYMENT_NAME} --type merge -p '{"spec": {"zync": {"appSpec": {"replicas": 0}, "queSpec": {"replicas": 0}}}}'将 Zync 数据库转储复制到
zync-databasepod:oc cp ./zync-database-backup.gz $(oc get pods -l 'deploymentConfig=zync-database' -o json | jq '.items[0].metadata.name' -r):/var/lib/pgsql/
解压缩备份文件：
oc rsh $(oc get pods -l 'deploymentConfig=zync-database' -o json | jq -r '.items[0].metadata.name') bash -c 'gzip -d ${HOME}/zync-database-backup.gz'恢复 PostgreSQL DB 备份文件：
oc rsh $(oc get pods -l 'deploymentConfig=zync-database' -o json | jq -r '.items[0].metadata.name') bash -c 'psql -f ${HOME}/zync-database-backup'恢复到原始副本数：
oc patch APIManager ${DEPLOYMENT_NAME} --type merge -p '{"spec": {"zync":'"${ZYNC_SPEC}"'}}'
8.5.5.3. 使用 backend-redis 和 system-redis 恢复 3scale 选项
system-redis
通过恢复 3scale，您将恢复 backend-redis 和 system-redis。这些组件具有以下功能：
*backend-redis:在 3scale 中支持应用身份验证和速率限制的数据库。它还可用于统计存储和临时作业存储。*system-redis:为 3scale 的后台作业提供临时存储，也用作 system-app pod Ruby 流程的消息总线。
backend-redis 组件
backend-redis 组件有两个数据库，即 数据和 队列。在默认的 3scale 部署中，数据和 队列 部署在 Redis 数据库中，但在不同的逻辑数据库索引 /0 和 /1 中。恢复 数据 数据库不会有任何问题，但恢复 队列 数据库可能会导致重复的作业。
关于作业重复，在 3scale 中，后端 worker 以毫秒为单位处理后台作业。如果 backend-redis 在最后一次数据库快照后 30 秒失败，并且您尝试恢复它，则在 30 秒内发生的后台作业会执行两次，因为后端没有系统来避免重复。
在这种情况下，您必须恢复备份，因为 /0 数据库 索引包含没有在其它任何位置保存的数据。恢复 /0 数据库索引意味着您必须还原 /1 数据库索引，因为一个在没有数据库索引的情况下将无法存储。当您选择在不同的服务器中分隔数据库，而不是在不同的索引中分隔一个数据库时，队列的大小大约为零，因此最好不要恢复备份并丢失几个后台作业。在 3scale 托管设置中会出现这种情况，因此您需要为两者应用不同的备份和恢复策略。
'system-redis'component
大多数 3scale 系统后台作业是幂等的，也就是说，无论您运行它们多少次，相同的请求都会返回相同的结果。
以下是系统中由后台作业处理的事件示例：
- 通知作业，例如计划试用到期、即将到期的信用卡、激活提醒、计划更改、发票状态更改、PDF 报告.
- 例如开票和收费.
- 删除复杂对象。
- 后端同步作业.
- 索引作业，例如使用 sphinx。
- 清理工作，例如发票 ID.
- Janitorial 任务，如清除审计、用户会话、到期令牌、日志条目、暂停不活动帐户等。
- 流量更新.
- 代理配置更改监控和代理部署.
- 后台注册作业，
- Zync 作业，如单点登录(SSO)同步、路由创建。
如果您要恢复上述后台作业列表，3scale 的系统会维护每个恢复的作业的状态。在恢复完成后检查系统的完整性非常重要。
8.5.6. 确保 后端和系统 之间的信息一致性
恢复 backend-redis 后，应强制同步 系统的 配置信息，以确保 后端 中的信息与 系统中 的信息一致，这是事实的来源。
8.5.6.1. 管理 backend-redis的部署配置
这些步骤旨在运行 backend-redis 的实例。
步骤
编辑
redis-configconfigmap：oc edit configmap redis-config
注释
redis-configconfigmap 中的SAVE命令：#save 900 1 #save 300 10 #save 60 10000
在
redis-configconfigmap 中将appendonly设置为 no ：appendonly no
重新部署
backend-redis以加载新配置：oc rollout latest dc/backend-redis
检查推出部署的状态，以确保它已完成：
oc rollout status dc/backend-redis
重命名
dump.rdb文件：oc rsh $(oc get pods -l 'deploymentConfig=backend-redis' -o json | jq '.items[0].metadata.name' -r) bash -c 'mv ${HOME}/data/dump.rdb ${HOME}/data/dump.rdb-old'重命名
appendonly.aof文件：oc rsh $(oc get pods -l 'deploymentConfig=backend-redis' -o json | jq '.items[0].metadata.name' -r) bash -c 'mv ${HOME}/data/appendonly.aof ${HOME}/data/appendonly.aof-old'将备份文件移到 POD 中：
oc cp ./backend-redis-dump.rdb $(oc get pods -l 'deploymentConfig=backend-redis' -o json | jq '.items[0].metadata.name' -r):/var/lib/redis/data/dump.rdb
重新部署
backend-redis以加载备份：oc rollout latest dc/backend-redis
检查推出部署的状态，以确保它已完成：
oc rollout status dc/backend-redis
创建
附加文件：oc rsh $(oc get pods -l 'deploymentConfig=backend-redis' -o json | jq '.items[0].metadata.name' -r) bash -c 'redis-cli BGREWRITEAOF'
片刻后，请确保完成 AOF 重写：
oc rsh $(oc get pods -l 'deploymentConfig=backend-redis' -o json | jq '.items[0].metadata.name' -r) bash -c 'redis-cli info' | grep aof_rewrite_in_progress
-
aof_rewrite_in_progress = 1时，执行正在进行中。 -
定期检查，直到
aof_rewrite_in_progress = 0。零表示执行已经完成。
-
编辑
redis-configconfigmap：oc edit configmap redis-config
在
redis-configconfigmap 中取消注释SAVE命令：save 900 1 save 300 10 save 60 10000
在
redis-configconfigmap 中将appendonly设置为 yes ：appendonly yes
重新部署
backend-redis以重新载入默认配置：oc rollout latest dc/backend-redis
检查推出部署的状态，以确保它已完成：
oc rollout status dc/backend-redis
8.5.6.2. 管理 system-redis的部署配置
这些步骤旨在运行 system-redis 实例。
步骤
编辑
redis-configconfigmap：oc edit configmap redis-config
注释
redis-configconfigmap 中的SAVE命令：#save 900 1 #save 300 10 #save 60 10000
在
redis-configconfigmap 中将appendonly设置为 no ：appendonly no
重新部署
system-redis以加载新配置：oc rollout latest dc/system-redis
检查推出部署的状态，以确保它已完成：
oc rollout status dc/system-redis
重命名
dump.rdb文件：oc rsh $(oc get pods -l 'deploymentConfig=system-redis' -o json | jq '.items[0].metadata.name' -r) bash -c 'mv ${HOME}/data/dump.rdb ${HOME}/data/dump.rdb-old'重命名
appendonly.aof文件：oc rsh $(oc get pods -l 'deploymentConfig=system-redis' -o json | jq '.items[0].metadata.name' -r) bash -c 'mv ${HOME}/data/appendonly.aof ${HOME}/data/appendonly.aof-old'将
备份文件移到 POD 中：oc cp ./system-redis-dump.rdb $(oc get pods -l 'deploymentConfig=system-redis' -o json | jq '.items[0].metadata.name' -r):/var/lib/redis/data/dump.rdb
重新部署
system-redis以载入备份：oc rollout latest dc/system-redis
检查推出部署的状态，以确保它已完成：
oc rollout status dc/system-redis
创建
附加文件：oc rsh $(oc get pods -l 'deploymentConfig=system-redis' -o json | jq '.items[0].metadata.name' -r) bash -c 'redis-cli BGREWRITEAOF'
片刻后，请确保完成 AOF 重写：
oc rsh $(oc get pods -l 'deploymentConfig=system-redis' -o json | jq '.items[0].metadata.name' -r) bash -c 'redis-cli info' | grep aof_rewrite_in_progress
-
aof_rewrite_in_progress = 1时，执行正在进行中。 -
定期检查，直到
aof_rewrite_in_progress = 0。零表示执行已经完成。
-
编辑
redis-configconfigmap：oc edit configmap redis-config
在
redis-configconfigmap 中取消注释SAVE命令：save 900 1 save 300 10 save 60 10000
在
redis-configconfigmap 中将appendonly设置为 yes ：appendonly yes
重新部署
system-redis以重新载入默认配置：oc rollout latest dc/system-redis
检查推出部署的状态，以确保它已完成：
oc rollout status dc/system-redis
8.5.7. 恢复 backend-worker
恢复到 backend-worker 的最新版本：
oc rollout latest dc/backend-worker
检查推出部署的状态，以确保它已完成：
oc rollout status dc/backend-worker
8.5.8. 恢复 system-app
恢复到最新版本的 system-app ：
oc rollout latest dc/system-app
检查推出部署的状态，以确保它已完成：
oc rollout status dc/system-app
8.5.9. 恢复 system-sidekiq
恢复到
system-sidekiq的最新版本：oc rollout latest dc/system-sidekiq
检查推出部署的状态，以确保它已完成：
oc rollout status dc/system-sidekiq
8.5.9.1. 恢复 system-sphinx
恢复到最新版本的
system-sphinx：oc rollout latest dc/system-sphinx
检查推出部署的状态，以确保它已完成：
oc rollout status dc/system-sphinx
8.5.9.2. 恢复由 Zync 管理的 OpenShift 路由
强制 Zync 重新创建缺少的 OpenShift 路由：
oc rsh $(oc get pods -l 'deploymentConfig=system-sidekiq' -o json | jq '.items[0].metadata.name' -r) bash -c 'bundle exec rake zync:resync:domains'
第 9 章 使用自定义资源进行 3scale 备份和恢复
本章包含使用 API Manager 自定义资源(CR)部署的 Red Hat 3scale API 管理安装的备份和恢复功能详情。在这种情况下，CRD 由 3scale Operator 提供。
来自 operator 功能的自定义资源不属于 3scale 安装的一部分。因此，在 3scale 安装备份和恢复功能中不包含自定义资源。
使用 operator 进行 3scale 备份和恢复只是一个技术预览功能。技术预览功能不受红帽产品服务等级协议（SLA）支持，且功能可能并不完整。红帽不推荐在生产环境中使用它们。这些技术预览功能可以使用户提早试用新的功能，并有机会在开发阶段提供反馈意见。有关红帽技术预览功能支持范围的更多信息，请参阅技术预览功能支持范围。
先决条件
- 3scale 安装
以下小节包含使用 Operator 执行 3scale 备份和恢复的步骤。
9.1. 使用操作器备份 3scale
下面的部分提供了备份由 APIManager 自定义资源部署的 3scale 安装所需的信息和步骤。
9.1.1. 备份兼容场景
要查看可以备份的 3scale 安装配置，请查看以下部分：
先决条件
备份 3scale 外部数据库：
-
backend-redis -
system-redis -
system-database- MySQL 或 PostgreSQL
-
- 为 PVC 置备足够空间，使其包含备份的数据。
使用 APIManager 部署的一个 3scale 部署无法使用 S3 作为系统的 FileStorage 进行备份。
9.1.2. 备份场景范围
外部配置以下数据库时，可以使用备份功能：
- 后端 Redis 数据库
- 系统 Redis 数据库
- 系统数据库 - MySQL 或 PostgreSQL
9.1.3. 备份数据
下表显示了已备份的数据的列表：
表 9.1. 备份的数据
| 对象 | 对象类型数据 |
|---|---|
| Secrets |
|
| ConfigMaps |
|
| APIManager | APIManager 自定义资源 Kubernetes 对象定义 - json 模式定义 |
| System FileStorage | 当系统文件存储的位置位于 PersistentVolumeClaim(PVC)中时 |
9.1.4. 备份 3scale
要备份使用现有 APIManager 部署 3scale 安装，请使用以下步骤：
步骤
备份以下 Kubernetes secret：
-
backend-redis -
system-redis -
system-database
-
在部署了由
APIManager 对象管理的 3scale 安装的同一命名空间中创建 APIManager Backup自定义资源，例如：示例 1
apiVersion: apps.3scale.net/v1alpha1 kind: APIManagerBackup metadata: name: example-apimanagerbackup-pvc spec: backupDestination: persistentVolumeClaim: resources: requests: "10Gi"示例 2 提供已存在的 PersistentVolume 名称：
apiVersion: apps.3scale.net/v1alpha1 kind: APIManagerBackup metadata: name: example-apimanagerbackup-pvc spec: backupDestination: persistentVolumeClaim: # resources specification is required but ignored when providing a volumeName as per K8s PVCs requirements behavior resources: requests: "10Gi" volumeName: "my-preexisting-persistent-volume"-
等待
APIManagerBackup完成。通过获取APIManagerBackup 的内容并等待.status.completed字段设置为 true 进行检查。
备份内容在备份 数据中 详细介绍。
APIManagerBackup 的 status 部分中的其他字段显示备份详情，如当配置的备份目的地为 PVC 时备份数据的 PVC 名称。
如需以后的引用，请记下 status.backupPersistentVolumeClaimName 字段的值。当使用 APIManager Restore 恢复 APIManager 安装时，它所需的其中一个字段是 PersistentVolumeClaimName 备份源。
9.2. 使用 Operator 恢复 3scale
下面的部分提供了恢复 3scale 安装所需的信息和步骤，该安装之前由 APIManager 自定义资源部署并由 APIManagerBackup 进行 备份。
9.2.1. 恢复兼容场景
要查看可以恢复的 3scale 安装配置，请查看以下部分：
先决条件
恢复 3scale 外部数据库：
-
backend-redis -
system-redis -
system-database- MySQL 或 PostgreSQL
-
9.2.2. 恢复场景范围
3scale 操作器的恢复功能可以使用 APIManagerBackup 自定义资源生成的备份。
有关您可以备份的 3scale 解决方案场景列表，请参阅 备份数据 以供参考。
以下不在 Operator 的恢复功能范围内：
-
恢复没有使用
APIManagerBackup自定义资源执行的备份数据。 -
从不同的 3scale 版本恢复通过
APIManagerBackup提供的备份数据。
9.2.3. 恢复数据
下表显示了已恢复的数据的列表：
表 9.2. 恢复的数据
| 对象 | 对象类型数据 |
|---|---|
| Secrets |
|
| ConfigMaps |
|
| APIManager | APIManager 自定义资源 Kubernetes 对象定义 - json 模式定义 |
| System FileStorage | 当系统文件存储的位置位于 PersistentVolumeClaim(PVC)中时 |
| Routes | 3scale 相关的 OpenShift 路由，如 master 和租户 |
9.2.4. 恢复 3scale
要恢复之前通过 APIManager Backup 自定义资源备份的 APIManager 的 3scale 安装，请按照以下步骤执行：
- 确保您要执行恢复的项目不包含 APIManager 自定义资源及其对应的 3scale 安装。
恢复以下 Kubernetes secret：
-
backend-redis -
system-redis -
system-database
-
创建
APIManagerRestore自定义资源，并指定之前由APIManagerBackup自定义资源备份的安装的备份数据。详情请参阅 备份场景范围。
以下是
APIManagerRestore自定义资源的示例：apiVersion: apps.3scale.net/v1alpha1 kind: APIManagerRestore metadata: name: example-apimanagerrestore-pvc spec: restoreSource: persistentVolumeClaim: claimSource: claimName: example-apimanagerbackup-pvc # Name of the PVC produced as the backup result of an `APIManagerBackup` readOnly: true等待
APIManagerRestore完成。通过获取APIManagerRestore的内容并等待.status.completed字段设置为 true 进行检查。您应该会看到创建了一个新的 APIManager 自定义资源并部署 3scale 安装。
第 10 章 为 3scale 配置 reCAPTCHA
本文档论述了如何为红帽 3scale API 管理内部配置 reCAPTCHA，以防止垃圾邮件。
先决条件
- 在 受支持的 OpenShift 版本 上安装并配置了 3scale On-Premises 实例。
- 获取 reCAPTCHA v2 的站点密钥和 secret key。请参阅 Register a new site web 页面。
- 如果要使用域名验证，请将 Developer Portal 域添加到 allowlist 中。
要为 3scale 配置 reCAPTCHA，请执行以下步骤中介绍的步骤：
10.1. 配置 reCAPTCHA for spam 保护 3scale
要配置 reCAPTCHA 以实现垃圾邮件保护，有两个选项可用于修补包含 reCAPTCHA 的机密文件。这些选项位于 OpenShift Container Platform(OCP)用户界面中，或者使用命令行界面(CLI)。
步骤
- OCP 4.x：导航到 Project: [Your_project_name] > Workloads > Secrets。
编辑
system-recaptchasecret 文件。reCAPTHCA 服务的
PRIVATE必须使用 base64 格式编码。手动将密钥转换为 base64 编码。_KEY和 PUBLIC_KEY
CLI reCAPTCHA 选项不需要 base64 格式编码。
CLI：输入以下命令：
oc patch secret/system-recaptcha -p '{"stringData": {"PUBLIC_KEY": "public-key-from-service", "PRIVATE_KEY": "private-key-from-service"}}'
流程后的步骤
- 完成上述选项之一后重新部署系统 pod。
在 3scale 管理门户中，打开对未签名用户的垃圾邮件保护：
- 导航到 Audience > Developer Portal > Spam Protection。
选择以下选项之一：
- Always - 当向未登录的用户显示表单时，reCAPTCHA 始终会显示。
- 仅显示可疑 - 只有 自动检查检测到可能的垃圾邮件时才会显示 reCAPTCHA。
- 永不 - 关闭 Spam 保护.
重新部署 system-app 后，开发人员门户上使用垃圾邮件保护的页面将显示 reCAPTCHA I'm not a robot 复选框。
其他资源
- 如需更多信息、指南和支持，请参阅 ReCAPTCHA 主页。
第 11 章 对 API 基础架构进行故障排除
本指南旨在帮助您识别和修复 API 基础架构问题的原因。
API 基础架构是一个冗长而复杂的主题。但是，您的基础架构中至少需要三个移动部分：
- API 网关
- 3scale
- API
这三种元素中的任何一个错误都会导致 API 用户无法访问您的 API。但是，很难找到导致失败的组件。本指南将为您提供对基础架构进行故障排除以确定问题的一些建议。
使用以下部分来识别并修复可能出现的常见问题：
11.1. 常见集成问题
有一些证据可以指出您与 3scale 集成时存在一些非常常见的问题。它们将根据您是处于 API 项目开头、设置基础架构还是已存在于生产中而有所不同。
11.1.1. 集成问题
以下小节尝试概述了在与 3scale 集成的初始阶段，APIcast 错误日志中可能看到的一些常见问题：从使用 APIcast Hosted 开始，在启动之前，运行自我管理的 APIcast。
11.1.1.1. APIcast Hosted
当您首次在 Service Integration 屏幕上将 API 与 APIcast Hosted 集成时，您可能会在页面中看到一些以下错误，或者通过测试调用返回，以检查集成是否成功。
测试请求失败：执行过期检查您的 API 是否可从公共互联网访问。APIcast Hosted 无法与私有 API 一起使用。如果您不想使 API 公开可用于与 APIcast Hosted 集成，您可以在 APIcast Hosted 和 API 之间设置一个私有 secret，以拒绝任何来自 API 网关的调用。
可接受的格式是
protocol://address(:port)删除 API 专用基础 URL 末尾的所有路径。您可以在"映射规则"模式或 API 测试 GET 请求 的开头添加它们。
使用 HTTP 代码 XXX 测试请求失败-
405:检查端点是否接受 GET 请求。APIcast 只支持 GET 请求来测试集成。 -
403:缺少身份验证参数：如果您的 API 已有一些身份验证，APIcast 将无法发出测试请求。 -
403:身份验证失败：如果这不是您通过 3scale 创建的第一个服务，请检查您是否在服务下创建了带有凭据的应用，以发出测试请求。如果是您要集成的第一个服务，请确保您还没有删除在注册时创建的测试帐户或应用程序。
-
11.1.1.2. APIcast 自我管理
在成功测试了与 APIcast 自我管理的集成后，您可能希望自己托管 API 网关。以下是首次安装自我管理网关并通过它调用 API 时您可能会遇到的一些错误。
上游超时（110：连接超时），同时连接到上游检查 API 网关和公共 Internet 之间没有防火墙或代理，从而妨碍您自我管理的网关到达 3scale。
获取服务列表失败：无效的状态：403（禁止）2018/06/04 08:04:49 [emerg] 14#14: [lua] configuration_loader.lua:134: init(): failed to load configuration, exiting (code 1) 2018/06/04 08:04:49 [warn] 22#22: *2 [lua] remote_v2.lua:163: call(): failed to get list of services: invalid status: 403 (Forbidden) url: https://example-admin.3scale.net/admin/api/services.json , context: ngx.timer ERROR: /opt/app-root/src/src/apicast/configuration_loader.lua:57: missing configuration
检查您在
THREESCALE_PORTAL_ENDOINT值中使用的访问令牌是否正确，以及帐户管理 API 范围。使用curl命令验证它：curl -v "https://example-admin.3scale.net/admin/api/services.json?access_token=<YOUR_ACCESS_TOKEN>"它应当通过 JSON 正文返回 200 响应。如果返回错误状态代码，请检查响应正文以了解详细信息。
主机 apicast.example.com 没有找到服务2018/06/04 11:06:15 [warn] 23#23: *495 [lua] find_service.lua:24: find_service(): service not found for host apicast.example.com, client: 172.17.0.1, server: _, request: "GET / HTTP/1.1", host: "apicast.example.com"
此错误表示公共基本 URL 尚未正确配置。您应该确保配置的 Public Base URL 与用于自助管理的 APIcast 请求的相同。配置正确的公共基本 URL 后：
-
确保 APIcast 已配置为"生产环境"（如果不使用
THREESCALE_DEPLOYMENT_ENV变量覆盖独立 APIcast 的默认配置）。确保您将配置提升到生产环境。 -
如果您使用 APICAST_CONFIGURATION_
CACHE 和 APICAST_cast。CONFIGURATION_LOADER 环境变量自动重新加载配置，请重新启动 API
-
确保 APIcast 已配置为"生产环境"（如果不使用
以下是一些可能指向不正确 APIcast 自助管理的集成的其他症状：
- 映射规则与 API 调用的 / Double 计数不匹配 ：根据您定义 API 上方法和实际 URL 端点之间的映射方式，您可能会发现有时每个请求都不匹配的方法或被递增一次。要对此进行故障排除，请通过 3scale 调试标头 对 API 发出测试调用。这将返回 API 调用匹配的所有方法的列表。
- 未找到身份验证参数 ：确保您将参数发送到 Service Integration 屏幕中指定的正确位置。如果没有将凭证作为标头发送，则凭据必须以 GET 请求和正文参数的查询参数形式发送，所有其他 HTTP 方法。使用 3scale 调试标头来再次检查从 API 网关的请求读取的凭据。
11.1.2. 产品问题
在全面测试了设置并且已使用 API 长时间使用 API 后，很少会出现与 API 网关相关的问题。但是，以下是您可能在真实生产环境中遇到的一些问题：
11.1.2.1. 可用性问题
可用性问题通常由 nginx error.log 中的 上游超时 错误定性；例如：
upstream timed out (110: Connection timed out) while connecting to upstream, client: X.X.X.X, server: api.example.com, request: "GET /RESOURCE?CREDENTIALS HTTP/1.1", upstream: "http://Y.Y.Y.Y:80/RESOURCE?CREDENTIALS", host: "api.example.com"
如果您遇到 3scale 的可用性问题，这可能是原因：
您解析了不再使用的旧 3scale IP。
最新版本的 API 网关配置文件将 3scale 定义为每次强制 IP 解析的变量。为获得快速修复，重新加载您的 NGINX 实例。对于长期修复，请确保将其定义为每个服务器块中的变量，而不是在上游块中定义 3scale 后端；例如：
server { # Enabling the Lua code cache is strongly encouraged for production use. Here it is enabled . . . set $threescale_backend "https://su1.3scale.net:443";引用它时：
location = /threescale_authrep { internal; set $provider_key "YOUR_PROVIDER_KEY"; proxy_pass $threescale_backend/transactions/authrep.xml?provider_key=$provider_key&service_id=$service_id&$usage&$credentials&log%5Bcode%5D=$arg_code&log%5Brequest%5D=$arg_req&log%5Bresponse%5D=$arg_resp; }您缺少白名单中的一些 3scale IP。以下是 3scale 解析到的 IP 的当前列表：
- 75.101.142.93
- 174.129.235.69
- 184.73.197.122
- 50.16.225.117
- 54.83.62.94
- 54.83.62.186
- 54.83.63.187
54.235.143.255
以上问题是指感知的 3scale 可用性问题。但是，如果您的 API 位于 AWS ELB 后面，您可能会遇到与 API 网关的 API 可用性类似的问题。这是因为 NGINX 默认在启动时执行 DNS 解析，然后缓存 IP 地址。但是，ELB 无法确保静态 IP 地址，它们可能会经常更改。当 ELB 更改为其他 IP 时，NGINX 无法访问它。
此问题的解决方案与强制进行运行时 DNS 解析的修复程序类似。
-
通过在
http部分的顶部添加以下行来设置特定的 DNS 解析器，如 Google DNS：解析器 8.8.8.8 8.8.4.4;。 -
将 API 基本 URL 设置为
server部分顶部附近任何位置的变量。设置 $api_base "http://api.example.com:80"; -
在
位置 /部分中，找到proxy_pass行并将其替换为proxy_pass $api_base;。
-
通过在
11.1.3. 部署后的问题
如果您更改了 API，如添加新端点，您必须确保在下载 API 网关的新配置文件之前添加新方法和 URL 映射。
当您修改了从 3scale 下载的配置时，最常见问题是在 Lua 中的代码错误，这会导致 500 - 内部服务器错误，例如：
curl -v -X GET "http://localhost/" * About to connect() to localhost port 80 (#0) * Trying 127.0.0.1... connected > GET / HTTP/1.1 > User-Agent: curl/7.22.0 (x86_64-pc-linux-gnu) libcurl/7.22.0 OpenSSL/1.0.1 zlib/1.2.3.4 libidn/1.23 librtmp/2.3 > Host: localhost > Accept: */* > < HTTP/1.1 500 Internal Server Error < Server: openresty/1.5.12.1 < Date: Thu, 04 Feb 2016 10:22:25 GMT < Content-Type: text/html < Content-Length: 199 < Connection: close < <head><title>500 Internal Server Error</title></head> <center><h1>500 Internal Server Error</h1></center> <hr><center>openresty/1.5.12.1</center> * Closing connection #0
您可以看到 nginx error.log 了解原因，例如：
2016/02/04 11:22:25 [error] 8980#0: *1 lua entry thread aborted: runtime error: /home/pili/NGINX/troubleshooting/nginx.lua:66: bad argument #3 to '_newindex' (number expected, got nil) stack traceback: coroutine 0: [C]: in function '_newindex' /home/pili/NGINX/troubleshooting/nginx.lua:66: in function 'error_authorization_failed' /home/pili/NGINX/troubleshooting/nginx.lua:330: in function 'authrep' /home/pili/NGINX/troubleshooting/nginx.lua:283: in function 'authorize' /home/pili/NGINX/troubleshooting/nginx.lua:392: in function while sending to client, client: 127.0.0.1, server: api-2445581381726.staging.apicast.io, request: "GET / HTTP/1.1", host: "localhost"
在 access.log 中，类似如下：
127.0.0.1 - - [04/Feb/2016:11:22:25 +0100] "GET / HTTP/1.1" 500 199 "-" "curl/7.22.0 (x86_64-pc-linux-gnu) libcurl/7.22.0 OpenSSL/1.0.1 zlib/1.2.3.4 libidn/1.23 librtmp/2.3"
上一节将向您介绍在 3scale 旅程的任何阶段可能会遇到的最常见、知名的问题。
如果已经检查所有这些内容，且您仍无法找到问题的原因和解决方案，您应该进入有关 识别 API 请求问题 的更详细部分。从 API 开始，再重新尝试确定故障点到客户端。
11.2. 处理 API 基础架构问题
如果您在连接到服务器时遇到失败，无论是 API 网关、3scale 或 API，以下故障排除步骤应该是您调用的第一个端口：
11.2.1. 我们可以连接吗？
使用 telnet 检查基本 TCP/IP 连接 telnet api.example.com 443
- 成功
telnet echo-api.3scale.net 80 Trying 52.21.167.109... Connected to tf-lb-i2t5pgt2cfdnbdfh2c6qqoartm-829217110.us-east-1.elb.amazonaws.com. Escape character is '^]'. Connection closed by foreign host.
- 失败
telnet su1.3scale.net 443 Trying 174.129.235.69... telnet: Unable to connect to remote host: Connection timed out
11.2.2. 服务器连接问题
尝试从不同的网络位置、设备和方向连接到同一服务器。例如，如果您的客户端无法访问您的 API，请尝试从应该有权访问 API 的机器（如 API 网关）连接到您的 API。
如果有任何尝试的连接成功，您可以排除实际服务器中的任何问题，并在它们之间的网络上集中进行故障排除，因为这是问题最有可能是的地方。
11.2.3. 这是 DNS 问题吗？
尝试使用 IP 地址而不是其主机名（如 telnet 94.125.104.17 80 而不是 ）连接到服务器
telnet apis.io 80
这将排除 DNS 中的任何问题。
您可以使用 dig 获取服务器的 IP 地址，例如 3scale dig su1.3scale.net 或 dig any su1.3scale.net （如果怀疑主机可能解析到多个 IP 地址）。
NB:有些主机阻止 'dig any'
11.2.4. 这是 SSL 问题吗？
您可以使用 OpenSSL 测试：
保护到主机或 IP 的连接，例如从 shell prompt
openssl s_client -connect su1.3scale.net:443输出：
CONNECTED(00000003) depth=1 C = US, O = GeoTrust Inc., CN = GeoTrust SSL CA - G3 verify error:num=20:unable to get local issuer certificate --- Certificate chain 0 s:/C=ES/ST=Barcelona/L=Barcelona/O=3scale Networks, S.L./OU=IT/CN=*.3scale.net i:/C=US/O=GeoTrust Inc./CN=GeoTrust SSL CA - G3 1 s:/C=US/O=GeoTrust Inc./CN=GeoTrust SSL CA - G3 i:/C=US/O=GeoTrust Inc./CN=GeoTrust Global CA --- Server certificate -----BEGIN CERTIFICATE----- MIIE8zCCA9ugAwIBAgIQcz2Y9JNxH7f2zpOT0DajUjANBgkqhkiG9w0BAQsFADBE ... TRUNCATED ... 3FZigX+OpWLVRjYsr0kZzX+HCerYMwc= -----END CERTIFICATE----- subject=/C=ES/ST=Barcelona/L=Barcelona/O=3scale Networks, S.L./OU=IT/CN=*.3scale.net issuer=/C=US/O=GeoTrust Inc./CN=GeoTrust SSL CA - G3 --- Acceptable client certificate CA names /C=ES/ST=Barcelona/L=Barcelona/O=3scale Networks, S.L./OU=IT/CN=*.3scale.net /C=US/O=GeoTrust Inc./CN=GeoTrust SSL CA - G3 Client Certificate Types: RSA sign, DSA sign, ECDSA sign Requested Signature Algorithms: RSA+SHA512:DSA+SHA512:ECDSA+SHA512:RSA+SHA384:DSA+SHA384:ECDSA+SHA384:RSA+SHA256:DSA+SHA256:ECDSA+SHA256:RSA+SHA224:DSA+SHA224:ECDSA+SHA224:RSA+SHA1:DSA+SHA1:ECDSA+SHA1:RSA+MD5 Shared Requested Signature Algorithms: RSA+SHA512:DSA+SHA512:ECDSA+SHA512:RSA+SHA384:DSA+SHA384:ECDSA+SHA384:RSA+SHA256:DSA+SHA256:ECDSA+SHA256:RSA+SHA224:DSA+SHA224:ECDSA+SHA224:RSA+SHA1:DSA+SHA1:ECDSA+SHA1 Peer signing digest: SHA512 Server Temp Key: ECDH, P-256, 256 bits --- SSL handshake has read 3281 bytes and written 499 bytes --- New, TLSv1/SSLv3, Cipher is ECDHE-RSA-AES256-GCM-SHA384 Server public key is 2048 bit Secure Renegotiation IS supported Compression: NONE Expansion: NONE No ALPN negotiated SSL-Session: Protocol : TLSv1.2 Cipher : ECDHE-RSA-AES256-GCM-SHA384 Session-ID: A85EFD61D3BFD6C27A979E95E66DA3EC8F2E7B3007C0166A9BCBDA5DCA5477B8 Session-ID-ctx: Master-Key: F7E898F1D996B91D13090AE9D5624FF19DFE645D5DEEE2D595D1B6F79B1875CF935B3A4F6ECCA7A6D5EF852AE3D4108B Key-Arg : None PSK identity: None PSK identity hint: None SRP username: None TLS session ticket lifetime hint: 300 (seconds) TLS session ticket: 0000 - a8 8b 6c ac 9c 3c 60 78-2c 5c 8a de 22 88 06 15 ..l..<`x,\.."... 0010 - eb be 26 6c e6 7b 43 cc-ae 9b c0 27 6c b7 d9 13 ..&l.{C....'l... 0020 - 84 e4 0d d5 f1 ff 4c 08-7a 09 10 17 f3 00 45 2c ......L.z.....E, 0030 - 1b e7 47 0c de dc 32 eb-ca d7 e9 26 33 26 8b 8e ..G...2....&3&.. 0040 - 0a 86 ee f0 a9 f7 ad 8a-f7 b8 7b bc 8c c2 77 7b ..........{...w{ 0050 - ae b7 57 a8 40 1b 75 c8-25 4f eb df b0 2b f6 b7 ..W.@.u.%O...+.. 0060 - 8b 8e fc 93 e4 be d6 60-0f 0f 20 f1 0a f2 cf 46 .......`.. ....F 0070 - b0 e6 a1 e5 31 73 c2 f5-d4 2f 57 d1 b0 8e 51 cc ....1s.../W...Q. 0080 - ff dd 6e 4f 35 e4 2c 12-6c a2 34 26 84 b3 0c 19 ..nO5.,.l.4&.... 0090 - 8a eb 80 e0 4d 45 f8 4a-75 8e a2 06 70 84 de 10 ....ME.Ju...p... Start Time: 1454932598 Timeout : 300 (sec) Verify return code: 20 (unable to get local issuer certificate) ---SSLv3 支持（当前受 3scale 支持）
openssl s_client -ssl3 -connect su.3scale.net:443输出。
CONNECTED(00000003)
140735196860496:error:14094410:SSL routines:ssl3_read_bytes:sslv3 alert handshake failure:s3_pkt.c:1456:SSL alert number 40
140735196860496:error:1409E0E5:SSL routines:ssl3_write_bytes:ssl handshake failure:s3_pkt.c:644:
---
no peer certificate available
---
No client certificate CA names sent
---
SSL handshake has read 7 bytes and written 0 bytes
---
New, (NONE), Cipher is (NONE)
Secure Renegotiation IS NOT supported
Compression: NONE
Expansion: NONE
No ALPN negotiated
SSL-Session:
Protocol : SSLv3
Cipher : 0000
Session-ID:
Session-ID-ctx:
Master-Key:
Key-Arg : None
PSK identity: None
PSK identity hint: None
SRP username: None
Start Time: 1454932872
Timeout : 7200 (sec)
Verify return code: 0 (ok)
---详情请查看 OpenSSL man page。
11.3. 识别 API 请求问题
要识别向您的 API 请求可能存在问题，请执行以下检查：
11.3.1. API
要确认 API 已启动并响应请求，请直接向 API 发出相同的请求（而不是通过 API 网关）。您应该确保发送与通过 API 网关的请求相同的参数和标头。如果您不确定失败的确切请求，请捕获 API 网关和 API 之间的流量。
如果调用成功，您可以排除 API 中的任何问题，否则您应该进一步对 API 进行故障排除。
11.3.2. API Gateway > API
要排除 API 网关和 API 之间的任何网络问题，请对您的 API 网关服务器发出与 before SAS-sule 相同的调用。
如果调用成功，您可以继续对 API 网关本身进行故障排除。
11.3.3. API 网关
可以通过多个步骤来检查 API 网关是否正常工作。
11.3.3.1. API 网关是否已启动并运行？
登录正在运行网关的计算机。如果此操作失败，您的网关服务器可能会停机。
登录后，检查 NGINX 进程是否正在运行。为此，请运行 ps ax | grep nginx 或 htop。
如果您看到列表中看到 nginx master 进程和 ，则 NGINX 正在运行。
nginx worker 进程
11.3.3.2. 网关日志中是否存在任何错误？
以下是您可能在网关日志中看到的一些常见错误，例如在 error.log 中：
API 网关无法连接到 API
upstream timed out (110: Connection timed out) while connecting to upstream, client: X.X.X.X, server: api.example.com, request: "GET /RESOURCE?CREDENTIALS HTTP/1.1", upstream: "http://Y.Y.Y.Y:80/RESOURCE?CREDENTIALS", host: "api.example.com"
API 网关无法连接到 3scale
2015/11/20 11:33:51 [error] 3578#0: *1 upstream timed out (110: Connection timed out) while connecting to upstream, client: 127.0.0.1, server: , request: "GET /api/activities.json?user_key=USER_KEY HTTP/1.1", subrequest: "/threescale_authrep", upstream: "https://54.83.62.186:443/transactions/authrep.xml?provider_key=YOUR_PROVIDER_KEY&service_id=SERVICE_ID&usage[hits]=1&user_key=USER_KEY&log%5Bcode%5D=", host: "localhost"
11.3.4. API gateway > 3scale
确保 API 网关正确运行后，下一步是对 API 网关和 3scale 之间的连接进行故障排除。
11.3.4.1. API 网关能否访问 3scale？
如果您使用 NGINX 作为 API 网关，当网关无法联系 3scale 时，nginx 错误日志中会显示以下消息：
2015/11/20 11:33:51 [error] 3578#0: *1 upstream timed out (110: Connection timed out) while connecting to upstream, client: 127.0.0.1, server: , request: "GET /api/activities.json?user_key=USER_KEY HTTP/1.1", subrequest: "/threescale_authrep", upstream: "https://54.83.62.186:443/transactions/authrep.xml?provider_key=YOUR_PROVIDER_KEY&service_id=SERVICE_ID&usage[hits]=1&user_key=USER_KEY&log%5Bcode%5D=", host: "localhost"
注意上游值。此 IP 对应于 3scale 产品解析到的 IP 地址之一。这意味着到达 3scale 存在问题。您可以通过调用 nslookup 进行反向 DNS 查找来检查 IP 的域。
例如，由于 API 网关无法访问 3scale，这并不表示 3scale 已关闭。其中一个最常见的原因是防火墙规则阻止 API 网关连接到 3scale。
网关和 3scale 之间可能存在网络问题，可能会导致连接超时。在这种情况下，您应该执行对 通用连接问题进行故障排除 的步骤，以确定问题所在的位置。
要排除网络问题，请使用 traceroute 或 MTR 来检查路由和数据包传输。您也可以从能够连接到 3scale 和 API 网关并比较输出的计算机运行相同的命令。
此外，若要查看 API 网关和 3scale 之间发送的流量，只要您临时切换为 3scale 产品(su1.3scale.net)的 HTTP 端点，就可以使用 tcpdump。
11.3.4.2. API 网关是否正确解析 3scale 地址？
确保已将 resolver 指令添加到 nginx.conf 中。
例如，在 nginx.conf 中：
http {
lua_shared_dict api_keys 10m;
server_names_hash_bucket_size 128;
lua_package_path ";;$prefix/?.lua;";
init_by_lua 'math.randomseed(ngx.time()) ; cjson = require("cjson")';
resolver 8.8.8.8 8.8.4.4;您可以将 Google DNS（8.8.8.8 和 8.8.4.4）替换为您首选的 DNS。
要从 API 网关检查 DNS 解析，请按指定解析器 IP 调用 nslookup：
nslookup su1.3scale.net 8.8.8.8 ;; connection timed out; no servers could be reached
上面的例子显示了如果无法到达 Google DNS，则返回的响应。如果出现这种情况，您必须更新解析器 IP。您可能还会在 nginx error.log 中看到以下警报：
2016/05/09 14:15:15 [alert] 9391#0: send() failed (1: Operation not permitted) while resolving, resolver: 8.8.8.8:53
最后，运行 dig 任何 su1.3scale.net 以查看 3scale 服务管理 API 当前运行的 IP 地址。请注意，这不是 3scale 可能使用的整个 IP 地址范围。些可能因为容量原因而被交换和移出。此外，未来您可以为 3scale 服务添加更多域名。对于这一点，您应该始终针对集成期间为您提供的特定地址进行测试（如果适用）。
11.3.4.3. API 网关调用 3scale 是否正确？
如果要检查 API 网关是否要进行 3scale 来满足故障排除的需要，您只能将以下代码片段添加到 nginx.conf 中的 3scale authrep 位置（API 密钥和 App\_id 身份验证模式为 /threescale_authrep ）：
body_filter_by_lua_block{
if ngx.req.get_headers()["X-3scale-debug"] == ngx.var.provider_key then
local resp = ""
ngx.ctx.buffered = (ngx.ctx.buffered or "") .. string.sub(ngx.arg[1], 1, 1000)
if ngx.arg[2] then
resp = ngx.ctx.buffered
end
ngx.log(0, ngx.req.raw_header())
ngx.log(0, resp)
end
}
当发送 X-3scale-debug 标头 时，此片段会将以下额外日志记录添加到 nginx error.log 中，例如 curl -v -H 'X-3scale-debug:YOUR_PROVIDER_KEY' -X GET "https://726e3b99.ngrok.com/api/contacts.json?access_token=7c6f24f5"
这会生成以下日志条目：
2016/05/05 14:24:33 [] 7238#0: *57 [lua] body_filter_by_lua:7: GET /api/contacts.json?access_token=7c6f24f5 HTTP/1.1 Host: 726e3b99.ngrok.io User-Agent: curl/7.43.0 Accept: */* X-Forwarded-Proto: https X-Forwarded-For: 2.139.235.79 while sending to client, client: 127.0.0.1, server: pili-virtualbox, request: "GET /api/contacts.json?access_token=7c6f24f5 HTTP/1.1", subrequest: "/threescale_authrep", upstream: "https://54.83.62.94:443/transactions/oauth_authrep.xml?provider_key=REDACTED&service_id=REDACTED&usage[hits]=1&access_token=7c6f24f5", host: "726e3b99.ngrok.io" 2016/05/05 14:24:33 [] 7238#0: *57 [lua] body_filter_by_lua:8: <?xml version="1.0" encoding="UTF-8"?><error code="access_token_invalid">access_token "7c6f24f5" is invalid: expired or never defined</error> while sending to client, client: 127.0.0.1, server: pili-virtualbox, request: "GET /api/contacts.json?access_token=7c6f24f5 HTTP/1.1", subrequest: "/threescale_authrep", upstream: "https://54.83.62.94:443/transactions/oauth_authrep.xml?provider_key=REDACTED&service_id=REDACTED&usage[hits]=1&access_token=7c6f24f5", host: "726e3b99.ngrok.io"
第一个条目(2016/05/05 14:24:33 [] 7238#0: *57 [lua] body_filter_by_lua:7:)显示发送到 3scale 的请求标头，本例中为：主机、用户辅助、验收、X-Forwarded-Proto 和 X-Forwarded-For.
第二个条目(2016/05/05 14:24:33 [] 7238#0: *57 [lua] body_filter_by_lua:8:)从 3scale 打印出响应，本例中为 <error code="access_token_invalid">access_token "7c6f24f5" is invalid: expire 或 neverdefined</error>。
两者都将打印出原始请求(GET /api/contacts.json?access_token=7c6f24f5)和 subrequest 位置(/threescale_authrep)以及上游请求（upstream: "https://54.83.62.94:443/transactions/threescale_authrep.xml?provider_key=REDACTED&service_id=REDACTED&usage[hits]=1&access_token=7c6f24f5"） 通过这个最后一个值，您可以查看 3scale IP 中的哪些已被解决，以及向 3scale 发出的确切请求。
11.3.5. 3scale
11.3.5.1. 3scale 返回错误吗？
3scale 也可能可用，但会向您的 API 网关返回错误，防止调用进入您的 API。尝试直接在 3scale 中发出授权调用并检查响应。如果遇到错误，请检查 #troubleshooting-api-error-codes[Error Codes] 部分以查看问题所在。
11.3.5.2. 使用 3scale 调试标头
您还可以通过调用 X-3scale-debug 标头来打开 3scale 调试标头，例如：
curl -v -X GET "https://api.example.com/endpoint?user_key" X-3scale-debug:YOUR_SERVICE_TOKEN
这将返回带有 API 响应的以下标头：
X-3scale-matched-rules: /, /api/contacts.json < X-3scale-credentials: access_token=TOKEN_VALUE < X-3scale-usage: usage[hits]=2 < X-3scale-hostname: HOSTNAME_VALUE
11.3.5.3. 检查集成错误
您还可以检查管理门户中的集成错误，以检查是否报告流量到 3scale。请参阅 https://YOUR_DOMAIN-admin.3scale.net/apiconfig/errors。
集成错误的原因之一是在标头中发送凭据，并附带 下划线_in_headers 指令未在 server 块中启用。
11.3.6. 客户端 API 网关
11.3.6.1. API 网关是否可从公共互联网访问？
尝试将浏览器定向到网关服务器的 IP 地址（或域名）。如果此操作失败，请确保您已在相关端口上打开防火墙。
11.3.6.2. 客户端是否可访问 API 网关？
如果可能，尝试使用前面概述的方法之一（telnet、curl 等）从客户端连接到 API 网关。 如果连接失败，问题在于这两者之间的网络。
否则，您应该继续对 API 发出调用的客户端进行故障排除。
11.3.7. 客户端
11.3.7.1. 使用其他客户端测试相同的调用
如果请求没有返回预期结果，请使用不同的 HTTP 客户端进行测试。例如，如果您使用 Java HTTP 客户端调用 API，您会看到错误，使用 cURL 进行交叉检查。
您还可以通过客户端和网关之间的代理调用 API，以捕获客户端发送的确切参数和标头。
11.3.7.2. 检查客户端发送的流量
使用 Wireshark 等工具来查看客户端发出的请求。这样，您可以识别客户端是否在调用 API 以及请求的详细信息。
11.4. ActiveDocs 问题
当您从命令行调用 API 时，当通过 ActiveDocs 时，调用 会失败。
要启用 ActiveDocs 调用，我们通过我们的代理将这些内容发送出来。此代理会添加特定的标头，如果不需要它们，则有时会导致 API 上出现问题。要识别是否是这种情况，请尝试以下步骤：
11.4.1. 使用 petstore.swagger.io
swagger 在 petstore.swagger.io 处提供托管的 swagger-ui，您可以通过最新版本的 swagger-ui 测试您的 Swagger 规格和 API。如果 swagger-ui 和 ActiveDocs 都以同样方式失败，您可以排除 ActiveDocs 或 ActiveDocs 代理出现的任何问题，并将故障排除集中到您自己的规格上。或者，您可以检查 swagger-ui GitHub 存储库，以了解当前版本的 swagger-ui 是否存在已知问题。
11.4.2. 检查防火墙是否允许来自 ActiveDocs 代理的连接
我们建议您不要使用您的 API 将客户端的 IP 地址列入白名单。ActiveDocs 代理使用浮动 IP 地址来实现高可用性，目前没有机制通知对这些 IP 的任何更改。
11.4.3. 使用不正确的凭证调用 API
要确定 ActiveDocs 代理是否正常工作，一种方法是使用无效凭证调用您的 API。这将帮助您确认或排除 ActiveDocs 代理和 API 网关中的任何问题。
如果您从 API 调用中获取 403 代码（或者来自网关上为无效凭证配置的代码），问题在于您的 API，因为这些调用将到达您的网关。
11.4.4. 比较调用
要识别 ActiveDocs 与 ActiveDocs 外部调用之间的标头和参数差异，请通过 APItools 内部或运行作用域等服务运行调用。这将允许您在将 HTTP 调用发送到 API 之前检查并比较 HTTP 调用。然后，您将能够识别可能导致问题的请求中潜在的标头和/或参数。
11.5. 登录 NGINX
有关此内容的综合指南，请参阅 NGINX 日志和监控 文档。
11.5.1. 启用调试日志
要了解更多有关启用调试日志的信息，请参阅 NGINX 调试日志文档。
11.6. 3scale 错误代码
要重复检查 3scale Service Management API 端点返回的错误代码，请查看 3scale API 文档 页面，按照以下步骤执行：
- 单击位于管理门户右上角的问号(?)图标。
- 选择 3scale API 文档。
以下是 3scale 返回的 HTTP 响应代码列表，以及返回它们的条件：
400:错误请求.这可能是因为：
- 无效的编码
- 有效负载过大
-
内容类型无效（用于 POST 调用）。
Content-Type标头的有效值为：application/x-www-form-urlencoded、multipart/form-data或空标头。
403:
- 凭证无效
- 将正文数据发送到 3scale 的 GET 请求
- 404:引用的不存在的实体，如应用、指标等.
409:
- 超过用量限制
- 应用程序未激活
-
应用程序密钥无效或缺失（用于
app_id/app_key身份验证方法） - 不允许或缺少推荐器（当启用和需要引用器过滤器时）
- 422:缺少所需的参数
大多数错误响应也将包含 XML 正文，其中含有计算机可读的错误类别和人类可读的说明。
使用标准 API 网关配置时，任何与 3scale 提供的 200 不同的返回代码都可能会通过以下代码之一响应客户端：
- 403
- 404
