●Change8

Migrating to Linkerd edge-25.3.1

Version edge-25.3.1 introduces 2 breaking changes. This guide details how to update your code.

Released: 3/6/2025

2
Breaking Changes
3
Migration Steps
7
Affected Symbols

⚠️ Check Your Code

If you use any of these symbols, you need to read this guide:

linkerd installenableHttpRoutesenableTcpRoutesenableTlsRoutesinstallGatewayAPIappProtocoloutbound-transport-mode

Breaking Changes

●Issue #1

The settings `enableHttpRoutes`, `enableTcpRoutes`, and `enableTlsRoutes` for controlling Gateway API CRD installation are deprecated and replaced by the new `installGatewayAPI` setting.

●Issue #2

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. 1
    If you were using `enableHttpRoutes`, `enableTcpRoutes`, or `enableTlsRoutes` to control CRD installation, switch to using the new `installGatewayAPI` setting.
  2. 2
    If you encounter issues related to IPv6 or the HTTPRoute CRD installation bug, consider upgrading to `edge-25.7.4`.
  3. 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`.

Release 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.

Need More Details?

View the full release notes and all changes for Linkerd edge-25.3.1.

View Full Changelog