Skip to main content
Version: 1.11.0

Resource Projection

The control plane 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 familyOwnership and projectionRequest scope
Models and caller API keysBelong to one environment and project to every gateway connected to it.The requested model and resolved caller API key select the applicable entries.
Provider keysBelong 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 serversBelong 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 agentsBelong to the organization and project only to their allowed environments.The caller API key must allow the agent.
Guardrails and attachmentsBelong 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 policiesBelong to one environment and project to its gateways.A policy can cover the environment, a model alias, or a caller API key.
Rate-limit policiesBelong 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 mappingsBelong to one environment and project to its gateways.They authenticate JWT callers and resolve eligible claims to caller API keys.
Passthrough routesBelong to one environment and project to its gateways.Route matching and the caller API key's route grant determine access.
Observability exportersBelong 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 settingsBelong 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 policiesBelong 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.
Blocking budgets and the budget enforcement modeA budget projects to every environment it applies to: an organization, team, member, per-member, or tag budget to every environment in the organization, an environment budget to that environment, a caller API key budget to the key's environment, and a provider key budget to every environment the provider key is allowed in. Warn-only budgets are not projected. The strict budget enforcement mode projects to every environment in the organization.The gateway checks the projected budgets locally and keeps enforcing them during an outage. See Behavior During a Control-Plane Outage.

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. Check Gateway Node Status​

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 AISIX Enterprise quickstart uses http://localhost:8080/api
export AISIX_CP="YOUR_AISIX_CONTROL_PLANE_API_URL"
export AISIX_TOKEN="YOUR_ADMIN_TOKEN"
export ENV_ID="YOUR_ENVIRONMENT_ID"

List the environment's gateway nodes with their status:

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

The control plane decides each node's status:

statusLabel in Data planesMeaning
healthyHealthyThe node reported within the last two heartbeat intervals.
out_of_syncConfig out of syncThe node reports on time, but configuration saved five minutes ago or earlier has still not been applied on it. config_out_of_sync_since gives the time the lag began.
warningMissed heartbeatsThe node has been silent for more than two heartbeat intervals but fewer than five.
offlineOfflineThe node has been silent for five heartbeat intervals or more.

The heartbeat interval is 15 seconds by default, so warning and offline start after 30 and 75 seconds of silence. out_of_sync replaces only healthy: a node in warning or offline keeps that status whatever its configuration.

For a node the control plane can judge, healthy means the node is current. The gateway reports, separately for the environment's configuration and for the configuration shared by every environment, the revision up to which it has processed every change. The node lags when the newest saved revision of either is higher. When a node catches up with everything that was newest when its lag began and a newer save then overtakes it, the lag restarts from that point. A node that keeps up with a steady stream of changes is therefore not reported, and out_of_sync means that configuration saved at least five minutes ago has not taken effect.

Only gateways at 1.11.0 or later report these per-environment revisions. The control plane does not judge an older gateway, so its status is never out_of_sync. For such a node, use the gateway status endpoint in the next step.

store_revision is the newest saved revision of the environment's configuration and of the shared configuration; changes to other environments do not move it. Do not compare it with a node's applied_revision to decide whether the node is current. applied_revision is a single number, and it cannot show whether the node has applied both the environment's and the shared configuration. Matching config_hash values indicate that gateway instances have accepted the same configuration.

In Data planes, an out_of_sync node shows a Config out of sync badge, and hovering over it shows when the lag began. The environment overview counts out-of-sync nodes separately from healthy and offline ones. For an out-of-sync node, first check the gateway's logs for errors on its configuration connection to the control plane. Restart the gateway pod only after that connection is healthy again. A gateway restarted while the connection is down cannot load configuration from the control plane until the connection recovers. See Configuration Changes Stop Arriving While Heartbeats Continue.

partially_compatible_resources lists resources the node serves while ignoring fields it does not recognize. Require this list to be empty or omitted when every field must take effect.

The dashboard surfaces the same gateway reports. The environment overview distinguishes ignored fields from whole-resource rejections, and Data planes shows the compatibility state and details for each node. The oldest release the control plane supports is 1.9.0. A node that runs an older release is marked Unsupported version with an instruction to upgrade it. The response reports the supported release as support_floor and marks the node with below_support_floor: true. Saves are not checked against such a node, and it may fail to load newly saved configuration. Check these runtime signals even when the original save returned no warning, because a gateway can register or roll back afterward.

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 a Gateway.

2. Inspect the Gateway Snapshot​

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

# AISIX_STATUS_URL is the metrics and status listener origin without a trailing slash or endpoint path
# The open-source quickstart uses http://127.0.0.1:9090
export AISIX_STATUS_URL="YOUR_AISIX_STATUS_LISTENER_URL"

curl -sS "${AISIX_STATUS_URL}/status/config" \
| jq '{
state,
source,
applied,
rejected,
partially_compatible,
last_failure
}'

The change is fully applied when state is synced, source.connected is true, applied.applied_revision reflects the expected revision, and both rejected and partially_compatible are 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. If partially_compatible is non-empty, the resource is in service but its listed fields have no effect on this gateway. 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:

# AISIX_PROXY is the gateway origin without a trailing slash or endpoint path
# The local quickstarts use http://127.0.0.1:3000
export AISIX_PROXY="YOUR_AISIX_GATEWAY_URL"
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 the gateway reports the change as applied, 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.