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, so 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 Proxy Readiness

Treat a successful configuration write as resource acceptance. Treat a proxy-visible result as readiness.

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

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. A positive probe is more reliable than assuming a specific propagation time.

Use one of these caller-facing probes:

• GET /v1/models, when the change should make a model alias visible to a caller API key.
• The exact proxy endpoint your application uses, when the change should make a request succeed.

Use admin health to detect a stale or wedged configuration watch. Use the proxy endpoint, with the same caller API key your application uses, to confirm that a specific change is ready for traffic.

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:

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 configuration. A steadily growing age, especially one that grows past several minutes during active configuration changes, can indicate that the watch is stalled or that the gateway cannot reach the configuration store.

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.

Review Propagation

When writes succeed but proxy requests still fail, first confirm that the dependent resources exist and reference each other correctly. Then check whether the proxy-visible state has caught up.

If a newly created model returns 404, check whether the model alias appears in GET /v1/models for the caller API key. If it does not appear, inspect the caller API key access list and the configuration watch freshness before retrying the same write.

If one gateway instance behaves differently from another, compare snapshot freshness and deployment configuration across those instances. Repeating the same write usually does not fix a gateway that is not receiving configuration updates.

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.