Skip to content

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

Merged
HoustonPutman merged 14 commits into
apache:mainfrom
HoustonPutman:helm-oci-index
Nov 19, 2026
Merged

HoustonPutman merged 14 commits into
apache:mainfrom
HoustonPutman:helm-oci-index

Conversation

@HoustonPutman

@HoustonPutman HoustonPutman commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

Part of #813, and supersedes #863.

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 include Document the OCI registry as the default Helm chart source #863 (OCI as the default chart source), adjusted so that both sources are supported rather than the HTTPS repository being deprecated:
    • The Antora pages (running-the-operator, local-tutorial, upgrade-notes) show both sources as tabs, OCI Charts (default) and Charts Repo. The tutorial's tabs are synced, so the choice carries through every step.
    • The chart READMEs and the top-level README are Markdown, so they use matching "OCI Charts" / "Charts Repo" subsections.
    • Both chart changelogs: an added entry for the OCI charts and a changed entry for the repository listing them (Helm 3.8+), in place of Document the OCI registry as the default Helm chart source #863's deprecated entry.
    • 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.

janhoy and others added 10 commits October 24, 2026 14:15
Makes oci://ghcr.io/apache/solr-operator/helm the documented way to install both charts, and marks the HTTPS Helm repository at https://solr.apache.org/charts as deprecated. Installing from an OCI registry needs no 'helm repo add' and no credentials.

Charts are published to both the OCI registry and the HTTPS repository throughout the 0.x releases, so nobody has to change anything on a patch upgrade. Starting with v1.0.0, charts will be published to the OCI registry only. A major version is the natural place to drop the old channel, and it gives users a version-anchored deadline rather than a date that slips with the release schedule.

Artifact Hub still indexes the HTTPS repository. Migrating it would need one repo entry per chart and would change every existing artifacthub.io/packages/helm/apache-solr/... URL, so it is better done as part of the v1.0.0 cutover. Dual publishing keeps the current Artifact Hub entry accurate in the meantime.

Requires the publishing tooling to be in place and the ghcr.io packages to be public first.

Fixes apache#813
… for install docs

Both charts gain 'added' and 'deprecated' artifacthub.io/changes entries for the
OCI switch, so the change shows up in the Artifact Hub changelog for v0.10.0.

running-the-operator.adoc called Artifact Hub "the official documentation for
installing the Solr Operator Helm chart" a few lines above the text deprecating
the HTTPS repository. Artifact Hub generates its install snippet from how the
repository is registered, which is still the HTTPS Helm repo, so it contradicted
the page it was on. Artifact Hub is now referenced once, as the place the chart's
values and changelog are listed, with a note that its install command still uses
the deprecated repository.
Update Helm repository instructions for Apache Solr.

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
The step only appeared in the OCI block, so following the HTTPS
alternative left the ZookeeperCluster CRD missing.
The HTTPS alternative skipped the step its own introduction calls for.
The docs said charts would be published to the OCI registry only "starting with
v1.0.0". We are not ready to commit to when the HTTPS repository stops being
updated, so the wording is now open-ended: charts go to both locations for now,
and the HTTPS repository will be retired in a future release.

The deprecation itself is unchanged, and the upgrade notes promise the retirement
will be announced in advance rather than naming a version. Removing the deadline
also drops the "update your automation before upgrading to v1.0.0" instruction,
which is now phrased as a recommendation.
The deprecation notice was repeated on five pages: the top-level README, the
local-tutorial and running-the-operator docs, and both chart READMEs. That is
five places to keep in sync, and they had already started to drift.

The upgrade notes are now the single place that explains it, under the existing
"Where the Helm charts are published" anchor. Everywhere else that needs to
mention the old repository links there instead: the Antora pages with an xref,
and the Markdown READMEs with an absolute link to the published page, since they
are also rendered on Artifact Hub where a relative link would not resolve.

The HTTPS install snippet in running-the-operator.adoc is kept, since it is still
a working alternative; only the repeated explanation is gone.
Installing via OCI never registers apache-solr, so each HTTPS
alternative has to add it to stand on its own.
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.

@janhoy janhoy left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

Comment thread helm/solr-operator/README.md Resolved
@HoustonPutman

Copy link
Copy Markdown
Contributor Author

Yeah I didn't mean for this to be the default way. We should still advertise the OCI way first and merge #863. Maybe we can have Antora tabs to differentiate the two methods like we do for v1 and v2 apis in Solr.

… source

Brings in apache#863, adjusted for the Helm repository now
listing the OCI charts, so both chart sources are supported rather than the
HTTPS repository being deprecated.

- The Antora pages show both sources as tabs, "OCI Charts" (the default) and
  "Charts Repo". The tutorial's tabs are synced, so the choice carries
  through every step.
- The chart READMEs, which are Markdown, use matching "OCI Charts" and
  "Charts Repo" subsections.
- The deprecation notes and changelog entries are replaced by entries for
  the OCI charts and for the repository listing them. Changes made on main
  since apache#863 branched (changelog entries, the 9.11.0 image tag, the logging
  note) are kept.
The charts are signed, but the docs never said how to verify them. Add a
"Verifying the Helm charts" section to the upgrade notes, with both chart
sources as tabs, and link it from the install docs and the chart READMEs.

--verify is not added to every install command, since it needs the Solr KEYS
exported to a legacy-format keyring first: Helm reads ~/.gnupg/pubring.gpg by
default, which GnuPG 2.1 and later no longer write.
@HoustonPutman

Copy link
Copy Markdown
Contributor Author

This now incorporates the changes from #863, merged in with all of its commits, so that the docs present both chart sources:

  • The Antora pages (running-the-operator, local-tutorial, upgrade-notes) show the two sources as tabs, OCI Charts (the default) and Charts Repo, like the v1/v2 API tabs in the Solr Ref Guide. The tutorial's tabs are synced, so a choice carries through every step.
  • The chart READMEs and the top-level README are Markdown, which has no tabs, so they use matching "OCI Charts" / "Charts Repo" subsections.
  • The HTTPS repository is no longer described as deprecated, since it now lists the OCI charts. In both chart changelogs, Document the OCI registry as the default Helm chart source #863's deprecated entry is replaced by an added entry for the OCI charts and a changed entry for the repository.
  • A new "Verifying the Helm charts" section in the upgrade notes shows --verify with a keyring exported from the Solr KEYS, for both sources, and is linked from the install docs and the READMEs.

Once this is merged, #863 can be closed as superseded.

# Conflicts:
#	docs/modules/upgrade-notes/pages/upgrade-notes.adoc
#	helm/solr-operator/Chart.yaml
#	helm/solr/Chart.yaml
@HoustonPutman
HoustonPutman merged commit fdfc8f3 into apache:main Nov 19, 2026
4 checks passed
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.

2 participants