# Environment Variables

APISIX supports environment variables in [configuration files](https://docs.api7.ai/apisix/reference/configuration-files.md#use-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[​](#reserved-environment-variables "Direct link to Reserved Environment Variables")

APISIX currently reserves the following environment variables:

| Variable Name                 | Description                                                                                                                                                                |
| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `APISIX_DEPLOYMENT_ETCD_HOST` | JSON array of etcd endpoint URLs, for example, `["http://etcd:2379"]`.                                                                                                     |
| `APISIX_PROFILE`              | Deployment environment differentiating the [configuration files](https://docs.api7.ai/apisix/reference/configuration-files.md#manage-configuration-files-by-environments). |
| `APISIX_WORKER_PROCESSES`     | Number of worker processes.                                                                                                                                                |

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

The following example sets the reserved etcd host variable to a quoted JSON array:

```
export APISIX_DEPLOYMENT_ETCD_HOST='["http://etcd:2379"]'
```

APISIX decodes the value as JSON and replaces `deployment.etcd.host` before validating the configuration. A plain URL such as `http://etcd:2379` is not valid JSON. APISIX reports a parse failure and retains the etcd hosts from `config.yaml`.

## Custom Environment Variables[​](#custom-environment-variables "Direct link to Custom Environment Variables")

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

### Pass Variables to NGINX Workers[​](#pass-variables-to-nginx-workers "Direct link to 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](https://docs.api7.ai/apisix/reference/apisix-cli.md#apisix-reload) 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[​](#configuration-files "Direct link to 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](https://docs.api7.ai/apisix/reference/configuration-files.md#use-environment-variables-in-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[​](#plugins "Direct link to Plugins")

APISIX supports `$env://NAME` and `$ENV://NAME` references in plugin string fields, including confidential values such as a [Redis password](https://docs.api7.ai/hub/limit-count/configuration.md#parameters) or [authentication key](https://docs.api7.ai/hub/jwt-auth.md#manage-secrets-in-environment-variables). The referenced variable must be available to the APISIX worker process, such as through the NGINX [`env` directive](https://nginx.org/en/docs/ngx_core_module.html#env) 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](https://docs.api7.ai/hub.md).
