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.

Minimal Self-Hosted Example

Start with a small self-hosted config.yaml, then add only the settings your deployment needs:

config.yaml

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"

cache:
  backend: "memory"

Loading and Overrides

AISIX loads startup configuration in this order:

1. defaults
2. file contents
3. 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"

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:

config.yaml

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 TLS or mTLS.

The default cache backend is memory. Use Redis when several gateway instances should share cached responses:

config.yaml

cache:
  backend: redis
  redis:
    url: "redis://127.0.0.1:6379"

When cache.backend is redis, startup fails if the Redis block is missing or the gateway cannot connect. Dynamic cache policies still decide which requests participate in response caching.

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:

config.yaml

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:

config.yaml

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 Prometheus exposure.

Use a dedicated metrics listener when Prometheus should scrape metrics without reaching the admin listener:

config.yaml

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

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.

Choose Self-Hosted or Managed Mode

Startup configuration also decides whether the gateway runs as self-hosted or managed.

Enable managed mode only when AISIX Cloud is the control plane:

config.yaml

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. AISIX Cloud uses certificate-based managed bootstrap; the certificate bundle can be 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.

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 the process starts but model resources are not visible, check etcd connectivity and prefix alignment first. Startup success alone does not confirm that dynamic config reads are healthy.

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.