feat: custom url override for Helm AddOns

[abhay-nutanix]

How it works

Resolution order

For each addon, the repository URL is chosen in this order:

1. Override – If you set helmAddonsOverrides.<addonKey>.repositoryURL, that value is used.
2. Internal OCI – If helmRepository.enabled is true and there is no override, the chart is pulled from the in-cluster Helm repository: oci://helm-repository.<namespace>.svc/charts.
3. Default HTTPS – Otherwise the chart is pulled from the addon’s default index (e.g. https://nutanix.github.io/helm-releases/ for Nutanix CSI).

So: override > internal OCI > default HTTPS.

OCI support

Charts can be pulled from OCI registries (e.g. Harbor) using oci:// URLs. CAREN supports this in two ways:

• Full path: oci://harbor.example.com/project/nutanix-csi-storage
  CAREN normalizes this to a base URL + chart name when creating the HelmChartProxy, so the Cluster API Helm addon provider can run helm pull oci://... correctly.

• Base URL: oci://harbor.example.com/project
  Used as-is; the chart name comes from the addon’s default (e.g. nutanix-csi-storage).

For private OCI registries, ensure the workload cluster can authenticate (e.g. helm registry login or image pull secrets as required by your setup).

---

Where to add a custom URL

When installing CAREN via Helm

Set helmAddonsOverrides in the Helm values. The keys are the addon keys (same as in the helm-config ConfigMap).

Example: Nutanix CSI from Harbor OCI (QA)

helmAddonsOverrides:
  nutanix-storage-csi:
    repositoryURL: "oci://harbor.eng.nutanix.com/k8s-ha/nutanix-csi-storage"

Example: Override multiple addons

helmAddonsOverrides:
  nutanix-storage-csi:
    repositoryURL: "oci://harbor.eng.nutanix.com/k8s-ha/nutanix-csi-storage"
  nutanix-ccm:
    repositoryURL: "https://my-index.example.com/nutanix-ccm"

Install command example

helm upgrade --install caren caren/cluster-api-runtime-extensions-nutanix \
  --namespace caren-system \
  --create-namespace \
  --set helmAddonsOverrides.nutanix-storage-csi.repositoryURL="oci://harbor.eng.nutanix.com/k8s-ha/nutanix-csi-storage" \
  --wait

Or use a values file:

# my-values.yaml
helmAddonsOverrides:
  nutanix-storage-csi:
    repositoryURL: "oci://harbor.eng.nutanix.com/k8s-ha/nutanix-csi-storage"

helm upgrade --install caren caren/cluster-api-runtime-extensions-nutanix \
  --namespace caren-system \
  --create-namespace \
  -f my-values.yaml \
  --wait

---

Addon keys (where to add custom URL)

Use these keys under helmAddonsOverrides to override the repository URL for each addon:

Addon key	Default chart source	Typical use
nutanix-storage-csi	https://nutanix.github.io/helm-releases/	Nutanix CSI (e.g. Harbor OCI for QA)
nutanix-ccm	https://nutanix.github.io/helm/	Nutanix Cloud Controller Manager
aws-ccm	https://kubernetes.github.io/cloud-provider-aws	AWS Cloud Controller Manager
aws-ebs-csi	https://kubernetes-sigs.github.io/aws-ebs-csi-driver	AWS EBS CSI driver
aws-load-balancer-controller	https://aws.github.io/eks-charts	AWS Load Balancer Controller
cilium	https://helm.cilium.io/	Cilium CNI
cluster-autoscaler	https://kubernetes.github.io/autoscaler	Cluster Autoscaler
cncf-distribution-registry	https://mesosphere.github.io/charts/staging/	Docker registry
cosi-controller	https://mesosphere.github.io/charts/stable/	COSI controller
konnector-agent	https://nutanix.github.io/helm-releases/	Konnector agent
local-path-provisioner-csi	https://charts.containeroo.ch	Local path provisioner
metallb	https://metallb.github.io/metallb	MetalLB
multus	https://mesosphere.github.io/charts/stable/	Multus
nfd	https://kubernetes-sigs.github.io/node-feature-discovery/charts	Node Feature Discovery
registry-syncer	https://mesosphere.github.io/charts/staging/	Registry syncer
snapshot-controller	https://piraeus.io/helm-charts/	Snapshot controller
tigera-operator	https://docs.tigera.io/calico/charts	Calico (Tigera operator)

---

Flow summary

1. Helm install/upgrade – You set helmAddonsOverrides.<addonKey>.repositoryURL (and/or install with a values file that contains it).
2. Rendered ConfigMap – The chart template resolves each addon’s RepositoryURL via the caren.helmAddonRepoURL helper (override → internal OCI → default).
3. Runtime – CAREN reads the ConfigMap and creates a HelmChartProxy per addon per cluster. For OCI URLs, it normalizes full paths to base URL + chart name so the Cluster API Helm addon provider can pull the chart correctly.
4. Provider – The Helm addon provider runs helm pull / install using the resolved URL and chart name.

This is how a custom URL (including OCI Harbor for nutanix-csi) is applied end-to-end.

[faiq]

What's the plan for changing the chart values? We're using it mostly to generate the runtime-extensions.yaml file which most people use to deploy cluster api providers.

[github-actions]

🚫 [golangci-lint] _{reported by reviewdog 🐶}
File is not properly formatted (gofumpt)

[abhay-nutanix]

What's the plan for changing the chart values? We're using it mostly to generate the runtime-extensions.yaml file which most people use to deploy cluster api providers.

This is done to support custom CSI image uploaded to harbor.eng.nutanix.com for testing ahvMetro clusters.
This is useful in doing helm install, this has no effect on when we use clusterctl.

[faiq]

None of our customers use the helm install method. It also seems like the helm install is mostly for development.