Menu Close

第 7 章 APIcast 环境变量

APIcast 环境变量允许您修改 APIcast 的行为。以下值是受支持的环境变量:

注意
  • 不支持或已弃用的环境变量不会被列出
  • 有些环境变量功能可能已移到 APIcast 策略

all_proxy,ALL_PROXY

Default: no value Value: string Example: http://forward-proxy:80

定义要在未指定特定于协议的代理时用于连接服务的 HTTP 代理。不支持身份验证。

APICAST_ACCESS_LOG_BUFFER

Default: 没有值

value: 正整数

允许以字节的块的形式包含访问日志写入。结果为更少的系统调用,这可以提高网关的性能。

APICAST_ACCESS_LOG_FILE

Default: stdout

定义将存储访问日志的文件。

APICAST_BACKEND_CACHE_HANDLER

Values: strict | resilient

Default: strict

Deprecated:改为使用 Caching 策略。

定义当后端不可用时授权缓存的行为方式。当后端不可用时,请严格删除缓存的应用。弹性仅在从后端获取授权时才会这样做。

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

Deprecated:改为使用 策略

定义实施自定义逻辑的 Lua 模块的名称,覆盖现有的 APIcast 逻辑。

APICAST_ENVIRONMENT

Default:

Value: string[:]

示例 :production:cloud-hosted

APIcast 应加载以冒号(:)分隔的环境(或路径)列表。此列表可以替代 CLI 上的 -e--environment 参数,例如,存储在容器镜像中作为默认环境。CLI 上传递的任何值都会覆盖此变量。

APICAST_EXTENDED_METRICS

默认 :false

:布尔值

示例 :"true"

启用 Prometheus 指标的附加信息。以下指标有 service_idservice_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

Default:1

:正整数。

定义客户端证书链的最大长度。如果此参数的值有 1,则可以在客户端证书链中包含额外证书。例如,root 证书认证机构。

APICAST_LOAD_SERVICES_WHEN_NEEDED

Values:

  • true1 用于 true
  • false0 或空用于 false

默认false

当配置了多个服务时,可以使用此选项。但是,其性能取决于其他因素,例如服务数量、APIcast 和 3scale 管理门户之间的延迟,以及配置的生存时间(TTL)。

默认情况下,APIcast 每次从管理门户下载其配置时加载所有服务。启用这个选项后,配置将使用延迟加载。APIcast 将仅加载为请求的主机标头中指定的主机配置的主机。

注意

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

Deprecated:改为使用 策略

指定实施 API 网关逻辑的主 Lua 模块的名称。自定义模块可以覆盖默认 apicast.lua 模块的功能。请参阅有关如何使用模块的示例

APICAST_OIDC_LOG_LEVEL

:debug | info | notice | warn | error | crit | alert | emerg

默认 :err

允许为与 OpenID Connect 集成相关的日志设置日志级别。

APICAST_PATH_ROUTING

  • true1 用于 true
  • false0 或空用于 false

当此参数设置为 true 时,除了基于主机的默认路由外,网关还将使用基于路径的路由。API 请求将从请求的 Host 标头值与公共基础 URL 匹配的服务列表中路由到具有匹配映射规则的第一个服务。

APICAST_PATH_ROUTING_ONLY

  • true1 用于 true
  • false0 或空用于 false

当此参数设置为 true 时,网关将使用基于路径的路由,并且不会回退到基于主机的默认路由。API 请求将从请求的 Host 标头值与公共基础 URL 匹配的服务列表中路由到具有匹配映射规则的第一个服务。

此参数的优先级高于 APICAST_PATH_ROUTING。如果启用了 APICAST_PATH_ROUTING_ONLY,APIcast 将只执行基于路径的路由,无论 APICAST_PATH_ROUTING 的值为何。

APICAST_POLICY_LOAD_PATH

Default: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

  • true1 用于 true
  • false0 或空用于 false

默认 :<empty>(false)

当设置为 true 时,APIcast 将记录 3scale 中 API 后端返回的响应代码。如需更多信息,请参阅 为您的 API 设置和评估 3scale 响应代码日志

APICAST_SERVICE_CACHE_SIZE

:整数 >= 0

Default:1000

指定 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”一节 中,则不会丢弃该服务。

例 7.1. 应用到后端端点的 Regexp 过滤器

Regexp 过滤器 http://.*.foo.dev 应用到以下后端端点:

在这种情况下,13 在 APIcast 中配置,24 将被丢弃。

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

Default: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_ENDPOINTTHREESCALE_CONFIG_FILE 才能成功运行网关。从这两个环境变量中,THREESCALE_CONFIG_FILE 优先

要使用网关配置来构建文件,根据服务数量,有两个替代方案:

  • 选项 1.使用 URL 从管理门户下载配置:

    <schema>://<admin-portal-domain>/admin/api/nginx/spec.json

    请考虑以下几点:

    • 在超过 20 个服务后,端点会受到限制。
    • 您可以在 https://account-admin.3scale.net/admin/api/nginx/spec.json中看到示例:
  • 选项 2.使用可用的 3scale API 端点:

    • Proxy Config ShowProxy Config Show Latest.
    • 然后,迭代服务以构建配置文件。在这一步中,使用可用的 3scale API 端点或等同的 3scale toolbox 命令

当使用容器镜像部署网关时:

  1. 将 文件配置为只读卷。
  2. 指定指示挂载卷的位置的路径。

您可以在 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>.

其中:

  • <password> 可以是 3scale 帐户管理 API 的供应商密钥访问令牌
  • <admin-portal-domain> 是要登录到 3scale 管理门户的 URL 地址。

示例https://access-token@account-admin.3scale.net

当提供了 THREESCALE_PORTAL_ENDPOINT 环境变量时,网关会在初始化时从 3scale 下载配置。配置包括 API 的 Integration 页面中提供的所有设置。

您还可以使用此环境变量 创建具有主管理门户的单一网关

需要为 网关提供成功运行的 THREESCALE_PORTAL_ENDPOINTTHREESCALE_CONFIG_FILE (优先)。