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"

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.

etcd.dial_timeout_ms defaults to 5000 milliseconds and etcd.request_timeout_ms is unset and unbounded. Before setting either, review their exact scope and failure behavior in etcd Configuration Store. A request_timeout_ms that is too short for the configuration read can prevent the proxy listener from binding or leave a running gateway behind the store.

When etcd cannot provide the first configuration, the gateway normally keeps the proxy listener closed and retries. See The Gateway Runs but the Proxy Port Refuses Connections to distinguish reachability, timeout, and credential failures.

The configuration source is the only startup dependency that can hold the listeners closed. A ratelimit.redis or a cache.redis the gateway cannot reach binds and serves in a degraded mode instead.

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.

The metrics/status listener normally binds when the process starts. With etcd or AISIX Cloud as the resource source, the proxy listener binds only after the gateway has applied its first configuration. A resources-file gateway binds after loading the file. See Startup and the First Configuration.

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 whether AISIX has applied a valid configuration on the metrics/status listener:

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

Once /status/ready returns 200, check the proxy listener:

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

If these commands are refused, use the metrics/status results and Troubleshooting to diagnose why the first configuration has not been applied. If they answer but a resource change is missing, use Configuration Propagation to trace the 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.