HashiConf 2025 Don't miss the live stream of HashiConf Day 2 happening now View live stream
Consul Home

Consul 2.1.x

We are pleased to announce the following Consul updates.

Release highlights

  • Consul Agentic Runtime Fabric (beta):
    Enterprise
     Consul Agentic Runtime Fabric extends service mesh governance to AI workloads. Service definitions accept an ai block that declares the workload's AI role as inference-model, mcp-server, or ai-agent. The inference-gateway service kind enforces intentions and routes requests to model upstreams by capability, with failover across providers by priority. The inference gateway can also reach external models through a terminating gateway over per-model mTLS. Consul manages OAuth clients for ai-agent and mcp-server services, and terminating gateways can inject Vault-backed credentials into egress requests. The builtin/ext-proc Envoy extension accepts Unix domain socket processor targets. These features are behind the consul-ai feature gate, which is disabled by default. For more information, refer to Consul Agentic Runtime Fabric.
  • Dynamic feature gates: Feature gates turn experimental functionality on or off for an entire datacenter without restarting agents. Consul stores gate settings in Raft, and a gate takes effect only after every server runs a version that supports it. Manage gates with the consul operator feature commands or the /v1/operator/feature HTTP API endpoints, and set initial values with the feature_gates server configuration block. For more information, refer to Feature gates.
  • API gateway parity with ingress gateway: The API gateway adds capabilities that were previously available only on the ingress gateway. Consul registers DNS for services exposed through an API gateway at <service>.api-gateway.consul. API gateway listeners accept the http2 and grpc protocols for end-to-end HTTP/2 and gRPC traffic. When you enable TLS on an API gateway without configuring a certificate, the gateway terminates TLS with its Connect certificate authority (CA) leaf certificate. You can also configure passive health checks for routed services, and HTTP route header matches support the invert field. For more information, refer to API gateway configuration entry reference and HTTP route configuration entry reference.
  • Hybrid post-quantum TLS: Consul supports the X25519MLKEM768 hybrid post-quantum key exchange group for service mesh mutual TLS (mTLS) and agent TLS. The mesh configuration entry accepts TLS.Incoming.ECDHCurves and TLS.Outgoing.ECDHCurves, and agent TLS configuration accepts tls_ecdh_curves. When the minimum TLS version is TLS 1.3 and you do not configure curves, Consul offers X25519MLKEM768 and X25519 by default. For more information, refer to Configure post-quantum TLS.
  • Sidecar resilience during control plane outages: Consul delivers leaf certificates and CA roots to sidecar proxies and terminating gateways over Envoy's secret discovery service (SDS). Certificate rotation does not drain established connections. Localized DNS lets the Envoy sidecar resolve virtual service domains locally, so DNS for configured upstreams keeps working when Consul servers are unreachable. Localized DNS is an experimental feature behind the localized-dns feature gate, which is disabled by default. For more information, refer to Certificate authority overview and Localized virtual DNS resolution.
  • OpenID Connect (OIDC) identity provider logout: Logging out of a token created by an oidc auth method can end the session at the identity provider (IdP). consul logout prints the IdP's logout URL, or opens it in the default browser with the -open-browser flag. The Consul UI opens the URL when you log out. Consul uses the IdP's advertised end_session_endpoint, or the OIDCLogoutURL auth method setting for providers that do not advertise one. For more information, refer to OIDC auth method.
  • Multiport routing across cluster peers:
    Enterprise
     You can route traffic to a specific named port on a multiport service that a cluster peer exports. Peered multiport routing is an experimental feature behind the peering-multiport-upstreams feature gate, which is disabled by default. For more information, refer to Multiport services across cluster peers and Feature gates.
  • Consul Operations Hub (beta):
    Enterprise
     Consul Operations Hub provides a centralized management view of your Consul datacenters. Consul servers publish snapshots and incremental updates of their data to the Operations Hub global registry. For more information, refer to Install and set up Consul Operations Hub.
  • Consul UI on the HashiCorp Design System: The Consul UI uses the HashiCorp Design System for the global navigation, breadcrumbs, list pages, and the access control, namespace, and admin partition forms. The update includes accessibility fixes.
  • Product telemetry updates:
    Enterprise
     Opt-in telemetry reporting adds product usage metrics for ACL auth methods, audit logging, mesh gateway modes, service intentions, auto-encrypt, API gateways, and transparent proxy adoption. For a complete list of metrics, refer to Consul agent telemetry reporting reference.

