Resource Projection

AISIX Cloud publishes saved resource changes to gateways connected to an environment. Each gateway validates a new revision and applies the accepted configuration to new requests. Publication is asynchronous, so gateway instances can temporarily report different revisions.

A successful dashboard or API response confirms only that the control plane accepted the change. To verify that it took effect, trace it from the control-plane revision to the gateway snapshot and then to a live request.

Resource Scope

Resource ownership and policy scope determine which gateways receive a resource and which requests use it.

Resource	Projection rule
Models and caller API keys	Project to gateways connected to their environment.
Provider keys	Project only to their allowed environments. A model must also reference the provider key.
Guardrails	Project with their environment and attach to the environment, a model, a caller API key, or a team.
Cache policies	Project with their environment and apply to all traffic, a model alias, or a caller API key.
Rate-limit policies	Project with their environment and target a caller API key, model, team, member, or team member.

Verify a Projected Change

Check the control plane, gateway, and live request in order.

1. Compare Published and Applied Revisions

Set the control-plane API URL, a read-scoped admin token, and the environment ID:

export AISIX_CP="https://<your-cp-api-host>/api"
export AISIX_TOKEN="YOUR_ADMIN_TOKEN"
export ENV_ID="YOUR_ENVIRONMENT_ID"

Compare store_revision with each node's applied_revision:

curl -sS "${AISIX_CP}/environments/${ENV_ID}/dp_nodes" \
  -H "Authorization: Bearer ${AISIX_TOKEN}" \
  | jq '{
    store_revision,
    nodes: [
      .data[] |
      {
        hostname,
        last_heartbeat_at,
        applied_revision,
        config_hash
      }
    ]
  }'

A node is current when its applied_revision is equal to or greater than store_revision. Matching config_hash values indicate that gateway instances have accepted the same configuration.

Optional revision fields

The control plane can omit store_revision, applied_revision, or config_hash when tracking is unavailable or a gateway has not reported them. In that case, use the gateway status endpoint in the next step. Heartbeats are periodic, so direct gateway status can also be newer than the control-plane view.

If a gateway has no recent heartbeat, troubleshoot its management connection before checking projection. See Connect an AISIX Gateway.

2. Inspect the Gateway Snapshot

Query the metrics and status listener on the gateway instance handling traffic:

curl -sS "http://127.0.0.1:9090/status/config" \
  | jq '{
    state,
    source,
    applied,
    rejected,
    last_failure
  }'

The change is fully applied when state is synced, source.connected is true, applied.applied_revision reflects the expected revision, and rejected is empty.

If source.connected is false, restore the configuration connection. The gateway can continue serving its last accepted snapshot during an outage, but it cannot receive new changes. See Offline Resilience.

If state is degraded or out_of_sync, use rejected and last_failure to identify the invalid resource. See Configuration Status for the state definitions, complete response, and Prometheus metrics.

Keep the status listener private

The status listener is unauthenticated. Keep port 9090 private to the monitoring network.

3. Verify Caller-Visible Behavior

After the gateway applies the change, verify it through the same gateway endpoint and caller identity the application uses.

For a model or caller-access change, first query model discovery:

export AISIX_PROXY="http://127.0.0.1:3000"
export AISIX_API_KEY="YOUR_CALLER_API_KEY"

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

Confirm that the expected model alias appears, then send a request from the relevant provider or feature guide.

If the result is unexpected after revisions match, first confirm that the request reached the inspected gateway. Then check the environment, model alias, caller API key, provider-key access, and policy scope.

Next Steps

If you have not sent live traffic yet, choose a provider upstream and follow its setup guide. Before placing multiple gateway instances behind a production load balancer, continue with High Availability.