API7 Gateway 3.10.7: Turn Upgrade Uncertainty Into Evidence

Key Takeaways

A successful restart is not enough to prove an API gateway upgrade is safe; teams also need evidence that configuration, compatibility, and runtime behavior match expectations.
API7 Gateway 3.10.7, released on September 8, 2026, rejects routes the gateway cannot distinguish before they become new runtime ambiguity.
Compatibility findings are grouped by machine-readable reason, and operators can dismiss only unknown fields that the Data Plane safely ignores.
During a Control Plane-first rollout, a blank compatibility report from an older Data Plane can mean unknown, not compatible.
Diagnostic Agents can collect CPU profiles and memory snapshots from gateway workers over an outbound mTLS connection without opening an inbound port.
The Dashboard image, entrypoint, health check, and browser asset paths changed; deployment automation, reverse proxies, Content-Security-Policy rules, and CDN cache keys may need updates.

An API gateway upgrade often has a deceptively simple success signal: the new container starts. That says little about whether two routes now compete for the same request, whether an older gateway instance rejected part of the configuration, or whether a green-looking report is actually empty because the old Data Plane cannot describe its problems in the new format.

The operational question is not "did the binary start?" It is "what evidence shows that the intended configuration reached the intended instances and behaves correctly under traffic?"

API7 Gateway 3.10.7 turns that question into a product story. It blocks indistinguishable duplicate routes, organizes compatibility findings by root cause, adds a controlled path for profiling live gateway workers, and makes several health and telemetry signals more truthful. The release also introduces deployment changes that must be included in the upgrade plan.

flowchart LR
    change[Upgrade Change] --> admission[Route Admission Checks]
    admission --> report[Structured Compatibility Evidence]
    report --> rollout[Data Plane Rollout]
    rollout --> verify[Runtime Verification]
    diagnostics[Diagnostic Agent] --> verify
    telemetry[Health and Telemetry] --> verify

This is not automatic remediation or automatic rollback. It is a stronger evidence chain for deciding whether to continue, pause, or investigate a rollout.

A Successful Restart Is Not Proof of a Safe Upgrade

API7 Gateway separates the Control Plane, where teams define and distribute configuration, from the Data Plane instances that process traffic. That architecture lets operators upgrade the Control Plane first and roll Data Plane nodes afterward, but it also creates a mixed-version window. During that window, the newest user interface and APIs may be interpreting reports from older gateway instances.

A useful upgrade gate therefore needs more than process health. It should answer four questions:

Did the Control Plane accept a configuration that has one clear runtime meaning?
Did every Data Plane accept the resources and plugin fields it received?
Can the team diagnose a live instance when latency or memory changes?
Do metrics and health APIs distinguish the traffic and failure modes the team cares about?

API7 Gateway 3.10.7 improves each layer, but its most important upgrade note is also a reminder: evidence is only useful when the reader understands which version produced it.

Reject Indistinguishable Routes Before They Become Runtime Guesswork

Until 3.10.7, the Dashboard warned about some route conflicts, but ADC, a7, and direct Admin API clients could still install routes the gateway could not tell apart. Within the same gateway group, two routes could match the same URL for the same HTTP methods at the same priority, leaving operators to reason about an ambiguity that should never have passed admission.

The Control Plane now rejects that result with HTTP 400 when it is created through POST, PUT, or PATCH /apisix/admin/routes. The same check applies when PUT or PATCH /apisix/admin/services/{id} changes a service and when an OpenAPI import creates routes.

The boundary is deliberately narrow:

Exact duplicates at the same priority and for the same HTTP-method set are rejected.
Routes at different priorities remain valid.
Routes with partially shared or disjoint methods remain valid.
Overlapping but non-identical paths remain valid.
Routes with vars remain valid because their conditional matching cannot be modeled by URL comparison alone.
Inactive services are excluded, but reactivating one runs the conflict check.

Existing duplicates continue to serve traffic after the upgrade. They become operational debt: the next edit to either route is rejected, and any update to the service that owns a conflicting pair—including a description or label change—re-evaluates all its routes and can fail.

