Chapter 7. APIcast Environment Variables

APICAST_LOG_FILE

The APICAST_LOG_FILE variable defines the file that will store the OpenResty web platform error log used by the bin/apicast error_log directive. Refer to the NGINX documentation for more information. The file path can either be absolute or relative to the prefix directory. The default prefix directory is apicast.

stderr

must be a valid file path

APICAST_LOG_LEVEL

The APICAST_LOG_LEVEL variable specifies the log level for the OpenResty web platform logs.

Warn

debug, info, notice, warn, error, crit, alert, emerg

APICAST_CONFIGURATION_LOADER

The APICAST_CONFIGURATION_LOADER variable specifies which method APIcast should use when it loads its configuration. The boot method requests configuration from the API manager when the gateway starts. The lazy method loads configuration in real-time with each incoming request. If you want to refresh configuration with each request, you must specify the lazy method and set the APICAST_CONFIGURATION_CACHE variable to 0.

lazy

boot, lazy

APICAST_RESPONSE_CODES

When the APICAST_RESPONSE_CODES variable is set to true, APIcast will log response codes returned by the API backend in 3scale. In some plans this information can later be consulted from the 3scale admin portal. Find more information about the Response Codes feature in the response codes tracking section of the 3scale documentation.

false

true or 1 for true, 0 or empty for false

APICAST_CONFIGURATION_CACHE

Specifies the duration, in seconds, in which APIcast will store the configuration. Red Hat 3scale recommends you set the value to either 0 or greater than 60. If you are using the APICAST_CONFIGURATION_LOADER boot method, you must set the value to a value greater than 60. For example, if APICAST_CONFIGURATION_CACHE is set to 120, the gateway will reload the configuration from the API manager every 120 seconds.

0

any number greater than 60

REDIS_HOST

APIcast requires a running Redis in memory database instance for the OAuth 2.0 Authorization code flow. The REDIS_HOST parameter is used to set the IP of the Redis in memory database instance.

127.0.0.1

Any valid IP

REDIS_PORT

APIcast requires a running Redis in memory database instance for the OAuth 2.0 Authorization code flow. The REDIS_PORT parameter can be used to set the port of the Redis instance.

6379

Any valid port

REDIS_URL

APIcast requires a running Redis in memory database instance for the OAuth 2.0 Authorization code flow. The REDIS_URL parameter specifies the full URI as DSN of the Redis in memory database instance. . This variable takes precedence over REDIS_PORT and REDIS_HOST.

No value

redis://PASSWORD@HOST:PORT/DB

APICAST_OAUTH_TOKENS_TTL

When OAuth authentication is enabled, the APICAST_OAUTH_TOKENS_TTL variable specifies the time-to-live, in seconds, of the tokens created.

604800

A numeric value

RESOLVER

Allows you to specify a custom DNS resolver that will be used by OpenResty web platform. If the RESOLVER parameter is empty, the DNS resolver will be autodiscovered.

No value

THREESCALE_DEPLOYMENT_ENV

The THREESCALE_DEPLOYMENT_ENV variable defines the 3scale staging or production environment from which the configuration will be downloaded when using a new APIcast. The variable will also be used in the X-3scale-User-Agent header as part of the authorize/report requests made to the 3scale Service Management API. These requests are used by 3scale to track statistics.

production

staging, production

THREESCALE_PORTAL_ENDPOINT

The THREESCALE_PORTAL_ENDPOINT variable stores a URI that includes your password and portal endpoint in the following format: <schema>://<password>@<admin-portal-domain>. The <password> can be either the provider key or an access token for the 3scale Account Management API. <admin-portal-domain> is the URL used to log into the admin portal. Example: https://access-token@account-admin.3scale.net. When THREESCALE_PORTAL_ENDPOINT environment variable is provided, the gateway will download the configuration from 3scale on initialization. The configuration includes all the settings provided on the integration page of the API. APIcast requires configuration through either THREESCALE_PORTAL_ENDPOINT or THREESCALE_CONFIG_FILE to run. The THREESCALE_CONFIG_FILE variable takes precedence over the THREESCALE_PORTAL_ENDPOINT variable.

