# Environment Variables

An AISIX gateway uses environment variables to select startup configuration files, override startup configuration fields, and provide deployment-specific values such as AISIX gateway certificate material.

Most runtime gateway resources are not configured directly through environment variables. For an open-source AISIX gateway, declare models, caller API keys, provider keys, guardrails, cache policies, and observability exporters in a [`resources.yaml` file](https://docs.api7.ai/ai-gateway/reference/resources-file.md). The file supports [environment interpolation](https://docs.api7.ai/ai-gateway/reference/resources-file.md#environment-interpolation) for values such as `${OPENAI_API_KEY}`.

For an AISIX gateway connected to AISIX Enterprise or AISIX Cloud, the control plane supplies these resources.

## Reserved Environment Variables[​](#reserved-environment-variables "Direct link to Reserved Environment Variables")

AISIX reserves the following environment variables:

| Variable            | Description                                                                                                                                                      |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AISIX_CONFIG`      | Startup configuration file path used by the AISIX binary, equivalent to passing `--config`. Read only when you run the binary directly.                          |
| `AISIX_CONFIG_PATH` | Config file path used by the official container entrypoint. Defaults to `/etc/aisix/config.yaml`.                                                                |
| `RUST_LOG`          | Process logging directive. When unset, AISIX uses `observability.log_level`. It does not affect the access log, which only `observability.access_log` turns off. |

These are the AISIX variables that name something other than a startup configuration field. AISIX reads each one by name and never treats it as a [startup configuration override](#startup-configuration-overrides).

The gateway no longer reads `AISIX_DP_BUDGET_STALE_MAX_SECONDS`, because it no longer caches budget decisions from the control plane; see [Budgets](https://docs.api7.ai/ai-gateway/traffic-controls/budgets.md#behavior-during-a-control-plane-outage). A gateway that still sets it starts normally and logs that the variable names no gateway setting.

When you run the binary directly, select the startup configuration with the `--config` option:

```
aisix --config /etc/aisix/config.yaml
```

Use `AISIX_CONFIG_PATH` only with the official container entrypoint:

```
docker run \

  -v "$(pwd)/config.prod.yaml:/etc/aisix/config.prod.yaml:ro" \

  -e AISIX_CONFIG_PATH="/etc/aisix/config.prod.yaml" \

  ghcr.io/api7/aisix:1.11.0
```

## Startup Configuration Overrides[​](#startup-configuration-overrides "Direct link to Startup Configuration Overrides")

After AISIX loads the config file, it applies environment-variable overrides with the `AISIX_` prefix. Use a single underscore after the prefix and double underscores between nested fields.

Helm deployments

The `api7/aisix` Helm chart renders the startup configuration file from its `config` value, and reads settings that hold a credential from Secrets through `configSecrets`. Set startup fields there rather than as environment variables in `extraEnvVars`. An `AISIX_*` variable set through `extraEnvVars` still overrides the rendered file. See [Set Any Other Gateway Configuration](https://docs.api7.ai/ai-gateway/cloud/kubernetes.md#set-any-other-gateway-configuration).

The following example overrides the proxy listener address:

```
export AISIX_PROXY__ADDR="0.0.0.0:3000"
```

Common override variables include:

| Variable                                   | Overrides                          |
| ------------------------------------------ | ---------------------------------- |
| `AISIX_PROXY__ADDR`                        | `proxy.addr`                       |
| `AISIX_PROXY__THREAD_PER_CORE`             | `proxy.thread_per_core`            |
| `AISIX_PROXY__WORKERS`                     | `proxy.workers`                    |
| `AISIX_PROXY__EXPOSE_DEBUG_HEADERS`        | `proxy.expose_debug_headers`       |
| `AISIX_ETCD__ENDPOINTS`                    | `etcd.endpoints`                   |
| `AISIX_ETCD__PREFIX`                       | `etcd.prefix`                      |
| `AISIX_OBSERVABILITY__LOG_LEVEL`           | `observability.log_level`          |
| `AISIX_CACHE__REDIS__MODE`                 | `cache.redis.mode`                 |
| `AISIX_CACHE__REDIS__URL`                  | `cache.redis.url`                  |
| `AISIX_CACHE__REDIS__MASTER_NAME`          | `cache.redis.master_name`          |
| `AISIX_CACHE__REDIS__USERNAME`             | `cache.redis.username`             |
| `AISIX_CACHE__REDIS__PASSWORD`             | `cache.redis.password`             |
| `AISIX_CACHE__REDIS__DATABASE`             | `cache.redis.database`             |
| `AISIX_CACHE__REDIS__TIMEOUT_SECS`         | `cache.redis.timeout_secs`         |
| `AISIX_RATELIMIT__BACKEND`                 | `ratelimit.backend`                |
| `AISIX_RATELIMIT__REDIS__MODE`             | `ratelimit.redis.mode`             |
| `AISIX_RATELIMIT__REDIS__URL`              | `ratelimit.redis.url`              |
| `AISIX_RATELIMIT__REDIS__MASTER_NAME`      | `ratelimit.redis.master_name`      |
| `AISIX_RATELIMIT__REDIS__USERNAME`         | `ratelimit.redis.username`         |
| `AISIX_RATELIMIT__REDIS__PASSWORD`         | `ratelimit.redis.password`         |
| `AISIX_RATELIMIT__REDIS__DATABASE`         | `ratelimit.redis.database`         |
| `AISIX_RATELIMIT__REDIS__TIMEOUT_SECS`     | `ratelimit.redis.timeout_secs`     |
| `AISIX_RATELIMIT__CONCURRENCY_TTL_SECS`    | `ratelimit.concurrency_ttl_secs`   |
| `AISIX_OUTBOUND__SSRF_PROTECTION__ENABLED` | `outbound.ssrf_protection.enabled` |
| `AISIX_BEDROCK_ENDPOINT_URL`               | Top-level `bedrock_endpoint_url`.  |

A list field takes a comma-separated value in an environment variable, such as `AISIX_ETCD__ENDPOINTS="http://etcd-0:2379,http://etcd-1:2379"`. The following fields accept one:

| Variable                                                     | Overrides                                           |
| ------------------------------------------------------------ | --------------------------------------------------- |
| `AISIX_ETCD__ENDPOINTS`                                      | `etcd.endpoints`                                    |
| `AISIX_ADMIN__ADMIN_KEYS`                                    | `admin.admin_keys`                                  |
| `AISIX_PROXY__REAL_IP__TRUSTED_PROXIES`                      | `proxy.real_ip.trusted_proxies`                     |
| `AISIX_PROXY__REQUEST_ID__ACCEPT_HEADERS`                    | `proxy.request_id.accept_headers`                   |
| `AISIX_OBSERVABILITY__METRICS__BUCKETS__REQUEST_E2E_LATENCY` | `observability.metrics.buckets.request_e2e_latency` |
| `AISIX_OBSERVABILITY__METRICS__BUCKETS__REQUEST_TTFT`        | `observability.metrics.buckets.request_ttft`        |
| `AISIX_OBSERVABILITY__METRICS__BUCKETS__GUARDRAIL_LATENCY`   | `observability.metrics.buckets.guardrail_latency`   |
| `AISIX_OBSERVABILITY__METRICS__BUCKETS__A2A_TTFB`            | `observability.metrics.buckets.a2a_ttfb`            |
| `AISIX_OBSERVABILITY__HEAP_PROFILING__AUTO_DUMP__THRESHOLDS` | `observability.heap_profiling.auto_dump.thresholds` |
| `AISIX_CACHE__REDIS__NODES`                                  | `cache.redis.nodes`                                 |
| `AISIX_CACHE__REDIS__SENTINELS`                              | `cache.redis.sentinels`                             |
| `AISIX_RATELIMIT__REDIS__NODES`                              | `ratelimit.redis.nodes`                             |
| `AISIX_RATELIMIT__REDIS__SENTINELS`                          | `ratelimit.redis.sentinels`                         |
| `AISIX_OUTBOUND__SSRF_PROTECTION__ALLOWED_HOSTS`             | `outbound.ssrf_protection.allowed_hosts`            |

Give these fields a comma-separated value, not a JSON array. For example, `AISIX_OUTBOUND__SSRF_PROTECTION__ALLOWED_HOSTS="media.internal,10.0.0.5:9000"` sets two hosts, while a JSON array value is read as invalid host entries and stops the gateway at startup.

A Redis node or sentinel URL given this way cannot contain a comma. Put Redis credentials in the separate `username` and `password` fields, such as `AISIX_CACHE__REDIS__PASSWORD`, rather than in the URL.

`AISIX_OBSERVABILITY__USAGE_EVENT__REQUEST_HEADERS` sets the retired `observability.usage_event.request_headers`, so the gateway ignores the variable and logs the [ignored-key warning](#misspelled-and-retired-keys) for it. Configure each exporter's `request_headers` list instead; see [Attribute Events with Request Headers](https://docs.api7.ai/ai-gateway/observability/metrics-and-usage-events.md#attribute-events-with-request-headers).

A list of objects — `proxy.listeners`, `proxy.url_rewrites`, or `observability.metrics.client_type_rules` — takes the whole list as one JSON array in a single variable. See [TLS and mTLS](https://docs.api7.ai/ai-gateway/deployment/tls-and-mtls.md) and [URL Rewriting](https://docs.api7.ai/ai-gateway/deployment/url-rewriting.md) for examples.

For configuration file fields, see the [Startup Configuration Reference](https://docs.api7.ai/ai-gateway/reference/configuration-files.md).

## Unrecognized AISIX Variables[​](#unrecognized-aisix-variables "Direct link to Unrecognized AISIX Variables")

AISIX judges an `AISIX_`-prefixed variable by its first segment. It converts the name to lower case, strips the prefix, and splits the rest on `__` or `.`. If that first segment is one of the top-level startup configuration sections — `admin`, `bedrock_endpoint_url`, `cache`, `downstream`, `etcd`, `managed`, `observability`, `outbound`, `proxy`, `ratelimit`, `resources_file`, `shutdown`, or `upstream` — the variable is applied as an override. Otherwise it is ignored, and AISIX logs one warning per variable at startup:

```
AISIX_OSS_PORT_9090_TCP_PROTO was not applied as a configuration override: it names no gateway setting, and a nested setting is spelled AISIX_<SECTION>__<KEY>. If the configuration reads it by name (etcd.password_env, a resources-file interpolation) it still applies; otherwise nothing reads it — Kubernetes injects variables of this shape for every Service named aisix or aisix-*, which enableServiceLinks: false on the pod spec turns off.
```

Ignoring the variable is not the same as nothing reading it. A variable AISIX names from the startup configuration — `etcd.password_env`, for example — or from a [`resources.yaml` interpolation](https://docs.api7.ai/ai-gateway/reference/resources-file.md#environment-interpolation) still applies, because that reference is resolved by name after the configuration is parsed. The warning is emitted before either is known.

The [reserved variables](#reserved-environment-variables) are skipped without a warning, because AISIX reads each of them by name.

### Misspelled and Retired Keys[​](#misspelled-and-retired-keys "Direct link to Misspelled and Retired Keys")

A key *under* a real section that names no setting is a different case. `AISIX_PROXY__TIMEOTU` leads with `proxy`, so it reaches the configuration parser, which finds no `proxy.timeotu` setting. The gateway ignores that key and still starts, and it logs one warning per ignored key, naming the full dotted key and the variable that set it:

```
WARN proxy.timeotu (set by AISIX_PROXY__TIMEOTU) is not a setting this gateway knows and was ignored. Check its spelling, or delete it if it was retired.
```

The startup configuration file is treated the same way, without the variable in parentheses. A misspelled key therefore does not stop the gateway, but the setting you meant to change does not take effect. Check the startup log for this warning after changing the configuration. It is written whatever `observability.log_level` is: when the level hides warnings, the same line goes to standard error, prefixed with `WARN`.

A setting that a gateway release retired produces the same warning, so delete it from the configuration file, environment, or Helm values to silence it. The retired `observability.metrics.otlp`, `observability.tracing`, and `observability.usage_event` blocks are examples.

When the configuration fails to load for another reason, such as a value of the wrong type or a missing required field, the gateway still refuses to start. The error then ends with the keys it ignored, because the warnings are logged only for a configuration that loads, and a misspelled key is usually what left the reported setting missing:

```
... (also ignored, as no setting this gateway knows: proxy.adress)
```

### Kubernetes Service Links[​](#kubernetes-service-links "Direct link to Kubernetes Service Links")

Kubernetes injects a set of Docker-style link variables into every container for each Service in the namespace, named after the Service. A Service called `aisix` or `aisix-something` therefore produces variables such as `AISIX_PORT_80_TCP_ADDR` and `AISIX_OSS_SERVICE_HOST` inside the gateway container — including the Service this very gateway is published through, and any control plane installed in the same namespace.

None of them name a gateway setting, so each produces one startup warning. Turn them off on the pod spec:

```
spec:

  template:

    spec:

      enableServiceLinks: false
```

The official `api7/aisix` Helm chart sets this on the gateway pods already. Set it yourself if you deploy the gateway from hand-written manifests.

## Managed Connection Variables[​](#managed-connection-variables "Direct link to Managed Connection Variables")

AISIX gateways use the same `AISIX_` override mechanism for `managed.*` startup settings.

| Variable                                 | Description                                                                                                                              |
| ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `AISIX_MANAGED__ENABLED`                 | Connects the gateway to AISIX Enterprise or AISIX Cloud when set to `true`.                                                              |
| `AISIX_MANAGED__CP_BASE_URL`             | Control-plane origin used for heartbeat and telemetry. An `https://` URL such as `https://dpm.example.com:7944`.                         |
| `AISIX_MANAGED__CP_ETCD_ENDPOINT`        | Control-plane etcd endpoint used by the gateway at startup. A bare `host:port` without a URL scheme.                                     |
| `AISIX_MANAGED__CP_CA_CERT_FILE`         | Optional CA bundle file used to trust control-plane and etcd TLS connections.                                                            |
| `AISIX_MANAGED__CP_CERT_PEM`             | Inline client certificate PEM used for mTLS with the control plane.                                                                      |
| `AISIX_MANAGED__CP_KEY_PEM`              | Inline private key PEM paired with the client certificate.                                                                               |
| `AISIX_MANAGED__CP_CA_PEM`               | Inline CA certificate PEM used as the trust anchor.                                                                                      |
| `AISIX_MANAGED__CP_CERT_FILE`            | File path for the client certificate PEM.                                                                                                |
| `AISIX_MANAGED__CP_KEY_FILE`             | File path for the private key PEM.                                                                                                       |
| `AISIX_MANAGED__CP_CA_FILE`              | File path for the CA certificate PEM.                                                                                                    |
| `AISIX_MANAGED__MTLS_DIR`                | Directory where the gateway persists the materialized mTLS bundle.                                                                       |
| `AISIX_MANAGED__DP_ID_FILE`              | File where the gateway persists its AISIX gateway ID.                                                                                    |
| `AISIX_MANAGED__SNAPSHOT_CACHE_ENABLED`  | Enable the on-disk configuration snapshot cache. Defaults to `false`.                                                                    |
| `AISIX_MANAGED__SNAPSHOT_CACHE_PATH`     | File path for the on-disk snapshot cache when `AISIX_MANAGED__SNAPSHOT_CACHE_ENABLED` is `true`. A path alone does not enable the cache. |
| `AISIX_MANAGED__HEARTBEAT_INTERVAL_SECS` | AISIX gateway heartbeat interval in seconds. Defaults to `15`; values are clamped between `5` and `300`.                                 |

Use either the inline PEM variables or the file-path variables for the certificate, key, and CA bundle. Do not mix inline and file variants for the same bundle.

For AISIX Enterprise or AISIX Cloud setup, see [Connect a Gateway](https://docs.api7.ai/ai-gateway/cloud/connect-a-gateway.md).
