Add resource annotations for storing manager properties (#99683)

What is this feature?

This change adds properties and known annotations to store them in for recording resource manager information, such as:

The type (kind) of the manager (ex. Terraform / kubectl / etc.)
The identity of the manager (ex. grafana/terraform-provider-grafana)
Whether the managers allows the resource to be edited by others.
Whether a resource is temporarily excluded from the manager's control.
These annotations are inspired by Kubernetes field management API (https://kubernetes.io/docs/reference/using-api/server-side-apply/#field-management) and known Kubernetes annotations
(https://kubernetes.io/docs/reference/labels-annotations-taints/#app-kubernetes-io-managed-by).

It also adds annotations for storing information about the source of a provisioned resource, such as path, checksum & timestamp.

Why do we need this feature?

To make it possible to mark resources as managed by specific managers, modifying how these resources appear in the UI and are treated in the backend APIs.

For example, we'd like to make managed resources read-only, or show specific docs / workflows based on the tool which is used to manage resources and so on.

The identity is required for ensuring that managers of the same kind can still be told apart.

Who is this feature for?

For as-code practitioners and API users.

---------

Signed-off-by: Igor Suleymanov <igor.suleymanov@grafana.com>
Co-authored-by: Ryan McKinley <ryantxu@gmail.com>

pkg/apimachinery/utils/meta.go

@@ -46,6 +46,19 @@ const AnnoKeyRepoPath = "grafana.app/repoPath"
 const AnnoKeyRepoHash = "grafana.app/repoHash"
 const AnnoKeyRepoTimestamp = "grafana.app/repoTimestamp"
 
+// Annotations used to store manager properties
+
+const AnnoKeyManagerKind = "grafana.app/managedBy"
+const AnnoKeyManagerIdentity = "grafana.app/managerId"
+const AnnoKeyManagerAllowsEdits = "grafana.app/managerAllowsEdits"
+const AnnoKeyManagerSuspended = "grafana.app/managerSuspended"
+
+// Annotations used to store source properties
+
+const AnnoKeySourcePath = "grafana.app/sourcePath"
+const AnnoKeySourceHash = "grafana.app/sourceHash"
+const AnnoKeySourceTimestamp = "grafana.app/sourceTimestamp"
+
 // LabelKeyDeprecatedInternalID gives the deprecated internal ID of a resource
 // Deprecated: will be removed in grafana 13
 const LabelKeyDeprecatedInternalID = "grafana.app/deprecatedInternalID"
@@ -138,6 +151,22 @@ type GrafanaMetaAccessor interface {
 	//  * title
 	// and return an empty string if nothing was found
 	FindTitle(defaultTitle string) string
+
+	// GetManagerProperties returns the identity of the tool,
+	// which is responsible for managing the resource.
+	//
+	// If the identity is not known, the second return value will be false.
+	GetManagerProperties() (ManagerProperties, bool)
+
+	// SetManagerProperties sets the identity of the tool,
+	// which is responsible for managing the resource.
+	SetManagerProperties(ManagerProperties)
+
+	// GetSourceProperties returns the source properties of the resource.
+	GetSourceProperties() (SourceProperties, bool)
+
+	// SetSourceProperties sets the source properties of the resource.
+	SetSourceProperties(SourceProperties)
 }
 
 var _ GrafanaMetaAccessor = (*grafanaMetaAccessor)(nil)
@@ -718,6 +747,107 @@ func (m *grafanaMetaAccessor) FindTitle(defaultTitle string) string {
 	return defaultTitle
 }
 
+func (m *grafanaMetaAccessor) GetManagerProperties() (ManagerProperties, bool) {
+	res := ManagerProperties{
+		Identity:    "",
+		Kind:        ManagerKindUnknown,
+		AllowsEdits: true,
+		Suspended:   false,
+	}
+
+	annot := m.obj.GetAnnotations()
+
+	id, ok := annot[AnnoKeyManagerIdentity]
+	if !ok || id == "" {
+		// If the identity is not set, we should ignore the other annotations and return the default values.
+		//
+		// This is to prevent inadvertently marking resources as managed,
+		// since that can potentially block updates from other sources.
+		return res, false
+	}
+	res.Identity = id
+
+	if v, ok := annot[AnnoKeyManagerKind]; ok {
+		res.Kind = ParseManagerKindString(v)
+	}
+
+	if v, ok := annot[AnnoKeyManagerAllowsEdits]; ok {
+		res.AllowsEdits = v == "true"
+	}
+
+	if v, ok := annot[AnnoKeyManagerSuspended]; ok {
+		res.Suspended = v == "true"
+	}
+
+	return res, true
+}
+
+func (m *grafanaMetaAccessor) SetManagerProperties(v ManagerProperties) {
+	annot := m.obj.GetAnnotations()
+	if annot == nil {
+		annot = make(map[string]string, 4)
+	}
+
+	annot[AnnoKeyManagerIdentity] = v.Identity
+	annot[AnnoKeyManagerKind] = string(v.Kind)
+	annot[AnnoKeyManagerAllowsEdits] = strconv.FormatBool(v.AllowsEdits)
+	annot[AnnoKeyManagerSuspended] = strconv.FormatBool(v.Suspended)
+
+	m.obj.SetAnnotations(annot)
+}
+
+func (m *grafanaMetaAccessor) GetSourceProperties() (SourceProperties, bool) {
+	var (
+		res   SourceProperties
+		found bool
+	)
+
+	annot := m.obj.GetAnnotations()
+	if annot == nil {
+		return res, false
+	}
+
+	if path, ok := annot[AnnoKeySourcePath]; ok && path != "" {
+		res.Path = path
+		found = true
+	}
+
+	if hash, ok := annot[AnnoKeySourceHash]; ok && hash != "" {
+		res.Checksum = hash
+		found = true
+	}
+
+	if timestamp, ok := annot[AnnoKeySourceTimestamp]; ok && timestamp != "" {
+		if t, err := time.Parse(time.RFC3339, timestamp); err == nil {
+			res.Timestamp = t
+			found = true
+		}
+	}
+
+	return res, found
+}
+
+func (m *grafanaMetaAccessor) SetSourceProperties(v SourceProperties) {
+	annot := m.obj.GetAnnotations()
+	if annot == nil {
+		annot = make(map[string]string, 3)
+	}
+
+	if v.Path != "" {
+		annot[AnnoKeySourcePath] = v.Path
+	}
+
+	if v.Checksum != "" {
+		annot[AnnoKeySourceHash] = v.Checksum
+	}
+
+	if !v.Timestamp.IsZero() {
+		annot[AnnoKeySourceTimestamp] = v.Timestamp.Format(time.RFC3339)
+	}
+
+	m.obj.SetAnnotations(annot)
+}
+
 type BlobInfo struct {
 	UID      string `json:"uid"`
 	Size     int64  `json:"size,omitempty"`