For the complete documentation index, see llms.txt. Markdown versions of all docs pages are available by appending .md to any docs URL.
Release notes
Review summaries of the main changes in the latest release of Solo Enterprise for agentgateway in Kubernetes mode.
Caution
General information
These release notes cover the 2026.11 long-term support (LTS) release of Solo Enterprise for agentgateway. Changes are relative to the previous LTS release, version 2026.7.1. If you use an interim release, some changes already apply to your environment. For changes in each release, see the changelog.
This release includes upstream agentgateway versions 1.5, 1.6, and 1.7, plus later changes. Review the upstream breaking changes for updates to upstream resources.
✨ Highlights
- MCP connectors: Users can connect MCP tools to services such as GitHub without exposing their credentials to agents.
- Role-based authorization: Control access to HTTP traffic, backends, and MCP tools by user, group, or virtual key.
- LLM controls: Apply policies to batch inference jobs, send budget notifications, and choose when guardrails run.
- Bundled UI: Install and upgrade the UI with the control plane. Existing
managementinstallations need migration to use the bundled UI. - Standalone mode: Deploy without a control plane or Kubernetes cluster, now in an LTS release.
Before you upgrade, review the breaking changes and installation changes. Authentication, token limits, and active MCP sessions can be affected.
WAF arguments over the limit are not inspected
Version 2026.10.0 updates the WAF server to use Coraza 3.8.1. In addition to query-string arguments, SecArgumentsLimit (default 1000) now applies to URL-encoded and JSON request bodies. Coraza drops arguments past the limit and sets ARGUMENTS_LIMIT_REACHED.
Until you add a rule that acts on ARGUMENTS_LIMIT_REACHED, rules that inspect ARGS cannot see arguments past the limit. An attacker can exploit this behavior by placing a malicious argument after the limit (CVE-2026-41510).
Required action:
Upgrade Solo Enterprise for agentgateway to version 2026.10.0 or later.
Wait until all WAF server pods are running.
In each WAFPolicy, add rules for
ARGUMENTS_LIMIT_REACHEDtospec.ruleEngineSettingsso that requests that exceed the argument limit are rejected. Do not make this change before the upgrade. Earlier monthly releases with WAF, through version 2026.9.3, use Coraza 3.7, which does not recognizeARGUMENTS_LIMIT_REACHED, so the policy fails to load andwaf-serverrejects all requests that the policy applies to.Add rules
200004and200005or equivalent rules onARGUMENTS_LIMIT_REACHED. WhenSecRuleEngineisOn, these rules reject requests that exceed the limit. Update either the field’s inline configuration or the ConfigMap that it references, for example:spec: ruleEngineSettings: inline: | # ...your existing settings SecRule ARGUMENTS_LIMIT_REACHED "@eq 1" \ "id:'200004',phase:1,t:none,log,deny,status:400, \ msg:'Argument limit reached; request rejected (GET/PATH args)'" SecRule ARGUMENTS_LIMIT_REACHED "@eq 1" \ "id:'200005',phase:2,t:none,log,deny,status:400, \ msg:'Argument limit reached; request rejected (POST args)'"If your configuration already includes these rules or equivalent rules, skip this step.
If your applications legitimately exceed the default argument limit, increase
SecArgumentsLimitinstead of removing these rules. For examples of inline and ConfigMap-basedruleEngineSettings, see Custom Coraza rules.
JWT authentication requires iss, and requires aud when audiences are set
🔥 Breaking changes
Review these changes before you upgrade.
Upstream agentgateway breaking changes
This release includes upstream agentgateway versions 1.5, 1.6, and 1.7, and later changes from the upstream main branch. The previous LTS release, version 2026.7.1, included upstream version 1.4. Review the breaking changes in each upstream version that you skip.
| Upstream version | Breaking changes and removals |
|---|---|
| 1.5 |
|
| 1.6 |
|
| 1.7 |
|
| Later changes |
|
Other upstream 1.7 upgrade changes
- Model namespaces: By default, an AgentgatewayModel must be in the listener’s namespace. For cross-namespace models, set
allowedRoutes.namespaces.fromtoAllorSelector, or move the model. - Proxy callouts: External authorization, guardrail requests, and AWS and Azure credential fetches now honor
HTTPS_PROXY,HTTP_PROXY,ALL_PROXY, andNO_PROXY. Review these variables. To keep callouts direct, setNO_PROXYto*. - Controller metrics: Update dashboards that use
agentgateway_controller_reconcile_duration_secondsoragentgateway_controller_reconciliations_running, which are removed. Theagentgateway_controller_reconciliations_totalmetric no longer hasnameornamespacelabels. - Configuration warnings: Also alert on
agentgateway_xds_warnings_total. Warnings no longer incrementagentgateway_xds_rejects_total. - Streamed usage: Chat Completions streams now always end with a usage chunk before
data: [DONE]. Clients must handle this chunk’s emptychoicesarray.
For details, see Upstream 1.7 behavior changes.
JWT authentication requires matching claims
JWT tokens must now include an iss claim that matches the configured issuer. If the JWT provider sets audiences, tokens must also include a matching aud claim. Previously, tokens without these claims could pass validation.
These checks apply to jwtAuthentication providers on an EnterpriseAgentgatewayPolicy. An empty jwtValidationOptions.requiredClaims list does not turn off the checks.
Actions to take: Check that your identity provider issues tokens with matching claims. To accept tokens without aud, omit audiences from the provider configuration. The issuer field is required, so tokens without iss fail authentication.
For more information, see Set up JWT auth.
LLM token counts include cache tokens
In logs, metrics, and CEL, input and total token counts now include cache-read and cache-creation tokens for every provider.
llm.inputTokensincludes all input tokens.llm.totalTokensincludes all input and output tokens.- The new
llm.providerInputTokensandllm.providerTotalTokensfields preserve the counts from the provider. llm.cachedInputTokensandllm.cacheCreationInputTokensdo not change. Both counts are subsets ofllm.inputTokens.
Counts increase for requests that use prompt caching with the following providers:
- Anthropic and Amazon Bedrock.
- Anthropic models through Vertex AI or GitHub Copilot.
- Custom providers that use the
messagesoranthropicTokenCountformat.
The change affects token rate limits, budgets with unit: Tokens, and CEL expressions that read the normalized counts. Logs, spans, and the agentgateway_gen_ai_client_token_usage metric also use the normalized counts. USD budgets, cost tracking, and llm.cost do not change.
Actions to take: Review token limits and budgets because affected requests consume more tokens. Mark the upgrade in token dashboards to explain the increase. To use the original provider counts in custom logs, metrics, or rate limit descriptors, use the new llm.provider* fields.
The AGENTGATEWAY_LEGACY_LLM_USAGE_TOKEN_SEMANTICS environment variable is removed. You can no longer restore the previous behavior.
For details, see Token usage fields and the CEL reference.
OAuth issuer uses PKCE for all clients
The enterprise OAuth issuer now uses S256 Proof Key for Code Exchange (PKCE) with the downstream identity provider. PKCE applies to both public and confidential clients. Previously, only public clients used PKCE. Some identity providers reject PKCE for confidential clients.
Actions to take: If your identity provider rejects these requests, set downstream_server.pkce: public_only in KGW_OAUTH_ISSUER_CONFIG. This setting restores the previous behavior. See Issuer settings.
Vendor guardrails scan tool output by default
Vendor guardrails, including Microsoft Purview DLP, now scan tool output in addition to system prompts and messages. The scope field controls which parts of a request each guardrail scans.
Actions to take: To keep the previous behavior, set scope: [SystemPrompt, Messages] on each vendor request guardrail. See Microsoft Purview DLP.
STS OAuth storage is encrypted at rest
OAuth flow state, client registration secrets, and cached authorization-server metadata are now encrypted at rest in the security token service (STS).
During upgrade, existing plaintext client registrations are removed and recreated on first use. Affected users must authorize again. Users with logins in progress must restart authorization. Cached authorization-server metadata is fetched again.
For more information, see STS elicitation.
A custom provider reference overrides the provider name
When an LLM backend uses a custom provider reference, the provider name is now the name of the custom provider, instead of custom.
Actions to take: Check your custom model cost catalog for entries that use the provider name custom. Update those entries to use your custom provider’s name.
UI data moves to a new ClickHouse database
The bundled UI now stores its data in a ClickHouse database of its own, agwe. The database holds only the tables that the UI reads. The UI refuses to start on a database that an earlier version created. For example, the UI does not use the agentgateway database of the bundled UI in versions 2026.10.1 to 2026.11.0. It also does not use the platformdb database of the management chart.
When you upgrade, the UI creates the new database next to the earlier database and starts with an empty history. The UI does not change the earlier database, so you can roll back. The release also includes the following changes:
- The UI no longer collects metrics. The chart ignores the
ui.telemetry.metrics,ui.telemetry.selfMonitoring, andui.telemetry.collector.shardingvalues. - The telemetry collector always runs as a Deployment. Its persistent queue uses a new volume claim and requires
ui.telemetry.collector.replicaCount: 1. - The connection Secret that the chart generates is renamed from
enterprise-agentgateway-ui-clickhouse-configtoenterprise-agentgateway-ui-clickhouse-connection. - If the collectors use their own ClickHouse Secret, the Secret must name the same database as the Secret of the UI. Otherwise, the upgrade with the Helm CLI fails.
The cost management pages show only the spend since the upgrade, until you copy your history. On the Budgets tab, the usage of a budget shows again after the next request that the budget counts. Budgets and their limits do not change.
Actions to take: Before you upgrade, remove any database name that points at the earlier database. Point your own connection Secrets at the new database. To keep collecting metrics, scrape them with your own Prometheus instance. To show the earlier history in the UI, copy it into the new database. For the steps, see Upgrade to the new UI database. If you ran the bundled UI on the platformdb database of management, see Move the UI to a database of its own.
⚠️ Deprecations
These fields still work in this release. Use the replacements for new configurations.
| Deprecated field | Replacement | More information |
|---|---|---|
tokenExchange.entra on an EnterpriseAgentgatewayPolicy | entTokenExchange.entra | Microsoft Entra ID |
entElicitation.interactive and tokenExchange.elicitation | entConnector | MCP connectors |
⚒️ Installation changes
Review these changes when you upgrade from the previous LTS release, version 2026.7.1.
UI is bundled with the control plane
The UI is now an enterprise-agentgateway-ui subchart of enterprise-agentgateway. The subchart is off by default. Set ui.enabled=true to install the UI. The bundled UI shares the control plane’s license and upgrades with the control plane.
Existing installations of the separate management chart keep working after a control plane upgrade. Migration to the bundled UI is a separate step.
Actions to take: If you use Argo CD with management, set installRBACPolicyCRD=false on the CRD chart before upgrading. To migrate the UI, move your settings under ui. Update the telemetry collector endpoint. Follow Migrate from the management chart to keep your RBAC policies before you remove the old release. The bundled UI starts with an empty history. To keep your ClickHouse history, see UI data moves to a new ClickHouse database.
For new installations, see Set up the UI.
Warning
Configure ui.oidc.issuer before you expose the UI to untrusted users. Without an external identity provider, the built-in evaluation provider signs visitors in as admin without credentials.
Shared extensions are isolated per installation and GatewayClass
Starting in 2026.9.3, each controller installation and GatewayClass has separate shared extensions. This isolation prevents RBAC conflicts and split rate limit counters. Each Gateway uses its own class’s extensions. Deleted extension resources are recreated immediately. The external cache restarts during the upgrade, so rate limit and budget counters of the current window start again at zero.
During the upgrade, rate limiter pods restart once, and their Services and PodDisruptionBudgets (PDBs) automatically adopt per-class selectors. Policies that are shared across GatewayClasses now use the extensions of each class.
Actions to take:
- Upgrade every controller installation in the cluster. Older installations can still delete another installation’s extension RBAC. Until all installations are upgraded, keep any workaround that restricts RBAC deletion.
- After all installations are upgraded, delete the old WAF RBAC resources. Remove
waf-server-<gatewayclass>ClusterRoles and ClusterRoleBindings for every class that used WAF, including the default class. Replacement names include the namespace:waf-server-<install-namespace>-<gatewayclass>. - If GatewayClasses share a namespace and use rate limiter HorizontalPodAutoscalers (HPAs), consider recreating their Deployments. During a maintenance window, delete each
rate-limiter-<gatewayclass>Deployment. Each Deployment is recreated with a per-class selector. Until then, the HPA averages CPU usage across classes. This optional step briefly interrupts rate limiting for each class. - Remove stale extension PDBs and HPAs. Check the installation namespace for
<extension>-<gatewayclass>resources from classes or extensions removed before the upgrade. Delete these resources manually. Stale rate limiter PDBs can block node drains.
For more information about shared extensions, see Shared extensions.
Managed MCP session keys
Each Gateway now has a managed session key in a Secret named <gateway-name>-session-key. This key encrypts MCP session IDs to keep sessions working across replicas and proxy restarts.
Actions to take: Schedule the upgrade when few MCP sessions are active. Proxy pods restart once to load the key. Existing sessions end, and clients must start new sessions. To use your own key, see Manage MCP session keys.
Elicitation database migration
You can now select the JWT claim that owns an elicitation by setting AGW_ELICITATION_USER_ID_CLAIM. The default is sub. For more information, see Elicitation owner claim.
On the first controller start after upgrade, the STS migrates the elicitation database.
- Existing elicitations use
sub. If you keep this default, the database migration preserves stored authorizations. - OAuth flows that are in progress during the upgrade fail. Those users restart authorization.
- The migration rewrites every elicitation row and creates a new index. On PostgreSQL, the table is locked against reads and writes until the migration commits. Larger tables take longer.
Actions to take:
- If you use PostgreSQL, plan a maintenance window that matches the size of your elicitation table.
- If you set the
downstream_server.user_id_claimfield inKGW_OAUTH_ISSUER_CONFIG, remove the field and set theAGW_ELICITATION_USER_ID_CLAIMenvironment variable instead. When only the older field is set, token exchange cannot find the credentials that the brokered flow stores.
FIPS image variants
FIPS builds of the control plane and proxy are available as -fips image variants. The proxy uses FIPS AWS-LC, and the control plane uses the Go FIPS 140-3 module. TLS, JWTs, and JWT signing keys must use FIPS-approved algorithms and keys.
To select FIPS builds for the control plane, proxy, and extensions, set the image.variant Helm value. See FIPS.
License from a mounted file
You can now load the license from a file instead of a Kubernetes Secret, such as a file that a Secrets Store CSI driver mounts. Set the licensing.licenseFilePath Helm value to the absolute path of the file. When you set this value, the chart does not create a license Secret. You cannot set both licensing.licenseFilePath and licensing.licenseKey. For more information about licenses, see Licensing.
Mirrored third-party images
Third-party images, such as redis, are verified and mirrored to us-docker.pkg.dev/solo-public/mirrored-third-party before each release. If you use a private registry, update your mirrored images. See the image list in the Air-gapped installation guide.
Other Helm and version changes
- The
controllerNameHelm value is removed from theenterprise-agentgatewaychart, because the controller uses a fixed identity. The chart no longer setsAGW_CONTROLLER_NAME. Remove the value from your Helm values files. - The version that the controller, the UI, and
agentgateway --versionreport no longer has a leadingv, such as2026.11.0. The version now matches the image tags. If your automation parses the reported version, update it. - New Helm values for the control plane include
extraInitContainersandtopologySpreadConstraints.
🌟 New features
These features are new since the previous LTS release, version 2026.7.1.
Security and identity
Role-based authorization
Control access to HTTP traffic, backends, and MCP tools by role. Use an EnterpriseAgentgatewayRoleBinding to assign roles to users, groups, or virtual keys. Then apply roles in authorization rules with roles.anyOf, or in CEL expressions with ent.has_role().
See About role-based authorization.
Token exchange and elicitation
New authentication options help you connect to identity providers and share authorizations:
- Entra on-behalf-of preset: Use
entTokenExchange.entrato exchange a user token for a Microsoft Entra token. See Microsoft Entra ID. - Client ID metadata documents (CIMD): Public MCP clients can identify themselves with an HTTPS URL instead of dynamic client registration. See Client ID metadata documents.
- PKCE and PAR: Configure PKCE for chained authorization. Public clients can also use pushed authorization requests (PAR).
- Elicitation owner claim: Share authorizations across applications that use the same JWT claim value. See Elicitation owner claim.
- Redirect URI allowlist: Restrict the redirect URIs that the issuer proxy accepts from MCP clients. See Redirect URI allowlist.
- SAML for Cross App Access: Use a SAML 2.0 assertion as the subject credential for Cross App Access (ID-JAG) with the
entCrossAppAccesspolicy. See Cross App Access. - AWS assume-role chaining: Chain AWS roles for backend authentication. See AWS assume role chaining.
- Scoped tokens: Exchanged tokens cannot outlive the source token or exceed its scopes. Issued scopes are limited to the requested scopes.
- Certificate-based client authentication for Entra: The OAuth issuer can authenticate to Microsoft Entra with a client certificate.
FIPS-validated cryptography
Run the control plane and the proxy with FIPS-validated cryptography. For the image variants and the Helm value, see FIPS image variants.
LLM
Batch inference
Apply prompt guards and cost tracking to OpenAI, Anthropic, and Amazon Bedrock batch jobs. Each record in an uploaded batch file is checked. For more information, see About batch inference.
Budget notifications
Get notified when spending crosses a budget threshold. Customize the notification payload by using CEL expressions. For more information, see Budget notifications.
Guardrail improvements
- Conditional guardrails: Run a prompt guard only for requests that match a
condition. See Conditional and reversible guards. - Failure mode: Every guardrail type can fail open or fail closed.
- Reasoning scan: Response guardrails can scan the reasoning content of a response, and support the
scopefield. - Scope on vendor guardrails: Select the parts of a request that a vendor guardrail scans. See Vendor guardrails scan tool output by default.
- Tool modes: MCP guardrails apply in the search, code, and code search tool modes.
Global rate limit failure mode
Set failureMode: FailOpen on entRateLimit.global to allow requests when the rate limit service is unavailable. The default is FailClosed. You can also customize global rate limits for each request with the cost and limitOverride CEL expressions. For more information about global rate limits, see Global rate limiting.
MCP
MCP connectors
Users can authorize MCP tools to access services such as GitHub or Atlassian without exposing credentials to agents. Users connect services from the UI’s Connectors page or from a link returned when a tool needs authorization. Credentials are stored per user and target in PostgreSQL.
Connectors replace interactive elicitation and are off by default. Enable the identity service and configure entConnector to use connectors. For setup steps, see About connectors.
MCP provider catalog
Deploy common MCP servers from a catalog of MCP providers in the Solo Enterprise for agentgateway UI.
Traffic management
Active health checks
Check backend health on a fixed schedule by setting entHealthCheck. Results appear in the agentgateway_ent_backend_health metric and proxy logs. For more information, see Active health checks.
EnterpriseListenerSet
Attach more listeners to a Gateway with the EnterpriseListenerSet resource, on platforms where the Kubernetes Gateway API ListenerSet is not available.
CEL data imports
Import data from Kubernetes Secrets and ConfigMaps into the CEL context of an EnterpriseAgentgatewayPolicy with the imports field. To use the imported data in every CEL expression on a Gateway, set importScope: Global and target the Gateway.
HTTPS and TLS listeners on one port
HTTPS and TLS listeners on the same Gateway can now share a port.
Solo UI
Access control for trace payloads
In fine-grained access mode, trace payloads such as prompts, completions, and tool arguments are hidden by default. To let users view payloads, grant agentgateway:traces:payloads in an EnterpriseAgentgatewayRBACPolicy.
For more information, see Trace payloads.
Other UI improvements
- Branding: Show your company name, logos, favicon, a settings-page message, and custom CSS in the UI with the
brandingHelm values of the UI chart. - Cost Management: Export budget spending, utilization, status, and remaining amounts for all dimensions in the selected time range. View 1-hour and 12-hour cache write rates in the model cost catalog.
- Tracing: View budget dimensions, such as virtual key, user, and group, in LLM traces. Identify traces that another product started by their parent span ID.
- Elicitations: The Elicitations page appears only while token exchange is running.
Upstream agentgateway features
This release includes upstream versions 1.5, 1.6, and 1.7. Key additions include:
- New providers include Meta, Perplexity, and Copilot. New API formats include native Gemini, OpenAI Decisions, and TypeSafe SystemOne.
- Model metadata in
/v1/modelsand CEL, plus service-tier pricing for cost tracking. - MCP backends with up to 128 targets, list pagination, and CEL guardrails.
- Session affinity, per-key local rate limits, and new
agctldiagnostic commands.
For the full feature lists, see the upstream release notes for 1.5, 1.6, and 1.7.
🐛 Fixes
- MCP OpenAPI targets now accept YAML schemas as well as JSON.
- OIDC front-channel logout now ends the session. The
logoutPathsetting redirects to the identity provider’s logout endpoint. - Token exchange with an actor token now works with the enterprise STS.
- An invalid RateLimitConfig no longer prevents the controller from starting. Affected policies report the error.
For all fixes, see the changelog.