Release notes

Review summaries of the main changes in the Solo Enterprise for kgateway 2.2 release.

Make sure that you review the breaking changes 🔥 that were introduced in this release and the impact that they have on your current environment.

General information

The release notes on this page cover the new features that were introduced in 2.2.x.

The release notes include important installation changes and known issues. They also highlight ways that you can take advantage of new features or enhancements to improve your product usage.

For more information, see the following related resources:

Kgateway OSS release notes: Release notes for the kgateway open source project that Solo Enterprise for kgateway depends on.
Upgrade guide: Steps to upgrade from the previous minor version to the current version.
Version reference: Information about Solo’s version support.

🔥 Breaking changes

Review details about the following breaking changes. The severity is intended as a guide to help you assess how much attention to pay to this area during the upgrade, but can vary depending on your environment.

🚨 High

Review severe changes that can impact production and require manual intervention.

New controller lease name

The Kubernetes lease name for the controller changed to ensure smooth upgrades from kgateway OSS to Solo Enterprise for kgateway. Previously, the OSS and enterprise controllers both used the same lease name, which led to a race condition when updating and writing Kubernetes objects if both controllers were installed in the same namespace.

To resolve this issue, during the upgrade from version 2.1.x to 2.2.x, a new controller instance is deployed alongside the old controller with the new lease name. Solo Enterprise for kgateway follows a rolling upgrade strategy and removes the old controller. However, during this process both controllers are elected leaders and might fight over the same Kubernetes resource. To prevent this race condition:

Scale down the 2.1.x controller instance to 0 instances.

kubectl scale deploy/kgateway -n kgateway-system --replicas=0

Upgrade Solo Enterprise for kgateway to version 2.2. For example, you can follow the Upgrade guide. After the new control plane instance is deployed, the old control plane instance is automatically removed.
During the upgrade, your data plane proxy continues to function. However, keep in mind that no configuration updates can be pushed from the control plane to your gateway proxies while the control plane is scaled down to 0. After you installed Solo Enterprise for kgateway version 2.2.x and the new controller is fully deployed, the controller automatically pushes xDS snapshots to the gateway proxies.

XListenerSet API promoted to ListenerSet

The experimental XListenerSet API is promoted to the standard ListenerSet API in version 1.5.0. You must install the standard channel of the Kubernetes Gateway API to get the ListenerSet API definition. If you use XListenerSet resources in your setup today, update the CRD kind from XListenerSet to ListenerSet and api version from gateway.networking.x-k8s.io/v1alpha1 to gateway.networking.k8s.io/v1 as shown in the following examples.

Old XListenerSet example:

apiVersion: gateway.networking.x-k8s.io/v1alpha1
kind: XListenerSet
metadata:
  name: http-listenerset
  namespace: httpbin
spec:
  parentRef:
    name: http
    namespace: kgateway-system
    kind: Gateway
    group: gateway.networking.k8s.io
  listeners:
  - protocol: HTTP
    port: 80
    name: http
    allowedRoutes:
      namespaces:
        from: All

Updated ListenerSet example:

apiVersion: gateway.networking.k8s.io/v1
kind: ListenerSet
metadata:
  name: http-listenerset
  namespace: httpbin
spec:
  parentRef:
    name: http
    namespace: kgateway-system
    kind: Gateway
    group: gateway.networking.k8s.io
  listeners:
  - protocol: HTTP
    port: 80
    name: http
    allowedRoutes:
      namespaces:
        from: All

ServiceEntry resource watching gate

The Istio ServiceEntry resource watching capability is now gated by the KGW_ENABLE_ISTIO_INTEGRATION controller environment variable, which defaults to false. Previously, this environment variable defaulted to true.

Without the Istio integration enabled, ServiceEntries are now ignored, which can impact annotations, such as networking.istio.io/traffic-distribution for multi-cluster peering.

To restore the old behavior, set controller.extraEnv.KGW_ENABLE_ISTIO_INTEGRATION=true in your Helm values.

🔔 Medium

Review changes that might have impact to production and require manual intervention, but possibly not until the next version is released.

ℹ️ Low

Review informational updates that you might want to implement but that are unlikely to materially impact production.

⚒️ Installation changes

