Split TargetRef definitions by usage context

[lobkovilya]

Description

There are 2 distinct contexts for TargetRef usage:

1. Top-level spec.targetRef

   Available kinds are Mesh and Dataplane. This targetRef is used to select a group of proxies that'll be affected by the policy.

2. Outbound selection spec.to[].targetRef

   Available kinds are MeshService, MeshExternalService, MeshMultiZoneService, MeshHTTPRoute.
   This targetRef is used to select the destination (outbound) that'll be affected by policy.

Mixing these targetRef produces

• confusing OpenAPI schemas (just see https://kuma.io/docs/2.12.x/policies/meshtimeout/#all-policy-options)
• complex validation code

Without changing the API we can have 2 TargetRef types instead of a single super type.

So instead of

kuma/api/common/v1alpha1/targetref.go

Lines 85 to 113 in 943c73f

	type TargetRef struct {
	// This is needed to not sync policies with empty topLevelTarget ref to old zones that does not support it
	// This can be removed in 2.11.x
	UsesSyntacticSugar bool `json:"-"`
	// Kind of the referenced resource
	// +kubebuilder:validation:Enum=Mesh;MeshSubset;MeshGateway;MeshService;MeshExternalService;MeshMultiZoneService;MeshServiceSubset;MeshHTTPRoute;Dataplane
	Kind TargetRefKind `json:"kind"`
	// Name of the referenced resource. Can only be used with kinds: `MeshService`,
	// `MeshServiceSubset` and `MeshGatewayRoute`
	Name *string `json:"name,omitempty"`
	// Tags used to select a subset of proxies by tags. Can only be used with kinds
	// `MeshSubset` and `MeshServiceSubset`
	Tags *map[string]string `json:"tags,omitempty"`
	// Mesh is reserved for future use to identify cross mesh resources.
	Mesh *string `json:"mesh,omitempty"`
	// ProxyTypes specifies the data plane types that are subject to the policy. When not specified,
	// all data plane types are targeted by the policy.
	ProxyTypes *[]TargetRefProxyType `json:"proxyTypes,omitempty"`
	// Namespace specifies the namespace of target resource. If empty only resources in policy namespace
	// will be targeted.
	Namespace *string `json:"namespace,omitempty"`
	// Labels are used to select group of MeshServices that match labels. Either Labels or
	// Name and Namespace can be used.
	Labels *map[string]string `json:"labels,omitempty"`
	// SectionName is used to target specific section of resource.
	// For example, you can target port from MeshService.ports[] by its name. Only traffic to this port will be affected.
	SectionName *string `json:"sectionName,omitempty"`
	}

we can have

type TopLevelTargetRef struct {
	// Kind of the referenced resource
	// +kubebuilder:validation:Enum=Mesh;Dataplane
	Kind TopLevelTargetRefKind `json:"kind"`
	// Name of the referenced resource. 
	Name *string `json:"name,omitempty"`
	// Namespace specifies the namespace of target resource. If empty only resources in policy namespace
	// will be targeted.
	Namespace *string `json:"namespace,omitempty"`
	// Labels are used to select group of MeshServices that match labels. Either Labels or
	// Name and Namespace can be used.
	Labels *map[string]string `json:"labels,omitempty"`
	// SectionName is used to target specific section of resource.
	// For example, you can target port from MeshService.ports[] by its name. Only traffic to this port will be affected.
	SectionName *string `json:"sectionName,omitempty"`
}

type OutboundTargetRef struct {
	// Kind of the referenced resource
	// +kubebuilder:validation:Enum=MeshService;MeshExternalService;MeshMultiZoneService;MeshHTTPRoute
	Kind OutboundTargetRefKind `json:"kind"`
	// Name of the referenced resource. 
	Name *string `json:"name,omitempty"`
	// Namespace specifies the namespace of target resource. If empty only resources in policy namespace
	// will be targeted.
	Namespace *string `json:"namespace,omitempty"`
	// Labels are used to select group of MeshServices that match labels. Either Labels or
	// Name and Namespace can be used.
	Labels *map[string]string `json:"labels,omitempty"`
	// SectionName is used to target specific section of resource.
	// For example, you can target port from MeshService.ports[] by its name. Only traffic to this port will be affected.
	SectionName *string `json:"sectionName,omitempty"`
}

[lukidzi]

Triage: we need to be careful about backward compatible types e.g.: MeshSubset, Mesh... let's verify