Upgrade AISIX
An AISIX deployment is upgraded in two parts: the AISIX Cloud control plane and the AISIX gateways that serve traffic. They are upgraded independently, in a fixed order, and the releases they run may differ while you work through the fleet.
This page states which upgrade paths are supported, the order to follow, and the procedure for each installation method. For what changed in a given release, see the release notes.
Supported Upgrade Paths
The supported upgrade floor is 0.12.0. A deployment running 0.12.0 or later upgrades directly to any newer release, including the current one.
Releases may be skipped. Upgrading 0.12.0 straight to the current release is supported and does not require stepping through the releases in between. The floor is what makes the jump supported, not the distance: any source at or above 0.12.0 reaches any newer target in one step.
The floor moves only when a release announces that it moves. It is not raised silently as new releases ship, so a deployment that is supported today stays supported until an announcement says otherwise. Check the release notes of the version you are upgrading to before planning a jump from an old deployment.
A deployment below 0.12.0 upgrades in two steps: first to a release between 0.12.0 and the version you are on your way to, letting it start and finish its database migrations, then to your target.
Compatibility exceptions are per feature, not per version: what can differ during an upgrade is one configuration setting, never the release pairing as a whole. Two things can differ, and they are not the same. A setting a gateway release cannot load would cost that gateway the whole resource — between 0.12.0 and the current release there is no such setting, so every configuration the control plane can save loads as a whole resource on every gateway from the floor up. A setting a gateway release does not recognize is the ordinary case during an upgrade: the resource loads and serves normally, and that one setting does nothing on that gateway until it is upgraded.
Upgrade Order and the Mixed-Version Window
Upgrade the control plane first, then the gateways. The control plane understands every gateway release from the floor up; a gateway does not necessarily understand a control plane newer than itself.
Between the two steps the deployment runs mixed versions: a control plane on the new release and gateways still on the old one. That window is bounded by the floor, not by a clock. It may last as long as you need it to — a staged fleet rollout, a canary environment held back for a week, a gateway that is upgraded on its own maintenance schedule — provided every gateway stays at or above 0.12.0. Gateways serve traffic normally throughout.
Gateway versions are reported per instance in the environment's Data planes view, so you can see which instances are still behind. The control-plane version is shown at the bottom of the dashboard's left navigation and by GET /api/config/public; see Verify the Installation.
Saving a setting that some gateways in scope do not recognize is allowed, and the save response says so: it names the field, the oldest gateway release that implements it, and how many gateways will ignore it. The console shows the same warning on the form. Read it before you rely on the setting — a restrictive setting that is ignored is not enforced on those gateways, which is the direction that matters.
On the gateway side, aisix_config_partially_compatible_resources counts resources carrying fields the gateway's own version does not recognize. It is expected to be non-zero during the window and should return to zero once the gateways are upgraded. See Metrics Reference for the configuration-health metrics.
Read the Upgrade Notes for Every Release You Skip
Skipping a release skips its release notes, not its behavior. When you upgrade across several releases at once, every intermediate release's Upgrade Notes apply to you, and they apply in order — read them oldest first, from the release after the one you are on through the release you are upgrading to.
Upgrade Notes are the pre-upgrade actions: a configuration key whose meaning changed, a Helm value that starts being honored, an alert expression to review. A note in a release you jumped over is not superseded by the notes of a later release.
Before upgrading to 1.0.0 from an earlier release, also work through Review Existing Guardrails When Upgrading to 1.0.0, which is a pre-upgrade checklist rather than a note: it asks you to identify and disable affected semantic guardrails before the control plane starts under the new version.
Upgrade a Package Installation
The Docker Compose packages — the online quickstart package and the offline package — are upgraded the same way: extract the new package over the existing installation directory and re-run run.sh.
Take a database backup first. cp-api migrates the schema on its first start under the new version, and a restored backup is what a rollback depends on.
An online installation upgrades by re-running the quickstart from the directory that contains the installation — it fetches the current package, extracts it over aisix-self-hosted, and runs run.sh:
curl -sL "https://run.api7.ai/aisix-self-hosted/quickstart" | bash
An air-gapped installation needs the offline package carried in. Download it on a connected machine — the URL below resolves to the current release, and a version-pinned URL of the form aisix-self-hosted-offline-<version>.tar.gz is published alongside it:
curl -fSL "https://run.api7.ai/aisix-self-hosted/aisix-self-hosted-offline-latest.tar.gz" \
-o aisix-self-hosted-offline-latest.tar.gz
Extract it over the installation directory from the directory that contains it, not from inside it:
cd /path/that/contains/aisix-self-hosted
tar -xzf aisix-self-hosted-offline-latest.tar.gz
cd aisix-self-hosted
./run.sh
Running tar from inside aisix-self-hosted unpacks a nested copy instead, which leaves the original installation untouched.
The package contains no .env, so this replaces the Compose file, scripts, and bundled images while leaving your secrets and the data volume in place. The one value in .env that belongs to the package is AISIX_VERSION, which pins every image — including the gateway image the dashboard hands out in generated install commands. run.sh moves it to match the package and prints what it did:
==> Upgrading AISIX 1.0.0 -> 1.1.0.
AISIX_VERSION in .env now matches this package; your secrets are untouched.
run.sh prints one of two lines here. The one above is the normal case; a .env that carried no AISIX_VERSION at all gets ==> Added AISIX_VERSION=<version> to .env (it had none). instead, and that upgrade proceeds too. If neither line appears, nothing was upgraded. Confirm what is actually running:
COMPOSE_PROJECT_NAME=aisix-self-hosted docker compose images
Individual image overrides — AISIX_API_IMAGE, AISIX_DPM_IMAGE, AISIX_UI_IMAGE, and AISIX_CLOUD_DP_IMAGE — are never rewritten by run.sh and continue to override AISIX_VERSION. Remove an override before upgrading if you want the component to follow the package. See On-Premises Configuration.
Extracting the new package into a different directory is the one variation to avoid. The Compose project name belongs to the package, so the new directory would adopt the same data volume while sitting next to a brand-new .env. run.sh stops rather than starting: it refuses as soon as it finds containers for this stack running from another directory, whatever the new .env holds. Go back to the original directory and upgrade there — or, if you mean to move the installation, run ./run.sh down in the original directory first and copy its .env across before running the new one.
Upgrade with Helm
The control-plane chart and the gateway chart ship with the same version and appVersion every release, so both move to the same release tag. Upgrade the control-plane chart first.
Take a database backup before upgrading the control-plane chart, whether the database is the bundled one or external.
helm repo update
helm upgrade aisix-cp api7/aisix-cp -f your-cp-values.yaml
Upgrade with your own values file rather than --reuse-values. --reuse-values replays the previous release's fully resolved values, chart defaults included, so a default the new chart changed is not adopted. The charts' probe budgets are among the defaults that move with a release, and a workload brought up on a new image under the previous chart's budget can be restarted by its own probe. If you have never kept a values file, helm get values aisix-cp prints the overrides the release was installed with; save those and pass them with -f.
Wait for the cp-api pods to become ready — the schema migration runs on first start under the new version — before continuing.
Then upgrade the gateways, one release at a time or all at once, depending on how you stage the fleet:
helm upgrade aisix api7/aisix -f your-gateway-values.yaml
Gateways are replaced by the Deployment's rolling update, which is Kubernetes' default unless you set updateStrategy on the chart, so on a larger deployment several pods are replaced at once. A replacement pod does not receive traffic before it can serve it: Kubernetes keeps it out of the Service endpoints until the gateway has applied configuration from the control plane. See Deploy Gateways on Kubernetes for the probe budget and drain settings that govern the roll.
One value deserves a check before you start: api.dpImage on the control-plane chart pins the gateway image the console hands out in generated install commands, exactly as AISIX_CLOUD_DP_IMAGE does in a package installation. If you set it explicitly, it carries forward across upgrades, and gateways added after the upgrade come up on the old image. Leave it empty to follow the chart's appVersion.
Repeat the gateway step for every gateway release in the deployment. Until you do, those gateways are in the mixed-version window described above, which is supported.
What the Control Plane Checks During the Window
While gateways are still behind, the control plane checks each configuration you save against what those gateways can actually load.
Saving a configuration that a registered gateway would not load fails with HTTP 422 and the error code DP_INCOMPATIBLE. The response names the gateway release that cannot load it, the affected gateways, the field path, and the schema reason. Nothing is written: the resource keeps the configuration it had. The check is per feature — it is triggered by the specific setting you are saving, not by the version difference itself — so it appears only when you configure something the older gateways cannot serve. Upgrade those gateways, or leave the setting out until they are upgraded.
Right after a gateway upgrade, the previous registration of a restarted gateway can still be counted for up to five minutes. A save refused in that window naming a version you have already upgraded away from is usually that stale registration; wait and retry.
Gateways below the floor are not checked at all. There is no supported contract to check them against, so the save succeeds and the response carries a below_floor warning giving how many gateways are affected, the versions they report, and the floor. Treat it as what it is: those gateways are out of support and the control plane cannot tell you whether they will load what you just saved. Upgrade them to 0.12.0 or later.
The Upgrade Floor Gate
An upgrade from below the floor is refused rather than attempted, because a half-migrated database is much harder to recover from than a second upgrade step.
cp-api refuses to start when the database was last run by a version below the floor. The error names the version recorded in the database, the oldest version this release can upgrade from, and the override. Nothing is migrated before the check runs, so a refused start leaves the database exactly as the previous release left it. The fix is to upgrade to a supported version first.
The check reads a version record the control plane writes from this release onward, so it can only judge a database that a release carrying that record has already run. A database last run by an earlier release carries no record, cannot be judged, and is therefore not refused — on that one upgrade the package installer's .env check is the only thing that catches it, and a Helm upgrade is not gated at all. Check the version you are coming from yourself.
The offline and online packages refuse the same upgrade in run.sh, before any container starts, and tell you the two steps: get a package between 0.12.0 and the version you are installing, extract that over the installation directory and run it, let it finish its migrations, then extract your target package and run it again.
To proceed anyway, set AISIX_ALLOW_UNSUPPORTED_UPGRADE=1. The value must be exactly 1. Take a database backup first — this runs migration paths that have not been exercised from that far back, and the backup is your only way out.
For a package installation, set it on the command:
AISIX_ALLOW_UNSUPPORTED_UPGRADE=1 ./run.sh
For Helm, pass it to cp-api through api.extraEnvVars:
api:
extraEnvVars:
- name: AISIX_ALLOW_UNSUPPORTED_UPGRADE
value: "1"
Add it to the values file you upgrade with, so it is actually applied:
helm upgrade aisix-cp api7/aisix-cp -f your-cp-values.yaml
The override is read by cp-api and by the package's run.sh, so one name covers both paths. Remove it again once the upgrade has completed, so it cannot silently permit a later unsupported upgrade.
Roll Back
Roll back in the reverse order: gateways first, then the control plane.
A rollback of the control plane is a database restore, not just an image change. The new version has already migrated the schema, so starting the previous version against it runs old code against a database it does not know. Restore the backup you took before the upgrade, then start the previous version against the restored database.
For a package installation, run.sh refuses to start when the package in the directory is older than the version recorded in .env, because that is nearly always an accident — an old tarball re-downloaded, or a latest URL fetched onto a newer install. A deliberate rollback, after restoring the database backup, acknowledges it:
AISIX_ALLOW_DOWNGRADE=1 ./run.sh
run.sh prints the deployed version when it finishes. Check that line against the version you meant to roll back to.
For a Helm installation, helm rollback returns the workloads to the previous revision; the database restore is still yours to perform first.
Situations That Are Not Supported
- Upgrading from a release below the floor in one step. Upgrade to a release between 0.12.0 and your target first, let it finish its migrations, then upgrade again.
- Adding a gateway older than the environment's existing configuration already requires. The mixed-version window covers gateways being upgraded forward. Introducing a gateway on an older release into an environment whose saved configuration already depends on a newer one is not supported — that gateway would not load the configuration it is given.
- Running a gateway below 0.12.0 against a current control plane. Such a gateway is outside the supported range; the control plane cannot answer for what it will load.
- Upgrading the gateways before the control plane. The order is control plane first, in every deployment option.