Introduce ArtifactGenerator API #255

stefanprodan · Sep 8, 2025

Part of: fluxcd/flux2#5504
Closes: fluxcd/source-controller#854

Artifact Generators

The ArtifactGenerator is an extension of Flux APIs that allows source composition and decomposition.
It enables the generation of ExternalArtifacts from multiple sources (GitRepositories, OCIRepositories and Buckets) or the splitting of a single source into multiple artifacts.

The generated artifacts are versioned based on the hash computed from the artifact's content. This means:

✅ Identical content = same revision (no unnecessary reconciliations)
✅ Any change to included content = new revision (guaranteed updates)
✅ Automatic change detection across all source types

Source Composition Example

The following example shows how to compose an artifact from multiple sources:

apiVersion: source.extensions.fluxcd.io/v1beta1
kind: ArtifactGenerator
metadata:
  name: my-app
  namespace: apps
spec:
  sources:
    - alias: backend
      kind: GitRepository
      name: my-backend
    - alias: frontend
      kind: OCIRepository
      name: my-frontend
    - alias: config
      kind: Bucket
      name: my-configs
  artifacts:
    - name: my-app-composite
      copy:
        - from: "@backend/deploy/**"
          to: "@artifact/my-app/backend/"
        - from: "@frontend/deploy/*.yaml"
          to: "@artifact/my-app/frontend/"
        - from: "@config/envs/prod/configmap.yaml"
          to: "@artifact/my-app/env.yaml"

The above generator will create an ExternalArtifact named my-app-composite
in the apps namespace, which contains the deployment manifests from both
the my-backend Git repository and the my-frontend OCI repository,
as well as a ConfigMap from the my-configs Bucket.

The ExternalArtifact revision is computed based on the final content of the artifact,
in the format latest@sha256:<hash>, where <hash> is a SHA256 checksum of the combined files.

The generated ExternalArtifact can be deployed using a Flux Kustomization, for example:

apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
  name: my-app
  namespace: apps
spec:
  interval: 30m
  targetNamespace: apps
  sourceRef:
    kind: ExternalArtifact
    name: my-app-composite
  path: "./my-app"
  prune: true

Every time one of the sources is updated, a new artifact revision will be generated
with the latest content and the Flux Kustomization will automatically reconcile it.

Helm Chart Composition Example

The following example shows how to compose a Helm chart from multiple sources:

apiVersion: source.extensions.fluxcd.io/v1beta1
kind: ArtifactGenerator
metadata:
  name: podinfo
  namespace: apps
spec:
  sources:
    - alias: chart
      kind: OCIRepository
      name: podinfo-chart
      namespace: apps
    - alias: repo
      kind: GitRepository
      name: podinfo-values
      namespace: apps
  artifacts:
    - name: podinfo-composite
      originRevision: "@chart"
      copy:
        - from: "@chart/"
          to: "@artifact/"
        - from: "@repo/charts/podinfo/values-prod.yaml"
          to: "@artifact/podinfo/values.yaml"
          strategy: Merge # Or `Overwrite` to replace the values.yaml

The above generator will create an ExternalArtifact named podinfo-composite in the apps namespace,
which contains the Helm chart from the podinfo-chart OCI repository with the values.yaml merged with
values-prod.yaml from the Git repository.

The generated ExternalArtifact can be deployed using a Flux HelmRelease, for example:

apiVersion: helm.toolkit.fluxcd.io/v2
kind: HelmRelease
metadata:
  name: podinfo
  namespace: apps
spec:
  interval: 10m
  releaseName: podinfo
  chartRef:
    kind: ExternalArtifact
    name: podinfo-composite

Source Decomposition Example

The following example shows how to decompose a source into multiple artifacts:

apiVersion: source.extensions.fluxcd.io/v1beta1
kind: ArtifactGenerator
metadata:
  name: my-app
  namespace: apps
spec:
  sources:
    - alias: repo
      kind: GitRepository
      name: my-monorepo
  artifacts:
    - name: frontend
      copy:
        - from: "@repo/deploy/frontend/**"
          to: "@artifact/"
    - name: backend
      copy:
        - from: "@repo/deploy/backend/**"
          to: "@artifact/"

The above generator will create two ExternalArtifacts named frontend and backend
in the apps namespace, each containing the respective deployment manifests
from the my-monorepo Git repository.

The generated ExternalArtifacts can be deployed using Flux Kustomizations, for example:

---
apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
  name: backend
  namespace: apps
spec:
  interval: 30m
  sourceRef:
    kind: ExternalArtifact
    name: backend
  path: "./"
  prune: true
---
apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
  name: frontend
  namespace: apps
spec:
  interval: 30m
  sourceRef:
    kind: ExternalArtifact
    name: frontend
  path: "./"
  prune: true

Every time the monorepo is updated, new revisions will be generated only for the affected artifacts.
If the manifests in deploy/frontend/ directory are modified, only the frontend artifact will
receive a new revision, triggering the Flux Kustomization that applies it.
While the backend artifact remains unchanged and its Kustomization will not reconcile.