Skip to main content

Version: 3.11.0

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 NameDescription
APISIX_DEPLOYMENT_ETCD_HOSTetcd host address.
APISIX_PROFILEDeployment environment differentiating the configuration files.
APISIX_WORKER_PROCESSESNumber 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.


API7.ai Logo

API Management for Modern Architectures with Edge, API Gateway, Kubernetes, and Service Mesh.

Product

API7 Cloud

SOC2 Type IIISO 27001HIPAAGDPRRed Herring

Copyright © APISEVEN Ltd. 2019 – 2024. Apache, Apache APISIX, APISIX, and associated open source project names are trademarks of the

Apache Software Foundation