Breaking changes

Consul 2.1.x includes the following breaking changes.

Transparent proxy uses nftables

  • consul connect redirect-traffic redirects transparent proxy traffic with nftables instead of iptables and ip6tables. Redirection requires the nft binary and a Linux kernel with stateful NAT support in nftables inet chains. Upstream Linux provides this support starting with kernel 5.2, and some distributions backport it, such as RHEL 8 and its derivatives. Consul does not fall back to iptables, so hosts without this support fail to set up traffic redirection.
  • consul connect redirect-traffic validates exclusions before it applies rules. User IDs must be numeric, and outbound exclusions must be IP addresses or CIDR blocks. Consul no longer accepts user names, UID ranges, or host names.
  • consul connect redirect-traffic does not remove iptables rules that earlier Consul versions created. Before you upgrade a host or VM in place, remove those rules to avoid double NAT or inconsistent traffic redirection.
  • The official Consul container images include nftables instead of iptables. Update scripts that run iptables inside the Consul image.
  • The SDK replaces the iptables package with an nftables package.

For more information, refer to Enable transparent proxy mode on VMs.

API request limits and ACL enforcement

  • Consul limits agent HTTP API request bodies to 512 KiB by default, including chunked requests. Oversized requests return HTTP 413, so very large /v1/config writes that previously succeeded can fail. To raise the limit, set limits.http_max_request_body_size.
  • Resource API (/api/...) request bodies follow the same limits.http_max_request_body_size limit.
  • GET /v1/agent/connect/ca/leaf/:service requires service:write on the requested service for every request, including requests served from the agent's cached leaf certificate. Requests without that permission return HTTP 403.
  • Catalog.Register requires write permission on the node or service of an existing health check to update it. Tokens without that permission receive a permission denied error.

API gateway upstream routing behind a feature gate

  • API gateway HTTPRoute upstream-routing composition is behind the experimental api-gateway-upstream-routing feature gate, which is disabled by default. While the gate is disabled, agentless API gateways keep the earlier HTTPRoute routing behavior. Enable the gate only after you upgrade the full datacenter. For more information, refer to Feature gates.

Standard API gateway uses Gateway API v1.6 CRDs

  • The Standard API gateway uses the Kubernetes Gateway API v1.6 custom resource definitions (CRDs) in the gateway.networking.k8s.io API group. These CRDs include TCPRoute.
  • The Helm values for an upgrade depend on whether your cluster uses TCPRoute and which Gateway CRD version it has. Check both before you upgrade.
  • On non-OCP clusters where the platform manages Gateway CRDs v1.6.0 or later, the Standard API gateway supports TCPRoute. Keep global.crds.enableTcpRoute set to true. Use the Consul API gateway only when the platform provides CRDs earlier than v1.6.0 and you require TCPRoute.
  • On OpenShift Container Platform (OCP) 4.19 and later, the Standard API gateway controller does not watch TCPRoute, even with v1.6 CRDs. Use the Consul API gateway when your cluster uses TCPRoute.

For more information, refer to API gateway resource upgrade.

Upgrading

Review the following Consul 2.1.x upgrade considerations before you upgrade:

For more detailed information, refer to the upgrade details page and the changelogs.

Known issues

There are no known issues at this time. These release notes are updated as issues are discovered.

Report issues on GitHub.

Changelogs

The changelogs for this major release version and any maintenance versions are listed below.

Edit this page on GitHub