Implement origin revision tracking

Signed-off-by: Stefan Prodan <[email protected]>

Author: stefanprodan

api/v1beta1/artifactgenerator_types.go

@@ -26,16 +26,17 @@ import (
 )
 
 const (
-	ArtifactGeneratorKind        = "ArtifactGenerator"
-	Finalizer                    = "source.extensions.fluxcd.io/finalizer"
-	ArtifactGeneratorLabel       = "source.extensions.fluxcd.io/generator"
-	ReconcileAnnotation          = "source.extensions.fluxcd.io/reconcile"
-	ReconciliationDisabledReason = "ReconciliationDisabled"
-	AccessDeniedReason           = "AccessDenied"
-	ValidationFailedReason       = "ValidationFailed"
-	SourceFetchFailedReason      = "SourceFetchFailed"
-	EnabledValue                 = "enabled"
-	DisabledValue                = "disabled"
+	ArtifactGeneratorKind            = "ArtifactGenerator"
+	Finalizer                        = "source.extensions.fluxcd.io/finalizer"
+	ArtifactGeneratorLabel           = "source.extensions.fluxcd.io/generator"
+	ArtifactOriginRevisionAnnotation = "org.opencontainers.image.revision"
+	ReconcileAnnotation              = "source.extensions.fluxcd.io/reconcile"
+	ReconciliationDisabledReason     = "ReconciliationDisabled"
+	AccessDeniedReason               = "AccessDenied"
+	ValidationFailedReason           = "ValidationFailed"
+	SourceFetchFailedReason          = "SourceFetchFailed"
+	EnabledValue                     = "enabled"
+	DisabledValue                    = "disabled"
 )
 
 // ArtifactGeneratorSpec defines the desired state of ArtifactGenerator.
