Skip to main content
API7.ai Logo

Release Notes

APISIX Ingress Controller and API7 Ingress Controller let Kubernetes users configure their respective gateways through Gateway API and APISIX custom resources. Starting with 2.1.0, the controllers use aligned release numbers, bringing their release history into one shared view. Product-specific availability or behavior is identified where it occurs.

For releases before 2.1.0, use the separate APISIX Ingress Controller and API7 Ingress Controller release archives.

2.2.1​

ProductReleased
API7 Ingress Controller2026-09-10

API7 Ingress Controller published 2.2.1 before the corresponding APISIX release completed its release process. This patch adds safer secret and certificate handling and corrects route validation, listener matching, and stale data-plane configuration. APISIX Ingress Controller 2.2.0 was still the current stable APISIX release on this date.

Breaking Changes​

The following corrections can stop serving configurations that an earlier controller continued to accept or retain.

Routes Stop When They Are No Longer Accepted​

The controller now removes a route from the data plane after an edit confirms that the route has no managed Gateway or accepted listener. This includes moving a route to another GatewayClass, removing its selected listener, restricting allowedRoutes, or changing host names until they no longer intersect.

A temporarily unresolved Gateway or GatewayClass does not trigger removal because ownership cannot yet be determined.

Upgrade: Before upgrading, correct any route that should remain active but does not have an accepted parent and listener. Do not rely on previously synchronized configuration remaining active after route ownership or listener admission is revoked.

Routes Stop When Their Plugin Configuration Is Deleted​

Deleting an ApisixPluginConfig now removes the configuration for an ApisixRoute or Ingress that still references it. Earlier releases could report the reference as invalid while continuing to serve the last synchronized plugins. Recreating the referenced object allows reconciliation to restore the route.

Upgrade: Apply the reference removal before deleting an ApisixPluginConfig. Keep the object available until every dependent route and Ingress has been updated.

Invalid ApisixRoute Service Ports Are Rejected​

An ApisixRoute backend whose servicePort is empty or does not match a port on the referenced Service is now rejected instead of being accepted with an empty upstream. An empty string no longer matches an unnamed port on a single-port Service accidentally.

Upgrade: Confirm that every servicePort is a valid Service port name or number before rollout.

Routes Follow Their Accepted Listener Protocols​

HTTPRoute and GRPCRoute resources now serve traffic only over the protocols accepted by their attached listeners. A route attached only to HTTPS listeners no longer answers plaintext HTTP requests, and a route attached only to HTTP listeners no longer answers over TLS. Routes attached to both protocols continue to serve both.

Upgrade: Check clients and health probes against the protocols declared by the route's accepted Gateway listeners.

New Features​

This patch makes two options available in the released API7 controller while the corresponding APISIX patch release is pending.

Trust a Private Control Plane CA​

GatewayProxy can provide a PEM-encoded certificate bundle in spec.provider.controlPlane.caCert.value. With tlsVerify: true, the controller uses this bundle in place of the system trust store when connecting to a control plane that uses a private or self-signed certificate authority. Invalid certificate material is rejected, and the field has no effect when certificate verification is disabled.

Load Plugin Configuration from Secrets​

Plugins in v1alpha1 PluginConfig, Consumer, and L4RoutePolicy resources can reference a same-namespace Secret through secretRef. Secret keys use dot-separated paths into the plugin configuration, values are merged as strings, and Secret values override matching inline fields. Updating the Secret triggers reconciliation. If the Secret is missing, the controller rejects the affected configuration instead of publishing only its inline fields.

Source Releases​

2.2.0​

ProductReleased
APISIX Ingress Controller2026-08-18
API7 Ingress Controller2026-08-21

This release expands Gateway API and Layer 4 traffic support, adds downstream mutual TLS (mTLS), and strengthens validation and credential security. Both controllers support Kubernetes 1.31 or later and Gateway API 1.6.0.

Breaking Changes​

The following changes can reject previously accepted resources or change how existing routes match.

Review Listener-Port Matching​

APISIX Ingress Controller changes the value used when listener_port_match_mode is omitted from config.yaml from auto to off. API7 Ingress Controller adds port-based listener matching with the same omitted-field default.

The official Helm charts render this field explicitly, so their defaults determine installed behavior. APISIX Helm installations default to auto, while API7 Helm installations default to off; explicit chart values override either setting.

APISIX Ingress Controller also adds a safeguard that excludes hostname listeners when deciding whether to add a server_port match. API7 Ingress Controller adds port-based matching in this release but does not include that safeguard. A route can fail to match when the selected Gateway listener port differs from the port on which the gateway accepts traffic.

Upgrade: Review the effective listener_port_match_mode in the mounted config.yaml and the physical gateway ports before rollout. If the declared Gateway listener ports differ from the physical gateway ports, use off unless the ports can be aligned.

Authorize Cross-Namespace Consumer Secrets​

Both controllers now require a ReferenceGrant when a Consumer references a credential Secret in another namespace. Without the grant, the credential is not programmed.

Upgrade: Create the grant in the Secret namespace before rollout.

Correct Invalid Plugin Configuration​

