Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

Appearance settings

Conversation

stefanprodan
Copy link
Member

@stefanprodan stefanprodan commented 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.

Signed-off-by: Stefan Prodan <stefan.prodan@gmail.com>
Signed-off-by: Stefan Prodan <stefan.prodan@gmail.com>
Signed-off-by: Stefan Prodan <stefan.prodan@gmail.com>
Signed-off-by: Stefan Prodan <stefan.prodan@gmail.com>
Signed-off-by: Stefan Prodan <stefan.prodan@gmail.com>
Signed-off-by: Stefan Prodan <stefan.prodan@gmail.com>
Signed-off-by: Stefan Prodan <stefan.prodan@gmail.com>
Signed-off-by: Stefan Prodan <stefan.prodan@gmail.com>
Signed-off-by: Stefan Prodan <stefan.prodan@gmail.com>
Signed-off-by: Stefan Prodan <stefan.prodan@gmail.com>
Signed-off-by: Stefan Prodan <stefan.prodan@gmail.com>
Signed-off-by: Stefan Prodan <stefan.prodan@gmail.com>
Signed-off-by: Stefan Prodan <stefan.prodan@gmail.com>
Signed-off-by: Stefan Prodan <stefan.prodan@gmail.com>
Signed-off-by: Stefan Prodan <stefan.prodan@gmail.com>
Signed-off-by: Stefan Prodan <stefan.prodan@gmail.com>
Signed-off-by: Stefan Prodan <stefan.prodan@gmail.com>
Signed-off-by: Stefan Prodan <stefan.prodan@gmail.com>
Signed-off-by: Stefan Prodan <stefan.prodan@gmail.com>
Signed-off-by: Stefan Prodan <stefan.prodan@gmail.com>
Signed-off-by: Stefan Prodan <stefan.prodan@gmail.com>
Signed-off-by: Stefan Prodan <stefan.prodan@gmail.com>
Signed-off-by: Stefan Prodan <stefan.prodan@gmail.com>
Signed-off-by: Stefan Prodan <stefan.prodan@gmail.com>
internal/controller/artifactgenerator_controller.go Outdated Show resolved Hide resolved
internal/controller/artifactgenerator_controller.go Outdated Show resolved Hide resolved
internal/controller/artifactgenerator_controller.go Outdated Show resolved Hide resolved
Signed-off-by: Stefan Prodan <stefan.prodan@gmail.com>
internal/builder/builder.go Outdated Show resolved Hide resolved
internal/builder/builder.go Outdated Show resolved Hide resolved
Signed-off-by: Stefan Prodan <stefan.prodan@gmail.com>
internal/builder/builder_test.go Outdated Show resolved Hide resolved
Signed-off-by: Stefan Prodan <stefan.prodan@gmail.com>
Signed-off-by: Stefan Prodan <stefan.prodan@gmail.com>
@stefanprodan stefanprodan force-pushed the v2 branch 3 times, most recently from 67c1afb to f23835e Compare September 11, 2025 17:44
Signed-off-by: Stefan Prodan <stefan.prodan@gmail.com>
docs/spec/v1beta1/artifactgenerators.md Show resolved Hide resolved
Signed-off-by: Stefan Prodan <stefan.prodan@gmail.com>
Signed-off-by: Stefan Prodan <stefan.prodan@gmail.com>
@stefanprodan stefanprodan marked this pull request as ready for review September 12, 2025 15:11
@stefanprodan stefanprodan force-pushed the v2 branch 4 times, most recently from 5b1eea6 to 18206f1 Compare September 12, 2025 16:19
Copy link
Member

@matheuscscp matheuscscp left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM! 🚀 🚀 🚀

Just more proof of Flux's technical excellence!

Signed-off-by: Stefan Prodan <stefan.prodan@gmail.com>
@stefanprodan stefanprodan added the area/api API related issues and pull requests label Sep 12, 2025
@stefanprodan stefanprodan merged commit 1506f3c into main Sep 12, 2025
2 checks passed
@stefanprodan stefanprodan deleted the v2 branch September 12, 2025 19:48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area/api API related issues and pull requests enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Ability to include other type of source in GitRepository

2 participants

Morty Proxy This is a proxified and sanitized view of the page, visit original site.