In addition to comparing differences across versions in the changelog, review the following installation changes from the previous minor version to version .

🌟 New features

Review the following new features that are introduced in version and that you can enable in your environment.

Kubernetes Gateway API version 1.5.1

The Kubernetes Gateway API dependency is updated to support version 1.5.1. This version introduces several changes, including:

XListenerSets promoted to ListenerSets: The experimental XListenerSet API is promoted to the standard ListenerSet API in version 1.5.0. You must install the standard channel of the Kubernetes Gateway API to get the ListenerSet API definition. If you use XListenerSet resources in your setup today, update these resources to use the ListenerSet API instead.
AllowInsecureFallback mode for mTLS listeners: If you set up mTLS listeners on yourproxy, you can now configure the proxy to establish a TLS connection, even if the client TLS certificate could not be validated successfully. For more information, see the mTLS listener docs.
CORS wildcard support: The allowOrigins field now supports wildcard * origins to allow any origin.
BackendTLS: The BackendTLSPolicy resource implementation is now conformant to the Kubernetes Gateway API, including Gateway ancestor status reporting, ResolvedRefs conditions, and deterministic conflict handling.

Controller updates

This release includes the following control plane updates:

Autoscaling and disruption budget: Configure HPA and VPA policies to automatically scale control plane pods based on CPU and memory usage, and set a PodDisruptionBudget to maintain availability during upgrades.
Topology spread constraints: Distribute controller pods across availability zones or nodes to improve resilience and prevent single-zone failures.
Priority class support: Assign a PriorityClass to control plane pods so the Kubernetes scheduler prioritizes them over lower-priority workloads when resources are constrained.
Common labels: Apply custom labels to all resources created by the kgateway Helm chart to improve organization and integration with external tooling.
The default app.kubernetes.io/component: controller label is added to the controller deployment. Similarly, the app.kubernetes.io/component: proxy is added to all gateway proxies.

For more information, see Advanced settings.

Portal

Solo Enterprise for kgateway now provides a developer portal for managing and exposing your APIs. Key capabilities include the following:

Frontend portal: Deploy a self-service frontend that lets developers discover APIs, create teams and apps, manage subscriptions, and generate API credentials.
API product management: Define API products by composing API schemas and versions, and control visibility and access through claim groups.
Authentication: Secure your API products with OIDC-based authentication and API key credentials managed through the frontend portal.

For more information, see About Portal.

Go client for managing kgateway resources

The kgateway-client Go library (github.com/solo-io/kgateway-client/v2) provides typed Kubernetes clients for managing Solo Enterprise for kgateway resources programmatically. Use it to create and update EnterpriseKgatewayTrafficPolicy, AuthConfig, and other CRDs directly from Go code, without kubectl or YAML files. The library follows standard Kubernetes client-go conventions and ships with a fake clientset for writing unit tests without a running cluster.

For more information, see Manage resources with the Go client.

Security

Web Application Firewall (WAF)

You can now protect your routes with a Web Application Firewall (WAF) by using the WAFPolicy and EnterpriseKgatewayTrafficPolicy resources. The WAF is powered by the open source Coraza rule engine and integrates with Envoy via the External Processing (ExtProc) API. A dedicated waf-server is automatically deployed as a shared extension for each GatewayClass.

Key capabilities:

Custom rules: Write Coraza Seclang directives inline or load them from a Kubernetes ConfigMap. ConfigMap-referenced rules are automatically reloaded when the ConfigMap changes.
OWASP Core Rule Set (CRS): Enable the bundled CRS v4 to protect against the OWASP Top Ten and a broad range of common web attacks.
Flexible attachment: Apply a WAFPolicy at the HTTPRoute level or across all routes on a Gateway. Route-level policies can override or disable a gateway-level policy.
Fail-closed behavior: If a WAFPolicy contains invalid directives, the WAF server denies all matching requests with a 500 response until the policy is corrected.

For more information, see About WAF, Enable WAF, and Configure WAF policies.

Rate limit shadow mode and gradual rollout

Local rate limiting now supports percentEnabled and percentEnforced fields to control how aggressively the rate limit filter acts on incoming traffic. Two common use cases are supported:

