Consul on Kubernetes 2.1.x

Consul on Kubernetes 2.1.0 adds API gateway route filter custom resource definitions (CRDs), AI workload support in the service mesh, post-quantum key exchange, and nftables traffic redirection. It requires Consul 2.1.x and Consul Dataplane 2.1.x. This page lists release highlights, supported software, upgrade actions, and known issues.

Release highlights

• API gateway enhancements: Kubernetes API gateways add the following capabilities. For more information, refer to API gateway features that require a completed upgrade.
  • The RouteUpstreamLimitsFilter CRD sets per-service circuit-breaker limits and passive health checks on gateway backends.
  • The RouteHeaderMatchInvertFilter CRD routes requests when a header is absent or does not match.
  • The api-gateway.consul.hashicorp.com/listener-<sectionName>-protocol annotation sets the http2 or grpc protocol for each listener.
  • The consul.hashicorp.com/tls-enabled: "true" annotation terminates downstream TLS with the gateway's Connect leaf certificate, so you do not need certificateRefs or a Kubernetes secret.
  • The consul.hashicorp.com/consul-envoy-proxy-concurrency annotation overrides the Envoy worker thread count on API gateway pods.
• Kubernetes Gateway API v1.6: The API gateway supports TCPRoute under Gateway API v1.6.0 CRDs. For more information, refer to Upgrade API gateway resources.
• Consul Agentic Runtime Fabric (beta):
  Enterprise
  The control plane injects AI agents and inference gateways into the service mesh. Terminating gateways can inject Vault-backed credentials into external large language model (LLM) and Model Context Protocol (MCP) calls. For more information, refer to Consul Agentic Runtime Fabric and External credential injection.
• Hybrid post-quantum key exchange: The Mesh CRD accepts an ECDHCurves field, which enables the X25519MLKEM768 key exchange group for service mesh mutual TLS (mTLS). For more information, refer to Configure post-quantum TLS.
• nftables traffic redirection: Transparent proxy redirects traffic with nftables instead of iptables. Nodes require the nft binary and Linux kernel 5.2 or later, or a distribution that backports nftables inet NAT support. For more information, refer to Transparent proxy uses nftables.
• Metrics from multiple ports: The consul.hashicorp.com/service-metrics-endpoints annotation lets one container expose metrics on several ports. It takes precedence over the service-metrics-port and service-metrics-path annotations. For more information, refer to Consul on Kubernetes annotations and labels reference.
• Feature gate Job: A Helm-managed Job applies the feature gates that you configure in Helm values to Consul servers. For more information, refer to Feature gates.
• Helm chart updates: The Helm chart adds the following values. For more information, refer to Helm chart reference.
  • global.acls.authMethod.create uses Kubernetes auth methods that you manage outside the Helm release.
  • global.acls.authMethod.name sets a unique auth method name for each cluster that shares one Consul control plane.
  • global.globalRegistry connects Consul servers to an external global registry.
  • global.imageApplyManifests overrides the image for the post-upgrade apply-manifests Job.

Supported software

Consul on Kubernetes 2.1.x supports the following software versions:

• Consul 2.1.x
• Consul Dataplane 2.1.x
• Kubernetes 1.32.x - 1.37.x
• kubectl 1.32.x - 1.37.x
• Helm 3.11.3+

For OpenShift versions and earlier releases, refer to the Consul on Kubernetes compatibility matrix.

Upgrade to Consul on Kubernetes 2.1.x

Review Upgrade Consul to v2.1.x and Upgrade Consul on Kubernetes before you upgrade.

Consul on Kubernetes 2.1.0 also changes component ACL binding rules:

• Component binding rules now require the Consul release namespace in addition to the service account name. The upgrade updates existing rules, including rules in federated secondary datacenters. Move any component that runs outside the release namespace into it before you upgrade.
• The upgrade does not rewrite binding rules for components that are disabled. If you enabled a component and later disabled it, such as sync catalog, a mesh gateway, or another gateway, do one of the following:
  • Delete its old binding rule from the component auth method. Run consul acl binding-rule list -method <prefix>-k8s-component-auth-method to find the rule ID, then run consul acl binding-rule delete -id <id>.
  • Re-enable the component once and run the upgrade so that the upgrade updates its rule.

Known issues

• Consul does not support a combination of protocols for a multi-port service. All ports of a service must use the same protocol.
• Kubernetes annotations have a character limit, which constrains the number of upstreams you can specify for a service with the consul.hashicorp.com/connect-service-upstreams annotation.

Report issues on GitHub.

Changelogs

The following list links to the changelogs for this release and its maintenance releases.

• 2.1.0