Startup Configuration

Startup configuration defines the process-level settings AISIX needs before it can serve traffic. It controls how the gateway receives dynamic resources, which listeners it binds, which shared backends it uses, and how it connects to AISIX Cloud.

Dynamic resources are configured separately. Models, provider keys, caller API keys, guardrails, cache policies, rate-limit policies, and observability exporters come from a resources file, a configuration store, or the AISIX Cloud control plane.

Understand the Configuration Sources

AISIX uses different configuration sources for different responsibilities:

Configuration	Applies To	Source
Process settings	Every gateway	Startup configuration file with optional environment-variable overrides
Dynamic gateway resources	Open-source AISIX gateway	Declarative resources.yaml file or etcd
Dynamic gateway resources	Gateway connected to AISIX Cloud	AISIX Cloud control plane
On-Premises control-plane settings	On-Premises AISIX Cloud deployment	Docker Compose environment variables or Helm values

This page covers gateway startup configuration. For On-Premises control-plane settings, see the On-Premises Configuration Reference.

Choose the Dynamic-Resource Source

A gateway reads dynamic resources from one source. Choose that source in startup configuration before configuring listeners and runtime dependencies.

Resources File

Use a declarative resources file for the normal open-source gateway workflow:

config.yaml

resources_file: /etc/aisix/resources.yaml

proxy:
  addr: "0.0.0.0:3000"

admin:
  enabled: false

observability:
  metrics:
    prometheus:
      enabled: true
      path: "/metrics"
      addr: "0.0.0.0:9090"

The gateway loads the file at startup and reloads it on SIGHUP. Validate resource changes before applying them:

aisix validate --resources /etc/aisix/resources.yaml

See the Open-Source AISIX Gateway Quickstart for the complete workflow and the Resources File Reference for supported resource kinds.

Configuration Store

Use etcd when an existing automation system manages open-source AISIX gateway resources through a shared store:

config.yaml

etcd:
  endpoints:
    - "http://127.0.0.1:2379"
  prefix: "/aisix"
  dial_timeout_ms: 5000
  request_timeout_ms: 5000

Keep the prefix stable across gateway instances that should receive the same resources. Use env_id only when the configuration system writes environment-scoped keys. Configure etcd.tls when the store requires mTLS.

Do not configure both resources_file and etcd; AISIX rejects that combination at startup.

AISIX Cloud

The generated gateway installation snippet sets managed.enabled to true and supplies the control-plane endpoint, certificate bundle, runtime state directory, and gateway identity path. The gateway then receives environment resources from the control plane.

Do not combine managed.enabled: true with resources_file. Follow Connect an AISIX Gateway for certificate issuance and the complete connection workflow.

Configure Shared Runtime State

AISIX always has an in-process response cache. Configure Redis when cache policies should share entries across gateway instances:

config.yaml

cache:
  redis:
    mode: single
    url: "redis://127.0.0.1:6379"

Configuring cache.redis makes Redis available to cache policies. Each cache policy selects memory or Redis.

Rate-limit counters use process memory by default. Configure a shared Redis backend when request, token, or concurrency limits must apply across multiple instances:

config.yaml

ratelimit:
  backend: redis
  redis:
    mode: single
    url: "redis://127.0.0.1:6379"

Cache and rate-limit Redis connections support single-node, cluster, and Sentinel deployments. Use an available Redis topology when either feature is part of the production traffic path.

Configure Runtime Listeners

AISIX separates caller traffic from operational status:

Listener	Purpose	Exposure
Proxy	Caller-facing AI APIs and /livez and /readyz	Intended callers or ingress tier
Metrics/status	Prometheus metrics and /status/* routes	Trusted monitoring network

Set an explicit proxy address. The metrics/status routes do not require application authentication, so never expose that listener publicly.

Use listener TLS only when AISIX should terminate HTTPS directly. Resolve forwarded client addresses only when the gateway runs behind a trusted load balancer or ingress. See Network and Security for the exposure model and TLS and mTLS for the independent TLS contexts.

Configure Process Observability

Startup observability settings control process logging and the metrics/status listener:

config.yaml

observability:
  service_name: "aisix"
  log_level: "info"
  metrics:
    prometheus:
      enabled: true
      path: "/metrics"
      addr: "0.0.0.0:9090"

These settings are different from dynamic observability exporters. Startup settings control the process and local Prometheus listener. Configure runtime telemetry delivery through Observability Exporters.

Configure Shutdown Behavior

On SIGTERM the gateway reports itself unready straight away. It keeps accepting new connections for a further window, so the load balancer in front has time to withdraw it before the listener closes:

config.yaml

shutdown:
  min_drain_secs: 30

Set the window above the detection latency of whatever load-balances the instance, and give the platform enough termination time for the in-flight drain that follows. See Shutdown and Draining.

Load and Verify the Configuration

AISIX applies built-in defaults, then the startup configuration file, then AISIX_ environment-variable overrides. Use __ between nested field names:

export AISIX_PROXY__ADDR="0.0.0.0:3000"

See the Startup Configuration Reference for file formats, field behavior, file selection, and loading precedence. See Environment Variables for override syntax.

After starting the gateway, check the proxy listener:

curl -i "http://127.0.0.1:3000/livez"
curl -i "http://127.0.0.1:3000/readyz"

When the metrics/status listener is enabled, confirm that AISIX has applied a valid configuration:

curl -sS "http://127.0.0.1:9090/status/config"

If the proxy starts but resources do not appear, check the configured resource source rather than changing listener settings. Use Configuration Propagation to trace a change from its source to the caller-facing path.

Next Steps

Continue with Thread-per-Core Workers to size the worker pool behind the proxy listener, then Network and Security to protect the listeners, stores, and credentials configured here.