第 6 章 APIcast 环境变量
APIcast 环境变量允许您修改 APIcast 的行为。以下值是受支持的环境变量:
- 不支持或已弃用的环境变量不会被列出
- 有些环境变量功能可能已移到 APIcast 策略
- all_proxy, ALL_PROXY
- APICAST_ACCESS_LOG_BUFFER
- APICAST_ACCESS_LOG_FILE
- APICAST_BACKEND_CACHE_HANDLER
- APICAST_CACHE_MAX_TIME
- APICAST_CACHE_STATUS_CODES
- APICAST_CONFIGURATION_CACHE
- APICAST_CONFIGURATION_LOADER
- APICAST_CUSTOM_CONFIG
- APICAST_ENVIRONMENT
- APICAST_EXTENDED_METRICS
- APICAST_HTTPS_CERTIFICATE
- APICAST_HTTPS_CERTIFICATE_KEY
- APICAST_HTTPS_PORT
- APICAST_HTTPS_PROXY_PROTOCOL
- APICAST_HTTPS_VERIFY_DEPTH
- APICAST_HTTP_PROXY_PROTOCOL
- APICAST_LOAD_SERVICES_WHEN_NEEDED
- APICAST_LOG_FILE
- APICAST_LOG_LEVEL
- APICAST_MANAGEMENT_API
- APICAST_MODULE
- APICAST_OIDC_LOG_LEVEL
- APICAST_PATH_ROUTING
- APICAST_PATH_ROUTING_ONLY
- APICAST_POLICY_BATCHER_SHARED_MEMORY_SIZE
- APICAST_POLICY_LOAD_PATH
- APICAST_PROXY_HTTPS_CERTIFICATE
- APICAST_PROXY_HTTPS_CERTIFICATE_KEY
- APICAST_PROXY_HTTPS_PASSWORD_FILE
- APICAST_PROXY_HTTPS_SESSION_REUSE
- APICAST_REPORTING_THREADS
- APICAST_RESPONSE_CODES
- APICAST_SERVICE_CACHE_SIZE
- APICAST_SERVICE_${ID}_CONFIGURATION_VERSION
- APICAST_SERVICES_LIST
- APICAST_SERVICES_FILTER_BY_URL
- APICAST_UPSTREAM_RETRY_CASES
- APICAST_WORKERS
- BACKEND_ENDPOINT_OVERRIDE
- HTTP_KEEPALIVE_TIMEOUT
- http_proxy HTTP_PROXY
- https_proxy HTTPS_PROXY
- no_proxy NO_PROXY
- OPENSSL_VERIFY
- OPENTRACING_CONFIG
- OPENTRACING_HEADER_FORWARD
- OPENTRACING_TRACER
- RESOLVER
- THREESCALE_CONFIG_FILE
- THREESCALE_DEPLOYMENT_ENV
- THREESCALE_PORTAL_ENDPOINT
ALL_PROXY
Default: 没有值
值 :字符串
定义要在未指定特定于协议的代理时用于连接服务的 HTTP 代理。不支持身份验证。
APICAST_ACCESS_LOG_BUFFER
Default: 没有值
value: 正整数
允许以字节的块的形式包含访问日志写入。结果为更少的系统调用,这可以提高网关的性能。
APICAST_ACCESS_LOG_FILE
Default: stdout
定义将存储访问日志的文件。
APICAST_BACKEND_CACHE_HANDLER
Default: strict
Values: strict | resilient
弃用 :使用 缓存策略。
定义当后端不可用时授权缓存的行为方式。当后端不可用时,请严格删除缓存的应用。弹性仅在从后端获取授权时才会这样做。
APICAST_CACHE_MAX_TIME
默认: 1m
Value: 字符串
在系统中选择要缓存的响应时,此变量的值表示要缓存的最长时间。如果未设置 cache-control 标头,则缓存的时间将是定义的标头。
此值的格式由 proxy_cache_valid
NGINX 指令定义。
此参数仅供使用内容缓存策略的 API 使用,并且请求符合缓存条件。
APICAST_CACHE_STATUS_CODES
默认: 200, 302
Value: 字符串
当上游的响应代码与此环境变量中定义的一个状态代码匹配时,响应内容将缓存在 NGINX 中。缓存时间取决于其中一个值:标头缓存时间值或 APICAST_CACHE_MAX_TIME
环境变量定义的最长时间。
此参数仅供使用内容缓存策略的 API 使用,并且请求符合缓存条件。
APICAST_CONFIGURATION_CACHE
Default :0
值 :整数
指定配置要存储的时间间隔(以秒为单位)。该值应设置为 0(不兼容 APICAST_CONFIGURATION_LOADER
的引导值)或超过 60 个。例如,如果 APICAST_CONFIGURATION_CACHE
设为 120,则网关将每 2 分钟从 API 管理器重新加载配置(120 秒)。值 < 0 禁用重新加载。
APICAST_CONFIGURATION_LOADER
值 :boot | lazy
默认 : lazy
定义如何加载配置。启动将在网关启动时向 API 管理器请求配置。lazy 将根据每个传入请求按需加载(保证对每个请求 APICAST_CONFIGURATION_CACHE 应该为
0 完全刷新)。
APICAST_CUSTOM_CONFIG
弃用 :使用 策略。
定义实施自定义逻辑的 Lua 模块的名称,覆盖现有的 APIcast 逻辑。
APICAST_ENVIRONMENT
Value: string[:]
示例 :production:cloud-hosted
APIcast 应加载以冒号(:
)分隔的环境(或路径)列表。此列表可以替代 CLI 上的 -e
或 --environment
参数,例如,存储在容器镜像中作为默认环境。CLI 上传递的任何值都会覆盖此变量。
APICAST_EXTENDED_METRICS
默认 :false
值 :布尔值
示例 :"true"
启用 Prometheus 指标的附加信息。以下指标有 service_id
和 service_system_name
标签,它们提供了有关 APIcast 的更多深入详情:
-
total_response_time_seconds
-
upstream_response_time_seconds
-
upstream_status
APICAST_HTTPS_CERTIFICATE
Default: 没有值
HTTPS 的 PEM 格式带有 X.509 证书的文件路径。
APICAST_HTTPS_CERTIFICATE_KEY
Default: 没有值
使用 PEM 格式的 X.509 证书 secret 密钥的文件路径。
APICAST_HTTPS_PORT
Default: 没有值
控制哪些端口 APIcast 应开始侦听 HTTPS 连接。如果此冲突与 HTTP 端口冲突,它将仅用于 HTTPS。
APICAST_HTTPS_PROXY_PROTOCOL
Default: false Values: boolean Example: true
此参数为 HTTPS 侦听器启用代理协议。
APICAST_HTTPS_VERIFY_DEPTH
默认: 1
值 :正整数
定义客户端证书链的最大长度。如果此参数的值有 1
,则可以在客户端证书链中包含额外证书。例如,root 证书认证机构。
APICAST_HTTP_PROXY_PROTOCOL
默认: false
值 : 布尔值
示例: true
此参数为 HTTP 侦听器启用代理协议。
APICAST_LOAD_SERVICES_WHEN_NEEDED
在 3scale 2.14 中,删除了 APICAST_LOAD_SERVICES_WHEN_NEEDED
环境变量。现在,它被默认处于活跃状态。请参阅 THREESCALE_PORTAL_ENDPOINT。
默认 :false
Values:
-
true
或1
用于 true -
false
、0
或空用于 false
当配置了多个服务时,可以使用此选项。但是,其性能取决于其他因素,例如服务数量、APIcast 和 3scale 管理门户之间的延迟,以及配置的生存时间(TTL)。
默认情况下,APIcast 每次从管理门户下载其配置时加载所有服务。启用这个选项后,配置将使用延迟加载。APIcast 将仅加载为请求的主机标头中指定的主机配置的主机。
-
应用的
APICAST_CONFIGURATION_CACHE
定义的缓存。 -
当
APICAST_CONFIGURATION_LOADER
是boot
时将禁用此选项。 -
与
APICAST_PATH_ROUTING
不兼容。
APICAST_LOG_FILE
默认 : stderr
定义包含 OpenResty 错误日志的 文件。文件供 error_log
指令中的 bin/apicast
使用。文件路径可以是绝对的,也可以是相对于 APIcast 前缀目录。请注意,默认前缀目录为 APIcast。如需更多信息,请参阅 NGINX 文档。
APICAST_LOG_LEVEL
默认 :warn
值 :debug | info | notice | warn | error | crit | alert | emerg
指定 OpenResty 日志的日志级别。
APICAST_MANAGEMENT_API
Values:
-
disabled
:完全禁用,只侦听端口。 -
Status
: 为健康检查启用/status/
端点,以及显示可用策略列表的/policies
端点。 -
policies
:仅启用/policies
端点。 -
Debug
: full API 为 open。
管理 API 功能强大,可以控制 APIcast 配置。您应该只为调试启用 debug 级别。
APICAST_MODULE
默认 :apicast
弃用 :使用 策略。
指定实施 API 网关逻辑的主 Lua 模块的名称。自定义模块可以覆盖默认 apicast.lua
模块的功能。请参阅有关如何使用模块的示例。
APICAST_OIDC_LOG_LEVEL
值 :debug | info | notice | warn | error | crit | alert | emerg
默认 :err
允许为与 OpenID Connect 集成相关的日志设置日志级别。
APICAST_PATH_ROUTING
值 :
-
true
或1
用于 true -
false
、0
或空用于 false
当此参数设置为 true 时,除了基于主机的默认路由外,网关还将使用基于路径的路由。API 请求将从请求的 Host
标头值与公共基础 URL 匹配的服务列表中路由到具有匹配映射规则的第一个服务。
APICAST_PATH_ROUTING_ONLY
值 :
-
true
或1
用于 true -
false
、0
或空用于 false
当此参数设置为 true 时,网关将使用基于路径的路由,并且不会回退到基于主机的默认路由。API 请求将从请求的 Host
标头值与公共基础 URL 匹配的服务列表中路由到具有匹配映射规则的第一个服务。
此参数的优先级高于 APICAST_PATH_ROUTING。如果启用了 APICAST_PATH_ROUTING_ONLY
,APIcast 将只执行基于路径的路由,无论 APICAST_PATH_ROUTING
的值为何。
APICAST_POLICY_BATCHER_SHARED_MEMORY_SIZE
使用最小值 20m。
默认 :20m
值 :字符串
设置批处理程序策略使用的最大共享内存量。
接受的大小单位是 k
和 m
:
http { lua_shared_dict batched_reports 20m; ... }
APICAST_POLICY_LOAD_PATH
默认:APICAST_DIR/policies
Value: string[:]
示例 :~/apicast/policies:$PWD/policies
冒号(:
)分隔的路径列表,APIcast 应该在其中查找策略。它可用于首先从开发目录加载策略或加载示例。
APICAST_PROXY_HTTPS_CERTIFICATE
Default:
值 :字符串
示例 :/home/apicast/my_certificate.crt
APIcast 与上游连接时将使用的客户端 SSL 证书的路径。请注意,此证书将用于配置中的所有服务。
APICAST_PROXY_HTTPS_CERTIFICATE_KEY
Default:
值 :字符串
示例 :/home/apicast/my_certificate.key
客户端 SSL 证书密钥的路径。
APICAST_PROXY_HTTPS_PASSWORD_FILE
Default:
值 :字符串
示例 :/home/apicast/passwords.txt
使用 APICAST_PROXY_HTTPS_CERTIFICATE_KEY
指定 SSL 证书密钥的密语文件的路径。
APICAST_PROXY_HTTPS_SESSION_REUSE
默认 : on
值 :
-
on
:重用 SSL 会话。 -
off
:不重复使用 SSL 会话。
APICAST_REPORTING_THREADS
Default :0
值 :整数 >= 0
实验性 :在极端负载下,可能会有无法预计的性能并丢失报告。
大于 0 的值将启用对后端的带外报告。这是一个全新的 实验 功能,用于提高性能。客户端不会看到后端延迟,一切都将异步处理。这个值决定了在客户端因增加延迟而节流前可以同时运行多少异步报告。
APICAST_RESPONSE_CODES
默认 :<empty>(false)
值 :
-
true
或1
用于 true -
false
、0
或空用于 false
当设置为 true 时
,APIcast 将记录 3scale 中 API 后端返回的响应代码。如需更多信息,请参阅为 API 设置和评估 3scale API 管理响应代码日志。
APICAST_SERVICE_CACHE_SIZE
默认: 1000
值 :整数 >= 0
指定 APIcast 可存储在内部缓存中的服务数量。高值会影响性能,因为 Lua 的 lru
缓存将初始化所有条目。
APICAST_SERVICE_${ID}_CONFIGURATION_VERSION
将 ${ID}
替换为实际的服务 ID。该值应当是您可以在管理门户的配置历史记录中看到的配置版本。将它设置为特定版本将阻止它自动更新,并且始终使用该版本。
APICAST_SERVICES_LIST
value :以逗号分隔的服务 ID 列表
APICAST_SERVICES_LIST 环境变量用于过滤您在 3scale API Manager 中配置的服务。这仅应用网关中特定服务的配置,从而丢弃未在列表中指定的服务标识符。您可以在 Products > [Your_product_name] > Overview 下的 Admin Portal 中找到您的产品的服务标识符,然后参阅 Configuration、Methods 和 Settings 以及 API 调用的 ID。
APICAST_SERVICES_FILTER_BY_URL
值 :PCRE(Perl 兼容正则表达式),如 *.example.com
。
过滤 3scale API Manager 中配置的服务。
此过滤器与公共基本 URL 匹配,可以是暂存或生产。与过滤器不匹配的服务将被丢弃。如果无法编译正则表达式,则不会加载任何服务。
如果服务不匹配但包含在 “APICAST_SERVICES_LIST”一节 中,则不会丢弃该服务。
例 6.1. 应用到后端端点的 Regexp 过滤器
Regexp 过滤器 http://.*.foo.dev
应用到以下后端端点:
在这种情况下,1
和 3
在 APIcast 中配置,2
和 4
将被丢弃。
APICAST_UPSTREAM_RETRY_CASES
值: error | timeout | invalid_header | http_500 | http_502 | http_503 | http_504 | http_403 | http_404 | http_429 | non_idempotent | off
这只在配置了重试策略并且指定何时应重试对上游 API 的请求时使用。它接受与 Nginx 的 PROXY_NEXT_UPSTREAM 模块 相同的值。
APICAST_WORKERS
默认 :auto
值: integer | auto
这是 nginx worker_processes
指令 中使用的值。默认情况下,APIcast 使用 auto
,但使用 1
的开发环境除外。
BACKEND_ENDPOINT_OVERRIDE
从配置覆盖后端端点的 URI。在 OpenShift 外部部署 AMP 时非常有用.示例:https://backend.example.com
.
HTTP_KEEPALIVE_TIMEOUT
默认: 75
值 :正整数
示例 :1
此参数设置一个超时,期间 keep-alive 客户端连接将在服务器端保持打开状态。零值禁用 keep-alive 客户端连接。
默认情况下,网关会禁用 HTTP_KEEPALIVE_TIMEOUT。此配置允许使用默认值为 75 秒 的 NGINX 中保留超时。
HTTP_PROXY,HTTP_PROXY
Default: 没有值
值 :字符串
定义用于连接 HTTP 服务的 HTTP 代理。不支持身份验证。
HTTPS_PROXY,HTTPS_PROXY
Default: 没有值
值 :字符串
定义用于连接 HTTPS 服务的 HTTP 代理。不支持身份验证。
NO_PROXY,NO_PROXY
Default: 没有值
值: string\[,<string>\]; *
示例 :foo,bar.com,.extra.dot.com
定义不应代理请求的主机名和域名的逗号分隔列表。设置为单个 *
字符(匹配所有主机)有效禁用代理。
OPENSSL_VERIFY
值 :
-
0
,false
: 禁用对等验证 -
1,
true
:启用对等验证
控制 OpenSSL 对等验证.它默认为 off,因为 OpenSSL 无法使用系统证书存储。它需要自定义证书捆绑包并将其添加到可信证书中。
建议您使用 https://github.com/openresty/lua-nginx-module#lua_ssl_trusted_certificate 并指向由 export-builtin-trusted-certs 生成的证书捆绑包。
OPENTRACING_CONFIG
此环境变量用于决定 opentracing tracer 的配置文件,如果未设置 OPENTRACING_TRACER
,则忽略此变量。
每个 tracer 都有一个默认配置文件:* jaeger: conf.d/opentracing/jaeger.example.json
通过使用此变量设置文件路径,您可以选择挂载与默认情况下提供的不同的配置。
示例 :/tmp/jaeger/jaeger.json
OPENTRACING_HEADER_FORWARD
默认 :uber-trace-id
此环境变量控制用于转发 Opentracing 信息的 HTTP 标头,此 HTTP 标头将转发到上游服务器。
OPENTRACING_TRACER
示例 :jaeger
此环境变量控制将加载的追踪库,现在只有一个打开追踪器可用,即 jaeger
。
如果为空,将禁用 opentracing 支持。
RESOLVER
允许指定将由 OpenResty 使用的自定义 DNS 解析器。如果 RESOLVER
参数为空,则会自动发现 DNS 解析器。
THREESCALE_CONFIG_FILE
带有网关配置的 JSON 文件的路径。您必须提供 THREESCALE_PORTAL_ENDPOINT 或 THREESCALE_CONFIG_FILE
才能成功运行网关。从这两个环境变量中,THREESCALE_CONFIG_FILE
优先
要使用网关配置来构建文件,根据服务数量,有两个替代方案:
使用可用的 3scale API 端点:
Proxy Config Show、Proxy Config Show Latest,或 Proxy Configs 列表。您必须知道服务的 ID。使用以下选项:
-
使用 Proxy Configs List 供应商端点: <
schema>://<admin-portal>/admin/api/account/proxy_configs/<env>.json
- 端点会返回供应商的所有存储代理配置,而不只返回每个服务的最新内容。
-
迭代 JSON 中返回的
proxy_configs
数组。 -
选择
proxy_config.content
,其proxy_config.version
是具有相同proxy_config.content.id
的所有proxy_configs
最高。ID 是服务之一。
-
使用 Proxy Configs List 供应商端点: <
- 然后,迭代服务以构建配置文件。在这一步中,使用可用的 3scale API 端点或等同的 3scale toolbox 命令。
当使用容器镜像部署网关时:
- 将 文件配置为只读卷。
- 指定指示挂载卷的位置的路径。
您可以在 Example 文件夹中找到 示例 配置文件。
THREESCALE_DEPLOYMENT_ENV
默认 :production
值 : stage | production
此环境变量的值定义从中下载配置的环境;在使用新 APIcast 时是 3scale staging 或 production。
这个值也会在对 3scale Service Management API 的 authorize/report 请求的 header X-3scale-User-Agent
中使用。3scale 仅将它用于统计数据目的。
THREESCALE_PORTAL_ENDPOINT
以以下格式包含密码和门户端点的 URI:
<schema>://<password>@<admin-portal>
.
其中:
示例 :https://access-token@account-admin.3scale.net
.
当提供了 THREESCALE_PORTAL_ENDPOINT
环境变量并且 APICAST_CONFIGURATION_LOADER
=boot
时,网关会在初始化时从 3scale 下载配置。配置包括在 [Your_product_name] > Integration 下 API 集成页面中提供的所有设置。
您还可以使用此环境变量 创建具有主管理门户的单一网关。
要成功运行网关,您必须提供 THREESCALE_PORTAL_ENDPOINT
或 THREESCALE_CONFIG_FILE
。请注意,THREESCALE_CONFIG_FILE
优先于 THREESCALE_PORTAL_ENDPOINT
。
在 3scale 2.14 中,删除了 APICAST_LOAD_SERVICES_WHEN_NEEDED
环境变量。现在,它被默认处于活跃状态。
默认情况下,获取配置。以下是逻辑规格:
THREESCALE_PORTAL_ENDPOINT
不在 URL 中包含路径。APICAST_CONFIGURATION_LOADER
=boot
http://${THREESCALE_PORTAL_ENDPOINT}/admin/api/account/proxy_configs/<env>.json?version=latest
/admin/api/account/proxy_configs/${env}
端点被分页。APICAST_CONFIGURATION_LOADER
=lazy
http://${THREESCALE_PORTAL_ENDPOINT}/admin/api/account/proxy_configs/<env>.json?host=<hostname_of_the_request>&version=latest
/admin/api/account/proxy_configs/${env}
端点被分页。
THREESCALE_PORTAL_ENDPOINT
在 URL 中包含一个带有 master 端点的路径,即/master/api/proxy/configs
APICAST_CONFIGURATION_LOADER
=boot
http://${THREESCALE_PORTAL_ENDPOINT}/<env>.json
这适用于来自 master 端点的所有服务,这与当前的行为相同。
APICAST_CONFIGURATION_LOADER
=lazy
http://${THREESCALE_PORTAL_ENDPOINT}/<env>.json?host=<hostname_of_the_request>
这适用于与 master 端点的主机匹配的所有服务,这与当前的行为相同。
APICAST_CONFIGURATION_LOADER =boot | APICAST_CONFIGURATION_LOADER =lazy | |
---|---|---|
端点没有路径 |
|
|
端点有一个路径 |
|
|