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 determines which environments receive a resource. Its attachments, references, or conditions then determine which requests use it.

Resource family	Ownership and projection	Request scope
Models and caller API keys	Belong to one environment and project to every gateway connected to it.	The requested model and resolved caller API key select the applicable entries.
Provider keys	Belong to the organization and project only to their allowed environments.	Models reference provider keys. Passthrough routes reference one when they inject upstream credentials.
MCP and OpenAPI-backed servers	Belong to the organization. Approved servers project only to their allowed environments; an OpenAPI-backed server is an MCP server with type: openapi.	Caller tool grants and applicable guardrail attachments control access and inspection.
A2A agents	Belong to the organization and project only to their allowed environments.	The caller API key must allow the agent.
Guardrails and attachments	Belong to one environment and project together. An unattached guardrail is not enforced.	Attachments scope a guardrail to an environment, model, caller API key, team, MCP server, or passthrough route.
Cache policies	Belong to one environment and project to its gateways.	A policy can cover the environment, a model alias, or a caller API key.
Rate-limit policies	Belong to one environment and project to its gateways.	Conditions can select traffic by team, member, caller API key, model, model name, or provider.
OIDC providers and claim mappings	Belong to one environment and project to its gateways.	They authenticate JWT callers and resolve eligible claims to caller API keys.
Passthrough routes	Belong to one environment and project to its gateways.	Route matching and the caller API key's route grant determine access.
Observability exporters	Belong to one environment and project to its gateways.	Each enabled exporter receives eligible gateway telemetry according to its kind and content settings.
MCP environment access and authentication settings	Belong to one environment and project to its gateways.	The environment policy defines a default tool-access layer. Authentication settings define the API key, OAuth, or anonymous behavior of /mcp.
MCP team access policies	Belong to an organization through their team and project to every environment in that organization.	A team policy applies to caller API keys bound to that team and intersects with the environment and key-level access layers.
Budgets	Remain in the AISIX Cloud control plane instead of entering the projected snapshot.	The gateway requests a decision for the resolved caller API key and can temporarily use a cached decision during an outage. See Budgets.

Changing an organization-owned resource's allowed environments adds or removes that resource from the corresponding snapshots. A successful write confirms only that the control plane accepted the resource and its target environments; it does not confirm that every gateway has received it.

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:

# AISIX_CP includes /api and has no trailing slash.
# The local On-Premises quickstart uses http://localhost:8080/api.
export AISIX_CP="YOUR_AISIX_CLOUD_ADMIN_API_BASE_URL"
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.