Configuration Propagation

AISIX separates configuration updates from proxy request handling. Every gateway serves requests from its latest applied snapshot, regardless of where its dynamic resources originate.

An accepted resource update and proxy readiness are therefore not the same state. Verify important changes through the same caller-facing path the application uses.

How Updates Reach the Gateway

The update trigger depends on the configured resource source:

Resource Source	How an Update Reaches AISIX
Declarative resources.yaml file	The gateway loads the file at startup and re-reads it after SIGHUP.
etcd	The gateway watches its configured keyspace for resource changes.
AISIX Cloud	The control plane projects environment resources to connected gateways.

Each source feeds the same snapshot-application path:

AISIX replaces the loaded configuration atomically after a successful application. New requests use the current snapshot. A request that started before the replacement can continue using the previous snapshot.

Invalid updates do not silently replace a valid snapshot. Depending on the source and failure, AISIX either applies the accepted subset and reports rejected resources, or continues serving the last-known-good configuration.

Reload a Resources File

An open-source AISIX gateway does not watch resources.yaml for changes. Validate an edited file before sending SIGHUP, then confirm that the gateway applied the new snapshot.

The commands below use the container name and resources path from the Open-Source AISIX Gateway Quickstart. Adapt them if your gateway uses a different container name or path.

Edit the resources file mounted into the running container. The quickstart provides a complete example that adds a second model and grants the existing caller API key access to it.

Add New Environment Variables

A running container cannot inherit environment variables that you export later on the host. If an edited resources file introduces a new ${VAR} reference, first validate the file in a short-lived container with every required variable:

docker run --rm \
  -v "$(pwd):/etc/aisix:ro" \
  -e OPENAI_API_KEY \
  -e CALLER_API_KEY \
  -e PROVIDER_VARIABLE_1 \
  -e PROVIDER_VARIABLE_2 \
  --entrypoint /usr/local/bin/aisix \
  ghcr.io/api7/aisix:latest \
  validate --resources /etc/aisix/resources.yaml

Replace the provider-variable names with those used in the resources file. If the provider needs only one credential variable, remove the -e PROVIDER_VARIABLE_2 line from both commands. Re-export OPENAI_API_KEY and CALLER_API_KEY first if they are not available in the current shell.

After validation succeeds, recreate the quickstart container with the same variables:

docker rm -f aisix-quickstart

docker run -d --name aisix-quickstart \
  -v "$(pwd):/etc/aisix:ro" \
  -e OPENAI_API_KEY \
  -e CALLER_API_KEY \
  -e PROVIDER_VARIABLE_1 \
  -e PROVIDER_VARIABLE_2 \
  -p 3000:3000 -p 9090:9090 \
  ghcr.io/api7/aisix:latest

The mounted working directory preserves resources.yaml when the old container is removed. The replacement loads the validated file at startup, so skip SIGHUP and continue with Confirm the Applied Configuration.

Reload with Existing Environment Variables

If the edited file does not introduce any new environment variables, validate it inside the running container:

docker exec aisix-quickstart \
  /usr/local/bin/aisix validate --resources /etc/aisix/resources.yaml

This command reuses the running container and its environment. Validation uses the same file-loading pipeline as startup and reload, including environment-variable interpolation, name-reference resolution, and schema validation. An invalid file exits non-zero with the full error report.

Successful validation reports that the file loaded and shows its resource count:

OK: /etc/aisix/resources.yaml loaded <number> resource(s)

Send SIGHUP to reload the file:

docker kill --signal=HUP aisix-quickstart

Confirm the Applied Configuration

Confirm that the new configuration was applied:

curl -sS "http://127.0.0.1:9090/status/config"

A successful application reports "state": "synced" and resource counts that reflect the edit. After a SIGHUP reload, apply_seq is greater than its previous value. If a reload fails, the gateway keeps serving the last valid configuration, reports out_of_sync, and identifies the rejected entries.

Apply Related Resources in Order

Dynamic resources can depend on one another: a model can reference a provider key, and a caller API key can allow that model. When a source delivers resources individually, one accepted resource can become visible before another during a multi-resource change.

Apply related resources in dependency order:

1. Create or update the provider key.
2. Create or update the model that references it.
3. Create or update the caller API key that can use the model.
4. Verify the resulting model and request path.

This order reduces temporary reference failures, but the final caller-facing check remains the readiness signal for the complete change.

Verify a Configuration Change

For model access changes, query model discovery with the same caller API key the application will use:

AISIX_API_KEY="YOUR_CALLER_API_KEY"

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

When automation must wait for a change, poll for the expected model alias instead of sleeping for a fixed interval. After the alias appears, send a request through the exact endpoint and model whose behavior changed.

A caller-facing probe confirms more than configuration acceptance. It verifies that the gateway serving the application loaded the resource relationship and can resolve the caller's access.

Inspect a Delayed Change

If the expected behavior does not appear, inspect the configuration state on the affected gateway:

curl -sS "http://127.0.0.1:9090/status/config"

Use the result to locate the delay:

• source shows the latest configuration observation and store connectivity where applicable.
• applied shows the snapshot AISIX is serving.
• rejected identifies resources that failed validation.
• last_failure records the latest load error.

A degraded state means AISIX is serving an accepted subset while reporting rejected resources. An out_of_sync state means the latest observation was rejected as a whole and AISIX continues serving the last valid configuration when one is available.

For the complete response schema, state meanings, metrics, and alerts, see Configuration Status.

Separate Propagation from Request Failures

Use the point of failure to avoid repeating an update that already propagated:

• If /status/config reports a rejection, correct the rejected resource or source document.
• If the source revision does not advance during an expected etcd change, check store connectivity and the watched prefix.
• If a model is missing from GET /v1/models, check its alias, type, caller access, environment, and applied snapshot.
• If the model appears but the provider request fails, troubleshoot the provider credential, endpoint, quota, or network path.
• If one gateway differs from its peers, compare the resource source and applied snapshot on each instance.

Repeating the same write does not repair a gateway that is not receiving configuration. Establish whether the source, application step, resource relationship, or request path is failing before changing the resource again.

Next Steps

Continue with Health Checks to choose probes for process, traffic, configuration, and model health.