Before upgrading, inventory exact duplicate routes and decide which path, method set, or priority should differ. That converts a future blocked change into a planned cleanup.

Read Compatibility by Root Cause, Not Row Count

A compatibility report becomes noisy when the same underlying issue appears on hundreds or thousands of resources. API7 Gateway 3.10.7 groups findings by issue and reports a machine-readable reason such as resource_invalid, plugin_unavailable, plugin_config_invalid, or plugin_unknown_fields. Errors are ordered first, followed by the number of affected resources.

This changes the operator's unit of work. Instead of clearing repeated rows one by one, the team can identify the plugin, field, or resource rule causing the largest set of failures and fix the root cause.

For plugin_unknown_fields, an operator can add a dismiss rule for a field the Data Plane does not recognize but safely ignores. A rule applies across gateway groups and instances, and array fields can be matched with a pattern such as nodes[*].weight.

Three limits keep dismissal from becoming a false fix:

Only unrecognized-field warnings can be dismissed.
Dismissing a warning does not change the configuration that a Data Plane runs.
A dismissal never turns an Incompatible instance into a Compatible one.

Dismiss rules reduce acknowledged noise; they do not repair a resource or make an old plugin understand a new field. Every change to the rules is permission-controlled and audited.

Treat a Blank Report as Unknown During Mixed Versions

The grouped report and dismiss rules depend on structured compatibility data. On the 3.10 line, that arrives from Data Plane 3.10.7 and later; on the 3.9 line, it arrives from 3.9.20 and later. Earlier instances report rendered English sentences without a machine-readable reason.

Because API7 Enterprise upgrades the Control Plane first, a 3.10.7 Control Plane will temporarily communicate with older Data Planes. When an older instance sends one of those sentence-only findings, the Control Plane drops it as the heartbeat arrives. The compatibility report for that instance can therefore be empty even when it rejected a resource or lacks a plugin.

The instance is still marked as needing an upgrade, and the limitation affects only the report display—not traffic or the configuration already running. The practical rule is simple:

Until the Data Plane is on 3.10.7 or another release that emits structured issues, treat an empty compatibility report as unknown, not clean.

Use the version indicator as part of the evidence. Upgrade one gateway group, confirm its instances report structured findings, and only then use the grouped report as a rollout gate for that group.

Diagnose a Running Gateway Without Opening an Inbound Port

When an upgraded gateway uses more CPU or memory than expected, logs and aggregate metrics may not identify the worker or code path responsible. API7 Gateway 3.10.7 adds Diagnostic Agents that can collect CPU profiles and memory snapshots from the gateway's own worker processes.

The connection model is important. The agent dials out to the Control Plane over mTLS on the port the Data Plane already uses; operators do not need to expose a new inbound port into the gateway network. A cluster-level Diagnostic Agents area under API Runtime lists agents, shows status, opens the diagnostic console, and generates a Docker command or Kubernetes manifest with the certificate, host PID namespace, and required capabilities.

The agent name is carried in its certificate so operators can identify the machine rather than only a generated ID. That makes the diagnostic path easier to inventory and audit.

No-inbound does not mean no privilege. CPU and memory profiling of gateway processes requires host-level process visibility and capabilities. Deploy the agent only where needed, protect its generated credentials, limit who can operate the console, and remove or disable it according to the team's incident-access policy.

Make Health and Telemetry Signals Say What Happened

Several smaller 3.10.7 changes improve the evidence available after rollout:

A response with 101 Switching Protocols is classified as request_type=websocket in apisix_http_status, apisix_http_latency, and apisix_bandwidth; a refused handshake remains traditional_http. Dashboards that aggregate without filtering may see WebSocket traffic move into separate series.
AI Proxy Multi instance health checks appear through GET /v1/healthcheck, and GET /v1/healthcheck/{src_type}/{src_id}/checkers exposes every checker owned by a resource.
Empty Data Plane health-check collections now return [] rather than {}, giving clients a stable array shape.
When Prometheus returns non-JSON content, the Control Plane now returns HTTP 502 with the upstream status instead of a misleading parsing HTTP 500; the first 256 bytes are written to the Control Plane log rather than returned to the client.
Gateway instance lookups now include the gateway group and order instance runs, preventing stale runs from contradicting the current compatibility summary or receiving health data for the wrong group.

