Add well-known labels and annotation for weighted waypoint canary

[ymesika]

What this does

Registers the well-known labels and annotation for the weighted waypoint canary feature (Design Doc), which lets a service direct a configurable share of its connections (in-mesh) and requests (ingress) to a second "canary" waypoint alongside its primary one. This is the migration primitive for moving a service between two waypoints (for example two waypoint revisions, or two waypoint implementations) without changing clients or introducing a second Service.

Three additions:

Name	Kind	Purpose
istio.io/use-waypoint-canary	label	Names the second (canary) waypoint, alongside the primary istio.io/use-waypoint.
istio.io/use-waypoint-canary-namespace	label	Cross-namespace reference for the canary waypoint (mirrors istio.io/use-waypoint-namespace).
istio.io/use-waypoint-canary-weight	annotation	Relative weight (0-100) of the canary; the primary receives the remainder. In-mesh this is the share of new connections (selection is per-connection), at ingress the share of requests. Defaults to 0; invalid values keep the service on the primary.

These apply to Service, ServiceEntry, and Namespace - the service-level scope. We deliberately scope alpha narrower than istio.io/use-waypoint (which also covers Pod/WorkloadEntry): a pod-scoped canary is logically valid for in-mesh traffic, but it would need a separate weighted field on the Workload API and ztunnel's workload path, and it can't apply to ingress traffic (which is keyed off the service). Keeping to service-level scope for alpha keeps the change minimal and behaves identically across in-mesh and ingress. Workload scope can follow later.

Example:

metadata:
 labels:
   # primary (existing, unchanged)
   istio.io/use-waypoint: waypoint-a


   # optional, primary (existing, unchanged)
   istio.io/use-waypoint-namespace: waypoint-a-ns


   # NEW: canary waypoint (Gateway name)
   istio.io/use-waypoint-canary: waypoint-b
   
   # NEW: optional, only for cross-namespace canaries
   istio.io/use-waypoint-canary-namespace: waypoint-b-ns


 annotations:
   # NEW: 0..100; in-mesh: % of new connections, ingress: % of requests
   istio.io/use-waypoint-canary-weight: "5"

Scope

This PR only adds the API surface: the well-known label/annotation definitions. The implementation lands separately.

Why the canary references are labels but the weight is an annotation

The canary name references (use-waypoint-canary and use-waypoint-canary-namespace) are labels, following their use-waypoint and use-waypoint-namespace siblings.
They name a waypoint the same way the primary reference does, so they live in the same space for consistency.

The weight is an annotation because it is a configuration value, not identity:

• Labels are for identifying and selecting objects. They are indexed and used in selectors. A weight value is never something you would select on (kubectl get -l weight=50 is meaningless), so it does not belong in the label
  space. This is the standard Kubernetes label-vs-annotation split.
• Value-carrying config in this repo is already expressed as annotations, for example sidecar.istio.io/proxyCPULimit, sidecar.istio.io/proxyMemoryLimit, traffic.sidecar.istio.io/excludeInboundPorts, and traffic.sidecar.istio.io/includeOutboundPorts. All are numeric or list config, all are annotations.

[istio-policy-bot]

😊 Welcome @ymesika! This is either your first contribution to the Istio api repo, or it's been
a while since you've been here.

You can learn more about the Istio working groups, Code of Conduct, and contribution guidelines
by referring to Contributing to Istio.

Thanks for contributing!

Courtesy of your friendly welcome wagon.

[louiscryan]

LGTM