Why the Apache APISIX upgrade from 3.15 to 3.17 starts with authentication
A team running authenticated APIs on APISIX 3.15 cannot treat the move to 3.17 as a binary swap. The upgrade changes authentication defaults, so the plan has to cover how each protected route behaves under the new settings before any production traffic reaches the new version. The changes arrive in two steps: APISIX 3.16.0 (April 8, 2026) and APISIX 3.17.0 (June 16, 2026). Each release introduces behavior that can reject tokens, change how signed requests are verified, or remove an endpoint that automation may still call.
Read both release notes in full before scoping the work. The APISIX changelog lists each change by release, and the GitHub releases page carries the same notes in release form. Work from the combined list rather than from one release at a time, because a route that passes after 3.16 may still fail after 3.17. Confirm with your own route inventory which plugins each consumer depends on, since the changes touch openid-connect, jwt-auth, hmac-auth and proxy-cache, and a plugin you do not think of as an authentication control may still sit in an auth path.
The supported path is to plan and test against the full range, 3.15 to 3.17, in a staging environment that mirrors your production plugin configuration and consumer set. Do not assume that a direct jump is safe just because each change looks small on its own. Record which routes fail, which tokens or signatures are rejected, and which clients need code or configuration changes, then decide the cutover order and rollback point. Confirm with the project and with your own environment any behavior you cannot verify from the notes.
Which authentication and proxy defaults changed in 3.16 and 3.17
This table lists the security defaults and authentication behaviors that changed between APISIX 3.15 and 3.17, with the likely impact on running routes and the action to take. Read each row as a check against your current configuration, and confirm exact behavior against the changelog before you change anything. The main takeaway is that several changes fail closed, so token validation, JWE endpoints and cached responses can break without a code change.
| Change | Impact | Action needed |
|---|---|---|
| openid-connect ssl_verify defaults to true (3.16.0) | Identity provider calls over HTTPS fail if the provider certificate is not trusted by the gateway | Confirm the provider CA chain is in the gateway trust store, or set ssl_verify explicitly after review |
| jwt-auth requires configured claims (3.17.0) | Tokens missing claims that routes previously ignored are rejected with authorization errors | List required claims in each consumer and route, and test tokens from your issuer |
| jwt-auth enforces algorithm matching (3.17.0) | Tokens signed with an algorithm that differs from the configured one fail validation | Compare the signing algorithm in your issuer with the consumer configuration |
| jwe-decrypt encrypt endpoint removed (3.17.0) | Automation or clients that called the encrypt endpoint receive errors | Search scripts and clients for the endpoint and move encryption to an external process |
| Admin key required for schema validation (3.17.0) | Schema validation calls without the admin key are refused | Update CI and tooling that validates configuration to send the admin key |
| hmac-auth signed_headers defaults to date (3.17.0) | Signatures built over a different header set no longer verify | Confirm which headers each client signs and set signed_headers explicitly where needed |
| proxy-cache consumer_isolation defaults to true (3.17.0) | Cache entries are separated per consumer, so shared-cache hit rates may drop | Measure cache hit rates before and after, and disable isolation only with a documented reason |
| cas-auth requires cookie.secret (3.17.0) | CAS-protected routes without a configured secret do not start cleanly | Set cookie.secret from your secrets store on every cas-auth route |
| ai-rag ssl_verify defaults to true (3.17.0) | Calls from ai-rag to embedding or vector services with untrusted certificates fail | Verify backend certificates and trust chains for every ai-rag upstream |
| Environment variables resolved before YAML parsing in standalone mode (3.17.0) | Configuration values that contain unexpected characters may parse differently | Test standalone configuration files in a staging gateway before rollout |
Backups and inventory to complete before the Apache APISIX upgrade
Each item below gives you a way back if the 3.16 and 3.17 security defaults break a live flow. Together they cover the configuration you would restore, the routes and consumers that will change behavior, the credentials automation depends on, and the tokens and signatures you will test against.
Back up etcd or the standalone file
Take a snapshot of the etcd data in traditional or decoupled mode, or copy conf/apisix.yaml or conf/apisix.json in standalone mode, before any node changes. Store the copy outside the gateway hosts and confirm you can restore it into a scratch environment. Without this, a rollback to 3.15 reloads a configuration you cannot reproduce. Confirm the restore procedure with your platform team before the change window.
Inventory routes using auth and cache
List every route and consumer that uses jwt-auth, openid-connect, hmac-auth, cas-auth or proxy-cache. The 3.17 changes affect claim requirements, algorithm matching, signed headers, cache isolation and the cookie secret for CAS, so each affected route needs an owner and a test. Record the upstream service and the client team for each one. Routes you do not list will be discovered during an incident, not during the upgrade.
Record the Admin API key and its readers
The 3.17 release requires the Admin API key for schema validation, so any pipeline that validates configuration without it will fail. List every script, CI job, Helm value or secret manager entry that reads the key, and where each one reads it from. Confirm that the key value your automation uses matches the one in the running configuration. A missing reader found after cutover can block configuration deploys across all environments.
Copy custom Lua plugins and field use
Keep a versioned copy of every custom Lua plugin and note each place it reads or writes a field whose behavior changed, such as jwt claims, hmac signed headers or proxy-cache keys. A plugin that depends on the old defaults will behave differently after the upgrade even if it loads. Store the copy in source control with the APISIX version it was tested against. This lets you restore the exact plugin set that matches a 3.15 rollback.
Build staging from production config
Create a staging gateway from the production configuration, using the same plugins, certificates and etcd or file layout, and run the 3.15 to 3.17 upgrade there first. Do not copy production secrets into shared lab systems without your normal controls. Staging is only useful if it matches production closely enough to expose the same rejected configurations. Document any gap between the two environments before you rely on the results.
Capture tokens and signatures from clients
Collect real JWTs, OIDC tokens and HMAC-signed requests from each client team, including tokens with different algorithms and claim sets. Replay them against staging on both 3.15 and 3.17 and record each accept or reject result. This is the evidence that shows which clients will fail after the upgrade. Ask client teams to confirm which signing algorithms and headers they send today.
What the stricter jwt-auth and hmac-auth changes mean for existing consumers
The jwt-auth change in 3.17.0 can reject tokens that the gateway accepted before the upgrade. The release requires the configured claims on the plugin to be present and enforces that the token's algorithm matches the algorithm the route expects. A token issued by your identity provider with no exp, iss or other claim you have configured in the plugin, or signed with an algorithm that differs from the one set on the consumer or route, will now fail at the gateway even though it was valid the day before. Before you change anything on the client side, export a sample of current tokens from each issuer, decode them, and compare their claims and alg header with the plugin configuration on every route that uses jwt-auth. Each mismatch is either a gateway setting to correct or a token to reissue, and that decision belongs to the owner of the issuer.
The hmac-auth change alters what a signature covers. In 3.17.0 the default for signed_headers becomes date, so a signature that previously covered headers you added on purpose, such as a request ID or a content digest, may no longer include them, or may fail if the client computes the signature over a different list. Review the signing code in every client and partner integration and list the headers each one signs. If your clients rely on the old coverage, set signed_headers explicitly on the consumer or plugin configuration rather than depending on the default. Confirm the exact behavior, including how the default applies to existing consumers, in the 3.16 and 3.17 entries of the APISIX changelog before you write client changes, and test a signed request end to end in a staging gateway first.
Apache APISIX upgrade sequence with checks and rollback points
This sequence moves a gateway from the 3.15 line to 3.17 with each authentication change tested before the next step begins. Each step ends with a check that must pass and a point you can return to if it does not.
Inventory routes, plugins and consumers
Your platform or gateway team lists every route, upstream, consumer and plugin that runs on the 3.15 gateway, with particular attention to openid-connect, jwt-auth, hmac-auth, basic-auth, proxy-cache and any custom plugin that reads authentication headers. Export the configuration from the Admin API or your configuration-as-code repository and back up the etcd data or standalone configuration file, storing the copy outside the gateway hosts. The step is done when every authentication-related route maps to a named consumer or policy and a restore from the backup has been rehearsed on a separate host. Rollback point: the untouched 3.15 gateway and its backup remain the reference state.
Read the 3.16.0 and 3.17.0 release notes
The engineer responsible for the upgrade reads the APISIX changelog and the GitHub release notes for 3.16.0 and 3.17.0 and marks each change that touches your plugins. The changes that matter most for this path are the openid-connect ssl_verify default, the stricter jwt-auth claim and algorithm rules, the removed jwe-decrypt encrypt endpoint, the admin key requirement for schema validation, the hmac-auth signed_headers default, and the proxy-cache consumer_isolation default. The step closes with a written list of affected routes and an owner for each item, reviewed by the security lead. Rollback point: no runtime change has been made, so there is nothing to undo.
Build a staging gateway on the target version
The platform team deploys APISIX on the target 3.17 line in a staging environment that uses the same deployment mode, etcd layout, identity provider endpoints and TLS trust stores as production. Load the exported configuration and confirm that the gateway starts, reports the expected version and serves the health endpoints. Staging must reach the same identity provider, JWKS endpoints and upstream services that production uses, or the tests in later steps will not show real behavior. The step passes when the gateway starts cleanly with no configuration load errors in its logs. Rollback point: staging can be rebuilt from the same export at any time without affecting production.
Fix configuration tied to removed endpoints and defaults
The team edits the exported configuration to remove any call to the jwe-decrypt encrypt endpoint, sets explicit values for openid-connect ssl_verify where the identity provider uses a private certificate authority, and adds the configured jwt claims and algorithm values that each consumer and route should enforce. Where hmac-auth routes depended on the previous signed_headers default, record the header list explicitly so the signing behavior does not change silently. Keep these edits in version control with a reviewer named for each change. The step passes when schema validation succeeds for every modified route and a diff review confirms that only the intended fields changed. Rollback point: the previous configuration revision in version control.
Add the admin key and required claims
The administrator configures the Admin API key on the 3.17 gateway so that schema validation requests are authenticated, and confirms that the automation pipeline that calls the Admin API presents the key. Tokens for jwt-auth routes are checked against the new required claims, and the team confirms that the identity provider issues those claims for every client. Use a non-production test client to request tokens and verify that a token missing a required claim, or signed with an algorithm the route does not allow, is rejected. The step passes when a schema validation call without the key fails, a call with the key succeeds, and the test tokens behave as expected. Rollback point: the staging configuration can revert to the previous key and claim settings while the gaps are closed.
Run authentication and cache tests
The security team runs a test suite that covers each authentication method in use: valid and invalid tokens for openid-connect and jwt-auth, expired sessions, HMAC-signed requests with the chosen header list, basic-auth and key-auth failures, and proxy-cache responses requested by two different consumers. Confirm that the proxy-cache isolation default keeps one consumer's cached response away from another consumer, and that identity provider certificate errors surface as failures rather than being bypassed. Record the results with the gateway version and configuration revision. The step passes when every test case returns its expected status and no cached response crosses a consumer boundary. Rollback point: a failed case stops the sequence and the staging revision is corrected before the test is repeated.
Stage the production cutover
The operations team deploys the tested 3.17 configuration as a parallel gateway alongside the existing 3.15 gateway, then shifts a small share of traffic through a load balancer or DNS weight, starting with low-risk routes. Watch the authentication failure rate, TLS handshake errors and cache hit behavior at each increment, and only increase the share when the previous increment has been stable. Keep the 3.15 gateway running and its routing weight ready to restore until every route has been moved and reviewed. The step passes when the new gateway handles its full traffic share with authentication outcomes that match the 3.15 baseline. Rollback point: restore the routing weight to the 3.15 gateway.
Monitor failures and define the final rollback point
After full cutover, the operations team monitors authentication failures by route and consumer, TLS verification errors to identity providers, and any rise in rejected tokens that could indicate a missing claim or an algorithm mismatch. Compare these figures with the pre-upgrade baseline and assign an owner to investigate each deviation. The team decommissions the 3.15 gateway only after the agreed observation period has passed without unexplained authentication errors, and keeps its configuration backup for the same retention period as other gateway records. The step passes when the dashboards show no unexplained deviation and the decommission record is signed off. Rollback point: the retained 3.15 gateway and its backup remain available until that sign-off.
How rollback differs by APISIX deployment mode
In traditional mode, the data plane and control plane run together on each node, and configuration is stored in the etcd cluster that the gateway reads and the Admin API writes to. Rolling back means returning both the binaries and the configuration state to the point before the upgrade, so the etcd snapshot is the central artifact. Review the deployment modes documentation for the traditional layout before you plan the revert.
- Snapshot etcd before the upgrade: Take a consistent etcd snapshot and store it outside the cluster so routes, consumers and plugin settings written under 3.15 can be restored intact.
- Keep the previous package: Retain the 3.15 install package or image so each node can return to the exact version the snapshot was taken against.
- Pause writes during the window: Stop automation and Admin API changes during the upgrade, then record anything written after the snapshot so it can be reapplied or discarded on purpose.
- Revert nodes as one change: Plan the revert as a single coordinated operation, and confirm whether mixed versions are supported while it runs.
Confirm the snapshot and restore commands for your etcd version, and the node revert order, against the vendor documentation for your exact release before the cutover.
In decoupled mode, the data plane and control plane are separate tiers, and both read from one shared etcd cluster. The control plane writes configuration that the data plane consumes, so the etcd data is the state that connects the two. Rollback is harder here than in traditional mode because restoring etcd changes what every tier sees, and reverting one tier alone can leave it reading data written by the other.
- Shared etcd limits partial rollback: Reverting only the control plane or only the data plane may leave the other tier reading data in a format it does not expect, so plan for a restore that covers both.
- Restore affects every consumer: A snapshot restore rolls back shared state for everything using that etcd cluster, including any tier still running 3.17.
- Sequence the tier reverts: Decide which tier reverts first, and confirm the supported version pairing between control plane and data plane in the documentation.
- Inventory other cluster users: Any other system writing to the same etcd cluster is affected by a restore, so list those dependencies before you schedule the window.
Confirm the supported version pairs, the restore procedure for your etcd version, and the sequence for each tier before you approve the rollback plan.
In standalone mode, APISIX runs without etcd and reads its configuration from conf/apisix.yaml or conf/apisix.json, or from an API. For file-driven setups, the gateway checks the file for changes every second and hot-reloads without a restart. Rollback therefore means restoring one file, and the cutover window is short because a change is applied almost as soon as it is saved.
- Back up the configuration file: Copy conf/apisix.yaml or conf/apisix.json before the upgrade and label the copy with the version it was written for. That copy is the full rollback point.
- Expect changes within a second: Because the file is checked every second, a bad edit takes effect almost immediately, so stage changes in a separate file and move them into place deliberately.
- Review environment variable handling: The 3.17 changelog says standalone mode resolves environment variables before YAML parsing, so a file that depended on the earlier behavior may parse differently after rollback.
- Check for API-driven changes: Standalone mode can also be changed through an API, so confirm whether any change exists only in memory and not in the file on disk.
Confirm the file path, the reload behavior, and the version compatibility for your release in the deployment modes documentation before you change the file.
What makes this Apache APISIX upgrade longer or shorter
This table lists the factors that stretch or shorten a 3.15 to 3.17 upgrade and what to inventory for each. Read it before scoping, because the authentication changes touch consumers, identity providers and client teams as well as the gateway itself.
| Driver | Effect on effort | What to inventory |
|---|---|---|
| Routes and consumers using affected auth plugins | More routes and consumers using jwt-auth, hmac-auth, openid-connect or proxy-cache means more configs to review and retest after the claim, algorithm and signing defaults change. | Count routes per auth plugin, list consumers, and note which ones rely on default values that 3.17 changes. |
| Custom Lua or runner-based plugins | Plugins that read jwt claims, hmac headers or proxy-cache keys may break or need code changes, and each one needs its own test pass. | List custom plugins, the runner language used, and every field they read from authentication or cache context. |
| Use of openid-connect with external identity providers | TLS verification now defaults on, so each identity provider endpoint must present a certificate the gateway trusts, and internal CAs may need to be added. | Record each provider endpoint (discovery, token, introspection, JWKS), its certificate chain, and whether it uses a private CA. |
| Client teams that must change tokens or signatures | If signed headers move to date-based defaults or jwt claims become required, every calling team must update how it builds tokens or signatures, which adds coordination time. | Identify client teams and services that sign requests or issue jwt tokens, and confirm which claims and headers each one sends. |
| Use of proxy-cache | Consumer isolation is on by default in 3.17, so cached responses may stop being shared across consumers, which can change hit rates and load on upstreams. | Note which proxy-cache routes exist, whether they serve shared content, and how cache hit rates are measured today. |
| Deployment mode | Traditional and decoupled modes depend on etcd and the Admin API for rollout, while standalone mode reloads from a file, which changes how the new configuration reaches each node. | Confirm whether the gateway runs in traditional, decoupled or standalone mode, and how nodes receive configuration. |
| Automation that relies on the Admin API | The admin key is now required for schema validation and scripts that depended on defaults may fail, so pipelines need review before the upgrade. | List scripts, CI jobs and infrastructure code that call the Admin API, and whether they send an admin key and full field sets. |
| Staging environment availability | A staging gateway with realistic traffic and copies of identity provider settings shortens validation, while missing staging pushes testing into production windows. | Confirm whether a staging cluster exists, whether it can reach identity providers, and whether it can replay representative traffic. |
Apache APISIX upgrade questions buyers ask before hiring help
What drives the cost and effort of an APISIX 3.15 to 3.17 upgrade?
The main drivers are how many routes and consumers use the changed plugins, how many clients depend on the behavior that changed, and how much of your configuration is managed by hand rather than as code. Each of the changed defaults (openid-connect TLS verification, jwt-auth claims and algorithms, the removed jwe-decrypt encrypt endpoint, admin key requirement for schema validation, hmac-auth signed headers and proxy-cache isolation) adds its own review and test work. A written quote should itemize the inventory of affected routes and plugins, the configuration changes, the test plan for each plugin, the staging rehearsal, the production cutover and rollback steps, and the handover documentation. Ask whether ongoing support is included or quoted separately, since most engagements are fixed-scope and ongoing support is offered as a retainer.
Can our own team upgrade APISIX to 3.17 without outside help?
Yes, a team with working knowledge of APISIX can do it, provided it has the right skills and time. You need someone who can read the APISIX changelog and the 3.16.0 and 3.17.0 release notes, someone who understands your identity provider and token flows, someone who can write and run plugin-level tests, and someone who owns the deployment pipeline and etcd or standalone configuration. The security-sensitive items deserve a reviewer who understands JWT signing, OIDC token validation and HMAC canonicalization, because a silent change in claim checks or signed headers can reject valid traffic or accept invalid traffic. If one or more of these skills is missing, a fixed-scope engagement can cover only the gap, which keeps the work bounded.
What do we need to provide during an APISIX upgrade engagement?
Plan to provide access, test clients and a change window. Access means read access to the current APISIX configuration (Admin API exports or configuration files), the etcd or standalone configuration source, the identity provider settings used by openid-connect and jwt-auth, and the staging and production environments in your own accounts or data centers. Test clients matter most: you need representative API consumers that send valid and invalid JWTs, HMAC-signed requests and cached responses, so that the changes can be proven in staging. Someone from the API owner or partner side must confirm expected behavior for each client. You also need a change window agreed in advance for the production cutover and a named decision-maker who can approve a rollback. These items should be written into the scope before work starts.
Can we move directly from APISIX 3.15 to 3.17 in one step?
The supplied changelog facts cover the 3.16.0 and 3.17.0 releases, and this page covers the changes in both. Whether a single step is appropriate depends on your plugin usage, your deployment mode and what else differs in your environment, so confirm it against the project's upgrade notes and the changelog for each intermediate release before you commit to a plan. A practical approach is to rehearse the move in a staging environment built from a copy of production configuration, then decide whether to cut over in one change or in two. Keep the configuration backup and a tested rollback path in either case. Ask the implementation partner to state in writing which releases the plan covers and which it does not.
How do the proxy-cache and hmac-auth changes affect our API clients?
Proxy-cache isolation can change which cached responses a client receives. With consumer isolation enabled by default in 3.17.0, cached responses are separated by consumer, so clients that previously shared cache entries may see more cache misses and a higher load on upstream services until caches warm up. The hmac-auth change defaults signed_headers to date in 3.17.0, which means clients that signed requests with a different header set may now fail signature checks. Clients need to be told which headers they must sign and when the change takes effect. Confirm both behaviors in staging with the client teams before cutover, and plan a short coordinated window if a consumer cannot update its signing code in time.
How does DeployOpen agree the scope before an upgrade starts?
Most DeployOpen engagements are fixed-scope, so the scope, deliverables and timelines are agreed in writing before any work begins. For an upgrade like this one, the written scope usually lists the APISIX releases covered, the plugins and routes in the inventory, the test cases for each changed behavior, the environments involved, the cutover and rollback steps, and the client responsibilities described above. Anything outside that list, such as unrelated plugin changes or additional routes, should be handled as a written change to the scope. Ask for the scope document to name the exact releases and the exact client-side inputs, so both sides can see what is included before a quote is accepted.
Does DeployOpen certify that our APISIX gateway is compliant after the upgrade?
No. DeployOpen prepares systems, controls and evidence for compliance assessments, but it does not issue audit reports, attestations or certifications. Independent auditors and certification bodies perform those assessments. After an upgrade, DeployOpen can document the changed settings, record test results and provide configuration evidence that your assessor can review. Ask your auditor which evidence they expect for authentication controls, and agree that format during scoping so the upgrade records serve the assessment.
How DeployOpen scopes and delivers the APISIX authentication upgrade
DeployOpen plans the move from APISIX 3.15 to 3.17 as a written, fixed-scope engagement inside your own infrastructure. We start from the changes in the authentication plugins, test each affected route against them in a non-production environment, and hand over the configuration, runbook and evidence your team needs to run the upgraded gateway.
How we scope
- Inventory every route that uses openid-connect, jwt-auth, hmac-auth, proxy-cache or the jwe-decrypt endpoint in your current gateway.
- Confirm which clients, token issuers and signing algorithms each route depends on before any change is made.
- Agree in writing which 3.16 and 3.17 default changes apply to your estate, and which are out of scope.
How we build
- Stage the upgrade in a non-production APISIX cluster that mirrors your deployment mode and identity provider settings.
- Set TLS verification, jwt claim requirements, algorithm checks and admin key handling explicitly in versioned configuration.
- Run authentication tests for valid, expired, wrongly signed and missing-claim tokens against both the old and new versions.
How we hand over
- Deliver the updated configuration, a change log mapping each default change to the affected routes and plugins.
- Provide a rollback procedure and a parallel-run plan with the cutover steps your operations team will follow.
- Document the test results and the open items you need to confirm with your identity provider or application owners.
How we support
- Engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts.
- Ongoing support, upgrades and continuous testing for the gateway are available as a retainer.
- Ask for a quote based on the written scope, which covers the number of routes, plugins and environments involved.
