Why plan the APISIX 3.17 to 3.18 upgrade before touching production
Plan the APISIX 3.17 to 3.18 upgrade as a change to gateway behavior, not a routine binary swap. The 3.18.0 release changed defaults and enforcement in ways that can alter which requests are accepted, which upstream certificates are trusted, how logs are retained under load and which metrics your dashboards receive. A platform team that upgrades a running 3.17 cluster without reviewing these changes can see traffic that still returns 200 but is handled differently, and the first sign of the change may be a customer report or a broken alert rather than a failed health check.
The 3.18.0 release was published on August 20, 2026. The downloads page does not mark any APISIX release as long-term support, so the team should not assume that a patch-level fix on the 3.17 line will carry the same protections forward. Treat the 3.18.0 release notes and the project's upgrade guidance as the source of truth for what changed, and build your change list from them rather than from memory of earlier 3.x releases. Confirm with the project which later releases fall within your support expectations before you fix a target version.
Start by inventorying what your gateway actually uses: which plugins are attached to routes and consumers, whether ldap-auth or openid-connect sits in front of production APIs, whether AI plugins handle non-AI traffic, whether any route matches on post_arg predicates, and which dashboards and alerts read APISIX metrics. Each of those is a place where 3.18.0 changes behavior. Record the current configuration and etcd state so you can compare it against a staging cluster running 3.18.0 under representative traffic before any production cutover.
Which 3.18 changes affect your gateway and what to do about each
This table lists each 3.18.0 change that can alter gateway behavior, what it affects, and the action to take before cutover. Read it against your plugin inventory: a change matters only if your routes, consumers or dashboards use the affected plugin or setting.
| Change | Impact | Action needed |
|---|---|---|
| Body size limits (max_req_body_size, max_resp_body_size) | Default 64 MiB on about 19 plugins; larger bodies are rejected on those plugins | List plugins that handle large uploads or responses and set explicit limits |
| Logger backlog cap | Pending log entries are capped at 8,192; overflow is dropped rather than queued | Confirm your log volume and destination throughput can stay within the cap |
| Sanitized X-Forwarded headers | NGINX configuration now sanitizes incoming X-Forwarded headers | Check upstream services that trust client-supplied forwarded headers |
| ldap-auth tls_verify | Certificate verification is now real; previously it was silently ignored | Confirm the LDAP CA chain and hostnames are valid before enabling |
| ldap-auth bind DN lookup | Consumer lookup uses the escaped bind DN | Rewrite user_dn values containing RFC 4514 special characters |
| AI plugin fail_mode | New fail_mode setting; the skip default lets non-AI traffic through | Decide fail-open or fail-closed behavior and set it explicitly |
| Time-to-first-token and token histograms | New histograms; apisix_llm_latency gains a type label | Update dashboards and recording rules that query apisix_llm_latency |
| Duplicate consumer key rejection | Duplicate consumer authentication keys are now rejected | Audit consumers for shared keys before the upgrade |
| max_post_args_readable_size | Routes matching post_arg predicates stop matching bodies above 64 MiB | Review post_arg routes that receive large bodies and test their matching |
Which 3.18 changes break dashboards, LDAP logins and large request routing
Three of the 3.18.0 changes can fail in production without any error at deploy time, and each needs a check in your own environment before cutover. The first is metrics. APISIX 3.18.0 added a type label to apisix_llm_latency and new built-in Prometheus histograms for time to first token and token distribution. Any dashboard, alert rule or recording rule that queries apisix_llm_latency without expecting that label can return empty results or mismatched series, so the alerts may stay silent while the graphs look healthy. Export your current PromQL from Grafana and alerting tools, then confirm against a 3.18 test instance which series the new label produces before you retire the old queries.
The second is LDAP. In 3.18.0, ldap-auth with tls_verify performs real certificate verification, where the previous library ignored it. Clients that worked because verification was silently skipped will now fail to bind if the directory's certificate is not trusted by the gateway's CA store or does not match the hostname. The same release keys consumer lookup on the escaped bind DN, so any user_dn value containing RFC 4514 special characters, such as commas, plus signs or leading spaces in names, must be rewritten to its escaped form. Ask your directory team which DNs contain such characters, and test a login for each class of user. Treat certificate trust and DN escaping as separate findings, because fixing one does not reveal the other.
The third is request size. APISIX 3.18.0 introduced max_post_args_readable_size, and routes matching on post_arg predicates stop matching request bodies above 64 MiB. Routes that previously matched large form or JSON uploads will fall through to a default route or return an error. Identify every route with a post_arg predicate, check whether any receive bodies near that size, and decide whether the body should be handled by a different route or matched another way. Confirm the body buffering defaults of the plugins you run, since 3.18.0 also set max_req_body_size and max_resp_body_size to 64 MiB on about 19 plugins, and verify those limits against your largest real payloads.
What to inventory and back up before the 3.18 upgrade
Most 3.18 surprises come from settings nobody wrote down: plugins buried in old routes, consumer keys that now collide, and dashboards keyed to labels that change. Work through these items before any node is touched, so that rollback and comparison testing are possible.
Back up configuration state
Take a snapshot of the etcd data for traditional or decoupled deployments, or of the conf/apisix.yaml or conf/apisix.json file in standalone mode, together with conf/config.yaml and any custom plugin code. Store the copies outside the cluster being upgraded. A restore test on a separate host confirms the backup is usable before you rely on it for rollback. Note which etcd cluster version and Admin API key set each backup came from.
Inventory plugins by route and service
Export every route, service, and global rule, and list the plugins each one enables. Mark the plugins that 3.18 changes: those that gained max_req_body_size and max_resp_body_size limits, the AI plugins that gained a fail_mode, and the ldap-auth and openid-connect routes. Plugins attached through plugin metadata or consumer objects are easy to miss, so include those in the list. Routes that match on post_arg predicates need a separate check, because bodies above 64 MiB will stop matching.
Audit consumers and duplicate keys
Query every consumer and list its authentication keys for key-auth, jwt-auth, basic-auth and hmac-auth. In 3.18, duplicate consumer authentication keys are rejected, so any collision will block the upgrade or a later write. Decide which consumer keeps each contested key and rotate the others before cutover. Record consumer names and owning teams so the changes can be approved and communicated.
Map LDAP and OpenID Connect dependencies
List every route using ldap-auth or openid-connect, the identity provider behind each one, and the tls_verify setting in use. In 3.18, LDAP tls_verify performs real certificate checks, so confirm that the directory's certificate chain is trusted by the gateway. Also find any user_dn values containing RFC 4514 special characters, which must be rewritten because consumer lookup now uses the escaped bind DN. Confirm these details with your identity team and the directory administrators.
Capture logs and Prometheus baselines
Before the upgrade, export your current Prometheus dashboards, alert rules and log pipeline configuration, and record baseline request rates, latency and error counts for each route group. The LLM latency metric gains a type label in 3.18, so any panel or alert keyed to apisix_llm_latency needs updating. Logger plugins now cap pending entries at 8,192, so note the current log volume and any backlog alerts you rely on.
Build a staging environment that mirrors traffic
Stand up a staging cluster with the same plugins, consumers, etcd layout and deployment mode as production, then replay representative traffic, including large request bodies, LDAP logins and OIDC sessions. Compare response codes, header output and log delivery against the production baseline. Staging is the only place to observe how the body limits, logger caps and X-Forwarded header sanitization behave with your own clients. Ask your DeployOpen team, or your internal team, to define the traffic profile before testing starts.
Upgrade sequence for APISIX 3.17 to 3.18 with rollback points
This sequence moves a running APISIX gateway from 3.17 to 3.18 in controlled stages, with a verified backup and a documented rollback point before each change. It produces evidence that body limits, logger behavior, header handling, LDAP and LLM routes and dashboards behave as expected before production traffic moves.
Freeze configuration changes across the gateway
The platform owner announces a change freeze for routes, plugins, consumers and upstreams for the gateway estate, and the team records the current 3.17 build, container image tags or package versions, and the exact configuration revision in use. Anyone who owns an automation pipeline that writes to the Admin API confirms in writing that it is paused. The step is done when the freeze is recorded with a named owner and every writer confirms it has stopped, so the baseline you roll back to stays fixed.
Back up configuration and etcd data
The operations team exports the route, plugin, consumer and SSL objects through the Admin API or from the configuration repository, and takes a snapshot of the etcd cluster in traditional or decoupled mode, or copies the
conf/apisix.yamlorconf/apisix.jsonfile in standalone mode. Restore steps are rehearsed on a non-production copy. The check is a restore that reproduces the same route count and plugin set. Record where each backup is stored, who can access it, and how long it is retained, because this is the rollback point for the data layer.Upgrade a staging cluster to 3.18
The team deploys 3.18 to a staging cluster built from the same images, plugin list, TLS material and etcd topology as production, using the same deployment method (Helm, Linux packages or container images). Startup logs, the Admin API key handling and the plugin load output are compared with the 3.17 baseline. The check is that all routes load, health endpoints respond and no plugin reports a schema error. The staging build is the first place where any unexpected change is found, so no production stage should start until this check passes.
Replay representative traffic including large bodies, LDAP and LLM routes
Replay captured or synthetic traffic against staging, with specific cases for requests and responses near the 64 MiB body limits, routes that use
post_argpredicates, routes protected by ldap-auth with users whose DNs contain RFC 4514 special characters, and AI routes that depend on the fail mode or the new LLM metric labels. Compare status codes, latency and authentication outcomes against the 3.17 results. The step produces a comparison report, and any route whose result changes is held until its cause is understood.Check logs for logger drops and header changes
The team reviews the staging logs for dropped or delayed entries from logger plugins, now bounded at 8,192 pending entries, and for any upstream that sees different
X-Forwarded-*values after the sanitization change. Upstream applications that read client IP or protocol from forwarded headers are tested directly. The check is that logger backlog warnings are absent under replay load and that upstream header values match the expected trusted-proxy design. If drops appear, the rollout pauses until the logger destination or sizing is changed.Update dashboards and alert queries
Dashboards and alert rules that query the
apisix_llm_latencymetric are updated for the newtypelabel, and any panel that assumed the earlier label set is corrected in staging Prometheus or the observability tool in use. Alert thresholds are checked against replay results so that the new time to first token and token distribution series do not trigger false alarms. The check is that every panel renders data from staging and every alert rule evaluates without a query error. Keep the old dashboard definitions in version control so they can be restored.Roll out to production in stages with 3.17 kept available
Production is upgraded one node group or region at a time, with the 3.17 image or package kept available and the previous deployment revision retained so it can be redeployed quickly. Before each stage, the team records a rollback point with the configuration backup, the active version and the owner who can authorize a return. Error rates, latency and authentication failures are compared after each stage before the next one begins. The step is complete when all stages are finished and the 3.17 artifacts are archived according to the change record. Confirm the staging rhythm and the rollback approver with your own change board, since no durations are set here.
How to test 3.18 behavior and roll back safely
Start by testing each changed behavior on a staging gateway built from the same 3.18.0 artifacts you plan to promote, with the same plugins and routes as production. The first case is a request and a response above 64 MiB through a route using one of the plugins that gained max_req_body_size and max_resp_body_size. Confirm that the request is rejected or truncated as your configuration expects, and that the route still behaves for normal payloads. Repeat the test on any route that matches on post_arg predicates, because bodies above the new max_post_args_readable_size default will stop matching. Run a second case that floods a logger plugin with more entries than the 8,192 pending-entry cap and check what your team sees in the error log and in the destination system. Record the drop behavior before production, since your audit trail depends on it.
Next, send requests with spoofed X-Forwarded-For, X-Forwarded-Proto and X-Forwarded-Host headers to a route that uses client IP for rate limiting, allow lists or logging. Compare the values your backend and logs receive with the values you expect from your load balancer. For LDAP, bind with a certificate that does not chain to your trusted CA while tls_verify is enabled, and confirm the bind fails, since 3.18.0 now performs real verification. Then bind with a user whose DN contains RFC 4514 special characters and confirm the consumer lookup succeeds only after the user_dn values are rewritten. Finally, query apisix_llm_latency in Prometheus and check that the new type label appears and that existing dashboard panels and alert rules still return data. Confirm this with your own dashboards, because any panel keyed on the old label set needs an update.
Rollback depends on what changed during the window. Keep the 3.17 packages or images, the matching Helm values or deployment manifests, and a dated snapshot of conf/config.yaml and the route, consumer and plugin configuration exported through the Admin API before the cutover. If the upgrade only changed binaries and configuration, reverting means redeploying the 3.17 artifacts and restoring the snapshot, then re-running the same test cases to confirm the old behavior. If any consumer was created or edited on 3.18, check for rejected duplicate authentication keys and reconcile them before reverting, because 3.17 will not enforce that rule. Also confirm with your vendor or the project changelog whether any etcd data written by 3.18 is readable by 3.17 before you roll back. Plan the rollback window and decision owner in advance, and record the sign-off criteria next to the test results.
What makes an APISIX 3.18 upgrade longer or shorter
This table compares the factors that change how much work the move from 3.17 to 3.18 takes in your environment. Read each row against your own inventory of routes, plugins, consumers, dashboards and deployment layout. The main takeaway is that the number of routes and plugins using body buffering, LDAP and openid-connect, and LLM metric dashboards will matter more than the version jump itself.
| Driver | Why it matters | Effect on effort |
|---|---|---|
| Routes and plugins using body buffering | Plugins that gained max_req_body_size and max_resp_body_size limits may reject or truncate larger payloads once the defaults apply. | Longer when many routes carry large bodies. Confirm limits per route with test payloads before cutover. |
| Custom Lua plugins touching headers or request bodies | Custom code may depend on how request bodies are read or on X-Forwarded headers that 3.18 now sanitizes in the NGINX configuration. | Longer with each plugin that reads or rewrites these values. Shorter if the plugins are already covered by tests. |
| LDAP setups using ldap-auth | Certificate verification with tls_verify is now real, and consumer lookup uses the escaped bind DN, so user_dn values with RFC 4514 special characters need rewriting. | Longer for each LDAP consumer with special characters in its DN or with self-signed or private CA certificates. |
| openid-connect setups | Token introspection now fails closed, so endpoints or identity providers that were unreachable before may now block requests. | Longer when many routes use introspection or when identity provider reachability is not yet documented. |
| Consumer key hygiene | Duplicate consumer authentication keys are now rejected, so existing duplicates block the upgrade or the configuration reload. | Longer when the consumer inventory is large or has never been audited. Shorter when keys are already unique. |
| Dashboards and alerts on LLM metrics | The apisix_llm_latency metric gained a type label, which can break queries, recording rules and alert thresholds that match on the old series. | Longer with many dashboards or alerts built on those series. Inventory them before the upgrade. |
| Log volume and logger destinations | Logger backlogs are now bounded at 8,192 pending entries, so high-volume destinations may drop entries under sustained load. | Longer when logs are high volume or must be complete for audit. Confirm drop behavior and capacity for each destination. |
| Deployment mode: traditional, decoupled or standalone | Traditional and decoupled modes need coordinated rollout of data and control planes. Standalone mode reloads from a file that must match the new behavior. | Longer for decoupled clusters with many data plane nodes. Shorter for a single standalone instance with a version-controlled file. |
Common questions about the APISIX 3.17 to 3.18 upgrade
What drives the cost of an APISIX 3.17 to 3.18 upgrade?
The cost depends mainly on how many gateway nodes, routes and plugins the upgrade touches, how much custom plugin code must be reviewed, and how much traffic must be tested before cutover. Most engagements are fixed-scope, so a written scope listing the environments, the gateway inventory and the deliverables is the basis for a quote. The main cost components are inventory and planning, review of the configuration against the 3.18.0 changes, staging tests, cutover, a rollback rehearsal and documentation. These are one-time costs. A retainer for later upgrades or support is the only recurring cost. Ask any quote to name the plugins it covers, who updates dashboards and log pipelines, and whether a rollback test is included. DeployOpen does not publish a price list, so the quote follows from the written scope.
How long does the upgrade take, and what changes the timeline?
The duration depends on the number of gateways, how many routes use the affected plugins, how many environments must be tested, and how many approval windows the change process allows. No single duration applies to every estate, so the timeline should appear in the written scope rather than in a generic estimate. The changes that most often add time are body size limits on routes that receive large uploads, LDAP authentication flows that need certificate chain checks, and dashboards or alerts that depend on the LLM metric labels. Confirm the exact behavior of each change against the project's release notes and the CHANGELOG before you agree a schedule, because those documents are the authoritative record of what 3.18.0 changed.
What does the upgrade need from our own team?
The work needs a named owner for the gateway configuration, access to the etcd cluster or standalone configuration files, and access to the repositories that hold route and plugin definitions. It also needs:
- Owners for each dashboard, alert and log pipeline that reads APISIX metrics.
- An LDAP administrator who can confirm the directory certificate chain and sample bind DNs.
- Representative test traffic, including large request bodies and AI routes if you run them.
- Authority to approve a change window and a rollback plan.
Agree these owners at the start, because a delay in any one of them usually delays the cutover. Your team also needs to decide who signs off on the results of each test.
Can our internal team run this upgrade without a partner?
Yes, an internal team can run it if it has working knowledge of APISIX configuration, a staging environment that mirrors production, and time to test. The difficulty lies less in applying the upgrade than in finding behavior that changed silently. Two examples from the 3.18.0 changes are LDAP certificate verification that the previous library ignored, and request body limits that can stop routes from matching large bodies. An internal team should test each affected plugin against realistic traffic, keep the previous version available for rollback, and record the results. A partner adds value mainly through an independent review of the change list, a repeatable test plan and documented evidence, which is useful if your change process requires it.
Is APISIX 3.18 a long-term support release, or should we move to 3.19?
The APISIX downloads page does not mark any release as long-term support, so 3.18 should not be treated as an LTS line unless the project confirms that status in writing. According to the downloads page, APISIX 3.19.0 was released on September 28, 2026, and 3.18.0 was released on August 20, 2026 according to the GitHub releases. Choosing between them depends on your support policy, your security review cycle and the changes each release brings for your plugins. Review the 3.18 to 3.19 changes before you commit, and confirm the support status of each line with the Apache APISIX project and your own vendor if you have one.
How do we handle the LDAP authentication changes in 3.18?
Before the upgrade, identify every route that uses ldap-auth and check whether tls_verify is enabled. In 3.18.0, that setting performs real certificate verification, which the previous library ignored, so connections that once worked may now fail if the directory certificate is not trusted by the gateway. Install the correct CA chain on each gateway and test a login from every directory group. Consumer lookup now uses the escaped bind DN, so any user_dn value that contains RFC 4514 special characters must be rewritten to the escaped form. Test those accounts individually in staging, because a mismatch shows up as a failed login rather than an error at startup.
What breaks in our dashboards after the LLM metric changes?
APISIX 3.18.0 added built-in Prometheus histograms for time to first token and token distribution, and the apisix_llm_latency metric gained a type label. Existing queries that match on the metric without that label may return different series, and queries that aggregate across it may double count if you add the new histograms to the same panels. Review every dashboard and alert that reads apisix_llm_latency, update the queries, and check the results in staging. The release also added a fail_mode setting for AI plugins whose default skip lets non-AI traffic through. Decide the correct mode for each AI route, because the default can hide a failing guard from your alerts.
How DeployOpen scopes, delivers and supports the APISIX upgrade
DeployOpen plans and carries out the move from Apache APISIX 3.17 to 3.18 inside infrastructure you control. We start from a written scope that names your routes, plugins, consumers and dashboards, then test each changed behavior against your own configuration before cutover.
How we scope
- Inventory every route, plugin and consumer that touches the body buffering, logger, LDAP, openid-connect, AI or Prometheus changes in 3.18.
- Identify which dashboards and alert rules read the LLM latency metric labels and list the panels that need rework.
- Agree the scope, deliverables and timeline in writing before work starts, since engagements are fixed-scope.
How we build
- Stage the upgrade in a non-production environment that mirrors your deployment mode and etcd or standalone configuration.
- Test large request bodies, post_arg predicates and duplicate consumer keys against the 3.18 limits and rules.
- Verify LDAP bind DN handling, TLS verification and openid-connect introspection failure behavior with real identity provider responses.
How we hand over
- Deliver a dated change record covering each 3.18 behavior change, the affected configuration and the tested result.
- Document the rollback path, including the configuration backups taken before the upgrade and how to restore them.
- Walk your platform, security and observability teams through updated dashboards, alert rules and runbooks.
How we support
- Ongoing support, upgrades and continuous testing are available as a retainer after the handover.
- Review the next APISIX release notes, such as the 3.19 line, against your configuration before you schedule the next change.
- Confirm with the vendor and your own environment any setting not covered by the written scope before relying on it.
