# 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-scope "Direct link to 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.                                                                                                                  |
| Blocking budgets and the budget enforcement mode   | A 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](https://docs.api7.ai/ai-gateway/traffic-controls/budgets.md#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[​](#verify-a-projected-change "Direct link to Verify a Projected Change")

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

### 1. Check Gateway Node Status[​](#1-check-gateway-node-status "Direct link to 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`:

| `status`      | Label in **Data planes** | Meaning                                                                                                                                                                  |
| ------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `healthy`     | **Healthy**              | The node reported within the last two heartbeat intervals.                                                                                                               |
| `out_of_sync` | **Config out of sync**   | The 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. |
| `warning`     | **Missed heartbeats**    | The node has been silent for more than two heartbeat intervals but fewer than five.                                                                                      |
| `offline`     | **Offline**              | The 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](https://docs.api7.ai/ai-gateway/deployment/troubleshooting.md#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](https://docs.api7.ai/ai-gateway/cloud/connect-a-gateway.md).

### 2. Inspect the Gateway Snapshot[​](#2-inspect-the-gateway-snapshot "Direct link to 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](https://docs.api7.ai/ai-gateway/cloud/offline-resilience.md).

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](https://docs.api7.ai/ai-gateway/reference/config-status.md) 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[​](#3-verify-caller-visible-behavior "Direct link to 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[​](#next-steps "Direct link to Next Steps")

If you have not sent live traffic yet, [choose a provider upstream](https://docs.api7.ai/ai-gateway/providers/overview.md) and follow its setup guide. Before placing multiple gateway instances behind a production load balancer, continue with [High Availability](https://docs.api7.ai/ai-gateway/cloud/high-availability.md).
