Chapter 6. APIcast environment variables
APIcast environment variables allow you to modify behavior for APIcast. The following values are supported environment variables:
- Unsupported or deprecated environment variables are not listed
- Some environment variable functionality may have moved to APIcast policies
- 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: no value
Value: string
Example: http://forward-proxy:80
Defines a HTTP proxy to be used for connecting to services if a protocol-specific proxy is not specified. Authentication is not supported.
APICAST_ACCESS_LOG_BUFFER
Default: no value
Value: positive integer
Allows access log writes to be included in chunks of bytes. The result is fewer system calls, which improves the performance of the gateway.
APICAST_ACCESS_LOG_FILE
Default: stdout
Defines the file that will store the access logs.
APICAST_BACKEND_CACHE_HANDLER
Default: strict
Values: strict | resilient
Deprecated: Use the Caching policy instead.
Defines how the authorization cache behaves when backend is unavailable. Strict will remove cached application when backend is unavailable. Resilient will do so only on getting authorization denied from backend.
APICAST_CACHE_MAX_TIME
Default: 1m
Value: string
When the response is selected to be cached in the system, the value of this variable indicates the maximum time to be cached. If the cache-control header is not set, the time to be cached will be the defined one.
The format for this value is defined by the proxy_cache_valid
NGINX directive.
This parameter is only used by the APIs that are using a content caching policy and the request is eligible to be cached.
APICAST_CACHE_STATUS_CODES
Default: 200, 302
Value: string
When the response code from upstream matches one of the status codes defined in this environment variable, the response content is cached in NGINX. The caching time depends on one of these values: headers cache time value, or the maximum time defined by the APICAST_CACHE_MAX_TIME
environment variable.
This parameter is only used by the APIs that are using a content caching policy and the request is eligible to be cached.
APICAST_CONFIGURATION_CACHE
Default: 0
Value: integer
Specifies the interval (in seconds) that the configuration will be stored for. The value should be set to 0 (not compatible with boot value of APICAST_CONFIGURATION_LOADER
) or more than 60. For example, if APICAST_CONFIGURATION_CACHE
is set to 120, the gateway will reload the configuration from the API manager every 2 minutes (120 seconds). A value < 0 disables reloading.
APICAST_CONFIGURATION_LOADER
Values: boot | lazy
Default: lazy
Defines how to load the configuration. Boot will request the configuration to the API manager when the gateway starts. Lazy will load it on demand for each incoming request (to guarantee a complete refresh on each request APICAST_CONFIGURATION_CACHE
should be 0).
APICAST_CUSTOM_CONFIG
Deprecated: Use policies instead.
Defines the name of the Lua module that implements custom logic overriding the existing APIcast logic.
APICAST_ENVIRONMENT
Value: string[:]
Example: production:cloud-hosted
APIcast should load a list of environments (or paths), separated by colons (:
). This list can be used instead of -e
or --environment
parameter on the CLI and for example stored in the container image as default environment. Any value passed on the CLI overrides this variable.
APICAST_EXTENDED_METRICS
Default: false
Value: boolean
Example: "true"
Enables additional information on Prometheus metrics. The following metrics have the service_id
and service_system_name
labels which provide more in-depth details about APIcast:
-
total_response_time_seconds
-
upstream_response_time_seconds
-
upstream_status
APICAST_HTTPS_CERTIFICATE
Default: no value
Path to a file with X.509 certificate in the PEM format for HTTPS.
APICAST_HTTPS_CERTIFICATE_KEY
Default: no value
Path to a file with the X.509 certificate secret key in the PEM format.
APICAST_HTTPS_PORT
Default: no value
Controls on which port APIcast should start listening for HTTPS connections. If this clashes with HTTP port it will be used only for HTTPS.
APICAST_HTTPS_PROXY_PROTOCOL
Default: false Values: boolean Example: true
This parameter enables the Proxy Protocol for the HTTPS listener.
APICAST_HTTPS_VERIFY_DEPTH
Default: 1
Values: positive integers
Defines the maximum length of the client certificate chain. If this parameter has 1
as its value, it is possible to include an additional certificate in the client certificate chain. For example, root certificate authority.
APICAST_HTTP_PROXY_PROTOCOL
Default: false
Values: boolean
Example: true
This parameter enables the proxy protocol for the HTTP listener.
APICAST_LOAD_SERVICES_WHEN_NEEDED
In 3scale 2.14, the APICAST_LOAD_SERVICES_WHEN_NEEDED
environment variable has been removed. It is now active by default. See THREESCALE_PORTAL_ENDPOINT.
Default: false
Values:
-
true
or1
for true -
false
,0
or empty for false
This option can be used when there are many services configured. However, its performance depends on additional factors, for example, the number of services, the latency between APIcast and the 3scale Admin Portal, and the Time To Live (TTL) of the configuration.
By default, APIcast loads all the services each time it downloads its configuration from the Admin Portal. When this option is enabled, the configurations uses lazy loading. APIcast will only load the ones configured for the host specified in the host header of the request.
-
The caching defined by
APICAST_CONFIGURATION_CACHE
applies. -
This option will be disabled when
APICAST_CONFIGURATION_LOADER
isboot
. -
Not compatible with
APICAST_PATH_ROUTING
.
APICAST_LOG_FILE
Default: stderr
Defines the file that contains the OpenResty error log. The file is used by bin/apicast
in the error_log
directive. The file path can be either absolute, or relative to the APIcast prefix directory. Note that the default prefix directory is APIcast. Refer to NGINX documentation for more information.
APICAST_LOG_LEVEL
Default: warn
Values: debug | info | notice | warn | error | crit | alert | emerg
Specifies the log level for the OpenResty logs.
APICAST_MANAGEMENT_API
Values:
-
disabled
: completely disabled, just listens on the port -
status
: only the /status/ endpoints enabled for health checks -
debug
: full API is open
The Management API is powerful and can control the APIcast configuration. You should enable the debug level only for debugging.
APICAST_MODULE
Default: apicast
Deprecated: Use policies instead.
Specifies the name of the main Lua module that implements the API gateway logic. Custom modules can override the functionality of the default apicast.lua
module. See an example of how to use modules.
APICAST_OIDC_LOG_LEVEL
Values: debug | info | notice | warn | error | crit | alert | emerg
Default: err
Allows to set the log level for the logs related to OpenID Connect integration.
APICAST_PATH_ROUTING
Values:
-
true
or1
for true -
false
,0
or empty for false
When this parameter is set to true, the gateway will use path-based routing in addition to the default host-based routing. The API request will be routed to the first service that has a matching mapping rule, from the list of services for which the value of the Host
header of the request matches the Public Base URL.
APICAST_PATH_ROUTING_ONLY
Values:
-
true
or1
for true -
false
,0
or empty for false
When this parameter is set to true, the gateway uses path-based routing and will not fallback to the default host-based routing. The API request is routed to the first service that has a matching mapping rule, from the list of services for which the value of the Host
header of the request matches the Public Base URL.
This parameter has precedence over APICAST_PATH_ROUTING. If APICAST_PATH_ROUTING_ONLY
is enabled, APIcast will only do path-based routing regardless of the value of APICAST_PATH_ROUTING
.
APICAST_POLICY_BATCHER_SHARED_MEMORY_SIZE
Use the minimal value of 20m.
Default: 20m
Value: string
Sets the maximum size of shared memory used by batcher policy.
The accepted size units are k
and m
:
http { lua_shared_dict batched_reports 20m; ... }
APICAST_POLICY_LOAD_PATH
Default: APICAST_DIR/policies
Value: string[:]
Example: ~/apicast/policies:$PWD/policies
A colon (:
) separated list of paths where APIcast should look for policies. It can be used to first load policies from a development directory or to load examples.
APICAST_PROXY_HTTPS_CERTIFICATE
Default:
Value: string
Example: /home/apicast/my_certificate.crt
The path to the client SSL certificate that APIcast will use when connecting with the upstream. Notice that this certificate will be used for all the services in the configuration.
APICAST_PROXY_HTTPS_CERTIFICATE_KEY
Default:
Value: string
Example: /home/apicast/my_certificate.key
The path to the key of the client SSL certificate.
APICAST_PROXY_HTTPS_PASSWORD_FILE
Default:
Value: string
Example: /home/apicast/passwords.txt
Path to a file with passphrases for the SSL cert keys specified with APICAST_PROXY_HTTPS_CERTIFICATE_KEY
.
APICAST_PROXY_HTTPS_SESSION_REUSE
Default: on
Values:
-
on
: reuses SSL sessions. -
off
: does not reuse SSL sessions.
APICAST_REPORTING_THREADS
Default: 0
Value: integer >= 0
Experimental: Under extreme load might have unpredictable performance and lose reports.
Value greater than 0 is going to enable out-of-band reporting to backend. This is a new experimental feature for increasing performance. Client won’t see the backend latency and everything will be processed asynchronously. This value determines how many asynchronous reports can be running simultaneously before the client is throttled by adding latency.
APICAST_RESPONSE_CODES
Default: <empty> (false)
Values:
-
true
or1
for true -
false
,0
or empty for false
When set to true
, APIcast will log the response code of the response returned by the API backend in 3scale. For more information, see Setting up and evaluating the 3scale API Management response codes log for your API.
APICAST_SERVICE_CACHE_SIZE
Default: 1000
Values: integer >= 0
Specifies the number of services that APIcast can store in the internal cache. A high value has a performance impact because Lua’s lru
cache will initialize all the entries.
APICAST_SERVICE_${ID}_CONFIGURATION_VERSION
Replace ${ID}
with the actual Service ID. The value should be the configuration version you can see in the configuration history on the Admin Portal. Setting it to a particular version will prevent it from auto-updating and will always use that version.
APICAST_SERVICES_LIST
Value: a comma-separated list of service IDs
The APICAST_SERVICES_LIST environment variable is used to filter the services you configure in the 3scale API Manager. This only applies the configuration for specific services in the gateway, discarding those service identifiers that are not specified in the list. You can find service identifiers for your product in the Admin Portal under Products > [Your_product_name] > Overview, then see Configuration, Methods and Settings and the ID for API calls.
APICAST_SERVICES_FILTER_BY_URL
Value: a PCRE (Perl Compatible Regular Expression) such as .*.example.com
.
Filters the services configured in the 3scale API Manager.
This filter matches with the Public Base URL, either staging or production. Services that do not match the filter are discarded. If the regular expression cannot be compiled, no services are loaded.
If a service does not match but is included in the section called “APICAST_SERVICES_LIST”, the service will not be discarded.
Example 6.1. A Regexp filter applied to backend endpoints
The Regexp filter http://.*.foo.dev
is applied to the following backend endpoints:
In this case, 1
and 3
are configured in APIcast and 2
and 4
are discarded.
APICAST_UPSTREAM_RETRY_CASES
Values: error | timeout | invalid_header | http_500 | http_502 | http_503 | http_504 | http_403 | http_404 | http_429 | non_idempotent | off
This is only used when the retry policy is configured and specifies when a request to the upstream API should be retried. It accepts the same values as Nginx’s PROXY_NEXT_UPSTREAM Module.
APICAST_WORKERS
Default: auto
Values: integer | auto
This is the value that will be used in the nginx worker_processes
directive. By default, APIcast uses auto
, except for the development environment where 1
is used.
BACKEND_ENDPOINT_OVERRIDE
URI that overrides backend endpoint from the configuration. Useful when deploying outside OpenShift deployed AMP. Example: https://backend.example.com
.
HTTP_KEEPALIVE_TIMEOUT
Default: 75
Value: positive integers
Example: 1
This parameter sets a timeout during which a keep-alive client connection will stay open on the server side. The zero value disables keep-alive client connections.
By default, the gateway keeps HTTP_KEEPALIVE_TIMEOUT disabled. This configuration allows the use of the keepalive timeout from NGINX whose default value is 75 seconds.
http_proxy, HTTP_PROXY
Default: no value
Value: string
Example: http://forward-proxy:80
Defines a HTTP proxy to be used for connecting to HTTP services. Authentication is not supported.
https_proxy, HTTPS_PROXY
Default: no value
Value: string
Example: https://forward-proxy:443
Defines a HTTP proxy to be used for connecting to HTTPS services. Authentication is not supported.
no_proxy, NO_PROXY
Default: no value
Value: string\[,<string>\]; *
Example: foo,bar.com,.extra.dot.com
Defines a comma-separated list of hostnames and domain names for which the requests should not be proxied. Setting to a single *
character, which matches all hosts, effectively disables the proxy.
OPENSSL_VERIFY
Values:
-
0
,false
: disable peer verification -
1
,true
: enable peer verification
Controls the OpenSSL Peer Verification. It is off by default, because OpenSSL can’t use system certificate store. It requires custom certificate bundle and adding it to trusted certificates.
It is recommended to use https://github.com/openresty/lua-nginx-module#lua_ssl_trusted_certificate and point to to certificate bundle generated by export-builtin-trusted-certs.
OPENTRACING_CONFIG
This environment variable is used to determine the config file for the opentracing tracer, if OPENTRACING_TRACER
is not set, this variable will be ignored.
Each tracer has a default configuration file: * jaeger: conf.d/opentracing/jaeger.example.json
You can choose to mount a different configuration than the provided by default by setting the file path using this variable.
Example: /tmp/jaeger/jaeger.json
OPENTRACING_HEADER_FORWARD
Default: uber-trace-id
This environment variable controls the HTTP header used for forwarding opentracing information, this HTTP header will be forwarded to upstream servers.
OPENTRACING_TRACER
Example: jaeger
This environment variable controls which tracing library will be loaded, right now, there’s only one opentracing tracer available, jaeger
.
If empty, opentracing support will be disabled.
RESOLVER
Allows to specify a custom DNS resolver that will be used by OpenResty. If the RESOLVER
parameter is empty, the DNS resolver will be autodiscovered.
THREESCALE_CONFIG_FILE
Path to the JSON file with the configuration for the gateway. You must provide either THREESCALE_PORTAL_ENDPOINT or THREESCALE_CONFIG_FILE
for the gateway to run successfully. From these two environment variables, THREESCALE_CONFIG_FILE
takes precedence
To build the file with the configuration for the gateway, you have two alternatives depending on the number of services:
Use the available 3scale API endpoints:
Either Proxy Config Show, Proxy Config Show Latest, or Proxy Configs List. You must know the ID of the service. Use the following options:
-
Use the Proxy Configs List provider endpoint:
<schema>://<admin-portal>/admin/api/account/proxy_configs/<env>.json
- The endpoint returns all stored proxy configs of the provider, not only the latest of each service.
-
Iterate over the array of
proxy_configs
returned in JSON. -
Select the
proxy_config.content
whoseproxy_config.version
is the highest among allproxy_configs
with the sameproxy_config.content.id
. The ID is the one of the service.
-
Use the Proxy Configs List provider endpoint:
- Then, iterate over the services to build a configuration file. For this step, use the available 3scale API endpoints, or the equivalent 3scale toolbox commands.
When you deploy the gateway using a container image:
- Configure the file to the image as a read-only volume.
- Specify the path that indicates where you have mounted the volume.
You can find sample configuration files in examples folder.
THREESCALE_DEPLOYMENT_ENV
Default: production
Values: staging | production
The value of this environment variable defines the environment from which the configuration will be downloaded from; this is either 3scale staging or production, when using new APIcast.
The value will also be used in the header X-3scale-User-Agent
in the authorize/report requests made to 3scale Service Management API. It is used by 3scale solely for statistics.
THREESCALE_PORTAL_ENDPOINT
URI that includes your password and portal endpoint in the following format:
<schema>://<password>@<admin-portal>
.
where:
-
<password>
can be either the provider key or an access token for the 3scale Account Management API. -
<admin-portal>
is the URL address to log into the 3scale Admin Portal.
Example: https://access-token@account-admin.3scale.net
.
When the THREESCALE_PORTAL_ENDPOINT
environment variable is provided and APICAST_CONFIGURATION_LOADER
=boot
, the gateway downloads the configuration from 3scale on initializing. The configuration includes all the settings provided on the integration page of the APIs under [Your_product_name] > Integration.
You can also use this environment variable to create a single gateway with the Master Admin Portal.
To run the gateway successfully, you must provide either THREESCALE_PORTAL_ENDPOINT
or THREESCALE_CONFIG_FILE
. Note that THREESCALE_CONFIG_FILE
takes precedence over THREESCALE_PORTAL_ENDPOINT
.
In 3scale 2.14, the APICAST_LOAD_SERVICES_WHEN_NEEDED
environment variable has been removed. It is now active by default.
The configuration is fetched when needed by default. The following are logic specifications:
THREESCALE_PORTAL_ENDPOINT
does not include a path in the URL.APICAST_CONFIGURATION_LOADER
=boot
http://${THREESCALE_PORTAL_ENDPOINT}/admin/api/account/proxy_configs/<env>.json?version=latest
The
/admin/api/account/proxy_configs/${env}
endpoint is paginated.APICAST_CONFIGURATION_LOADER
=lazy
http://${THREESCALE_PORTAL_ENDPOINT}/admin/api/account/proxy_configs/<env>.json?host=<hostname_of_the_request>&version=latest
The
/admin/api/account/proxy_configs/${env}
endpoint is paginated.
THREESCALE_PORTAL_ENDPOINT
includes a path in the URL with the master endpoint, that is,/master/api/proxy/configs
APICAST_CONFIGURATION_LOADER
=boot
http://${THREESCALE_PORTAL_ENDPOINT}/<env>.json
This is for all services from master endpoint, which is the same as the current behavior.
APICAST_CONFIGURATION_LOADER
=lazy
http://${THREESCALE_PORTAL_ENDPOINT}/<env>.json?host=<hostname_of_the_request>
This is for all services that match host from master endpoint, which is the same as the current behavior.
APICAST_CONFIGURATION_LOADER =boot | APICAST_CONFIGURATION_LOADER =lazy | |
---|---|---|
endpoint has no path |
|
|
endpoint has a path |
|
|