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 shift a configurable percentage of its traffic 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	Percentage (0-100) of the service's traffic shifted to the canary. Defaults to 0; invalid values keep the service on the primary.

All three apply to Service, ServiceEntry, and Namespace, the same service-level scope, and deliberately not Pod/WorkloadEntry. The weight is a service-level traffic split keyed off the destination service, so a per-workload
target has no meaning here. This is why the scope is narrower than istio.io/use-waypoint, which legitimately covers workloads too.

Example:

metadata:
  labels:
    istio.io/use-waypoint: waypoint-a            # primary (existing, unchanged)
    istio.io/use-waypoint-canary: waypoint-b     # canary waypoint (Gateway name)
    # optional, only for cross-namespace canaries:
    # istio.io/use-waypoint-canary-namespace: waypoint-b-ns
  annotations:
    istio.io/use-waypoint-canary-weight: "5"     # 0..100, percent routed to the canary

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 traffic percentage 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.