Feature Request: Support buildMetadata configuration for Kustomize builds

[markussiebert]

Feature Request: Support buildMetadata configuration for Kustomize builds

Problem

Currently, to enable Kustomize build metadata (e.g., originAnnotations which adds source file path annotations to resources), users must add buildMetadata: [originAnnotations] to every kustomization.yaml file in their repositories.

This becomes impractical when:

• Managing many repositories/kustomizations
• Users don't control the source repositories
• Wanting to enforce this cluster-wide for observability/debugging

Proposed Solutions

Option 1: Environment Variable (Simplest)

Add an environment variable to the kustomize-controller deployment:

env:
- name: KUSTOMIZE_BUILD_METADATA
  value: "originAnnotations"

Pros: No API changes, easy cluster-wide enablement, backward compatible

Option 2: Kustomization CRD Field (Most Flexible)

Add a buildMetadata field to the Kustomization spec:

apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
  name: apps
spec:
  buildMetadata:
  - originAnnotations

Pros: Per-Kustomization control, explicit, follows Flux patterns

Option 3: Both (Recommended)

Support both with precedence: repo file > CRD field > env var

Use Case

The originAnnotations build metadata adds source file path annotations:

metadata:
  annotations:
    config.kubernetes.io/origin: |
      path: apps/tenant-a/deployment.yaml

Valuable for debugging, auditing, and tooling that needs to track resource origins.

Implementation

Changes required:

1. fluxcd/pkg/kustomize - Update Build() and SecureBuild() to accept buildMetadata []string parameter:

   func Build(fs filesys.FileSystem, dirPath string, buildMetadata []string) (res resmap.ResMap, err error) {
       buildOptions := &krusty.Options{
           LoadRestrictions: kustypes.LoadRestrictionsNone,
           PluginConfig:     kustypes.DisabledPluginConfig(),
           BuildMetadata:    buildMetadata,
       }
       // ...
   }

2. fluxcd/kustomize-controller - Read env var/CRD field and pass to build functions

The krusty.Options struct already supports BuildMetadata, so this is primarily plumbing.

Related

• Kustomize build metadata docs: https://kubectl.docs.kubernetes.io/references/kustomize/kustomization/buildmetadata/

[stefanprodan]

See #1008

[markussiebert]

This issue is not related to #1008. That issue was about the managedByLabel buildMetadata option which has a bug in Kustomize itself.

This issue is about the originAnnotations buildMetadata option, which works correctly but currently requires manual addition to every kustomization.yaml file. We're requesting a way to configure it globally (via env var or CRD field) rather than having to modify every repository.

Our use case: We're building a developer portal and it would be helpful to link Kubernetes resources back to their source files in Git repositories. The config.kubernetes.io/origin annotation from originAnnotations would enable this without requiring users to manually add buildMetadata to every kustomization.yaml in their repos.

[stefanprodan]

When you set originAnnotations in the kustomization.yaml does it show in-cluster with the full path of the tmp dir inside kustomize-controller container or it only shows relative paths to the root dir?

[markussiebert]

It shows the relative path in the kustomization - but that would be fine for us, as we have to look it up already to get the source repo.

metadata:
  annotations:
    config.kubernetes.io/origin: |
      path: ../../../base/something/something/some.yaml
  creationTimestamp: "2026-02-05T12:22:54Z"

the kustomizeconfig applied looks like

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
namespace: something-something
buildMetadata:
- originAnnotations
resources:
  - ../../../base/something/something

and the kustomization

apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
  name: something-abc
  namespace: flux-system
spec:
  force: false
  interval: 10s
  path: ./infrastructure/dev/something/something
  prune: true
  sourceRef:
    kind: GitRepository
    name: something

so the real path is

./infrastructure/base/something/something

[stefanprodan]

I'm Ok with adding .spec.buildMetadata to the API as an optional field with only these accepted values: originAnnotations and transformerAnnotations. In Flux we do not used env vars to change the API defaults.

@markussiebert do you wish to contribute this feature?

[markussiebert]

@stefanprodan yes, I would like to contribute this feature.

[stefanprodan]

Ok thanks, we are in code freeze this week as we are releasing all controller for Flux 2.8. This feature will go into 2.9