●Change8

Migrating to Linkerd edge-25.6.3

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

Released: 6/18/2025

2
Breaking Changes
2
Migration Steps
6
Affected Symbols

⚠️ Check Your Code

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

destinationsp-validatorpolicy-controlleridentityproxy-injectorlinkerd2-cni

Breaking Changes

●Issue #1

The histogram buckets for gRPC handling-time histograms have changed. This is potentially breaking if external monitoring relies on the exact bucket definitions.

●Issue #2

Port names used in Linkerd deployments have been updated to ensure uniqueness required by Kubernetes 1.33. This affects configurations referencing these ports by name in the following components: destination (grpc -> dest-grpc, admin-http -> dest-admin), sp-validator (admin-http -> spval-admin), policy-controller (grpc -> policy-grpc, admin-http -> policy-admin), identity (grpc -> ident-grpc, admin-http -> ident-admin), proxy-injector (admin-http -> injector-admin), and linkerd2-cni (admin-http -> repair-admin).

Migration Steps

  1. 1
    Review any monitoring configurations that rely on the specific bucket definitions of gRPC handling-time histograms and update them if necessary.
  2. 2
    If you are using custom configurations or manifests that explicitly reference the old port names (grpc, admin-http) within the affected components, update them to use the new, disambiguated names (e.g., dest-grpc, dest-admin, etc.).

Release Summary

This release is NOT RECOMMENDED and suggests upgrading to edge-25.8.1. It introduces breaking changes by updating gRPC histogram buckets and renaming container ports to satisfy Kubernetes 1.33 requirements, alongside bug fixes and new gRPC server metrics in the policy controller.

Need More Details?

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

View Full Changelog