第 7 章 APIcast 环境变量
APIcast 环境变量允许您修改 APIcast 的行为。以下值是受支持的环境变量:
- 不支持或已弃用的环境变量不会被列出
- 有些环境变量功能可能已移到 APIcast 策略
- all_proxy ALL_PROXY
- APICAST_ACCESS_LOG_FILE
- APICAST_BACKEND_CACHE_HANDLER
- 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_VERIFY_DEPTH
- 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_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_${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,ALL_PROXY
Default: no value Value: string Example: http://forward-proxy:80
定义要在未指定特定于协议的代理时用于连接服务的 HTTP 代理。不支持身份验证。
APICAST_ACCESS_LOG_FILE
Default: stdout
定义将存储访问日志的文件。
APICAST_BACKEND_CACHE_HANDLER
Values: strict | resilient
Default: strict
弃用 : 使用 缓存 策略。
定义当后端不可用时授权缓存的行为方式。当后端不可用时,请严格删除缓存的应用。弹性仅在从后端获取授权时才会这样做。
APICAST_CONFIGURATION_CACHE
值 :数字
默认 : 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
Default:
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_VERIFY_DEPTH
默认 : 1
值 :正整数。
定义客户端证书链的最大长度。如果此参数的值有 1
,则可以在客户端证书链中包含额外证书。例如,root 证书认证机构。
APICAST_LOAD_SERVICES_WHEN_NEEDED
Values:
-
true
或1
用于 true -
false
、0
或空用于 false
默认 :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
值 :debug | info | notice | warn | error | crit | alert | emerg
默认 :warn
指定 OpenResty 日志的日志级别。
APICAST_MANAGEMENT_API
Values:
-
disabled
:完全禁用,只侦听端口 -
status
:仅为健康检查启用 /status/ 端点 -
debug
:会打开完整的 API
管理 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_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
默认 : 0
值 :整数 >= 0
实验性: 在极端负载可能具有无法预计的性能并丢失报告。
大于 0 的值将启用对后端的带外报告。这是一个全新的 实验 功能,用于提高性能。客户端不会看到后端延迟,一切都将异步处理。这个值决定了在客户端因增加延迟而节流前可以同时运行多少异步报告。
APICAST_RESPONSE_CODES
值 :
-
true
或1
用于 true -
false
、0
或空用于 false
默认 :<empty>(false)
当设置为 true 时
,APIcast 将记录 3scale 中 API 后端返回的响应代码。在 3scale 客户门户网站上查找响应代码功能的更多信息。
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”一节 中,则不会丢弃该服务。
例 7.1. example
Regexp 过滤器 http://.*.foo.dev
应用到以下后端端点:
在这种情况下,1
和 3
在嵌入的 APIcast 和 2
中被丢弃。
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
值: number | 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: no value Value: string Example: http://forward-proxy:80
定义用于连接 HTTP 服务的 HTTP 代理。不支持身份验证。
HTTPS_PROXY,HTTPS_PROXY
Default: no value: string Example:https://forward-proxy:443
定义用于连接 HTTPS 服务的 HTTP 代理。不支持身份验证。
NO_PROXY,NO_PROXY
default: no value : string\[,<string>\]; *
Example: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
采用优先权。
Proxy Config Show 和 Proxy Config Show Latest 端点也按 service 和 Proxy Configs List 服务限定。您必须知道服务的 ID。使用以下选项:
使用 Proxy Configs List 供应商端点: <
schema>://<admin-portal-domain>/admin/api/account/proxy_configs/<env>.json
-
端点返回该提供程序的所有已存储代理配置,而不仅仅是每个服务的最新代理配置。迭代 JSON 返回的
proxy_configs
数组,并选择proxy_config.content
,其proxy_config.version
都是具有相同proxy_config.content.id
的所有代理配置之间的最高,即服务 ID。
-
端点返回该提供程序的所有已存储代理配置,而不仅仅是每个服务的最新代理配置。迭代 JSON 返回的
使用 Service List 端点:
/admin/api/services.json
- 端点列出了提供程序的所有服务。迭代服务的数组,每个服务都使用 Proxy Config Show Latest 端点,该端点由服务限定。
当使用容器镜像部署网关时:
- 将 文件配置为只读卷。
- 指定指示挂载卷的位置的路径。
您可以在 Example 文件夹中找到 示例 配置文件。
THREESCALE_DEPLOYMENT_ENV
值 : stage | production
默认 :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-domain>
.
其中:
示例 :https://access-token@account-admin.3scale.net
。
当提供了 THREESCALE_PORTAL_ENDPOINT
环境变量时,网关会在初始化时从 3scale 下载配置。配置包括 API 的 Integration 页面中提供的所有设置。
您还可以使用此环境变量 创建具有主管理门户的单一网关。
需要为 网关提供成功运行的 THREESCALE_PORTAL_ENDPOINT
或 THREESCALE_CONFIG_FILE
(优先)。