●Change8

edge-25.3.1

Breaking Changes
📦 linkerd
⚠ 2 breaking✨ 4 features🐛 4 fixes⚡ 1 deprecations🔧 7 symbols

Summary

This release introduces major changes to how Linkerd manages Gateway API CRDs, replacing older settings with `installGatewayAPI`, and adds support for explicit protocol declaration via Service ports. However, this version is marked as NOT RECOMMENDED due to critical bugs affecting CRD installation and IPv6 support.

⚠️ Breaking Changes

  • The settings `enableHttpRoutes`, `enableTcpRoutes`, and `enableTlsRoutes` for controlling Gateway API CRD installation are deprecated and replaced by the new `installGatewayAPI` setting.
  • When using `linkerd install --crds`, Linkerd will no longer install Gateway API CRDs if any are already present on the cluster (this requires Linkerd to read from the cluster).

Migration Steps

  1. If you were using `enableHttpRoutes`, `enableTcpRoutes`, or `enableTlsRoutes` to control CRD installation, switch to using the new `installGatewayAPI` setting.
  2. If you encounter issues related to IPv6 or the HTTPRoute CRD installation bug, consider upgrading to `edge-25.7.4`.
  3. If you rely on Helm to manage Gateway API CRDs, note that Linkerd now annotates CRDs it installs with `helm.sh/resource-policy: keep`.

✨ New Features

  • Added support for Linkerd protocol declaration via the `appProtocol` field in a Service port definition, bypassing protocol detection.
  • Introduced support for setting `outbound-transport-mode` to `transport-header` during installation to multiplex all traffic between meshed proxies on port 4143.
  • Gateway API CRDs installed by Linkerd will now be annotated with `helm.sh/resource-policy: keep` to prevent downtime during upgrades by avoiding Helm uninstallation.
  • Introduced the `installGatewayAPI` Helm chart value to control whether Linkerd installs Gateway API CRDs.

🐛 Bug Fixes

  • Fixed a bug where `linkerd install --crds --set enableHttpRoutes=false` would still install the HTTPRoute CRD.
  • Fixed an issue where IPv6 support did not work correctly.
  • Fixed a policy controller panic that occurred when the Gateway API was not installed.
  • Fixed policy controller runtime default features to ensure they are correct.

🔧 Affected Symbols

linkerd installenableHttpRoutesenableTcpRoutesenableTlsRoutesinstallGatewayAPIappProtocoloutbound-transport-mode

⚡ Deprecations

  • The settings `enableHttpRoutes`, `enableTcpRoutes`, and `enableTlsRoutes` are deprecated in favor of the new `installGatewayAPI` setting for controlling Gateway API CRD installation.