restructure how the source of related resources is configured

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

Author: xrstf

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

@@ -171,30 +171,79 @@ type RelatedResourceSpec struct {
 	// ConfigMap or Secret
 	Kind string `json:"kind"`
 
-	Reference RelatedResourceReference `json:"reference"`
+	// Source describes how the related resource can be found. The source expression is evaluated
+	// on both source and destination side of the sync.
+	Source RelatedResourceSource `json:"source"`
+
+	// Naming is used when a label selector is used in the source expression. Since the labels do
+	// not dictate how the actual object shall be named on the destination side, and the agent also
+	// does not simply want to re-use the source side's name/namespace (these could contain private
+	// information and leak details about how the service is structured), explicit naming rules need
+	// to be provided. These naming rules are used to form the destination name/namespace for the
+	// related object.
+	// When reference-based sources are used, this field is optional as the destination name/namespace
+	// are read from the main object.
+	Naming *ResourceNaming `json:"naming"`
 
 	// 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.
+type RelatedResourceSource struct {
+	// Name configures how the related object's name can be constructed or
+	// found. This must always be configured for a related resource.
+	Name RelatedResourceSourceSpec `json:"name"`
+	// 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 how the related object itself or its
+// namespace can be found. Selector and Reference are mutally 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"`
 }
 
-type ResourceLocator struct {
-	Path  string                `json:"path"`
-	Regex *RegexResourceLocator `json:"regex,omitempty"`
+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"`
 }
 
-type RegexResourceLocator struct {
+// 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.