Environment Variables

APISIX supports the use of environment variables in static configuration files and certain plugins. There are a few environment variables reserved for special purposes, and others that can be created with custom names and referenced.

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.

Configuration Files

In APISIX, you can use environment variables in the config.yaml or apisix.yaml configuration files for values that should be configurable during deployments, using the ${{ENV_VAR}} syntax or ${{ENV_VAR:default_value}} syntax.

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 the use of environment variables in plugin configurations for confidential information, such as Redis password and authentication key, through the NGINX env directive.

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

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.