Environment Variables
AISIX AI 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 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. |
AISIX_DP_BUDGET_STALE_MAX_SECONDS | Maximum age, in seconds, of a cached budget decision that a gateway connected to AISIX Cloud may keep honoring while the control plane is unreachable. Defaults to 600. |
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.
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:dev
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_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_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_OBSERVABILITY__USAGE_EVENT__REQUEST_HEADERS | observability.usage_event.request_headers |
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 |
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.
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, 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.
A misspelled key under a real section is a different case and is not tolerated. AISIX_PROXY__TIMEOTU leads with proxy, so it reaches the configuration parser and fails startup with an unknown-field error. That is deliberate: a typo in a setting you meant to set should stop the gateway rather than be silently dropped.
The reserved variables are skipped without a warning, because AISIX reads each of them by name.
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 AISIX Cloud 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.
AISIX Cloud Connection Variables
AISIX gateways use the same AISIX_ override mechanism for managed.* startup settings.
| Variable | Description |
|---|---|
AISIX_MANAGED__ENABLED | Connects the gateway to AISIX Cloud when set to true. |
AISIX_MANAGED__CP_BASE_URL | AISIX Cloud control-plane origin used for heartbeat, telemetry, and budget checks. 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 AISIX Cloud 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 Cloud setup, see Connect an AISIX Gateway.