3.5. 使用操作器部署 APIcast 网关自助管理解决方案
本指南提供了通过 Openshift Container Platform 控制台使用 APIcast operator 部署 APIcast 网关自助管理解决方案的步骤。
部署 APIcast 时,默认设置适用于生产环境。您始终可以调整这些设置来部署 staging 环境。例如,使用以下 oc
命令:
$ oc patch apicast/{apicast_name} --type=merge -p '{"spec":{"deploymentEnvironment":"staging","configurationLoadMode":"lazy"}}'
如需更多信息,请参阅:APIcast 自定义资源参考
先决条件
- OpenShift 容器平台(OCP)4.x 或更高版本,具有管理员特权。
- 您遵循在 OpenShift 上安装 APIcast operator 中的步骤。
流程
- 使用具有管理员特权的帐户登录 OCP 控制台。
- 点 Operators > Installed Operators。
- 从 Installed Operators 列表中点 APIcast Operator。
- 点 APIcast > Create APIcast。
3.5.1. APIcast 部署和配置选项
您可以使用两种方法部署和配置 APIcast 网关自我管理解决方案:
另请参阅:
3.5.1.1. 提供 3scale 系统端点
流程
创建一个包含 3scale 系统管理门户端点信息的 OpenShift secret:
$ oc create secret generic ${SOME_SECRET_NAME} --from-literal=AdminPortalURL=${MY_3SCALE_URL}
-
${SOME_SECRET_NAME}
是 secret 的名称,只要它与现有 secret 不冲突,可以是您想要的任何名称。 ${MY_3SCALE_URL}
是包含 3scale 访问令牌和 3scale 系统门户端点的 URI。如需了解更多详细信息,请参阅THREESCALE_PORTAL_ENDPOINT
示例
$ oc create secret generic 3scaleportal --from-literal=AdminPortalURL=https://access-token@account-admin.3scale.net
有关机密内容的更多信息,请参阅 管理门户配置 secret 参考。
-
为 APIcast 创建 OpenShift 对象
apiVersion: apps.3scale.net/v1alpha1 kind: APIcast metadata: name: example-apicast spec: adminPortalCredentialsRef: name: SOME_SECRET_NAME
spec.adminPortalCredentialsRef.name
必须是包含 3scale 系统管理门户端点信息的现有 OpenShift secret 的名称。确认与 APIcast 对象关联的 OpenShift Deployment 的
readyReplicas
字段是否为 1,以验证 APIcast 容器集正在运行并已就绪。或者,等待字段设置为:$ echo $(oc get deployment apicast-example-apicast -o jsonpath='{.status.readyReplicas}') 1
3.5.1.1.1. 验证 APIcast 网关正在运行且可用
流程
确保 OpenShift Service APIcast 已公开给您的本地计算机,并执行测试请求。通过将 APIcast OpenShift Service 端口转发到
localhost:8080
来做到这一点:$ oc port-forward svc/apicast-example-apicast 8080
向配置的 3scale 服务发出请求,以验证 HTTP 响应是否成功。使用在服务的
Staging Public Base URL
或Production Public Base URL
设置中配置的域名。例如:$ curl 127.0.0.1:8080/test -H "Host: localhost" { "method": "GET", "path": "/test", "args": "", "body": "", "headers": { "HTTP_VERSION": "HTTP/1.1", "HTTP_HOST": "echo-api.3scale.net", "HTTP_ACCEPT": "*/*", "HTTP_USER_AGENT": "curl/7.65.3", "HTTP_X_REAL_IP": "127.0.0.1", "HTTP_X_FORWARDED_FOR": ... "HTTP_X_FORWARDED_HOST": "echo-api.3scale.net", "HTTP_X_FORWARDED_PORT": "80", "HTTP_X_FORWARDED_PROTO": "http", "HTTP_FORWARDED": "for=10.0.101.216;host=echo-api.3scale.net;proto=http" }, "uuid": "603ba118-8f2e-4991-98c0-a9edd061f0f0"
3.5.1.1.2. 通过 Kubernetes 入口公开 APIcast
要通过 Kubernetes Ingress 向外部公开 APIcast,请设置并配置 exposeHost
部分。当设置 exposeHost
部分中的 host
字段时,这会创建一个 Kubernetes Ingress 对象。然后,以前安装的和现有的 Kubernetes Ingress Controller 可以使用 Kubernetes Ingress 对象,使 APIcast 从外部访问。
要了解 Ingress Controller 可用于使 APIcast 外部访问,以及如何配置它们,请参阅 Kubernetes Ingress Controller 文档。
以下示例使用主机名 myhostname.com
公开 APIcast:
apiVersion: apps.3scale.net/v1alpha1 kind: APIcast metadata: name: example-apicast spec: ... exposedHost: host: "myhostname.com" ...
这个示例使用 HTTP 在端口 80 上创建一个 Kubernetes Ingress 对象。当 APIcast 部署位于 OpenShift 环境中时,OpenShift 默认 Ingress Controller 将使用 Ingress 对象 APIcast 创建 Route 对象,以允许从外部访问 APIcast 安装。
您也可以为 exposeHost
部分配置 TLS。下表中可用字段的详情:
json/yaml 项 | 类型 | 必填 | 默认值 | 描述 |
---|---|---|---|---|
| 字符串 | 是 | N/A | 路由到网关的域名 |
| []networkv1.IngressTLS | 否 | N/A | ingress TLS 对象的数组。请参阅 TLS 的更多信息。 |
3.5.1.2. 提供配置 secret
流程
使用配置文件创建 secret:
$ curl https://raw.githubusercontent.com/3scale/APIcast/master/examples/configuration/echo.json -o $PWD/config.json $ oc create secret generic apicast-echo-api-conf-secret --from-file=$PWD/config.json
配置文件必须名为
config.json
。这是一个 APIcast CRD 引用 要求。有关机密内容的更多信息,请参阅 管理门户配置 secret 参考。
创建 APIcast 自定义资源 :
$ cat my-echo-apicast.yaml apiVersion: apps.3scale.net/v1alpha1 kind: APIcast metadata: name: my-echo-apicast spec: exposedHost: host: YOUR DOMAIN embeddedConfigurationSecretRef: name: apicast-echo-api-conf-secret $ oc apply -f my-echo-apicast.yaml
以下是嵌入式配置 secret 的示例:
apiVersion: v1 kind: Secret metadata: name: SOME_SECRET_NAME type: Opaque stringData: config.json: | { "services": [ { "proxy": { "policy_chain": [ { "name": "apicast.policy.upstream", "configuration": { "rules": [{ "regex": "/", "url": "http://echo-api.3scale.net" }] } } ] } } ] }
在创建 APIcast 对象时设置以下内容:
apiVersion: apps.3scale.net/v1alpha1 kind: APIcast metadata: name: example-apicast spec: embeddedConfigurationSecretRef: name: SOME_SECRET_NAME
spec.embeddedConfigurationSecretRef.name
必须是包含网关配置的现有 OpenShift secret 的名称。确认与 APIcast 对象关联的 OpenShift Deployment 的
readyReplicas
字段是否为 1,以验证 APIcast 容器集正在运行并已就绪。或者,等待字段设置为:$ echo $(oc get deployment apicast-example-apicast -o jsonpath='{.status.readyReplicas}') 1
3.5.1.2.1. 验证 APIcast 网关正在运行且可用
流程
确保 OpenShift Service APIcast 已公开给您的本地计算机,并执行测试请求。通过将 APIcast OpenShift Service 端口转发到
localhost:8080
来做到这一点:$ oc port-forward svc/apicast-example-apicast 8080
3.5.1.3. 使用 APIcast operator 注入自定义虚拟环境
在使用自我管理的 APIcast 的 3scale 安装中,您可以使用 APIcast
operator 注入自定义环境。自定义环境定义 APIcast 适用于网关服务的所有上游 API 的行为。要创建自定义环境,请在 Lua 代码中定义全局配置。
您可以注入自定义环境,作为 APIcast 安装的一部分或安装后。在注入自定义环境后,您可以将其删除,APIcast
operator 会协调更改。
先决条件
- 已安装 APIcast operator。
流程
编写用于定义您要注入的自定义环境的 Lua 代码。例如,以下
env1.lua
文件显示APIcast
operator 为所有服务加载的自定义日志策略。local cjson = require('cjson') local PolicyChain = require('apicast.policy_chain') local policy_chain = context.policy_chain local logging_policy_config = cjson.decode([[ { "enable_access_logs": false, "custom_logging": "\"{{request}}\" to service {{service.id}} and {{service.name}}" } ]]) policy_chain:insert( PolicyChain.load_policy('logging', 'builtin', logging_policy_config), 1) return { policy_chain = policy_chain, port = { metrics = 9421 }, }
从定义自定义环境的 Lua 文件创建 secret。例如:
$ oc create secret generic custom-env-1 --from-file=./env1.lua
secret 可以包含多个自定义虚拟环境。为定义自定义环境的每个文件指定
-from-file
选项。Operator 会加载每个自定义环境。定义一个
APIcast
自定义资源,用于引用您刚才创建的 secret。以下示例显示了相对于引用定义自定义环境的 secret 的内容。apiVersion: apps.3scale.net/v1alpha1 kind: APIcast metadata: name: apicast1 spec: customEnvironments: - secretRef: name: custom-env-1
APIcast
自定义资源可以引用定义自定义虚拟环境的多个 secret。Operator 会加载每个自定义环境。创建
APIcast
自定义资源来添加自定义虚拟环境。例如,如果您在apicast.yaml
文件中保存APIcast
自定义资源,请运行以下命令:$ oc apply -f apicast.yaml
后续步骤
如果更新您的自定义环境,请确保重新创建其 secret,以便 secret 包含更新。APIcast
operator 会监视是否有更新,并在找到更新时自动重新部署。
3.5.1.4. 使用 APIcast operator 注入自定义策略
在使用自助管理的 APIcast 的 3scale 安装中,您可以使用 APIcast
operator 注入自定义策略。注入自定义策略会将策略代码添加到 APIcast。然后,您可以使用以下任一策略将自定义策略添加到 API 产品策略链中:
- 3scale API
-
产品
自定义资源
要使用 3scale 管理门户将自定义策略添加到产品策略链中,还必须使用 CustomPolicyDefinition
自定义资源注册自定义策略的 schema。自定义策略注册是只有在您要使用管理门户配置产品策略链时才需要。
您可以注入自定义策略,作为 APIcast 安装的一部分或之后。注入自定义策略后,您可以将其删除,并且 APIcast
运算符协调更改。
先决条件
- APIcast operator 已安装,或正在安装它。
-
您已定义一个自定义策略,如写您自己的策略中所述。即,已创建了定义自定义策略的
my-first-custom-policy.lua
、apicast-policy.json
和init.lua
文件,
流程
从定义一个自定义策略的文件创建 secret。例如:
$ oc create secret generic my-first-custom-policy-secret \ --from-file=./apicast-policy.json \ --from-file=./init.lua \ --from-file=./my-first-custom-policy.lua
如果您有多个自定义策略,请为每个自定义策略创建一个 secret。secret 只能包含一个自定义策略。
定义一个
APIcast
自定义资源,用于引用您刚才创建的 secret。以下示例显示有关引用定义自定义策略的 secret 的内容。apiVersion: apps.3scale.net/v1alpha1 kind: APIcast metadata: name: apicast1 spec: customPolicies: - name: my-first-custom-policy version: "0.1" secretRef: name: my-first-custom-policy-secret
APIcast
自定义资源可以引用定义自定义策略的多个 secret。Operator 加载每个自定义策略。创建
APIcast
自定义资源,以添加自定义策略。例如,如果您在apicast.yaml
文件中保存APIcast
自定义资源,请运行以下命令:$ oc apply -f apicast.yaml
后续步骤
如果更新自定义策略,请确保重新创建其 secret,以便 secret 包含更新。APIcast
operator 会监视是否有更新,并在找到更新时自动重新部署。
其他资源
3.5.1.5. 使用 APIcast operator 配置 OpenTracing
在使用自助管理的 APIcast 的 3scale 安装中,您可以使用 APIcast
operator 来配置 OpenTracing。通过启用 OpenTracing,您可以在 APIcast 实例上获取更多见解和更好的可观察性。
先决条件
-
APIcast
operator 已安装,或正在安装它。 - 前提条件在配置 APIcast 以使用 OpenTracing中列出。
- Jaeger 已安装。
流程
在
stringData.config
中包含您的 OpenTracing 配置详情的 secret。这是包含您的 OpenTracing 配置详细信息的属性的唯一有效值。任何其他规格都阻止 APIcast 收到您的 OpenTracing 配置详细信息。以下示例显示了一个有效的 secret 定义:apiVersion: v1 kind: Secret metadata: name: myjaeger stringData: config: |- { "service_name": "apicast", "disabled": false, "sampler": { "type": "const", "param": 1 }, "reporter": { "queueSize": 100, "bufferFlushInterval": 10, "logSpans": false, "localAgentHostPort": "jaeger-all-in-one-inmemory-agent:6831" }, "headers": { "jaegerDebugHeader": "debug-id", "jaegerBaggageHeader": "baggage", "TraceContextHeaderName": "uber-trace-id", "traceBaggageHeaderPrefix": "testctx-" }, "baggage_restrictions": { "denyBaggageOnInitializationFailure": false, "hostPort": "127.0.0.1:5778", "refreshInterval": 60 } } type: Opaque
创建 secret.例如,如果您将以前的 secret 定义保存到
myjaeger.yaml
文件中,您将运行以下命令:$ oc create -f myjaeger.yaml
定义一个
APIcast
自定义资源,指定OpenTracing
属性。在 CR 定义中,将spec.tracingConfigSecretRef.name
属性设置为包含您的 OpenTracing 配置详情的 secret 的名称。下例仅显示了与配置 OpenTracing 相关的内容。apiVersion: apps.3scale.net/v1alpha1 kind: APIcast metadata: name: apicast1 spec: ... openTracing: enabled: true tracingConfigSecretRef: name: myjaeger tracingLibrary: jaeger ...
创建配置 OpenTracing 的
APIManager
自定义资源。例如,如果您将APIcast
自定义资源保存在apicast1.yaml
文件中,您将运行以下命令:$ oc apply -f apicast1.yaml
后续步骤
根据 OpenTracing 的安装方式,您应该在 Jaeger 服务用户界面中看到 trace。
其他资源