Add buildMetadata option to Kustomization spec

Allow users to configure kustomize buildMetadata per Kustomization
resource. Supported values are 'originAnnotations' and
'transformerAnnotations' which add source origin and transformer
tracking annotations to the built resources respectively.

Signed-off-by: Pierre-Gilles Mialon <pmialon@users.noreply.github.com>
Ref: #1579
Signed-off-by: Pierre-Gilles Mialon <pmialon@gmail.com>

Author: Pierre-Gilles Mialon

api/v1/kustomization_types.go

@@ -177,6 +177,13 @@ type KustomizationSpec struct {
 	// +optional
 	Wait bool `json:"wait,omitempty"`
 
+	// BuildMetadata specifies which kustomize build metadata should be added
+	// to the built resources. The allowed values are 'originAnnotations' to
+	// annotate resources with their source origin, and 'transformerAnnotations'
+	// to annotate resources with the transformers that produced them.
+	// +optional
+	BuildMetadata []BuildMetadataOption `json:"buildMetadata,omitempty"`
+
 	// Components specifies relative paths to kustomize Components.
 	// +optional
 	Components []string `json:"components,omitempty"`
@@ -194,6 +201,19 @@ type KustomizationSpec struct {
 	HealthCheckExprs []kustomize.CustomHealthCheck `json:"healthCheckExprs,omitempty"`
 }
 
+// BuildMetadataOption defines the supported buildMetadata options.
+// +kubebuilder:validation:Enum=originAnnotations;transformerAnnotations
+type BuildMetadataOption string
+
+const (
+	// BuildMetadataOriginAnnotations enables config.kubernetes.io/origin annotations
+	// that track which file and path each resource was loaded from.
+	BuildMetadataOriginAnnotations BuildMetadataOption = "originAnnotations"
+	// BuildMetadataTransformerAnnotations enables internal.config.kubernetes.io annotations
+	// that record which kustomize transformers modified each resource.
+	BuildMetadataTransformerAnnotations BuildMetadataOption = "transformerAnnotations"
+)
+
 // CommonMetadata defines the common labels and annotations.
 type CommonMetadata struct {
 	// Annotations to be added to the object's metadata.

api/v1/zz_generated.deepcopy.go

@@ -53,6 +53,20 @@ spec:
               KustomizationSpec defines the configuration to calculate the desired state
               from a Source using Kustomize.
             properties:
+              buildMetadata:
+                description: |-
+                  BuildMetadata specifies which kustomize build metadata should be added
+                  to the built resources. The allowed values are 'originAnnotations' to
+                  annotate resources with their source origin, and 'transformerAnnotations'
+                  to annotate resources with the transformers that produced them.
+                items:
+                  description: BuildMetadataOption defines the supported buildMetadata
+                    options.
+                  enum:
+                  - originAnnotations
+                  - transformerAnnotations
+                  type: string
+                type: array
               commonMetadata:
                 description: |-
                   CommonMetadata specifies the common labels and annotations that are

config/crd/bases/kustomize.toolkit.fluxcd.io_kustomizations.yaml

@@ -385,6 +385,23 @@ resources. When enabled, the HealthChecks are ignored. Defaults to false.</p>
 </tr>
 <tr>
 <td>
+<code>buildMetadata</code><br>
+<em>
+<a href="#kustomize.toolkit.fluxcd.io/v1.BuildMetadataOption">
+[]BuildMetadataOption
+</a>
+</em>
+</td>
+<td>
+<em>(Optional)</em>
+<p>BuildMetadata specifies which kustomize build metadata should be added
+to the built resources. The allowed values are &lsquo;originAnnotations&rsquo; to
+annotate resources with their source origin, and &lsquo;transformerAnnotations&rsquo;
+to annotate resources with the transformers that produced them.</p>
+</td>
+</tr>
+<tr>
+<td>
 <code>components</code><br>
 <em>
 []string
@@ -444,6 +461,13 @@ KustomizationStatus
 </table>
 </div>
 </div>
+<h3 id="kustomize.toolkit.fluxcd.io/v1.BuildMetadataOption">BuildMetadataOption
+(<code>string</code> alias)</h3>
+<p>
+(<em>Appears on:</em>
+<a href="#kustomize.toolkit.fluxcd.io/v1.KustomizationSpec">KustomizationSpec</a>)
+</p>
+<p>BuildMetadataOption defines the supported buildMetadata options.</p>
 <h3 id="kustomize.toolkit.fluxcd.io/v1.CommonMetadata">CommonMetadata
 </h3>
 <p>
@@ -1018,6 +1042,23 @@ resources. When enabled, the HealthChecks are ignored. Defaults to false.</p>
 </tr>
 <tr>
 <td>
+<code>buildMetadata</code><br>
+<em>
+<a href="#kustomize.toolkit.fluxcd.io/v1.BuildMetadataOption">
+[]BuildMetadataOption
+</a>
+</em>
+</td>
+<td>
+<em>(Optional)</em>
+<p>BuildMetadata specifies which kustomize build metadata should be added
+to the built resources. The allowed values are &lsquo;originAnnotations&rsquo; to
+annotate resources with their source origin, and &lsquo;transformerAnnotations&rsquo;
+to annotate resources with the transformers that produced them.</p>
+</td>
+</tr>
+<tr>
+<td>
 <code>components</code><br>
 <em>
 []string

docs/api/v1/kustomize.md

@@ -649,6 +649,41 @@ spec:
     digest: sha256:24a0c4b4a4c0eb97a1aabb8e29f18e917d05abfe1b7a7c07857230879ce7d3d3
 ```
 
+### Build metadata
+
+`.spec.buildMetadata` is an optional list used to specify which
+[Kustomize `buildMetadata`](https://kubectl.docs.kubernetes.io/references/kustomize/kustomization/buildmetadata/)
+options should be added to the built resources. The allowed values are:
+
+- `originAnnotations`: Adds `config.kubernetes.io/origin` annotations that
+  track which file and path each resource was loaded from.
+- `transformerAnnotations`: Adds `internal.config.kubernetes.io` annotations
+  that record which kustomize transformers modified each resource.
+
+```yaml
+apiVersion: kustomize.toolkit.fluxcd.io/v1
+kind: Kustomization
+metadata:
+  name: podinfo
+  namespace: flux-system
+spec:
+  # ...omitted for brevity
+  buildMetadata:
+  - originAnnotations
+```
+
+When `originAnnotations` is enabled, each resource gets an annotation like:
+
+```yaml
+metadata:
+  annotations:
+    config.kubernetes.io/origin: |
+      path: apps/deployment.yaml
+```
+
+This is useful for debugging, auditing, and tooling that needs to trace
+resources back to their source files.
+
 ### Components
 
 `.spec.components` is an optional list used to specify

docs/spec/v1/kustomizations.md

@@ -604,3 +604,104 @@ func checkSecret(list *corev1.SecretList, name string) bool {
 
 	return false
 }
+
+func TestKustomizationReconciler_BuildMetadata(t *testing.T) {
+	g := NewWithT(t)
+	id := "bm-" + randStringRunes(5)
+	revision := "v1.0.0"
+	resultK := &kustomizev1.Kustomization{}
+
+	err := createNamespace(id)
+	g.Expect(err).NotTo(HaveOccurred(), "failed to create test namespace")
+
+	err = createKubeConfigSecret(id)
+	g.Expect(err).NotTo(HaveOccurred(), "failed to create kubeconfig secret")
+
+	manifests := func(name string) []testserver.File {
+		return []testserver.File{
+			{
+				Name: "config.yaml",
+				Body: fmt.Sprintf(`---
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: %[1]s
+data:
+  key: val
+`, name),
+			},
+		}
+	}
+
+	artifact, err := testServer.ArtifactFromFiles(manifests(id))
+	g.Expect(err).NotTo(HaveOccurred())
+
+	repositoryName := types.NamespacedName{
+		Name:      fmt.Sprintf("bm-%s", randStringRunes(5)),
+		Namespace: id,
+	}
+
+	err = applyGitRepository(repositoryName, artifact, revision)
+	g.Expect(err).NotTo(HaveOccurred())
+
+	kustomizationKey := types.NamespacedName{
+		Name:      fmt.Sprintf("bm-%s", randStringRunes(5)),
+		Namespace: id,
+	}
+	kustomization := &kustomizev1.Kustomization{
+		ObjectMeta: metav1.ObjectMeta{
+			Name:      kustomizationKey.Name,
+			Namespace: kustomizationKey.Namespace,
+		},
+		Spec: kustomizev1.KustomizationSpec{
+			Interval: metav1.Duration{Duration: 2 * time.Minute},
+			Path:     "./",
+			KubeConfig: &meta.KubeConfigReference{
+				SecretRef: &meta.SecretKeyReference{
+					Name: "kubeconfig",
+				},
+			},
+			SourceRef: kustomizev1.CrossNamespaceSourceReference{
+				Name:      repositoryName.Name,
+				Namespace: repositoryName.Namespace,
+				Kind:      sourcev1.GitRepositoryKind,
+			},
+			Prune: true,
+			BuildMetadata: []kustomizev1.BuildMetadataOption{
+				kustomizev1.BuildMetadataOriginAnnotations,
+			},
+			TargetNamespace: id,
+		},
+	}
+
+	g.Expect(k8sClient.Create(context.Background(), kustomization)).To(Succeed())
+
+	t.Run("sets origin annotations", func(t *testing.T) {
+		g := NewWithT(t)
+		g.Eventually(func() bool {
+			_ = k8sClient.Get(context.Background(), client.ObjectKeyFromObject(kustomization), resultK)
+			return isReconcileSuccess(resultK)
+		}, timeout, time.Second).Should(BeTrue())
+		kstatusCheck.CheckErr(ctx, resultK)
+
+		var cm corev1.ConfigMap
+		g.Expect(k8sClient.Get(context.Background(), client.ObjectKey{Name: id, Namespace: id}, &cm)).To(Succeed())
+		g.Expect(cm.GetAnnotations()).To(HaveKey("config.kubernetes.io/origin"))
+	})
+
+	t.Run("removes origin annotations", func(t *testing.T) {
+		g := NewWithT(t)
+		resultK.Spec.BuildMetadata = nil
+		g.Expect(k8sClient.Update(context.Background(), resultK)).To(Succeed())
+
+		g.Eventually(func() bool {
+			_ = k8sClient.Get(context.Background(), client.ObjectKeyFromObject(kustomization), resultK)
+			return isReconcileSuccess(resultK)
+		}, timeout, time.Second).Should(BeTrue())
+		kstatusCheck.CheckErr(ctx, resultK)
+
+		var cm corev1.ConfigMap
+		g.Expect(k8sClient.Get(context.Background(), client.ObjectKey{Name: id, Namespace: id}, &cm)).To(Succeed())
+		g.Expect(cm.GetAnnotations()).ToNot(HaveKey("config.kubernetes.io/origin"))
+	})
+}