Sources: GitRepository & more

Where desired state comes from.

Advanced12 min · lesson 3 of 12

The source-controller is where desired state enters Flux. A source is a CRD describing where to fetch from and how often, and the controller pulls it, verifies it, and makes it available to the reconcilers as an artifact. The main source is GitRepository (a repo, a branch/tag/semver ref, an interval), but Flux also supports HelmRepository (chart repos), OCIRepository (manifests or charts as OCI artifacts), and Bucket (S3-compatible). Separating fetching from applying is central to the toolkit design.

SOURCE INGESTION & VERIFICATION

1Define source

GitRepository: url, ref, interval

2Fetch on interval

source-controller pulls the revision

3Verify signature

GPG/sigstore commit or Cosign; refuse if bad

4Publish artifact

made available to the reconcilers

Verification happens at ingestion, so tampered or unsigned content never reaches the reconcilers.

gitrepository.yaml

apiVersion: source.toolkit.fluxcd.io/v1
kind: GitRepository
metadata: { name: payments, namespace: flux-system }
spec:
  interval: 1m
  url: https://git.acme.internal/apps/payments.git
  ref:
    tag: v1.4.0            # or branch:, or semver: ">=1.4.0"
  secretRef: { name: git-credentials }

Verification at the source

A powerful property: the source-controller can verify what it fetches before anything is applied. For Git, it can check GPG/sigstore commit signatures against a set of trusted keys and refuse an unsigned or wrongly-signed revision. For OCI sources, it can verify Cosign signatures. This means supply-chain verification happens at ingestion — a tampered or unsigned source never reaches the reconcilers — which is one of Flux’s strongest security features.

gitrepository verify

spec:
  ref: { branch: main }
  verify:
    mode: HEAD
    secretRef: { name: flux-gpg-keys }   # trusted public keys
# Flux refuses to reconcile a revision whose commit signature does not verify

A source without verification trusts whatever it pulls

By default a GitRepository trusts the branch/tag it points at, so whoever can push there controls what Flux applies. Turn on source verification (signed-commit or OCI Cosign verification) for anything sensitive so Flux only reconciles content signed by trusted identities. Verification at the source is available and cheap; not using it means the Git host and network path are fully trusted by default.

Bootstrapping FluxKustomization: reconciling