split source and destination config for RR's, everything else is just confusing

This is because now, with support for label selectors, we need explicit naming on the destination
side, which means the old idea of "the same thing is done on both sides to figure out the names on
origin and destination" doesn't apply anymore, because the logic is now slightly different between
both sides. To not ack this in the CRD will just create endless confusion.

On-behalf-of: @SAP [email protected]

Author: xrstf

deploy/crd/kcp.io/syncagent.kcp.io_publishedresources.yaml

@@ -171,30 +171,98 @@ type RelatedResourceSpec struct {
 	// ConfigMap or Secret
 	Kind string `json:"kind"`
 
-	Reference RelatedResourceReference `json:"reference"`
+	// Source describes how the related resource can be found on the side where it originates.
+	Source RelatedResourceSource `json:"source"`
+
+	// Destination describes where to place the copy of the object on the destination side.
+	Destination RelatedResourceDestination `json:"destination"`
 
 	// Mutation configures optional transformation rules for the related resource.
 	// Status mutations are only performed when the related resource originates in kcp.
 	Mutation *ResourceMutationSpec `json:"mutation,omitempty"`
 }
 
-type RelatedResourceReference struct {
-	Name      ResourceLocator  `json:"name"`
-	Namespace *ResourceLocator `json:"namespace,omitempty"`
+// RelatedResourceSource configures how a related object can be found on its origin side.
+type RelatedResourceSource struct {
+	RelatedResourceSourceSpec `json:",inline"`
+
+	// Namespace configures in what namespace the related object resides in. If
+	// not specified, the same namespace as the main object is assumed. If the
+	// main object is cluster-scoped, an error will be raised during syncing.
+	Namespace *RelatedResourceSourceSpec `json:"namespace,omitempty"`
+}
+
+// RelatedResourceSourceSpec configures different ways an object can be located.
+// All fields are mutually exclusive.
+type RelatedResourceSourceSpec struct {
+	// Selector is a label selector that is useful if no reference is in the
+	// main resource (i.e. if the related object links back to its parent, instead
+	// of the parent pointing to the related object).
+	Selector *RelatedResourceSelector `json:"selector,omitempty"`
+	// Reference points to a field inside the main object. This reference is
+	// evaluated on both source and destination sides to find the related object.
+	Reference *RelatedResourceReference `json:"reference,omitempty"`
+	// Expression is a Go templated string that can make use of variables to
+	// construct the resulting string.
+	Expression string `json:"expression,omitempty"`
+}
+
+// RelatedResourceDestination configures where the copy of the related object on the
+// destination side should be created.
+type RelatedResourceDestination struct {
+	RelatedResourceDestinationSpec `json:",inline"`
+
+	// Namespace configures in what namespace the related object should be created
+	// in. If not specified, the same namespace as the main object is assumed.
+	// If the main object is cluster-scoped, an error will be raised during
+	// syncing.
+	Namespace *RelatedResourceDestinationSpec `json:"namespace,omitempty"`
 }
 
-type ResourceLocator struct {
-	Path  string                `json:"path"`
-	Regex *RegexResourceLocator `json:"regex,omitempty"`
+// RelatedResourceDestinationSpec configures different ways an object can be located.
+// All fields are mutually exclusive.
+type RelatedResourceDestinationSpec struct {
+	// Reference points to a field inside the main object. This reference is
+	// evaluated on both source and destination sides to find the related object.
+	Reference *RelatedResourceReference `json:"reference,omitempty"`
+	// Expression is a Go templated string that can make use of variables to
+	// construct the resulting string.
+	Expression string `json:"expression,omitempty"`
 }
 
-type RegexResourceLocator struct {
+// RelatedResourceReference describes a path expression that is evaluated inside
+// a JSON-marshalled Kubernetes object, yielding a string when evaluated.
+type RelatedResourceReference struct {
+	// Path is a simplified JSONPath expression like "metadata.name". A reference
+	// must always select at least _something_ in the object, even if the value
+	// is discarded by the regular expression.
+	Path string `json:"path"`
+	// Regex is a Go regular expression that is optionally applied to the selected
+	// value from the path.
+	Regex *RegularExpression `json:"regex,omitempty"`
+}
+
+// RegularExpression models a Go regular expression string replacement. See
+// https://pkg.go.dev/regexp/syntax for more information on the syntax.
+type RegularExpression struct {
 	// Pattern can be left empty to simply replace the entire value with the
 	// replacement.
-	Pattern     string `json:"pattern,omitempty"`
+	Pattern string `json:"pattern,omitempty"`
+	// Replacement is the string that the matched pattern is replaced with. It
+	// can contain references to groups in the pattern by using \N.
 	Replacement string `json:"replacement,omitempty"`
 }
 
+// RelatedResourceSelector is a dedicated struct in case we need additional options
+// for evaluating the label selector.
+
+// RelatedResourceSelector describes how to locate a related object based on
+// labels. This is useful if the main resource has no and cannot construct a
+// reference to the related object because its name/namespace might be randomized.
+type RelatedResourceSelector struct {
+	metav1.LabelSelector `json:",inline"`
+}
+
 // SourceResourceDescriptor and ResourceProjection are very similar, but as we do not
 // want to burden service clusters with validation webhooks, it's easier to split them
 // into 2 structs here and rely on the schema for validation.