Environment Variables

APISIX supports environment variables in configuration files and plugin string fields. Some variables have reserved purposes, and you can define custom variables for deployment-specific values and secrets.

Reserved Environment Variables

APISIX currently reserves the following environment variables:

Variable Name	Description
APISIX_DEPLOYMENT_ETCD_HOST	etcd host address.
APISIX_PROFILE	Deployment environment differentiating the configuration files.
APISIX_WORKER_PROCESSES	Number of worker processes.

To use these configurations, assign values to the environment variables before starting APISIX.

Custom Environment Variables

You can use custom environment variables in configuration files and for certain plugins.

Pass Variables to NGINX Workers

Use nginx_config.envs in config.yaml to make variables available to NGINX worker processes. A name without an equals sign inherits its value from the environment that starts APISIX. A NAME=value entry assigns the configured value to each worker:

config.yaml

nginx_config:
  envs:
    - APP_MODE
    - "GREETING=hello world"

APISIX quotes generated NGINX env directives, so assigned values can contain spaces. Embedded quotation marks and backslashes are escaped in the generated configuration. Control characters, including newlines, are rejected during configuration validation.

After changing nginx_config.envs, reload APISIX so new workers receive the values. Plugin fields can then reference them with $env://APP_MODE, $env://GREETING, or the uppercase $ENV:// form.

Configuration Files

Use ${{ENV_VAR}} to require a value or ${{ENV_VAR:=default_value}} to provide a fallback. How APISIX determines the value type depends on the configuration file:

• In apisix.yaml, APISIX substitutes placeholders in the raw file before parsing YAML. An unquoted placeholder can therefore become a number or boolean. Quote the placeholder to preserve the substituted value as a string.
• In config.yaml and apisix.json, APISIX parses the file before substituting placeholders. A substituted value that consists entirely of a number or the literal true or false is converted to that native type. Quoting the placeholder does not force it to remain a string in these files.

See Configuration Files for examples of each behavior.

The example below sets the listening ports for client requests and Admin API in environment variables:

export APISIX_NODE_LISTEN=8132
export ADMIN_API_PORT=9232

In config.yaml, reference the environment variables as follows:

config.yaml

apisix:
  node_listen:
    - ${{APISIX_NODE_LISTEN}}
deployment:
  admin:
    admin_listen:
      port: ${{ADMIN_API_PORT}}

After being started, APISIX will listen on port 8132 for client requests and port 9232 for Admin API requests.

You can also configure default values to fall back to if no environment variables are set, for example:

config.yaml

apisix:
  node_listen:
    - ${{APISIX_NODE_LISTEN:=9080}}
deployment:
  admin:
    admin_listen:
      port: ${{ADMIN_API_PORT:=9180}}

If APISIX cannot resolve values for APISIX_NODE_LISTEN and ADMIN_API_PORT in the environment, it will default to listen on port 9080 for client requests and port 9180 for Admin API requests.

Plugins

APISIX supports $env://NAME and $ENV://NAME references in plugin string fields, including confidential values such as a Redis password or authentication key. The referenced variable must be available to the APISIX worker process, such as through the NGINX env directive or the container environment.

The following example demonstrates how you can configure the key-auth plugin to fetch user authentication key from an environment variable.

Save the value of the key to an environment variable:

export JACK_AUTH_KEY=jack-key

tip

If you are running APISIX in Docker, you should set the environment variable using the -e flag when starting the container.

Create a consumer jack:

curl "http://127.0.0.1:9180/apisix/admin/consumers" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "username": "jack"
  }'

Configure the key-auth credential for the consumer:

curl "http://127.0.0.1:9180/apisix/admin/consumers/jack/credentials" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "cred-jack-key-auth",
    "plugins": {
      "key-auth": {
        "key": "$env://JACK_AUTH_KEY"
      }
    }
  }'

Create a route and enable key-auth:

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "key-auth-route",
    "uri": "/anything",
    "plugins": {
      "key-auth": {}
    },
    "upstream" : {
      "nodes": {
        "httpbin.org": 1
      }
    }
  }'

Send a request to the route with the authentication key:

curl "http://127.0.0.1:9080/anything" -H 'apikey: jack-key'

You should receive an HTTP/1.1 200 OK response.

For more information on the environment variable support in plugins, see plugin docs.