[🐛 Bug]: HelmReleases missing from topology with FluxCD ≥ 2.7

[gecube]

Summary

KeepHQ @ 0.1.93 does not display any HelmRelease objects on the topology map when integrated with FluxCD 2.7.2.
Only Kustomization and GitRepository resources are shown.

As a result, the FluxCD integration becomes practically unusable for modern clusters.

---

🧩 Environment

Component	Version
Kubernetes distro	k3s (not relevant)
KeepHQ chart	keep@0.1.93
FluxCD	v2.7.2
Helm Controller	v1.4.2
Kustomize Controller	v1.7.1
Source Controller	v1.7.2
Notification Controller	v1.7.3
Image Controller	v1.0.2

---

🧠 Root cause

Since FluxCD 2.7, API versions of several resources changed.
For example, helmreleases.helm.toolkit.fluxcd.io moved from v2beta2 to v2.

Running kubectl api-resources | grep flux now returns:

helmreleases                        hr                   helm.toolkit.fluxcd.io/v2                 true         HelmRelease
imagepolicies                       imgpol,imagepol      image.toolkit.fluxcd.io/v1                true         ImagePolicy
imagerepositories                   imgrepo,imagerepo    image.toolkit.fluxcd.io/v1                true         ImageRepository
imageupdateautomations              iua,imgupd,imgauto   image.toolkit.fluxcd.io/v1                true         ImageUpdateAutomation
kustomizations                      ks                   kustomize.toolkit.fluxcd.io/v1            true         Kustomization
alerts                                                   notification.toolkit.fluxcd.io/v1beta3    true         Alert
providers                                                notification.toolkit.fluxcd.io/v1beta3    true         Provider
receivers                                                notification.toolkit.fluxcd.io/v1         true         Receiver
artifactgenerators                  ag                   source.extensions.fluxcd.io/v1beta1       true         ArtifactGenerator
buckets                                                  source.toolkit.fluxcd.io/v1               true         Bucket
externalartifacts                                        source.toolkit.fluxcd.io/v1               true         ExternalArtifact
gitrepositories                     gitrepo              source.toolkit.fluxcd.io/v1               true         GitRepository
helmcharts                          hc                   source.toolkit.fluxcd.io/v1               true         HelmChart
helmrepositories                    helmrepo             source.toolkit.fluxcd.io/v1               true         HelmRepository
ocirepositories                     ocirepo              source.toolkit.fluxcd.io/v1               true         OCIRepository

However, in the current codebase (see line 483):

👉 fluxcd_provider.py#L483

The provider hardcodes the old API group/version helm.toolkit.fluxcd.io/v2beta2, so HelmReleases from the new API version are never discovered.

---

🧰 Steps to reproduce

1. Install FluxCD 2.7.x on any cluster
2. Install KeepHQ 0.1.93 via Helm
3. Add FluxCD provider in values.yaml (works, provider is visible)
4. Open Topology view → only Kustomizations + GitRepositories appear, HelmReleases are missing

---

💡 Expected behavior

• KeepHQ should discover HelmReleases regardless of their API version
• The provider should support both:
  • helm.toolkit.fluxcd.io/v2beta2 (old FluxCD)
  • helm.toolkit.fluxcd.io/v2 (new FluxCD ≥ 2.7)

---

✅ Suggested fix

In fluxcd_provider.py, update resource discovery logic to gracefully detect available API versions before querying resources.

Pseudo-code:

api_versions = [
    "helm.toolkit.fluxcd.io/v2",
    "helm.toolkit.fluxcd.io/v2beta2",
]

for api_version in api_versions:
    try:
        result = k8s_client.list_cluster_custom_object(api_version, "helmreleases")
        if result["items"]:
            break
    except ApiException as e:
        continue

This will ensure backward compatibility and proper detection on both new and old FluxCD installations.

---

Labels: type:bug area:integration-fluxcd priority:high

[gecube]

[dosubot]

The topology map in your image matches the current behavior of KeepHQ with FluxCD ≥ 2.7—only Kustomizations and GitRepositories are shown, while HelmRelease objects are missing. This is due to the provider code only querying the 'v2' API version for HelmReleases and not dynamically checking for older versions like 'v2beta2' source. As a result, the topology does not fully represent clusters using HelmReleases, which limits the usefulness of the FluxCD integration for modern setups. The relationships between Kustomize overlays and GitRepositories are correctly visualized, but the absence of HelmRelease nodes is a direct consequence of the API version mismatch.

To reply, just mention @dosu.

---

Docs are dead. Just use Dosu.

[gecube]

💬 Additional requirement: dynamic API version detection for FluxCD upgrades / downgrades

In addition to the main issue, it’s important to consider a runtime scenario:

FluxCD may be upgraded (or downgraded) while KeepHQ is running.

This means:

• The API versions of FluxCD resources (e.g. helm.toolkit.fluxcd.io/v2beta2 → v2) can change during the KeepHQ process lifetime.
• KeepHQ should detect such changes dynamically, without requiring a restart or redeployment.
• Alternatively, KeepHQ could expose a mechanism to refresh or reload the provider definitions manually or automatically.

✅ Expected behavior

• On FluxCD upgrade: KeepHQ should start using the new API versions automatically.
• On FluxCD downgrade: KeepHQ should gracefully fall back to the older API versions.
• Ideally, this adaptation happens at runtime, without downtime or manual Helm upgrade.

🧠 Rationale

This ensures that KeepHQ remains compatible in long-lived clusters where FluxCD may evolve independently, avoiding transient failures in topology or resource discovery when the API version changes.

[dosubot]

KeepHQ's current FluxCD provider does not support dynamic API version detection or runtime adaptation to FluxCD upgrades or downgrades. The provider uses hardcoded API versions (for example, HelmRelease is queried only with v2), and there is no mechanism to refresh or reload provider definitions or the Kubernetes client during runtime. Any change in FluxCD resource API versions requires a KeepHQ restart or redeployment to take effect. There is also no documented or implemented way to manually or automatically trigger a provider reload or API version re-discovery while KeepHQ is running. This means that, as of now, KeepHQ will not automatically adapt to FluxCD API changes in long-lived clusters without downtime or manual intervention.
Source: fluxcd_provider.py implementation

To reply, just mention @dosu.

---

Share context across your team and agents. Try Dosu.