skip to content

Why does helm search repo find nothing for charts in an OCI registry, and how do you discover versions?

level: seniorimportance: should knowfreq 40%

answer

  1. One command reads a local cache
  2. The other queries a submitted catalogue
  3. Neither ever asks the registry
  4. The tag list is the version list
  5. Rebuild the missing affordance as documentation

basics

~20 s

helm search repo reads cached index.yaml files from repositories added with helm repo add, and a registry has neither an index nor a repository entry. Discovery has to come from the registry's own tag listing, from a catalogue you publish, or from versions pinned in Chart.yaml.

solid answer

~50 s

`helm search repo` is a **local** search over the `index.yaml` files Helm cached for repositories added with `helm repo add`. A registry cannot be added that way and publishes no index, so there is nothing in the cache to match — the command returns nothing and no error. `helm search hub` does not help either: it queries a public hub that indexes charts publishers submitted to it, so a private registry path is invisible. What replaces it is the registry's own tag list. Helm itself uses that when resolving a SemVer range for an `oci://` dependency, and `helm show chart oci://.../tileserver --version 2.7.14` will read a specific version's metadata, but there is no `helm` command that enumerates charts in a registry. In practice teams query the registry's API or console for tags, publish a human catalogue of supported charts, and pin exact versions everywhere so discovery is never on the critical path of a deploy.

code

bash · 5 lines
bash
helm search repo tileserver
# no results: nothing was ever added to the local repository cache

helm show chart oci://registry.example.internal/platform-charts/tileserver --version 2.7.14
helm show values oci://registry.example.internal/platform-charts/tileserver --version 2.7.14

go deeper

for a junior

Know that a chart in a registry will not show up in Helm's search commands, and that you install it by naming the full oci:// reference and version instead.

for a middle

Explain the mechanism: one search reads a locally cached index, the other queries a submitted public catalogue, and a registry appears in neither.

for a senior

Show how you keep a team productive without search: a published catalogue, exact pins, a tag-listing helper, and reading chart versions back from release history during an incident.

for a principal

Weigh the trade openly. Decide whether your consumers browse or automate, and if they browse, own the documentation that replaces the affordance a registry does not provide.

## What helm search actually searches This question catches people because `helm search repo` fails *silently* — it prints nothing and exits successfully, which reads like "no such chart" rather than "I was never looking there". There are two search commands and neither one can see a registry: - **`helm search repo`** searches the **local cache**. When you run `helm repo add`, Helm downloads that repository's `index.yaml` — a file listing every chart, every version, and the URL of each archive — and caches it. `helm search repo` greps that cache. It makes no network call at search time, which is also why a stale cache silently hides a newly published version until `helm repo update`. - **`helm search hub`** queries a public hub that aggregates chart repositories which publishers have *submitted* to it. It has no knowledge of a private registry, and it does not crawl. A registry is not in either place. You cannot `helm repo add` it — there is no index for Helm to fetch — so nothing enters the cache, and no hub knows the path exists. The discovery affordance is simply gone. ## What is left **The registry's tag list.** Every OCI registry can list the tags published under a repository path, and that list *is* the version list for a chart, since the chart version is the tag. This is not a Helm feature — you reach it through the registry's own API, console, or CLI. It is the authoritative answer to "what versions of the tile-server chart exist?", and for a chart with 41 published tags it is the only complete one. **Helm's own range resolution.** When a `Chart.yaml` dependency names an `oci://` repository with a SemVer range, Helm asks the registry for that path's tags and resolves against them. So Helm *can* enumerate versions of a chart it has been told about — it just does not expose that as a search command over charts it has not. **`helm show`.** Given a specific reference and version, `helm show chart`, `helm show values` and `helm show readme` fetch and print that chart's metadata, defaults and documentation. That answers "what is in 2.7.14?" but never "what versions are there?". ## How teams operate without discovery The mature answer to this question is not a clever command, it is a set of habits: 1. **Publish a catalogue.** If your platform team ships a set of charts, the list of them and their supported versions belongs in documentation or a service catalogue, not in a tool's search output. This is the piece most teams skip, and then re-learn the hard way when a consumer cannot find out what exists. 2. **Pin exact versions everywhere.** In `Chart.yaml` dependencies, in CI, in whatever declares your deployments. If every reference is exact, nobody needs to search at deploy time, and the missing search is an inconvenience during authoring rather than a risk during a release. 3. **Make the registry's tag list reachable.** A short wrapper script or a CI helper that lists tags for a chart path removes the daily friction, and it keeps everyone reading the same authoritative source. 4. **Record what a release used.** Helm already stores the chart metadata with each release revision, so `helm get metadata` and `helm history` tell you what a given revision was installed from. On a release with a 34-revision history that is often faster than archaeology in the registry — the cluster remembers what it was given even when nobody remembers what was published. 5. **Do not let inspection substitute for a catalogue.** Pulling a chart to look at it is fine for one chart. It does not scale to "which of our forty charts supports the new cluster version". ## The trade being made It is worth being honest in an interview that this is a real regression, not a non-issue. Registry distribution buys you one artefact system, one authentication model, and one fewer static file to keep in sync — and it costs you browsability. Classic chart repositories are not deprecated; the documentation recommends registries, which is a different statement. A team whose consumers are internal, automated, and pinned loses almost nothing. A team publishing charts to a wide external audience that browses before installing loses the thing that made the audience able to browse, and has to rebuild it as documentation.

  • Would helm search hub find a chart published to your company's private registry?
    No. That command queries a public hub which indexes repositories publishers have submitted to it, and it does not crawl registries at all. A private path is invisible to it regardless of credentials. Treat both search commands as tools for the classic repository world and plan discovery for registry-hosted charts separately.
  • How do you find out which chart version a running release was installed from?
    Ask the cluster rather than the registry. Helm stores the chart's name and version with each release revision, so helm history shows the chart per revision and helm get metadata reports the current one. That works even if the tag has since been retagged or removed from the registry, which is exactly when you most need the answer.
  • Does the missing search affect a Chart.yaml dependency that uses a SemVer range against an oci:// repository?
    No. Helm resolves that range by asking the registry for the tags under the path, so ranges work. What is missing is a user-facing command to enumerate charts you have not already named. In practice you still pin exact versions in automation, so that Helm resolves nothing at deploy time and the deployed version is decided in review.

saying these in an interview costs you the question

  • Expects helm search repo to query a registry live
  • Thinks a public hub indexes private registry paths
  • Believes the registry serves a generated index.yaml
  • Confuses listing releases with listing chart versions
  • Says helm repo update refreshes registry contents
  • Treats the lost browsability as no real cost

context

resolving links…