Resolved

Enabling OCIRepository support in FluxCD after component upgrade

FluxCD
Kubernetes
Helm
OCI
GitOps
DevOps

Explains how to address FluxCD HelmRelease validation issues with OCIRepository sources by upgrading cluster components and updating CRD schemas.

Issue

FluxCD HelmRelease resources failed validation when referencing OCIRepository sources, despite the controllers supporting them. The error indicated that the HelmRelease resource was invalid because the OCIRepository kind was not recognized as a valid source reference. This blocked the deployment of Helm charts stored in OCI registries, such as those for Redis.

Culprit

The root cause was a version mismatch between the FluxCD CLI and cluster components:

  • The CLI version (v2.7.2) supported OCIRepository.
  • The cluster controllers (v1.2.4/v0.37.4) were outdated, reflecting the schema from an older FluxCD release (v2.2.x from January 2024).
  • The HelmChart Custom Resource Definition (CRD) did not include OCIRepository in its allowed sourceRef.kind enum, causing validation errors before the controllers could process the request.

Solution

Component Upgrade Process

To resolve this issue, follow these steps:

  1. Generate Updated Manifests: Use the current FluxCD CLI to generate updated manifests for the cluster components.

generate new manifests using: flux install —components-extra=image-reflector-controller,image-automation-controller —export > gotk-components-new.yaml


2. **Replace Legacy Components**:
Apply the newly generated manifests to replace outdated components in the cluster.
Use manual apply process to avoid GitOps path exclusions:
```bash
kubectl apply -f k8s/flux-system/gotk-components.yaml
  1. Recycle Pods: Force pod recycling to release CPU and ensure that new versions of the controllers are running: 
    kubectl delete pod -n flux-system helm-controller-f44c8988b-x2267 kustomize-controller-6479c8ddbb-6mgxh

CRD Schema Updates

To enable OCIRepository support, update the HelmChart CRD schema:

  1. Add OCIRepository CRD: Include the OCIRepository CRD in the cluster, ensuring both v1 and v1beta2 versions are available.

  2. Update sourceRef.kind Enum: Modify the HelmChart CRD to include OCIRepository in the allowed kinds for sourceRef.

  3. Enhance HelmRelease CRD: Update the HelmRelease CRD to support OCI artifacts.

Verification

Verify the successful deployment and use of OCI-based Helm charts:

  • Check the status of OCI repositories to ensure they are correctly recognized and can be referenced.
  • Confirm that HelmReleases referencing OCI repositories are successfully reconciled and that the pods are running as expected.