Skip to content

Serve a Helm repository index that points at the OCI charts - #900

Open
HoustonPutman wants to merge 2 commits into
apache:mainfrom
HoustonPutman:helm-oci-index
Open

HoustonPutman wants to merge 2 commits into
apache:mainfrom
HoustonPutman:helm-oci-index

Conversation

@HoustonPutman

@HoustonPutman HoustonPutman commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

Starting with v0.10.0 the Helm charts are only distributed as OCI artifacts on ghcr.io/apache/solr-operator/helm. This keeps helm repo add apache-solr https://solr.apache.org/charts working, by serving an index.yaml from solr-site whose entries point at the OCI copies instead of at tarballs on nightlies.apache.org:

solr-operator:
  - version: 0.10.0
    urls:
      - oci://ghcr.io/apache/solr-operator/helm/solr-operator:0.10.0
    digest: <sha256 of the released tgz, identical to the OCI copy>

The companion solr-site change serves this index: apache/solr-site#260 (draft).

Changes

  • hack/release/upload/update_helm_index.sh adds a release to the index. It downloads the released charts, verifies their checksums and signatures, and writes oci:// entries from helm repo index metadata. It also signs the index and writes its checksum.
    • An existing entry is replaced in place and keeps its created date. This is the path for backfilling older releases.
    • It refuses to replace an entry whose digest has changed.
    • It requires -c before it will create a new index.
  • hack/release/smoke_test/test_oci_index.sh packages and signs the charts and pushes them to a TLS registry:2. It generates the index with the script above and serves it, then checks each Helm version. The registry, the index server and each Helm version all run in containers. It is meant to be run locally when changing the index tooling, and is not run in CI.
  • Release wizard
    • Removes the nightlies upload step (publish_helm_charts).
    • Adds website_update_helm_index, which updates the index in the solr-site checkout after publish_helm_charts_oci.
    • publish_website now ends with a helm repo add / helm show chart check against the live site, and the ArtifactHub check now waits for the site to be published.
  • Docs: the upgrade notes, running-the-operator, the chart README and both chart changelogs note the Helm 3.8 minimum and the direct oci:// install. New dev-docs/helm-repository.md covers maintaining the index and backfilling.

Testing

./hack/release/smoke_test/test_oci_index.sh, run locally: 36/36 checks passed across Helm 3.8.2, 3.19.0 and 4.3.1.

  • control: direct oci:// pull
  • repo add / repo update / search repo / show chart
  • pull (byte-identical to the released tgz) and pull --verify
  • install-style chart resolution (helm template, with and without --verify)
  • dependency update with both a repository url and an @alias

Still to do (not in this PR)

  • Seed content/charts/index.yaml in solr-site from the current nightlies index before the site change merges, or /charts breaks.
  • Backfill released versions to GHCR with publish-helm-oci.yaml, then rewrite their entries with update_helm_index.sh. Older releases without .prov files will fail in that workflow.
  • Confirm that ArtifactHub accepts oci:// urls in a classic index after the first publish. This has not been tested.
  • Remove upload_helm.sh once the backfill is done.

Starting with v0.10.0 the Helm charts are only distributed as OCI artifacts on
ghcr.io. Keep 'helm repo add apache-solr https://solr.apache.org/charts' working
by serving an index.yaml from solr-site whose entries point at the OCI copies
(oci://ghcr.io/apache/solr-operator/helm/<chart>:<version>), instead of at
tarballs uploaded to nightlies.apache.org.

- hack/release/upload/update_helm_index.sh adds a release to that index. It
  verifies the released charts, replaces existing entries in place (for
  backfilling older releases), refuses digest changes, and signs the index.
- hack/release/smoke_test/test_oci_index.sh checks that Helm 3.8.2, 3.19.0 and
  4.3.1 can consume such an index: repo add/update, search, show, pull,
  --verify, install-style resolution and dependency update. It runs in the new
  "Helm OCI Index" workflow.
- The release wizard drops the nightlies upload, and adds a website step that
  updates the index after the charts are published to the OCI registry.
- Docs, upgrade notes and the chart changelogs note the Helm 3.8 minimum.
The test script is meant to be run locally when the index tooling changes.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant