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. The file supports 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
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. |
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.
The gateway no longer reads AISIX_DP_BUDGET_STALE_MAX_SECONDS, because it no longer caches budget decisions from the control plane; see Budgets. 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.8.0
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.
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.
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.
In 1.5.0 and earlier, observability.heap_profiling.auto_dump.thresholds, cache.redis.nodes, cache.redis.sentinels, ratelimit.redis.nodes, and ratelimit.redis.sentinels can be set only in the startup configuration file. Setting one of them through an environment variable stops those gateways from starting.
AISIX_OBSERVABILITY__USAGE_EVENT__REQUEST_HEADERS set observability.usage_event.request_headers in 1.6.0 only. That setting is retired, so the gateway ignores the variable and logs the ignored-key warning for it. Configure each exporter's request_headers list instead; see Upgrade from the Startup Setting.
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 and URL Rewriting for examples.
For configuration file fields, see the Startup Configuration Reference.
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 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 are skipped without a warning, because AISIX reads each of them by name.
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)
A gateway at 1.7.1 or earlier refuses to start on a key it does not know, with an unknown field error. On 1.7.x the error names the full dotted key, and the variable when one set it, such as deserialize: proxy.timeotu (set by AISIX_PROXY__TIMEOTU): unknown field .... A gateway at 1.6.x or earlier prints only the message from the parser, without the key.
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
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.