Startup Configuration
Startup configuration defines the static settings AISIX needs before it can serve traffic. It covers process-level concerns such as the configuration store, listener addresses, metrics, cache backend, and managed startup mode.
Dynamic resources are different. Models, caller API keys, provider keys, guardrails, cache policies, and observability exporters are loaded later from the configuration store.
Baseline Self-Hosted Example
Start with this self-hosted config.yaml, then adjust it for the deployment. The example makes common listener, observability, and rate-limit choices explicit; it is a baseline, not a list of built-in defaults.
etcd:
endpoints:
- "http://127.0.0.1:2379"
prefix: "/aisix"
dial_timeout_ms: 5000
request_timeout_ms: 5000
proxy:
addr: "0.0.0.0:3000"
request_body_limit_bytes: 10485760
admin:
addr: "127.0.0.1:3001"
admin_keys:
- "YOUR_ADMIN_KEY"
observability:
service_name: "aisix"
log_level: "info"
metrics:
prometheus:
enabled: true
path: "/metrics"
addr: "0.0.0.0:9090"
ratelimit:
backend: "memory"
For all startup fields and their defaults, see Configuration Files.
Loading and Overrides
AISIX loads startup configuration in this order:
- defaults
- file contents
- environment-variable overrides
Environment-variable overrides start with AISIX_ and use __ between nested config fields. They are useful when a container image should keep the same config file while deployment systems inject listener addresses, credentials, or managed-mode values.
Set a nested startup value with an environment variable:
export AISIX_PROXY__ADDR="0.0.0.0:3000"
Choose Self-Hosted or Managed Mode
Startup configuration decides whether the gateway runs as self-hosted or managed. Make this choice before configuring its management connection and admin listener.
Enable managed mode only when the gateway connects to the AISIX managed control plane:
managed:
enabled: true
mtls_dir: "/var/lib/aisix/mtls"
dp_id_file: "/var/lib/aisix/dp_id"
When managed.enabled = true, the Admin API is not bound, the local playground endpoint is not exposed, and dynamic resources are read through the managed configuration path. Managed bootstrap uses a certificate bundle supplied as inline PEM values or mounted file paths.
Use self-hosted startup configuration when local control through :3001 is required. Use managed startup configuration when the gateway should not expose a local admin write API.
Connect Runtime Dependencies
AISIX needs a configuration store before dynamic resources can reach the proxy. The etcd block tells AISIX where to read those resources after startup.
Most self-hosted deployments point AISIX to an etcd endpoint and keep a stable prefix, so all gateway resources live under the same keyspace:
etcd:
endpoints:
- "http://127.0.0.1:2379"
prefix: "/aisix"
dial_timeout_ms: 5000
request_timeout_ms: 5000
Use env_id only when your deployment model expects environment-scoped keys. Add etcd.tls when the configuration store requires mTLS. The current configuration requires a CA certificate, client certificate, and client key together.
AISIX always builds the in-process memory cache. Add Redis when cache policies should be able to share cached responses across gateway instances:
cache:
redis:
mode: single
url: "redis://127.0.0.1:6379"
The matching cache policy selects memory or Redis for each request. The cache.backend field is kept for compatibility; it no longer selects one global cache backend. When cache.backend is redis, startup still fails if the Redis block is missing or the gateway cannot connect.
Use mode: cluster with nodes for Redis Cluster, or mode: sentinel with sentinels and master_name for a Sentinel-managed master.
Rate-limit counters use local memory by default. Use Redis when multiple gateway instances should share request, token, and concurrency counters:
ratelimit:
backend: redis
redis:
mode: single
url: "redis://127.0.0.1:6379"
When the Redis backend is selected, startup requires the ratelimit.redis block. With the memory backend, counters are kept in each gateway process.
The rate-limit Redis backend supports the same single, cluster, and sentinel connection modes as response caching. concurrency_ttl_secs controls how long Redis-backed concurrency slots can remain before they are reclaimed.
Expose Runtime Listeners
AISIX separates caller traffic, self-hosted administration, and metrics into different listener concerns.
The proxy listener is the caller-facing entry point for model traffic:
proxy:
addr: "0.0.0.0:3000"
request_body_limit_bytes: 10485760
For local development, binding to loopback keeps the gateway private. For container or ingress deployments, bind to the interface that the ingress tier or caller network can reach. Keep the request-body limit large enough for expected traffic without making it arbitrary.
The admin listener is the management entry point for self-hosted deployments:
admin:
addr: "127.0.0.1:3001"
admin_keys:
- "YOUR_ADMIN_KEY"
Bind the admin listener to loopback or a private interface whenever possible. The default address uses a loopback ephemeral port, so self-hosted deployments should set an explicit private address. Admin keys are static startup configuration, not caller API key resources.
Use listener TLS only when AISIX should terminate HTTPS directly. Configure real-client-IP resolution only when AISIX runs behind a trusted load balancer or ingress that sets a forwarded client-IP header. By default, AISIX trusts no forwarded headers and uses the immediate TCP peer.
Configure Observability
Startup observability settings control process-wide logging and the metrics/status listener.
Configure the dedicated listener for Prometheus scraping and operational status routes:
observability:
service_name: "aisix"
log_level: "info"
metrics:
prometheus:
enabled: true
path: "/metrics"
addr: "0.0.0.0:9090"
When Prometheus is enabled, the same listener serves /status/config, /status/ready, and /status/models. These routes and the configured metrics path do not require application authentication. Bind the listener to a private interface or restrict it to trusted monitoring systems.
Treat access_log, metrics.otlp, and tracing.otlp as reserved or partial in the current release. Proxy handlers still emit structured access logs, OTLP metrics are not wired, and startup OTLP tracing does not install the full export pipeline.
Startup observability settings are not the same as dynamic observability exporters. Startup settings control the process; dynamic exporter resources control runtime telemetry delivery. For dynamic exporters added through the admin API, see Observability Exporters.
Verify the Startup Configuration
After updating the startup config, start the gateway and verify the proxy listener:
curl -sS "http://127.0.0.1:3000/livez"
For self-hosted mode, also verify the admin listener:
curl -sS "http://127.0.0.1:3001/livez"
If Prometheus metrics are enabled, verify that AISIX has applied a valid configuration through the metrics/status listener:
curl -i "http://127.0.0.1:9090/status/ready"
Use Health Checks to choose between process, traffic, configuration, and model status checks.
Then query admin health to confirm that the self-hosted gateway has loaded model and configuration state:
AISIX_ADMIN_KEY="YOUR_ADMIN_KEY"
curl -sS "http://127.0.0.1:3001/admin/v1/health" \
-H "Authorization: Bearer ${AISIX_ADMIN_KEY}"
The liveness endpoints confirm that the listeners are running. Admin health adds the loaded model state and, when available, configuration snapshot freshness. If the process starts but model resources are not visible, check etcd connectivity and prefix alignment first.
If the proxy listener is reachable but the admin listener is not, check whether managed.enabled = true. In managed mode, the Admin API is intentionally not bound.
If an environment-variable override does not take effect, confirm the AISIX_ prefix and nested __ separator.
Next Steps
You have now seen how startup settings start the gateway process and listeners. Continue with Configuration Propagation for runtime update timing.