@@ -102,6 +103,17 @@ type OutputArtifact struct {
 	// +optional
 	Revision string `json:"revision,omitempty"`
 
+	// OriginRevision is used to set the 'org.opencontainers.image.revision'
+	// annotation on the generated artifact metadata.
+	// If specified, it must point to an existing source alias in the format "@<alias>".
+	// If the referenced source has an origin revision (e.g. a Git commit SHA),
+	// it will be used to set the annotation on the generated artifact.
+	// If the referenced source does not have an origin revision, the field is ignored.
+	// +kubebuilder:validation:Pattern="^@([a-z0-9]([a-z0-9_-]*[a-z0-9])?)$"
+	// +kubebuilder:validation:MaxLength=64
+	// +optional
+	OriginRevision string `json:"originRevision,omitempty"`
+
 	// Copy defines a list of copy operations to perform from the sources to the generated artifact.
 	// The copy operations are performed in the order they are listed with existing files
 	// being overwritten by later copy operations.

api/v1beta1/observed_source.go

@@ -28,12 +28,21 @@ import (
 // an artifact in the ArtifactGeneratorStatus.ObservedSourcesDigest field.
 type ObservedSource struct {
 	// Digest is the artifact digest of the upstream source.
+	// +required
 	Digest string `json:"digest"`
 
 	// Revision is the artifact revision of the upstream source.
+	// +required
 	Revision string `json:"revision"`
 
+	// OriginRevision holds the origin revision of the upstream source,
+	// extracted from the 'org.opencontainers.image.revision' annotation,
+	// if available in the source artifact metadata.
+	// +optional
+	OriginRevision string `json:"originRevision,omitempty"`
+
 	// URL is the artifact URL of the upstream source.
+	// +required
 	URL string `json:"url"`
 }
 

config/crd/bases/source.extensions.fluxcd.io_artifactgenerators.yaml

@@ -79,6 +79,17 @@ spec:
                       maxLength: 253
                       pattern: ^[a-z0-9]([a-z0-9-]*[a-z0-9])?$
                       type: string
+                    originRevision:
+                      description: |-
+                        OriginRevision is used to set the 'org.opencontainers.image.revision'
+                        annotation on the generated artifact metadata.
+                        If specified, it must point to an existing source alias in the format "@<alias>".
+                        If the referenced source has an origin revision (e.g. a Git commit SHA),
+                        it will be used to set the annotation on the generated artifact.
+                        If the referenced source does not have an origin revision, the field is ignored.
+                      maxLength: 64
+                      pattern: ^@([a-z0-9]([a-z0-9_-]*[a-z0-9])?)$
+                      type: string
                     revision:
                       description: |-
                         Revision is the revision of the generated artifact.

docs/spec/v1beta1/artifactgenerators.md

@@ -90,7 +90,7 @@ spec:
       namespace: apps
   artifacts:
     - name: podinfo-composite
-      revision: "@chart"
+      originRevision: "@chart"
       copy:
         - from: "@chart/"
           to: "@artifact/"
@@ -229,26 +229,20 @@ regenerate the affected artifacts automatically.
 The `.spec.artifacts` field defines the list of ExternalArtifacts to be generated from the sources.
 Each artifact must specify:
 
-- `name`: The name of the generated ExternalArtifact resource. It must be unique in the context
+- `name` (required): The name of the generated ExternalArtifact resource. It must be unique in the context
   of the ArtifactGenerator and must conform to Kubernetes resource naming conventions.
+- `copy` (required): A list of copy operations to perform from sources to the artifact.
 - `revision` (optional): A specific source revision to use in the format `@alias`.
   If not specified, the revision is automatically computed as `latest@<digest>` based on the artifact content.
-- `copy`: A list of copy operations to perform from sources to the artifact.
-
-#### Copy Operations
-
-Each copy operation specifies how to copy files from sources into the generated artifact:
-
-- `from`: Source path in the format `@alias/pattern` where `alias` references 
-  a source and `pattern` is a glob pattern or a specific file/directory path within that source.
-- `to`: Destination path in the format `@artifact/path` where `artifact` is
-  the root of the generated artifact and `path` is the relative path to a file or directory.
+- `originRevision` (optional): A specific source origin revision to include in the artifact metadata
+  in the format `@alias`. This is useful for sources of type `OCIRepository` to track the origin Git commit.
 
 ```yaml
 spec:
   artifacts:
     - name: my-app
-      revision: "@backend"  # Use backend source revision
+      revision: "@backend"
+      originRevision: "@frontend"
       copy:
         - from: "@backend/deploy/*.yaml"
           to: "@artifact/backend/"
@@ -258,6 +252,15 @@ spec:
           to: "@artifact/env.yaml"
 ```
 
+#### Copy Operations
+
+Each copy operation specifies how to copy files from sources into the generated artifact:
+
+- `from`: Source path in the format `@alias/pattern` where `alias` references 
+  a source and `pattern` is a glob pattern or a specific file/directory path within that source.
+- `to`: Destination path in the format `@artifact/path` where `artifact` is
+  the root of the generated artifact and `path` is the relative path to a file or directory.
+
 Copy operations use `cp`-like semantics:
 
 - Operations are executed in order; later operations can overwrite files from earlier ones

internal/controller/artifactgenerator_controller.go

@@ -206,12 +206,8 @@ func (r *ArtifactGeneratorReconciler) reconcile(ctx context.Context,
 			return ctrl.Result{}, err
 		}
 
-		// Override the revision with the one from the source if specified.
-		if oa.Revision != "" {
-			if rs, ok := remoteSources[strings.TrimPrefix(oa.Revision, "@")]; ok {
-				artifact.Revision = rs.Revision
-			}
-		}
+		// Set the revision and origin revision metadata on the artifact.
+		r.setArtifactRevisions(artifact, oa, remoteSources)
 
 		// Reconcile the ExternalArtifact corresponding to the built artifact.
 		// The ExternalArtifact will reference the artifact stored in the storage backend.
@@ -314,15 +310,23 @@ func (r *ArtifactGeneratorReconciler) observeSources(ctx context.Context,
 				src.Name, src.Kind)
 		}
 
-		if source.GetArtifact() == nil {
+		artifact := source.GetArtifact()
+		if artifact == nil {
 			return nil, fmt.Errorf("source '%s/%s' is not ready", src.Kind, namespacedName)
 		}
 
-		observedSources[src.Alias] = swapi.ObservedSource{
-			Digest:   source.GetArtifact().Digest,
-			Revision: source.GetArtifact().Revision,
-			URL:      source.GetArtifact().URL,
+		observedSource := swapi.ObservedSource{
+			Digest:   artifact.Digest,
+			Revision: artifact.Revision,
+			URL:      artifact.URL,
+		}
+
+		// Capture the origin revision if present in the artifact metadata.
+		if originRev, ok := artifact.Metadata[swapi.ArtifactOriginRevisionAnnotation]; ok {
+			observedSource.OriginRevision = originRev
 		}
+
+		observedSources[src.Alias] = observedSource
 	}
 
 	return observedSources, nil
@@ -428,12 +432,15 @@ func (r *ArtifactGeneratorReconciler) reconcileExternalArtifact(ctx context.Cont
 		return nil, fmt.Errorf("failed to patch ExternalArtifact status: %w", err)
 	}
 
+	// Log if the artifact is up to date or emit an event if it is new or has changed.
 	if obj.HasArtifactInInventory(ea.Name, ea.Namespace, artifact.Digest) {
 		log.Info(fmt.Sprintf("%s/%s/%s is up to date",
 			ea.Kind, ea.Namespace, ea.Name))
 	} else {
-		log.Info(fmt.Sprintf("%s/%s/%s reconciled with revision %s",
-			ea.Kind, ea.Namespace, ea.Name, artifact.Revision))
+		msg := fmt.Sprintf("%s/%s/%s reconciled with revision %s",
+			ea.Kind, ea.Namespace, ea.Name, artifact.Revision)
+		log.Info(msg)
+		r.Event(obj, corev1.EventTypeNormal, meta.ReadyCondition, msg)
 	}
 
 	return &swapi.ExternalArtifactReference{
@@ -467,3 +474,30 @@ func (r *ArtifactGeneratorReconciler) findOrphanedReferences(
 
 	return orphaned
 }
+
+// setArtifactRevisions sets the revision and origin revision metadata on the artifact
+// based on the output artifact configuration and available remote sources.
+func (r *ArtifactGeneratorReconciler) setArtifactRevisions(artifact *meta.Artifact,
+	oa swapi.OutputArtifact,
+	remoteSources map[string]swapi.ObservedSource) {
+	// Override the revision with the one from the source if specified.
+	if oa.Revision != "" {
+		if rs, ok := remoteSources[strings.TrimPrefix(oa.Revision, "@")]; ok {
+			artifact.Revision = rs.Revision
+		}
+	}
+
+	// Set the origin revision in the artifact metadata if available from the source.
+	if oa.OriginRevision != "" {
+		if artifact.Metadata == nil {
+			artifact.Metadata = make(map[string]string)
+		}
+		if rs, ok := remoteSources[strings.TrimPrefix(oa.OriginRevision, "@")]; ok {
+			if rs.OriginRevision != "" {
+				artifact.Metadata[swapi.ArtifactOriginRevisionAnnotation] = rs.OriginRevision
+			} else {
+				artifact.Metadata[swapi.ArtifactOriginRevisionAnnotation] = rs.Revision
+			}
+		}
+	}
+}

internal/controller/artifactgenerator_controller_test.go

@@ -143,6 +143,11 @@ func TestArtifactGeneratorReconciler_Reconcile(t *testing.T) {
 
 		if inv.Name == fmt.Sprintf("%s-oci", obj.Name) {
 			ociArtifactDigest = externalArtifact.Status.Artifact.Digest
+
+			// Verify that the ExternalArtifact inherited the origin revision of the OCIRepository
+			originRev, ok := externalArtifact.Status.Artifact.Metadata[swapi.ArtifactOriginRevisionAnnotation]
+			g.Expect(ok).To(BeTrue(), "expected origin revision in metadata")
+			g.Expect(originRev).To(Equal("main@sha1:xyz123"))
 		}
 	}
 
@@ -245,9 +250,10 @@ func TestArtifactGeneratorReconciler_Reconcile(t *testing.T) {
 	// Verify events were recorded
 	events := getEvents(obj.Name, obj.Namespace)
 	g.Expect(events).ToNot(BeEmpty())
-	g.Expect(events[0].Type).To(Equal(corev1.EventTypeNormal))
-	g.Expect(events[0].Reason).To(Equal(meta.ReadyCondition))
-	g.Expect(events[0].Message).To(ContainSubstring("reconciliation succeeded"))
+	for _, e := range events {
+		g.Expect(e.Type).To(Equal(corev1.EventTypeNormal))
+		g.Expect(e.Reason).To(Equal(meta.ReadyCondition))
+	}
 
 	// Delete the object to trigger finalization
 	err = testClient.Delete(ctx, obj)
@@ -571,7 +577,8 @@ func getArtifactGenerator(objectKey client.ObjectKey) *swapi.ArtifactGenerator {
 					},
 				},
 				{
-					Name: fmt.Sprintf("%s-oci", objectKey.Name),
+					Name:           fmt.Sprintf("%s-oci", objectKey.Name),
+					OriginRevision: fmt.Sprintf("@%s-oci", objectKey.Name),
 					Copy: []swapi.CopyOperation{
 						{
 							From: fmt.Sprintf("@%s-oci/**", objectKey.Name),
@@ -689,6 +696,9 @@ func applyOCIRepository(objKey client.ObjectKey, revision string, files []testse
 			Revision:       revision,
 			Digest:         dig.String(),
 			LastUpdateTime: metav1.Now(),
+			Metadata: map[string]string{
+				swapi.ArtifactOriginRevisionAnnotation: "main@sha1:xyz123",
+			},
 		},
 	}