Both controllers now fail reconciliation when a plugin config value cannot be decoded as an object. Earlier controllers could discard the malformed value and publish the plugin with an empty configuration, silently removing the intended enforcement.

Upgrade: Find and correct malformed inline, referenced, global, annotation-based, and Consumer plugin configuration before rollout.

Add Missing CSRF Keys​

An Ingress with k8s.apisix.apache.org/enable-csrf: "true" must now set a non-empty k8s.apisix.apache.org/csrf-key. The admission webhook rejects an invalid resource when enabled. If admission is disabled or bypassed, the controller logs an annotation error and omits the CSRF plugin, leaving the route without the intended protection.

Upgrade: Add a non-empty key to every affected Ingress before rollout.

Update Manually Managed L4 Webhooks​

TCPRoute and UDPRoute webhook rules and service paths move from v1alpha2 to v1. The released controller manifests include the new paths, but a separately maintained ValidatingWebhookConfiguration does not update automatically.

Upgrade: Update both the API versions and service paths before rolling out the controller.

Security Fixes​

  • Both controllers redact credentials and Admin API keys from controller logs.
  • The Consumer webhook no longer reveals whether a Secret exists in another namespace.
  • Cross-namespace Consumer credential access now requires explicit ReferenceGrant authorization.
  • Invalid plugin configuration fails instead of being applied as an empty configuration.

New Features​

This release adds the following traffic-management and security capabilities.

Secure Gateway Listeners with mTLS​

Both controllers can require clients to present a certificate signed by a configured certificate authority. Gateway API declares this validation on the Gateway, with a default for all HTTPS listeners and optional per-port overrides.

Apply Policies to Layer 4 Traffic​

Both controllers add L4RoutePolicy for attaching stream plugins to TCPRoute, UDPRoute, and TLSRoute resources. Stream backends can also select tcp, tls, or udp as their upstream scheme.

Use Gateway API 1.6.0​

Both controllers support Gateway API 1.6.0, including the v1 TCPRoute, UDPRoute, TLSRoute, and ReferenceGrant APIs. Listener-port matching also extends to TCPRoute and UDPRoute.

Match API7 Routes by Listener Port​

API7 Ingress Controller adds port-based matching for Gateway API routes. APISIX Ingress Controller introduced this capability in 2.1.0.

Bug Fixes​

The following fixes improve route correctness, status reporting, and controller reliability.

Gateway and Route Reconciliation​

  • Gateway status conditions now report the reasons required by Gateway API 1.6.0.
  • Uppercase host names and server names are normalized so routes continue to match.
  • TCPRoute and UDPRoute honor an explicitly selected listener name or port.
  • BackendTrafficPolicy honors a Service port selected with targetRefs.sectionName.
  • HTTPRoute reads appProtocol from an ExternalName Service.

Controller Reliability​

  • A new leader rebuilds its synchronization baseline instead of using stale state.
  • The supplied NetworkPolicy allows admission-webhook traffic to the controller pod.
  • An Ingress using an ImplementationSpecific path no longer panics when its annotations are empty.

Source Releases​

2.1.0​

ProductReleased
APISIX Ingress Controller2026-06-01
API7 Ingress Controller2026-05-29

This release adds richer route, Consumer, health-check, and admission-validation capabilities to both controllers. APISIX Ingress Controller also introduces listener-port matching; API7 Ingress Controller does not include that capability until 2.2.0.

Breaking Changes​

APISIX Ingress Controller introduces one change that can affect existing Gateway API routes.

Align APISIX Listener Ports​

APISIX Ingress Controller adds a server_port condition to some Gateway API routes and uses auto as the controller default. APISIX evaluates that condition against the physical port on which it accepted the connection. Requests return 404 when that port differs from the selected Gateway listener port.

API7 Ingress Controller 2.1.0 does not include port-based listener matching.

Upgrade: Set listener_port_match_mode to off or make the Gateway listener ports match the APISIX listener ports before rollout.

New Features​

Both controllers expand their routing and resource-validation capabilities, with one APISIX-only addition.

Configure Richer Routes and Consumers​

Both controllers add request-body matching to ApisixRoute, plugin configuration to ApisixConsumer, and Consumer labels derived from Kubernetes metadata. BackendTrafficPolicy can also configure active upstream health checks.

Validate Custom Resources Before Reconciliation​

Both controllers add admission validation for APISIX custom resources. Invalid resources can be rejected before they reach translation and synchronization.

Match APISIX Routes by Listener Port​

APISIX Ingress Controller adds port-based matching for Gateway API routes. API7 Ingress Controller adds this capability in 2.2.0.

Bug Fixes​

The following fixes improve route translation, status reporting, synchronization, and health checks.

Route Translation and Status​

  • Regular-expression HTTPRoute paths no longer generate invalid URI matching.
  • Gateway API route status conditions now update observedGeneration correctly.
  • Status-only API resources no longer block controller readiness.
  • HTTPRoute translation preserves a backend scheme that was already selected.

Synchronization and Health Checks​

  • Both controllers use HTTPS certificate verification for standalone active health checks when configured.
  • APISIX Ingress Controller removes redundant route host configuration that caused persistent differences and unnecessary synchronization.

Source Releases​