These details matter because an upgrade gate is usually automated. Stable response shapes, accurate status codes, current instance identity, and explicit traffic classes make monitoring rules and validation scripts less likely to reach the wrong conclusion.

Update Deployment Assumptions Around the Dashboard

In 3.10.7, the Console is again served from the Dashboard process as a Vite-built static single-page application. Its container image is now distroless: it contains neither Node.js nor a shell, and the entrypoint is the api7-ee-dashboard binary.

If a deployment carries forward the old 3.10.6 command that started node /app/server.js, the Dashboard container will not start. The same applies to a health check built around the old command. Start with the docker-compose.yaml from the 3.10.7 offline package and reapply intentional customizations; use api7-ee-dashboard healthz for the packaged health check.

The browser assets also moved from /_next/static/ to content-hashed files under /assets/. Review reverse-proxy rules, Content-Security-Policy sources, observability exclusions, and CDN cache keys that mention the old path.

The Developer Portal frontend image is also distroless and has no shell, although its startup checks and non-root behavior remain unchanged. Any runbook based on docker exec ... sh or a shell-based entrypoint override must be replaced with supported health and diagnostic paths.

What to Validate Before Upgrading to 3.10.7

Known 3.10.7 blocker: A direct upgrade from 3.8.x or 3.9.x to the released 3.10.7 Control Plane can leave the Dashboard process crash-looping before it finishes starting when a published service references a legacy custom plugin. The migration fix was merged after the v3.10.7 tag and is not included in the released 3.10.7 image. If a deployment matches this scope, do not proceed with the generic direct-upgrade path to 3.10.7. Contact API7 Support and defer the upgrade until a release explicitly includes the fix, or use only a staged path reviewed and approved by API7 engineering.

Use the API7 Gateway upgrade guide and rolling-upgrade procedure together with the release notes:

Find Basic Auth consumers or credentials with an empty password, including $env:// and $secret:// references that resolve to ""; set a real password before the Control Plane and Data Plane begin rejecting them.
Inventory exact duplicate routes at the same priority and method set, including routes created by OpenAPI imports and routes owned by inactive services that may later be reactivated.
Find traffic-split plugin configurations whose tls.ca_certs is an empty list; add a CA certificate or remove the tls block.
Record the version of every Data Plane and define the point at which its compatibility report becomes trustworthy; do not approve an older instance because its report is blank.
Upgrade one gateway group first, inspect grouped reasons and affected resources, and test dismiss rules only against safely ignored plugin_unknown_fields.
Update Dashboard commands, health checks, reverse-proxy paths, Content-Security-Policy rules, CDN behavior, and shell-based runbooks for the distroless images and /assets/ path.
Compare WebSocket dashboards, AI Proxy Multi health checks, Prometheus error handling, and instance identity before and after the rollout.
Pre-authorize and scope Diagnostic Agent use so an incident responder can collect a profile without improvising network exposure or access policy during an outage.

Do not modify gateway configuration during the upgrade window. Back up the database and declarative configuration, test the same path in a pre-production environment, upgrade the Control Plane first, and roll Data Plane nodes according to the documented procedure.

Upgrade With Evidence, Not Assumptions

API7 Gateway 3.10.7 does not make upgrade risk disappear. It makes several important unknowns easier to prevent or interpret: indistinguishable duplicate routes are rejected before admission, compatibility findings are organized by cause, runtime profiles can be collected through a controlled outbound path, and telemetry more accurately represents protocols, health, and upstream failures.

The release also demonstrates why version context matters. A blank compatibility report from an older Data Plane is not proof of compatibility, and a healthy container is not proof that deployment assumptions survived the move to a distroless image.

Read the complete API7 Gateway 3.10.7 release notes, map each required change to a measurable check, and let that evidence—not the absence of an obvious error—decide when the rollout can continue.