Why an Apache APISIX 3.13 to 3.14 upgrade needs a config review first
For a team running APISIX 3.13 and planning the move to 3.14, the upgrade is mostly about configuration and automation behavior, not new features. The changes that matter sit in how the Admin API writes resources, which authentication plugins now demand secrets, and which scripts quietly depended on values the gateway used to fill in for them. Plan the work as a review of your route definitions, plugin settings and pipelines before you plan any deployment.
The supported path is a direct step from 3.13.0 to 3.14.0, and the release facts for that step are the ones this page works from. The downloads page does not mark any release as long-term support, so treat 3.14 as a current release line and confirm your own support requirements with your vendor or internal policy before you commit to it. Check the APISIX changelog against the exact patch release you plan to deploy, since later patches in the line may carry additional fixes.
Before scheduling a window, ask one question of every team that writes to the Admin API: does any script, Terraform module or GitOps pipeline send a resource and expect the gateway to return it with defaults already set? If the answer is yes for any of them, that work moves to the front of the plan. The sections that follow take each change in turn, but the first deliverable is an inventory of what your environment writes, what it authenticates with and what it reads back.
What changes in 3.14 and what each change breaks
This table lists each change from the 3.13.0 and 3.14.0 release notes, the failure it can cause in an existing gateway, and the action to take before cutover. Read each row against your own routes, plugin configuration and automation, because a change only matters where your setup depends on the old behavior.
| Change | Impact | Action before upgrading |
|---|---|---|
| Admin API stops filling default values on write (3.14.0) | Scripts or GitOps tools that expect defaults to appear in stored objects may see diffs, and ADC-style diffs can trigger full data plane updates. | Export current objects, apply them to a staging cluster on 3.14, and compare stored output with what your tooling expects. Write defaults explicitly where they matter. |
| jwt-auth requires a secret for algorithms other than RS256 and ES256 (3.14.0) | Consumers using HS256 or other symmetric algorithms without a configured secret will fail validation after upgrade. | Audit every jwt-auth consumer for algorithm and secret fields. Add a secret for each symmetric-algorithm consumer, and plan key rotation with the token issuer. |
| openid-connect requires session.secret when bearer_only is false (3.14.0) | Routes that perform browser login sessions without a session secret will be rejected or fail to start sessions. | Find openid-connect routes where bearer_only is false. Set session.secret from your secret store, and confirm the secret is the same across all gateway nodes. |
| server-info plugin deprecated (3.13.0) | The plugin still exists but is marked for removal, so any dashboard or health probe that depends on it has a future break point. | Search your configuration for server-info. Replace its use with the metrics and health endpoints your monitoring already uses, and record the decision. |
| additionalProperties set to false for consumer credentials (3.13.0) | Consumer credential objects carrying extra or misspelled fields are rejected on write, which can block scripted consumer updates. | Validate existing consumer payloads against the 3.13 and 3.14 schemas in staging. Remove unknown fields from automation before it writes to production. |
How the Admin API stops filling defaults and who notices
From APISIX 3.14.0, the Admin API no longer populates default values when it writes a resource. Before this change, a route, upstream or consumer that was posted without a field would come back from storage with that field filled in. After it, the stored object contains only what was written. Any script, GitOps pipeline or controller that sends a partial object and then reads it back will see a different document than it sent, even though nothing about the gateway's routing has changed. Before the upgrade, export the current stored objects from a non-production cluster and compare them with the files your automation holds, so you know which fields depend on server-side defaults.
The clearest documented effect is in the APISIX Ingress Controller 2.0 upgrade guide, which notes that because the Admin API fills in defaults, ADC diffs can break and trigger full data plane updates. ADC compares the desired configuration with what the Admin API reports as stored. When the stored form gains or loses default fields, the comparison can see drift on every run, and a sync may then rewrite the whole configuration to every gateway instance. Confirm with your team whether the Ingress Controller setup in your environment uses ADC, which controller version it runs, and whether a dry run after the upgrade shows unexpected changes across unrelated resources.
To find who is affected, search your repositories and pipelines for code that reads back a resource after writing it, or that diffs a local file against the Admin API response. Typical places are Terraform or other configuration-as-code modules, CI jobs that run curl against the Admin API, and reconciliation loops in custom controllers. Each one should be listed with its owner, the resource types it manages, and whether it compares full objects or only selected fields. Check the APISIX changelog for the 3.14.0 entry to confirm the exact scope of the change before you finalize that inventory.
What to prepare before touching the 3.13 cluster
Four things need to be in hand before any node is changed: a list of the routes and consumers that depend on the behavior 3.14 changes, a list of the tools that read Admin API objects back, a restorable copy of the data, and a staging environment that matches production closely enough to prove the upgrade. Each card below is one of those inputs and what to confirm about it.
Routes and consumers that set JWT algorithms
List every route and consumer that uses the jwt-auth plugin and record the algorithm value in each. In APISIX 3.14.0, a jwt-auth secret is required for any algorithm other than RS256 and ES256, so HS256 or HS512 configurations need a secret before the upgrade. Also list every route using openid-connect with bearer_only set to false, since those now need session.secret. Confirm the owner of each route so the fixes can be scheduled.
Routes using openid-connect sessions
Find every openid-connect configuration where bearer_only is false, which means the gateway manages browser sessions. Those configurations will need session.secret set in 3.14. Check whether the secret is stored in plain configuration or in a secrets manager, and confirm how it will be rotated without logging users out unexpectedly. Also confirm which applications depend on the current session cookie behavior.
Automation that reads Admin API objects back
List every GitOps tool, script, CI job and controller that reads routes, upstreams, consumers or plugin configuration through the Admin API and then compares or rewrites it. Because the Admin API no longer fills default values on write from 3.14, any diff that expects defaults in the stored object may show spurious changes. The APISIX Ingress Controller 2.0 upgrade guide notes this can trigger full data plane updates, so confirm the version of each tool and its diff behavior.
Backups of etcd and configuration files
Take a snapshot of the etcd data used by the cluster and copy the configuration files from every gateway node, including config.yaml and any custom plugin code. Store the copies outside the cluster and test that a snapshot can be restored in a non-production environment. Record the APISIX version and etcd version with each backup so a rollback targets the right combination. Confirm who can authorize a restore.
A staging copy built from production
Build a staging environment from the same configuration, plugin set, certificates and etcd topology as production, using the restored backup as its data. Run the 3.13 to 3.14 change there first and replay the traffic patterns that use the affected plugins, including JWT login, session logins and the automation jobs above. Compare the stored objects before and after the upgrade. Confirm that staging data is sanitized if it contains real credentials or personal data.
Which authentication setups need a secret added
APISIX 3.14.0 requires a jwt-auth secret for consumers that sign tokens with algorithms other than RS256 and ES256. In practice, this covers the HMAC family, HS256, HS384 and HS512. These consumers rely on a shared secret between the token issuer and the gateway, so the gateway needs that secret in its consumer configuration before the upgrade is applied. Public-key algorithms verify tokens with a public key and do not need this addition.
- Find the algorithm in use: Check the
algorithmvalue for every jwt-auth consumer, including consumers created through the Admin API, GitOps repositories and the Ingress Controller. - Confirm the secret source: Ask the identity or token-issuing team where the shared secret lives and whether it matches what the gateway holds today.
- Plan the secret rotation: Adding a secret to a consumer that already has tokens in circulation can invalidate them if the values differ, so coordinate the change with issuers.
- Check automation: Scripts that create consumers without a secret will fail validation after the upgrade.
Confirm with the identity provider or token issuer which algorithm each client uses and whether they can be moved to RS256 or ES256 instead.
Consumers that verify tokens signed with RS256 or ES256 are not covered by the 3.14.0 secret requirement. Verification uses the asymmetric public key that the issuer publishes, so the gateway does not hold a shared signing secret for these consumers. These consumers still need correct configuration under the other changes in the release line, so their absence from the secret requirement does not mean no review is needed.
- Confirm the algorithm: Verify that the consumer configuration actually specifies RS256 or ES256 and not a default or inherited value.
- Check the public key material: Ask the issuer which key is current and how key rotation is communicated to the gateway team.
- Review related fields: Confirm that the consumer fields you rely on are still accepted after the upgrade, since schema checks changed in this release line.
- Test a valid and an invalid token: Run both through a staging gateway to confirm the expected accept and reject behavior.
- Record the decision: Note in the change record that these consumers were reviewed and need no secret.
Confirm with the issuer that the key pair and algorithm in use match what the gateway consumer declares.
When an openid-connect route has bearer_only set to false, APISIX acts as an OpenID Connect relying party that manages a browser session. APISIX 3.14.0 requires a session.secret value in this case. The secret protects the session cookie that the gateway issues after login. Routes that depend on this flow will not load correctly until the secret is present, so this is the group most likely to affect end users directly.
- Identify session-based routes: Search all openid-connect configurations for
bearer_onlyset to false or left to a value that resolves to false. - Store the secret securely: Keep
session.secretin your secret store and reference it from configuration rather than writing it into plain files. - Coordinate with the identity provider team: Confirm the client registration, redirect URIs and whether the provider expects any change when sessions are reset.
- Expect session resets: Users may need to sign in again after the change, so plan the communication.
- Verify the login path: Test the full authorization code flow in staging, including logout and session expiry.
Confirm with the identity provider owner which client and redirect settings the route uses and when session invalidation is acceptable.
Routes with bearer_only set to true validate bearer tokens presented by clients, such as APIs called by single-page applications or services. These routes do not create a browser session, so the 3.14.0 session.secret requirement does not apply to them. They still depend on the identity provider's token validation, which means changes in other releases can affect them.
- Confirm the mode: Check that each route that validates bearer tokens explicitly sets
bearer_onlyto true rather than relying on an unclear default. - Review token validation settings: Confirm the discovery endpoint, client identifier and accepted audiences with the identity provider owner.
- Check callers: Make sure clients send tokens in the header the route expects.
- Avoid adding unused secrets: Adding a session secret to bearer-only routes adds configuration without a clear purpose, so keep these routes out of the session change.
- Test with real token flows in staging: Use tokens issued by the same provider that production clients use.
Confirm with the identity provider owner that the token audience and issuer for these routes are unchanged.
How to sequence the 3.13 to 3.14 upgrade with rollback points
This sequence moves an APISIX gateway from 3.13 to 3.14 in stages, so that each change has a tested state to return to and the team can confirm the gateway still authenticates and routes traffic before the next stage begins.
Confirm the current version and export configuration
The platform owner confirms the running APISIX version on every node and exports the full configuration: routes, upstreams, consumers, plugin metadata and the active configuration file, along with the current container image tag or package version. Store the export and the image reference outside the gateway hosts. This step is done when the team can name the exact previous version and holds a restorable copy of the configuration. Rollback point: the previous image and this backup are the restore set for every later step.
Audit automation that relies on default values
The platform team reviews every script, pipeline, GitOps repository and ingress controller sync job that writes to the Admin API, looking for requests that omit fields and rely on the server to fill them in. Since 3.14 stops the Admin API populating default values on write, these requests can produce different stored objects. Record each affected job and the fields it depends on. This step is done when each writer has an owner and a written list of fields to set explicitly. Rollback point: no gateway change has been made, so nothing needs restoring.
Add required secrets in staging
In a staging environment restored from the export, the team adds a jwt-auth secret to any consumer using an algorithm other than RS256 or ES256, and sets session.secret in every openid-connect configuration where bearer_only is false. Each secret comes from the organization's secret store, not from a value typed into a file. This step is done when staging routes still authenticate test clients with the new fields in place. Rollback point: remove the added fields from the staging copy and restore the export if authentication breaks.
Upgrade a staging cluster
The team upgrades the staging gateway to 3.14 using the installation method they already run, such as the container image, Helm chart or Linux package. Exact commands depend on that method, so confirm them against the official upgrade notes before running them. The step is done when every staging node reports 3.14 and the configuration loads without errors in the logs. Rollback point: redeploy the previous image and restore the staging export.
Run the authentication and Admin API test suite
Run the automated tests covering authentication flows, consumer credentials, openid-connect logins and the scripted Admin API calls from step two. Compare each result to the baseline recorded on 3.13. Also confirm that objects written by automation look as expected when read back, since defaults are no longer filled in. The step is done when all tests pass or each difference has a documented fix. Rollback point: if a test fails and the fix is not clear, return staging to 3.13 and the export before retrying.
Upgrade one production node or a canary set
Upgrade a single production node, or a small canary set that receives a limited share of live traffic, while the remaining nodes stay on 3.13. Confirm the node has the required secrets in its live configuration before it starts serving. The step is done when the canary serves traffic with normal error rates and authentication outcomes. Rollback point: drain the canary, redeploy the previous image on that node, and reapply the backed-up configuration.
Watch logs and data plane sync
For a defined observation window agreed in advance, the operations team watches gateway error logs, authentication failures, Admin API write errors and configuration sync status on the upgraded nodes. They confirm that configuration changes made through automation reach the data plane and that the control plane shows no sync errors. The step is done when the agreed window closes with no new error pattern tied to the upgrade. Rollback point: if sync stalls or authentication errors rise, stop the rollout and revert the canary to the previous image and backup.
Complete the rollout and keep the restore set
The team upgrades the remaining nodes in batches, repeating the checks from the previous step after each batch, then records the final version on every node. They keep the previous image and the pre-upgrade export until the operations owner confirms stability. The step is done when all nodes report 3.14, the checks pass and the restore set is archived. Rollback point: until the archive is closed, any batch can be reverted by redeploying the previous image and the backed-up configuration.
What makes this upgrade take longer
This table lists the factors that most change the effort of moving from APISIX 3.13 to 3.14, with the direction each one pushes effort and what to inventory to measure it. Read each row against your own gateway, then size the work from the rows that apply to you. The main takeaway is that the cost of this upgrade depends less on the version change itself and more on how many routes, consumers and automation pipelines depend on Admin API defaults and on the two authentication plugins that now require secrets.
| Driver | Effect on effort | What to inventory |
|---|---|---|
| Routes and consumers using jwt-auth or openid-connect | Higher count means more secrets and session settings to review and more consumers to test | Count routes with jwt-auth or openid-connect, and list consumers and algorithms in use |
| Automation pipelines that compare Admin API state | Each pipeline that diffs or rewrites stored objects may show false changes after the upgrade | List every script, CI job or GitOps tool that reads then writes Admin API objects |
| Ingress Controller with ADC diffs | Defaults filled on write can break ADC diffs and trigger full data plane updates, raising rollout effort | Confirm whether ADC is in use and which controller version manages the gateway |
| Use of the server-info plugin | Low effort when absent; removal or replacement requires changes to monitoring and health checks | Search route, global and plugin metadata for server-info and list the systems that call it |
| Custom plugins that call the Admin API | Plugins that depend on defaults or fixed response shapes need code review and tests | List custom plugins, their Admin API calls and the fields they read or write |
| Environments that need separate sign-off | Each separate approval path adds review cycles and a repeated test run | Count development, test, staging and production gateways and the approvers for each |
Questions teams ask before upgrading APISIX to 3.14
What drives the cost of an APISIX 3.13 to 3.14 upgrade?
The main cost driver is how many gateways, routes, consumers and plugin configurations you run, and how many of them depend on Admin API defaults or on the jwt-auth and openid-connect settings that 3.14 changed. A small gateway with declarative configuration usually costs far less to move than a large cluster with hand-written Admin API scripts. Costs are one-time for the assessment, test environment work, cutover and rollback planning. Recurring costs only appear if you add a retainer for later upgrades. Ask any partner for a quote built from a written scope that lists the environments, the number of clusters, the automation to review and the test cases to run.
Can our in-house team upgrade APISIX to 3.14 without a partner?
Yes, if your team already runs APISIX and has time to read the changelog, test in a staging copy of production and maintain a rollback path. The 3.14 changes are narrow: the Admin API no longer fills default values on write, jwt-auth needs a secret for algorithms other than RS256 and ES256, and openid-connect needs session.secret when bearer_only is false. Teams without recent APISIX operations experience, or with many custom plugins, often bring in outside help for the review and test plan. Whichever route you pick, assign an owner for each change in the changelog.
How long does the upgrade usually take, and what sets that?
No duration is fixed by the release notes, so treat any number you hear as a guess until your scope is written. Duration depends on the number of gateway clusters, whether you run traditional, decoupled or standalone mode, how much automation writes to the Admin API, how many plugins use jwt-auth or openid-connect, and how many change windows your organization allows. Plan separate time for staging tests, a parallel environment if you use one, and a rollback rehearsal. Ask your partner or internal lead to break the schedule into those phases.
What does the upgrade need from our team?
Expect to provide access to the Admin API or configuration repository for each environment, a copy of current route and plugin configuration, and sample traffic or test cases that reflect real client behavior. If you use openid-connect or jwt-auth, you also need contacts at the identity provider who can confirm client settings, token algorithms and session secret handling in staging. Someone from security should review the secret changes, and someone from platform operations should approve the change window and rollback steps. Confirm these responsibilities in writing before work starts.
Will our automation break on 3.14, and how do we detect it?
It can. Because 3.14 stops the Admin API filling default values on write, scripts, Terraform modules or GitOps templates that relied on those defaults may send incomplete objects and behave differently. The APISIX Ingress Controller 2.0 upgrade guide notes that because the Admin API fills in defaults, ADC diffs can break and trigger full data plane updates. To detect this, diff the stored configuration before and after a write in staging, check that every automated write sets the fields it needs explicitly, and watch for unexpected full reloads. Also verify that jwt-auth and openid-connect consumers still authenticate after the change.
Is APISIX 3.14 a long-term support release?
The APISIX downloads page does not mark any release as long-term support, so 3.14 should not be treated as LTS based on that page. Check the downloads page and the project release notes for the current support status before you plan your upgrade path, and confirm it with the Apache APISIX project if your policy depends on a support window. Plan your upgrades as a sequence of supported releases instead of relying on any single version staying in place.
What does a fixed-scope quote for this upgrade cover?
A fixed-scope quote should list the APISIX clusters and environments in scope, the configuration sources to review, the plugins and identity integrations affected by the 3.14 changes, the test cases, the cutover and rollback steps, and the documentation you will receive. It should also state what is excluded, such as later upgrades, custom plugin rewrites or work on the APISIX Ingress Controller. Ask for deliverables and acceptance criteria in writing, and confirm how the quote handles findings that change scope during testing.
What the server-info deprecation means for monitoring
The server-info plugin was marked deprecated in APISIX 3.13.0, so the window between 3.13 and 3.14 is the time to find out what still depends on it. Start by searching your Admin API configuration, route and plugin metadata, and any infrastructure code for server-info. Then check the consumers of its output: uptime probes, load balancer health checks, dashboards, and runbooks that expect the endpoint to answer. Each dependency should be listed with its owner, because a monitor that quietly starts failing after an upgrade is often the first sign of a missed migration. The 3.14.0 release notes are a useful companion check for anything else that changed in the same line, and the APISIX changelog records the deprecation alongside the other 3.13 changes.
Move each dependency to a supported observability path, but confirm the replacement against the official plugin documentation for your exact APISIX version rather than assuming one. The right choice depends on what the old endpoint told you: process health, version information, or request metrics each map to different plugins or to a metrics export, and the documented options and their configuration keys can differ from one release to the next. Ask your platform team to write the chosen replacement into the monitoring spec, test it in a staging gateway on 3.14, and confirm that alert thresholds still fire as expected. Keep the old check in place until the new one has been validated, then remove it so the deprecated plugin does not linger in production configuration.
How DeployOpen scopes and delivers an APISIX upgrade
DeployOpen plans, implements, tests, documents and supports self-hosted open-source platforms inside your own infrastructure. For an APISIX 3.13 to 3.14 upgrade, we start from your actual Admin API callers, plugin configuration and automation, then carry the change through a written scope into a documented handover.
How we scope
- We inventory which routes, consumers and plugins depend on Admin API default values before any version change is planned.
- The written scope names the APISIX instances, deployment mode and automation tools covered by the upgrade.
- Engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts.
How we build
- We set explicit values for jwt-auth secrets and openid-connect session secrets in a staging copy of your configuration first.
- We review server-info usage and replace or retire it according to the deprecation notice in your environment.
- We test automation and scripts against 3.14 behavior, including any pipeline that writes partial Admin API payloads.
How we hand over
- You receive the upgrade runbook, rollback steps, configuration diffs and the test results for each affected route and plugin.
- We document every changed default and secret so your team can reproduce the configuration without DeployOpen.
- Knowledge transfer sessions walk your platform team through the verification checks and the operational changes.
How we support
- Ongoing support, upgrades and continuous testing are available as retainers for APISIX after the handover.
- A retainer can cover monitoring of future release notes against the configuration you run in production.
- Confirm with us during scoping which support hours, response channels and review cadence the retainer would include.
