Upgrade Compatibility Matrix
The verified LTS-to-LTS upgrade paths, the version combinations to avoid, and the release lines that changed API7 Gateway's data model.
This page is a single reference for three questions that are otherwise answered by reading several release notes and upgrade guides in full: which upgrade paths are verified and self-service, which specific version combinations are known to fail, and which release lines changed how API7 Gateway models its data rather than just adding a feature. It does not replace the pair-specific guides — it tells you which one to open.
Verified LTS-to-LTS paths
| Source LTS | Target LTS | Verified anchors | Guide |
|---|---|---|---|
| 3.9 | 3.10 | Source 3.9.20, target 3.10.7 | Upgrade from 3.9 LTS to 3.10 LTS |
| 3.8 | 3.10 | Source 3.8.23, target 3.10.7 | Upgrade from 3.8 LTS to 3.10 LTS |
Both routes are self-service only within the applicability boundaries stated in their guide (external PostgreSQL 15.x, exact Helm chart and image versions, Deployment-workload gateways). Outside those boundaries — a different database, RPM, a DaemonSet gateway, or an earlier patch than the stated source anchor — contact API7 Support rather than adapting the self-service steps. For the chart-version-to-application-version pairs each route uses, see Release Notes: Chart and application version correspondence.
For a patch or adjacent minor-version upgrade that isn't an LTS-to-LTS jump, use Plan an API7 Gateway Upgrade and the target release's own release notes instead of this matrix.
Known upgrade blockers
These are specific version combinations documented elsewhere in this site as broken or unsafe. Check a planned upgrade against this table before scheduling it.
| Combination | What happens | Source |
|---|---|---|
Control plane 3.2.16.2 or earlier upgrading directly to 3.3.1 or later | The Dashboard fails to start. | 3.3.2 release notes |
Targeting 3.10.6 on the 3.9-to-3.10 LTS route | The target data plane can report Healthy and Compatible while Basic Auth still rejects a valid password containing a colon. 3.10.7 includes the required fix; 3.10.6 does not. | Upgrade from 3.9 LTS to 3.10 LTS |
Any LDAP Auth consumer whose user_dn contains a structural DN character (,, +, =, <, >, ;, ", \) | Source and target data planes require different stored representations of the same username. Schema validation and the compatibility report do not detect the mismatch. Requires an API7 Support-assisted plan on both the 3.8-to-3.10 and 3.9-to-3.10 routes. | Both pair-specific upgrade guides |
| Running source and target control-plane versions against the same database | Not supported on any route; both pair-specific guides call this out explicitly as a rule, not just a recommendation. | Both pair-specific upgrade guides |
Release lines that changed the data model
An upgrade that crosses one of these release lines changes more than configuration defaults — it changes what a resource is or how it's organized. Review the linked release notes in full before upgrading across the boundary, even if the target version isn't your final destination.
| Release | Change | Why it matters for upgrade planning |
|---|---|---|
3.6.0 | Service Templates lose their per-template service runtime configuration; publishing is simplified to carry no runtime configuration. | Existing service-template runtime configuration is dropped (published service configuration is not). Review templates that rely on template-level runtime settings before upgrading past this line. |
3.9.0 | The Developer Portal is completely redesigned: the built-in Portal SSO feature is removed, and the Portal frontend becomes a separate open-source, SDK-based frontend. The data-plane health-check control API (GET /v1/healthcheck, GET /v1/healthcheck/{src_type}/{src_id}) changes its response shape (healthy_nodes replaced by per-node status). | A Developer Portal deployment needs a migration plan before crossing this line — see the Developer Portal sections in both pair-specific guides. Monitoring scripts and dashboards that parse the health-check response need updating regardless of Developer Portal use. |
3.10.0 | The Service Template / Service Hub model is removed entirely: services are owned directly by gateway groups through the Admin API, with no separate template, publish, version, or rollback layer. Existing service templates and published services are migrated automatically (original data preserved, so the migration is reversible), and IAM permission policies that referenced service-template or published-service ARNs are rewritten. hmac-auth also changes its signed_headers default to ["date"], and the data-plane runtime moves from OpenResty 1.21.4.4 to 1.29.2.4. | This is the largest single-release model change in the matrix. Both LTS routes cross it, so both guides carry a full compatibility checklist — do not attempt a direct upgrade across 3.10.0 without reading it. |
Related
- Release Notes: Chart and application version correspondence — the chart-to-application version pairs referenced above.
- Upgrade History Highlights — smaller behavior changes scattered across individual patch releases, outside the two LTS boundaries above.
- Choose an LTS Upgrade Path — the routing page for the two pair-specific guides.
- Plan an API7 Gateway Upgrade — the general control-plane and data-plane upgrade mechanics this matrix assumes.
- Version Support Policy — which release lines are currently under LTS support.