Chart Repositories

### Two files, two roles A classic Helm chart repository is nothing more than a web server that serves an `index.yaml` plus a set of packaged `.tgz` charts. Everything `helm repo add` does happens on *your* machine - it does not register you with the server, and it does not tell the cluster anything. The first artefact is **`repositories.yaml`**, the list of repositories you have added: a name, the base URL, and any credential or TLS settings you supplied. Its location is `HELM_REPOSITORY_CONFIG`. This is per-user CLI state; nothing about it is stored in the cluster and nothing about it travels with a chart. The second is the **cached index**, written under `HELM_REPOSITORY_CACHE` (one file per repository). `helm env` prints both paths on any machine, which is the fastest way to answer "where is Helm actually reading from here?" during triage. ### What `index.yaml` contains The index is a full catalogue of the repository, not a pointer to one chart. For each chart name it holds an entry per published version, and each entry carries the chart `version`, the application's `appVersion`, a description, a creation timestamp, a `digest`, and one or more `urls` giving where the `.tgz` can be downloaded. An internal repository serving an 18-chart umbrella plus its history can easily reach a couple of thousand entries - a monitoring repository in one shop I have seen listed 2,317 chart versions in a single file - which is why `helm repo update` on a slow link is not instant. ### Why the cache goes stale, by design `helm repo add` fetches the index once, at add time (which is also why a typo'd URL fails immediately, reporting that the URL is not a valid chart repository or cannot be reached). After that, Helm treats the cached copy as authoritative until you refresh it. Resolution of `monitoring/monitoring-stack` at install, upgrade, pull, template or search time reads the cached file only. There is no TTL, no background refresh, and no automatic re-fetch on a miss. So the classic junior-day incident is: a colleague publishes `monitoring-stack` 4.11.2, tells you to install it, and your `helm install` fails with an error saying no chart version was found for that chart, plus the hint to try `helm repo update`. You run `helm repo update` and the same command now succeeds. Nothing was wrong with the repository; your catalogue was simply older than the publication. The mirror image is just as common and more confusing: `helm search repo monitoring/monitoring-stack --versions` happily lists versions while you are on a plane, because search is served entirely from the cache. Offline results are not proof the repository still exists or still holds those versions. ### The rest of the command family - `helm repo list` prints the configured name/URL pairs (`-o json` if you are scripting it). - `helm repo update` refreshes every configured repository; passing one or more names refreshes only those, which matters when one repo in your list is unreachable and you do not want the whole command to grind. - `helm repo remove <name>` deletes the entry and its cached index files. - Re-adding a name that already exists is rejected unless you pass `--force-update`, which replaces the existing entry - the flag to reach for when a repository moves to a new URL. ### Where this bites in CI A fresh CI runner has an empty `repositories.yaml`, so any pipeline that installs from a repository must `helm repo add` and `helm repo update` as explicit steps; "it works on my laptop" here means "my laptop has state your runner does not." The opposite failure appears when a pipeline caches the runner's Helm home to save a few seconds: now the runner has a *stale* index that it never refreshes, and the deploy job silently keeps selecting the version that was newest whenever the cache was seeded. If you cache anything, cache the packaged charts, not the index - and keep the `helm repo update` step unconditional. ### The boundary worth naming All of the above is the classic index-based repository. A chart referenced as `oci://...` is addressed directly in a registry and has no `index.yaml` to add, update or search - so none of this cache machinery applies to it, which is a separate topic in its own right. And this is purely client-side state: how the server produces or serves that index belongs to whoever runs the repository.