API7 Gateway 3.9.10

Release Date: 2026-04-22

Breaking Changes

Plugins

• OpenAPI to MCP (opens in Plugin Hub docs)

  Upgrade note

  The OpenAPI2MCP service is no longer bundled inside the gateway image. It now runs as a separate sidecar container (api7/openapi-to-mcp), reducing the gateway image size by approximately 150 MB. If you use the openapi-to-mcp or mcp-tools-acl plugins, you must deploy the OpenAPI2MCP sidecar alongside the gateway. In Kubernetes, enable openapiToMcp.enabled=true in the gateway Helm chart. In Docker Compose, run the api7/openapi-to-mcp container in the same network namespace as the gateway.

Upgrade Notes

Features

Plugins

• AI Proxy (opens in Plugin Hub docs), AI Proxy Multi (opens in Plugin Hub docs)
  • Added override.request_body for per-protocol deep-merge request body overrides and override.llm_options for provider-aware max_tokens mapping. Operators can set protocol-specific parameters (such as max_tokens, stop_sequences) as defaults or enforced settings using the request_body_force_override flag. Precedence order: model options → LLM options (always force) → request body (per-protocol deep merge). All three new fields (request_body, llm_options, request_body_force_override) are also available per instance under AI Proxy Multi's instances[].override.
  • Added max_stream_duration_ms and max_response_bytes safeguards to prevent unbounded LLM streaming responses from pinning a worker process at high CPU. When either limit is exceeded, the stream is terminated gracefully with appropriate error signaling.
  • The gateway now detects client disconnection during streaming and immediately stops reading from the LLM upstream, freeing worker resources and avoiding unnecessary API quota consumption.
• AI RAG (opens in Plugin Hub docs)
  • Added a top-level ssl_verify field (default true) that controls TLS certificate verification when the plugin calls the embeddings and vector search endpoints.
• Prometheus (opens in Plugin Hub docs), OpenTelemetry (opens in Plugin Hub docs), Zipkin (opens in Plugin Hub docs)
  • Added a new response_source label (Prometheus) and apisix.response_source span attribute (OpenTelemetry, Zipkin) that classifies each response as "apisix" (generated by APISIX, such as plugin rejections or route-not-found), "nginx" (NGINX proxy errors such as connection refused or upstream timeout), or "upstream" (real response from the upstream service). This enables more precise error attribution in dashboards and alerts.

Control Plane

• Added Consul as a service discovery source. Gateways can now discover upstream services registered in Consul, with support for metadata-based filtering and health-check-aware node selection.
• The Control Plane can now dynamically push telemetry configuration (such as trace sampling ratio and export endpoints) to Data Planes via heartbeat, without requiring a gateway restart.
• Added skip_mtls_uri_regex to SSL/SNI configuration, allowing specific URI patterns to bypass mTLS client certificate verification while keeping mTLS enforced for all other URIs.
• Added POST /apisix/admin/configs/validate endpoint for batch configuration validation. Operators can validate route, service, upstream, and plugin configurations before applying them, catching schema errors without affecting live traffic.
• DP Manager now supports native gRPC etcd protocol on port 7943 via cmux, providing Data Planes with an additional connectivity option alongside the existing HTTP-based etcd protocol.
• The encrypt_fields mechanism now supports nested and complex field structures, including arbitrary-depth dotted paths, arrays, and maps. Plugin configurations with deeply nested sensitive fields (such as auth.gcp.service_account_json) are now encrypted at rest correctly.

Console (Dashboard)

• Added form-based configuration modes for the Key Auth and Basic Auth plugins, enabling visual credential setup without manual JSON editing.
• Added OpenID Connect quick start presets with pre-filled configuration templates for common identity providers, simplifying initial OIDC plugin setup.
• Added Consul as a selectable service discovery type in the upstream configuration UI.
• Supported specifying the SNI when configuring skip_mtls_uri_regex.

Fixes

Plugins

• AI Proxy (opens in Plugin Hub docs)
  • Fixed issue: When an LLM provider emitted many small SSE chunks per second (such as single-character reasoning tokens), a single streaming request could monopolize a worker process at 100% CPU, degrading availability for all other traffic on that worker.
  • Fixed issue: When a protocol converter was active (for example, Anthropic-to-OpenAI) and the upstream returned SSE events in an unexpected format, the gateway returned a 500 error instead of 502. The gateway now correctly returns 502 Bad Gateway when the upstream response format is incompatible with the configured protocol conversion.
  • Fixed issue: When LLM providers returned JSON null for nullable response fields (such as prompt_tokens_details or usage), the gateway crashed because the JSON null sentinel value passed Lua truthiness checks but could not be indexed as a table.
• AI Rate Limiting (opens in Plugin Hub docs)
  • Fixed issue: Upstream-provided usage keys (from LLM response usage data) that collided with reserved expression environment names (such as math or abs) could shadow built-in functions, potentially breaking rate limiting expression evaluation or bypassing limits.

Control Plane

• Fixed issue: Creating OAuth credentials via Developer Portal with an OIDC-type DCR Provider failed on identity providers (such as Keycloak) that require the client_name field. The client_name is now included in both DCR register and update requests, using the Application name as the value.

Ingress Controller

• Fixed issue: The Ingress Controller set hosts on both Route and Service when translating ApisixRoute resources. For backends that do not support route-level hosts, this caused a false diff every sync cycle, triggering unnecessary PUT requests and generating massive audit log growth. In one production environment, this resulted in 8 GB / 4.2 million redundant UpdateService audit log entries.

Console (Dashboard)

• Fixed issue: The service discovery loading indicator remained visible indefinitely when the discovery request failed.
• Fixed issue: Nacos service metadata was not refreshed when switching between services in the upstream configuration.
• Fixed issue: Switching login option provider types did not clean up configuration fields from the previous provider, leaving stale values in the form.
• Fixed issue: The IAM policy statements editor crashed with a null reference error when policies data was not yet loaded.
• Fixed issue: The InviteUser and ResetPassword actions did not display error messages when the API call failed, making it unclear why the operation did not succeed.
• Fixed issue: The login option name uniqueness check loaded the full list of login options unnecessarily. It now uses a lightweight API call.
• Fixed issue: The IAM delete role operation used the wrong permission action (iam:UpdateRole instead of iam:DeleteRole).