Add well-known labels and annotation for weighted waypoint canary

annotation/annotations.yaml

@@ -597,6 +597,21 @@ annotations:
       - Service
       - ServiceEntry
 
+  - name: istio.io/use-waypoint-canary-weight
+    featureStatus: Alpha
+    description: |
+      Sets the percentage (0-100) of a service's traffic that is shifted to its canary waypoint
+      (`istio.io/use-waypoint-canary`). The remainder continues to the primary
+      `istio.io/use-waypoint`. Defaults to 0 (canary resolved but receives no traffic) when unset.
+      A value of 100 sends all traffic to the canary (a transient promotion step). Invalid values
+      (non-integer or outside 0-100) are rejected and the service stays on the primary waypoint.
+    deprecated: false
+    hidden: false
+    resources:
+      - Service
+      - ServiceEntry
+      - Namespace
+
   - name: ambient.istio.io/bypass-inbound-capture
     featureStatus: Alpha
     description: |

label/labels.yaml

@@ -265,6 +265,39 @@ labels:
       - ServiceEntry
       - Namespace
 
+  - name: istio.io/use-waypoint-canary
+    featureStatus: Alpha
+    description: |
+      When set on a `Service` or `ServiceEntry` (or its `Namespace`), names a second, canary waypoint for the
+      service in addition to the primary `istio.io/use-waypoint`. A configurable percentage of the
+      service's in-mesh (and, with `istio.io/ingress-use-waypoint`, ingress) traffic is shifted to
+      this canary waypoint, controlled by the `istio.io/use-waypoint-canary-weight` annotation.
+      This is the migration primitive for canarying a service between two waypoints (for example
+      two waypoint revisions, or two waypoint implementations).
+
+      The canary is assumed to be in the same namespace; for cross-namespace, see
+      `istio.io/use-waypoint-canary-namespace`. The canary waypoint must allow the type, see
+      `istio.io/waypoint-for`.
+    deprecated: false
+    hidden: false
+    resources:
+      - Service
+      - ServiceEntry
+      - Namespace
+
+  - name: istio.io/use-waypoint-canary-namespace
+    featureStatus: Alpha
+    description: |
+      When set on a resource, indicates the canary waypoint (`istio.io/use-waypoint-canary`) is in
+      the provided namespace. This must be set in addition to `istio.io/use-waypoint-canary`, when a
+      cross-namespace reference is desired.
+    deprecated: false
+    hidden: false
+    resources:
+      - Service
+      - ServiceEntry
+      - Namespace
+
   - name: istio.io/ingress-use-waypoint
     featureStatus: Beta
     descriptions: |

releasenotes/notes/weighted-waypoint-canary.yaml

@@ -0,0 +1,13 @@
+apiVersion: release-notes/v2
+kind: feature
+area: traffic-management
+issue:
+  - 60801
+
+releaseNotes:
+  - |
+    **Added** the `istio.io/use-waypoint-canary` and
+    `istio.io/use-waypoint-canary-namespace` labels and the
+    `istio.io/use-waypoint-canary-weight` annotation, which let a service shift a
+    configurable percentage of its traffic to a second (canary) waypoint alongside
+    its primary `istio.io/use-waypoint`.