Gradual rollout: Increase percentEnabled (and optionally percentEnforced) incrementally to roll out rate limiting to a growing percentage of traffic without affecting all requests at once.
Shadow mode: Set percentEnabled: 100 and percentEnforced: 0 to run the filter for all requests and record statistics — such as the number of requests that would have been rate limited — without blocking any traffic. Use this to validate your token bucket configuration before enforcing it in production.

For more information, see Gradual rollout and shadow mode.

IP-based access control (ACL)

The EnterpriseKgatewayTrafficPolicy resource now supports an acl field for IP-based access control. You can define allow and deny rules by using CIDR blocks or bare IP addresses, set a defaultAction for unmatched requests, and customize denial responses with a custom HTTP status code and headers.

For more information, see IP-based access control (ACL).

Require authentication on routes (fail-closed)

You can now mark an HTTPRoute as requiring authentication by adding the kgateway.dev/require-auth: "true" annotation. When this annotation is set, Solo Enterprise for kgateway denies all requests to the route with an HTTP 403 unless a valid auth policy is applied and successfully authenticates the request at runtime.

This feature protects against scenarios where an auth policy is misconfigured, accidentally deleted, or fails to sync, which would otherwise leave the route silently unprotected.

For more information, see Require authentication on routes.

HMAC digest for API key authentication

API key authentication now supports HMAC digest mode. Instead of storing raw API keys in Kubernetes secrets, you store the HMAC-SHA256 digest of each key. A separate Kubernetes secret holds the shared signing key. Clients still send the raw API key in the request header; Solo Enterprise for kgateway computes the digest on the fly and compares it to the stored value. Because raw keys are never persisted in your cluster, this mode reduces the risk of credential exposure.

For more information, see API keys.

Bring your own Redis

You can now replace the built-in ext-cache Redis instance with your own external Redis for the rate limiter and external auth extensions. Key capabilities include:

Amazon ElastiCache support: Authenticate by using AWS IAM Roles for Service Accounts (IRSA) or AWS EKS Pod Identity for secure, credential-free access to ElastiCache Valkey or Redis OSS engines.
Username/password authentication: Supply Redis credentials via a Kubernetes Secret.
TLS: Connect to Redis over TLS with public or private CA certificates.
Connection tuning: Configure connection pool size, idle connections, and timeouts for the external auth service.
Mixed mode: Keep one extension on the built-in ext-cache instance while routing the other to your own Redis.

For more information, see Bring your own Redis.

Traffic Management

Gateway proxy and shared extension customization with overlays

The EnterpriseKgatewayParameters resource now supports gateway proxy customization via overlay fields. Overlays use strategic merge patch (SMP) semantics to apply advanced customizations to the Kubernetes resources that are generated for gateway proxies and shared extensions, including the Service, ServiceAccount, and Deployment.

The following overlays are supported:

Use deploymentOverlay, serviceOverlay, and serviceAccountOverlay to patch the generated Deployment, Service, and ServiceAccount.
Use horizontalPodAutoscaler, verticalPodAutoscaler, and podDisruptionBudget to automatically create and configure these resources targeting the proxy Deployment.

For more information, see the following links:

Static IP addresses for Gateways

You can now assign a static IP address to the Kubernetes service that exposes your Gateway as shown in the following example.

kind: Gateway
apiVersion: gateway.networking.k8s.io/v1
metadata:
  name: http
  namespace: kgateway-system
spec:
  gatewayClassName: enterprise-kgateway
  addresses:
    - type: IPAddress
      value: 203.0.113.11
  listeners:
    - protocol: HTTP
      port: 80
      name: http
      allowedRoutes:
        namespaces:
          from: Same

Envoy application log format

Configure how Envoy formats its application logs by using the logFormat field in the GatewayParameters resource. You can choose between structured JSON or text output. This setting controls the Envoy application log format only and does not affect access logs.

For more information, see Change proxy settings.

Additional Envoy container arguments

Use spec.kube.envoyContainer.extraArgs to pass additional Envoy CLI arguments to the managed proxy container. User-supplied arguments are appended after the default built-in Envoy arguments.

The following example sets a custom base ID and enables CPU set threading:

kubectl apply --server-side -f- <<'EOF'
apiVersion: enterprisekgateway.solo.io/v1alpha1
kind: EnterpriseKgatewayParameters
metadata:
  name: gw-params
  namespace: kgateway-system
