Upgrade Flux to the Source v1beta2 API

[hiddeco]

Starting with v0.28, Flux comes with new reconcilers for Source objects and graduates the Flux Source API to v1beta2.

Breaking changes

• From this version on, controllers depending on Source kinds (kustomize-controller, helm-controller and image-automation-controller) do now require the Source v1beta2 Custom Resource Definition to be present on the cluster.

Features and improvements

API specifications in a user-friendly format

The new specifications for the v1beta2 API have been written in a new format with the aim to be more valuable to a user. Featuring separate sections with examples, and information on how to write and work with them.

Artifact now advertises size

The size (in bytes) of a tarball Artifact is now advertised in the Size (.size) field of the Artifact. This can be utilized by users to e.g. quickly see if .sourceignore rules have an effect, or be displayed in a UI.

Azure Blob Storage support for Bucket resources

The .spec.provider of a Bucket resource can now be set to azure to instruct the controller to use the Azure Blob Storage SDK while fetching objects. This allows for authenticating using Service Principals, Managed Identities and Shared Keys.

For more information, see the Bucket spec about the Azure provider.

Enhanced Kubernetes Conditions

Source API resources will now advertise more explicit Condition types (more about the types in "API changes"), provide Reconciling and Stalled Conditions where applicable for better integration with kstatus, and record the Observed Generation on the Condition.

For a detailed overview per Source type, refer to the spec:

• GitRepository
• HelmRepository
• HelmChart
• Bucket

Enhanced Kubernetes Events (and notifications)

The Kubernetes Events the controller emits have been reworked to provide a proper reason, and more informative messages. Users making use of the notification-controller will notice this as well, as this same information is used to compose notifications.

API changes

The source.toolkit.fluxcd.io/v1beta2 API is backwards compatible with v1beta1.

• Introduction of Reconciling and Stalled Condition types for better integration with kstatus.
• Introduction of new Condition types to provide better signals and failure indications:
  • ArtifactOutdated: indicates the current Artifact of the Source is outdated.
  • SourceVerified: indicates the integrity of the Source has been verified.
  • FetchFailed: indicates a transient or persistent fetch failure of the upstream Source.
  • BuildFailed: indicates a transient or persistent build failure of a Source's Artifact.
  • StorageOperationFailed: indicates a transient or persistent failure related to storage.
  • IncludeUnavailable: indicates an include is not available. For example, because it does not exist, or does not have an Artifact.
• Introduction of a Size (in bytes) field (.status.artifact.size) in the Artifact object.
• Introduction of ObservedChartName (.status.observedChartName) and ObservedSourceArtifactRevision (.status.observedSourceArtifactRevision) fields in the HelmChart Status.
• Introduction of azure provider implementation for Bucket.

Upgrade procedure

To upgrade your cluster, download the Flux CLI binary from the release page and rerun the flux bootstrap command. This will upgrade the Flux components on your cluster to the latest version. Other upgrade options can be found on the docs website.

ℹ️ Note that updating the manifests in Git from source.toolkit.fluxcd.io/v1beta1 to source.toolkit.fluxcd.io/v1beta2 can be done at any time after the Flux components upgrade. All users are encouraged to update the manifests as any deprecated fields will be removed when the next API version will be released. For more information, see post upgrade.

Terrafrom upgrade

When using the Terraform provider for Flux, you have to manually remove the v1beta1 GitRepository from the TF state:

terraform state rm 'kubectl_manifest.sync["source.toolkit.fluxcd.io/v1beta1/gitrepository/flux-system/flux-system"]'

Other upgrade methods

When upgrading without the CLI or Terraform (using e.g. GitHub Actions or RenovateBot), we recommend to bump the GitRepository API version in gotk-sync.yaml to v1beta2.

Post upgrade

After rolling out the upgrade, and when you have confirmed things to be working as expected. Resources in Git which refer to source.toolkit.fluxcd.io/v1beta1 can be updated to refer to source.toolkit.fluxcd.io/v1beta2:

@@ -1,4 +1,4 @@
-apiVersion: source.toolkit.fluxcd.io/v1beta1
+apiVersion: source.toolkit.fluxcd.io/v1beta2
 kind: GitRepository
 metadata:
   name: gitrepository-sample

[kingdonb]

(Discussions remain in a "response needed" queue for the weekly Bug Scrub until they are answered)

Marking this one as answered.