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:1.3.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 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.

etcd.endpoints accepts a comma-separated list in an environment variable.

For Redis Cluster and Sentinel node lists, configure cache.redis.nodes, cache.redis.sentinels, ratelimit.redis.nodes, or ratelimit.redis.sentinels in the startup configuration file.

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.