none

a URI, written as indicated in the description

THREESCALE_CONFIG_FILE

The THREESCALE_CONFIG_FILE variable specifies the path to a JSON file containing configuration data for the APIcast gateway. The configuration can be downloaded from the 3scale admin portal using the the following format: <schema>://<admin-portal-domain>/admin/api/nginx/spec.json For example: https://account-admin.3scale.net/admin/api/nginx/spec.json. If you are deploying APIcast on the Docker containerized environment, you must add the configuration file to the Docker image as a read only volume, and specify the path to the volume. Sample configuration files are available in the upstream examples folder. APIcast requires configuration through either THREESCALE_PORTAL_ENDPOINT or THREESCALE_CONFIG_FILE to run. The THREESCALE_CONFIG_FILE variable takes precedence over the THREESCALE_PORTAL_ENDPOINT variable.

BACKEND_ENDPOINT_OVERRIDE

The BACKEND_ENDPOINT_OVERRIDE variable specifies a URI which overrides any backend endpoint specified in the configuration. This is useful when deploying APIcast outside of an AMP deployed on OpenShift.

APICAST_MANAGEMENT_API

The APICAST_MANAGEMENT_API variable enables the APIcast management API, which controls the APIcast configuration.

disabled

disabled, status, debug

OPENSSL_VERIFY

The OPENSSL_VERIFY variable controls OpenSSL peer verification. OpenSSL does not have access to system certificate store. Instead, you must create a custom certificate bundle and add it to your trusted certificates. Red Hat 3scale recommends you use the lua_ssl_trusted_certificate directive and point it to the certificate bundle generated by the export-builtin-trusted-certs development utility.

0/false

0, false: disable peer verification 1, true: enable peer verification

APICAST_ENVIRONMENT

The APICAST_ENVRIONMENT variable is a colon separated list specifying environments or paths APIcast should load. Use the APICAST_ENVRIONMENT parameter instead of the -e or ---environment CLI parameter. This allows the parameter to be stored in the container image as part of a default environment. Any value passed from the CLI overrides this variable.

none

string[:], Example: production:cloud-hosted

APICAST_SERVICES

The APICAST_SERVICES variable allows you to filter services configured in the 3scale API Manager, and only uses the configuration for specific services in the gateway, discarding those services' IDs that are not specified in the list. Service IDs can be found on the Dashboard > APIs page, tagged as ID for API calls.

none

a comma-separated list of service IDs

APICAST_POLICY_LOAD_PATH

The APICAST_POLICY_LOAD_PATH variable specifies a list of directories from which APIcast will load policies.

APICAST_DIR/policies

string[:], Example: ~/apicast/policies:$PWD/policies

APICAST_PROXY_HTTPS_CERTIFICATE

The APICAST_PROXY_HTTPS_CERTIFICATE variable specifies the file path to a client SSL certificate which APIcast uses to connect with the upstream. All services in the configuration use this certificate.

none

string, Example: /home/apicast/my_certificate.crt

APICAST_PROXY_HTTPS_CERTIFICATE_KEY

The APICAST_PROXY_HTTPS_CERTIFICATE_KEY variable specifies the file path to the client SSL certificate key file.

none

string, must be a vaild file path, Example: /home/apicast/my_certificate.key

APICAST_PROXY_HTTPS_SESSION_REUSE

The APICAST_PROXY_HTTPS_SESSION_REUSE variable specifies whether or not APIcast will reuse SSL sessions. If set to on, APIcast will reuse SSL sessions.

on

enumerated string: on, off

APICAST_PROXY_HTTPS_PASSWORD_FILE

The APICAST_PROXY_HTTPS_PASSWORD_FILE variable specifies the path to a file containing passphrases for SSL certificate keys specified in the APICAST_PROXY_HTTPS_CERTIFICATE_KEY environment variable

none

string, must be a valid filepath, Example: /home/apicast/passwords.txt