Using FluxCD with OCI Helm Charts: Handling Tags in HelmRelease

[hmoens]

Hi!

I'm working on using FluxCD to manage and deploy Helm charts from an OCI repository. My workflow doesn’t use Git directly. Instead, CI pipelines build and publish Helm charts to an OCI repository. A HelmRelease resource in the cluster monitors for changes and applies updates as necessary.

I want to use tags from the OCI repository (e.g., prod) to determine the appropriate version of the Helm chart, for example:

flux tag artifact oci://my-registry/starter-app:1.2.3 --tag prod

This command properly adds a 'prod' tag to the chart, which gave me hope that this approach would work.

Here’s my current YAML configuration:

apiVersion: source.toolkit.fluxcd.io/v1beta2
kind: OCIRepository
metadata:
  name: starter-app-repo
  namespace: starter-app
spec:
  interval: 1m
  url: oci://my-registry/starter-app
  ref:
    tag: prod
  provider: aws
---
apiVersion: helm.toolkit.fluxcd.io/v2
kind: HelmRelease
metadata:
  name: starter-app
  namespace: starter-app
spec:
  chartRef:
    kind: OCIRepository
    name: starter-app-repo
  interval: 1m
  values: {}

When I apply this configuration, it fails with the error:

failed parsing artifact revision prod

If I manually change the ref.tag value in the OCIRepository resource to a specific version (e.g., 1.2.3), it works as expected. The issue seems to be that the HelmRelease interprets the ref.tag value (e.g., prod) as the chart version, even though the version in the Chart.yaml from the OCI repository is correct.

A possible workaround

To bypass this issue, I started building separate -prod and -dev variants of the chart and updated the OCIRepository to filter using semver:

spec:
  ref:
    semver: ">=0.0.0-0"
    semverFilter: ".*-prod"

This works but comes with drawbacks:

• It requires building additional chart variants for each environment.
  

• It feels like a hacky workaround rather than a proper solution.
  

An alternative option would be to just do away with chart versioning overall and just build 0.0.0-prod and 0.0.0-dev instead but this also comes with obvious drawbacks.

Question

Is there a better approach within the FluxCD ecosystem to handle this scenario? Ideally, I’d like to use OCI tags (e.g., prod, dev) for dynamic Helm chart management without introducing additional complexity like environment-specific chart variants.

Any insights or suggestions would be greatly appreciated!

Edit: in the original version of this post there was an error in the yaml manifests.

[matheuscscp]

Change:

  chart:
    spec:
      sourceRef:
        kind: OCIRepository
        name: starter-app-repo

to:

  chartRef:
    kind: OCIRepository
    name: starter-app-repo

[matheuscscp]

Helm only supports semver tags.

[matheuscscp]

x.y.z-prod is a valid semver tag.

[hmoens]

I understand that helm only supports semver tags, but OCI repositories do support tagging. In my example, the helm chart is tagged with two separate tags using
flux tag artifact oci://my-registry/starter-app:1.2.3 --tag prod

and I can download the artifact with

flux pull artifact oci://my-registry/starter-app:1.2.3 .
flux pull artifact oci://my-registry/starter-app:prod .

In both cases the exact same (valid) chart is returned, with version: 1.2.3 in Chart.yaml

To me it seems like it is the HelmRelease (or rather the helm-controller) is in this instance ignoring the version defined in Chart.yaml.

[matheuscscp]

If you try to install the tag prod using the helm CLI it will give the same error, that's what I mean. helm-controller does the same as the helm CLI.

[hmoens]

Given the split between OCIRepository and HelmRelease I was hoping that fetching assets from OCI repositories and the actual deploy would have been handled in separate stages allowing for a workflow like the one I attempted. I see now that that was an incorrect assumption.

I'll look a bit more into alternative workarounds. Thank you for the fast responses!