spec:
  kube:
    envoyContainer:
      extraArgs:
        - --base-id
        - "7"
        - --cpuset-threads
EOF

Proxy protocol updates

The following updates were added to the proxy protocol capability.

Upstream proxy protocol:

The BackendConfigPolicy resource now supports an upstreamProxyProtocol field. When configured, the gateway proxy prepends a PROXY protocol header to outbound TCP connections to the upstream backend, allowing the backend to see the original client IP address and port. Both PROXY protocol V1 (human-readable) and V2 (binary) are supported.

For more information, see Outbound proxy protocol.

Allow requests without proxy protocol:

The ListenerPolicy proxy protocol configuration now supports an allowRequestsWithoutProxyProtocol field. When set to true, a single listener accepts connections with or without a PROXY protocol header. By default, the field is set to false and the listener strictly requires a PROXY protocol header on all incoming connections.

For more information, see Allow connections without proxy protocol headers.

Dynamic direct response bodies

The DirectResponse resource now supports a bodyFormat field for returning dynamic response bodies by using Envoy format strings. Format strings use %VARIABLE% placeholders that Envoy substitutes at request time, such as request headers or dynamic metadata. You can choose between returning a text or JSON body. Both formats are mutually exclusive.

For more information, see Dynamic text body and Dynamic JSON body.

GRPCRoute support

Route traffic to gRPC services by using the GRPCRoute resource for protocol-aware routing. Unlike the HTTPRoute, which requires matching on HTTP paths and methods, the GRPCRoute allows you to define routing rules by using gRPC-native concepts, such as service and method names.

For more information, see gRPC routing.

TLS termination for TLSRoutes and TCPRoutes

Terminate TLS traffic at the gateway by using a TLS listener in Terminate mode with either a TLSRoute or a TCPRoute. The gateway decrypts incoming TLS traffic using a server-side certificate and forwards the plain traffic to the backend service via TCP proxy.

TLSRoute: Supports SNI-based hostname matching. Use this when you need to route traffic to different backends based on the requested hostname.
TCPRoute: Routes traffic based on listener port only, without SNI hostname matching. Use this listener for simpler port-based routing.

For more information, see TLS termination for TLSRoutes and TLS termination for TCPRoutes.

Resiliency

Fault injection

The EnterpriseKgatewayTrafficPolicy resource now supports a faultInjection field for chaos engineering and resiliency testing. You can inject the following fault types into a percentage of requests:

Delays: Inject a fixed latency before forwarding the request upstream to simulate slow networks or overloaded backends.
Aborts: Return an HTTP or gRPC error code without forwarding the request to simulate upstream failures.
Response rate limiting: Throttle the response body data rate to simulate degraded upstream connections.

Fault injection can be applied at the route level by targeting an HTTPRoute, or at the gateway level by targeting a Gateway. A route-level policy can use disable: {} to opt out of a gateway-level fault injection policy.

For more information, see Fault injection.

Circuit breaker remaining capacity metrics

The BackendConfigPolicy circuit breakers configuration now supports a trackRemaining field. When set to true, Envoy emits gauge metrics for the remaining capacity of each circuit breaker threshold group: remaining_cx, remaining_pending, remaining_rq, and remaining_retries. Note that enabling this field has a small performance overhead.

For more information, see Track remaining capacity.

Observability

OpenTelemetry tracing

Configure distributed tracing for your gateway by using the ListenerPolicy resource, and override tracing settings per route with a TrafficPolicy resource.

The following tracing improvements are included in this release:

Listener-level tracing: Configure the OTel provider, sampling rates (clientSampling, randomSampling, overallSampling), and custom span attributes in a ListenerPolicy that targets your Gateway.
Per-route tracing overrides: Use a TrafficPolicy that targets an HTTPRoute or GRPCRoute to override sampling rates, add route-specific span attributes, or disable tracing for specific routes.
Auto-populated resource attributes: OTel semantic convention resource attributes are automatically added to all spans, including service.name, service.namespace, service.instance.id, service.version, and Kubernetes identity attributes such as k8s.pod.name, k8s.node.name, and k8s.deployment.name.

For more information, see Tracing.

Changelog