Configuration Propagation

AISIX AI Gateway separates configuration writes from proxy request handling. In self-hosted deployments, writes usually come through the Admin API. In managed deployments, they come through the managed control plane. In both cases, the gateway serves proxy requests from its loaded snapshot.

That separation keeps request handling fast, but it also means an accepted write and proxy readiness are not the same state.

Configuration changes follow this path:

New proxy requests read from the latest snapshot the gateway has applied.

How Propagation Works

Propagation is asynchronous. A successful write response means the resource was accepted and stored; it does not guarantee that every proxy request can use the new resource immediately.

The configuration watch applies changes to an atomic snapshot. Each new proxy request loads the current snapshot. A request that starts before the update is applied can still use the previous configuration, while later requests use the updated one.

This matters most when resources depend on each other. For example, a model can refer to a provider key, and a caller API key can allow that model. During propagation, one accepted resource can become visible before another. Create the resources in dependency order, then verify the final caller-facing path before sending production traffic.

Verify Configuration Propagation

A successful configuration write confirms resource acceptance, not propagation. Confirm propagation by observing the expected result through the same caller-facing path your application uses.

For model access changes, check the caller-facing model list with the same caller API key your application will use:

AISIX_API_KEY="YOUR_CALLER_API_KEY"

curl -sS "http://127.0.0.1:3000/v1/models" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  | jq -r '.data[].id'

When automation needs to wait for a change, poll for the expected proxy-visible state instead of relying on a fixed timer. Use this sequence when several resources are part of one change:

1. Create or update resources in dependency order, such as provider key, model, and caller API key.
2. Poll GET /v1/models with the application caller key when the change should make a model alias visible.
3. Send a request through the exact endpoint and model the application will use when the change should affect proxy behavior.

A positive caller-facing probe is more reliable than assuming a specific propagation time. In self-hosted mode, admin health provides supporting snapshot information, but the proxy path remains the confirmation that a specific change is ready for traffic.

Inspect the Configuration Load

When Prometheus metrics are enabled, query the metrics/status listener to see whether AISIX accepted the latest configuration observation:

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

The response separates the latest source observation from the configuration AISIX actually applied. Use these fields when a source update does not produce the expected proxy behavior:

Field	What It Shows
state	Whether the applied configuration is synced, degraded, out_of_sync, empty, or never_loaded.
source	The source type, the latest observation time and hash, and etcd connection and revision details when applicable.
applied	The configuration hash, apply sequence, application time, per-resource counts, and etcd revision when applicable.
rejected	Resources that failed parsing, schema, reference, or key validation.
last_failure	The most recent configuration-load error recorded since startup.

If state is degraded, AISIX is serving the accepted subset and rejected identifies what did not apply. If it is out_of_sync, AISIX rejected the latest observation as a whole and continues serving the last-known-good configuration when one is available.

The companion GET /status/ready route returns 200 after the first valid configuration is applied and 503 before then. Both status routes are unauthenticated, so keep the metrics/status listener private. For response examples and all status meanings, see Health Checks.

Check Snapshot Freshness

In self-hosted mode, GET /admin/v1/health can include a config block that reports the configuration snapshot freshness. Use it when writes succeed but the proxy still behaves as if it is using older configuration.

Request admin health with an admin key:

AISIX_ADMIN_KEY="YOUR_ADMIN_KEY"

curl -sS "http://127.0.0.1:3001/admin/v1/health" \
  -H "Authorization: Bearer ${AISIX_ADMIN_KEY}"

The response can include snapshot freshness fields:

{
  "status": "ok",
  "models": [
    {
      "id": "m-uuid",
      "name": "gpt-4o-mini",
      "health": 0
    }
  ],
  "config": {
    "snapshot_revision": 1234567,
    "snapshot_age_seconds": 5
  }
}

Use snapshot_revision to see the highest etcd revision reflected in the loaded snapshot. Use snapshot_age_seconds to see how long it has been since the gateway last applied a configuration event.

Snapshot age does not report whether the watch is connected. It can grow while the configuration is idle, so a large value alone does not prove that the watch is stalled.

Interpret the age while an expected change is in progress. If the revision does not advance while new writes are accepted, the gateway may not be receiving or applying those updates.

The config block is omitted when snapshot freshness is not available. If freshness tracking is available but no snapshot has been applied yet, snapshot_age_seconds can be null.

Troubleshoot Propagation

When writes succeed but proxy requests still fail, use the observed scope to separate a resource problem from a propagation problem:

Observation	Check	Next Action
/status/config reports rejected resources.	state, rejected, and last_failure on the affected gateway instance.	Correct the rejected resource or source document, then confirm that the next load is synced.
A new model returns 404 and is missing from GET /v1/models.	Model alias, model type, caller API key access, and the latest snapshot revision.	Correct the resource relationship or wait for the expected revision, then query model discovery again.
The model appears in discovery but a provider request fails.	Provider key, upstream model ID, provider endpoint, and outbound connectivity.	Troubleshoot the provider path instead of repeating the configuration write.
One gateway instance differs from the others.	Startup configuration, etcd prefix, and snapshot revision on each self-hosted instance.	Restore the outlying instance's configuration connection, then verify the caller-facing path.
All instances continue to use old state while new writes succeed.	Whether the expected revision advances during the change.	Check etcd reachability and the configuration watch before retrying writes.

Repeating the same write usually does not fix a gateway that is not receiving configuration updates. First identify whether the resource relationship is wrong or whether the expected revision is not reaching the affected instance.

Next Steps

You have now seen how configuration writes move from the configuration store into the proxy request path. Continue with Production Deployment for production readiness checks, or Health Checks when you need to inspect health endpoints and snapshot freshness.