flux

Flux Generator

Published on kadet-hub: pin a released version by digest from its catalog page.

Kapitan kadet generator for Flux sources and the objects that consume them. Built for Flux 2.9.6, which pins source-controller 1.9.6, kustomize-controller 1.9.6 and helm-controller 1.6.5 (manifests/bases).

• GitRepository, OCIRepository, HelmRepository (source.toolkit.fluxcd.io/v1)
• Kustomization (kustomize.toolkit.fluxcd.io/v1): applies a directory of a Git or OCI source
• HelmRelease (helm.toolkit.fluxcd.io/v2): installs a chart from a HelmRepository, GitRepository or OCIRepository

Each consumer names its source with source: <name>; the generator looks the name up among the sources of the same inventory and writes the matching sourceRef, chart.spec or chartRef. Flux itself is installed with flux bootstrap or the helm input; Secrets for secret_ref belong in the kubernetes generator; pass secret chart values through values_from with a Secret rather than inline values, which land in the compiled output.

Usage

Kapitan Configuration

parameters:
  kapitan:
    dependencies:
      - type: oci
        source: ghcr.io/kadet-hub/flux@sha256:<digest>
        output_path: lib/flux
    compile:
      - output_path: manifests/
        input_type: kadet
        output_type: yml
        input_paths:
          - lib/flux

Inventory Contract

All keys live under parameters.generators.flux.

Every entry accepts namespace, labels, annotations and a spec dict that passes through to the resource spec. Precedence is generator defaults < spec < flat keys: a flat key wins over the same field in spec and logs Flat key '<key>' overrides spec passthrough '<field>' for resource '<name>'.

Flat keys map to the camelCase spec field of the same name; values pass through unless a shorthand below applies.

Shorthands

The compile fails, with a message naming the resource, when:

• a source name matches no source or sources of two kinds (use the dict form then), or a dict source lacks kind or name;
• a Kustomization’s source is not a GitRepository, OCIRepository, Bucket or ExternalArtifact;
• a HelmRelease ends up with neither or both of chart and chartRef, sets chart or version with an OCIRepository source (set its ref instead), lacks chart with a GitRepository or Bucket source, or has an unquoted numeric version such as 1.10, which YAML reads as 1.1;
• one OCIRepository serves both a HelmRelease and a Kustomization, since the chart layerSelector would hand the Kustomization a chart tarball.

These rules exist because QA-7 and QA-10 do not evaluate the CRDs’ CEL rules, such as “either chart or chartRef must be set”.

With --no-cross-namespace-refs=true on the controllers, a source must live in the namespace of its consumer (Kustomization, HelmRelease).

Defaults

The oci HelmRepository type is in maintenance mode upstream (type); prefer an oci_repositories entry as the HelmRelease source.

The interval defaults matter because the CRDs require the field for every kind except HelmRepository. Controller defaults (HelmRepository interval 1m, source timeout 60s, HelmRelease timeout 5m) are not emitted.

Deliberately not defaulted:

• prune: true. With pruning, a Kustomization deletes every object it applied once the object disappears from the source, and deleting the Kustomization deletes them all (prune). Set it per Kustomization together with a path; without path Flux applies the root of the source.
• ref. Without it a GitRepository tracks master and an OCIRepository the latest tag (Git reference, OCI reference).
• service_account_name. Without it a Kustomization or HelmRelease applies as cluster admin (role-based access control) unless the controllers run with --default-service-account (enforcing impersonation). The account and its RBAC are cluster specific; set it for tenant objects.
• HelmRelease driftDetection, install/upgrade strategies and upgrade.crds. The recommended RetryOnFailure suits stateful workloads, RemediateOnFailure stateless ones, and CreateReplace lets a chart replace cluster-wide CRDs; choose per release.

Example

parameters:
  generators:
    flux:
      git_repositories:
        fleet:
          url: https://git.example.com/platform/fleet.git
          ref: main
          secret_ref: fleet-git-token
      oci_repositories:
        podinfo-chart:
          namespace: apps
          url: oci://ghcr.io/stefanprodan/charts/podinfo
          ref:
            semver: ">=6.0.0"
      helm_repositories:
        jetstack:
          url: https://charts.jetstack.io
      kustomizations:
        infrastructure:
          source: fleet
          path: ./clusters/production/infrastructure
          prune: true
        apps:
          source: fleet
          path: ./apps/production
          prune: true
          depends_on:
            - infrastructure
          service_account_name: flux-apps
      helm_releases:
        podinfo:
          namespace: apps
          source: podinfo-chart
          values:
            replicaCount: 2
        cert-manager:
          namespace: cert-manager
          source: jetstack
          version: v1.21.2
          values:
            crds:
              enabled: true

This renders flux-system/fleet-gitrepository, apps/podinfo-chart-ocirepository with the Helm chart layer selector, flux-system/jetstack-helmrepository, the Kustomizations flux-system/infrastructure-kustomization and flux-system/apps-kustomization with sourceRef: {kind: GitRepository, name: fleet}, apps/podinfo-helmrelease with chartRef: {kind: OCIRepository, name: podinfo-chart} and cert-manager/cert-manager-helmrelease with chart.spec: {chart: cert-manager, version: v1.21.2, sourceRef: {kind: HelmRepository, name: jetstack, namespace: flux-system}}.