> ## Documentation Index
> Fetch the complete documentation index at: https://docs.celum.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Registries

> Where charts and images come from — registering one, why "reachable" is not the check that matters, and mirroring an estate that cannot reach the internet.

A **registry** is a place Celum pulls charts and images from, and pushes mirrored copies into. Registering one is what turns a public-upstream install into an internal-mirror install — for an air-gapped estate, for a restricted one, or simply to stop depending on someone else's uptime.

Registries have a page of their own, **Registries** in the sidebar's global section. They are kept in Celum's database and shared across supervisors. **Which registry a given supervisor actually uses is a separate decision** — see [Charts & the mirror](https://docs.celum.io/gitops/charts.md) for the resolution order, and note that a supervisor's own declaration beats every global default.

## "Reachable" is not the check that matters

This is the one thing to take from this page.

> [!WARNING]
>
> **A registry health endpoint answers for anonymous and for wrong credentials.** Harbor's does. So a credential that can only *pull* registers cleanly, reports healthy, lists charts, and fails the first time anything needs to be **pushed** — which is every mirror and every pre-pull.
>
> On one estate a credential with a non-existent username sat in place for days looking fine. The symptom when it finally bit was nothing to do with credentials: an install failed with *"Unable to apply the Cilium configuration"*, and the version picker marked **every** version as needing a fetch — including two that were physically stocked in the registry.
>
> **Test** does a real push probe rather than a health check: it starts a blob upload and cancels it, so nothing is committed but the actual push-scope token handshake is exercised. It reports **Push OK** or **Pull-only (no push)**. Read that, not the reachability.

## Registering one

> [tab] Dashboard
>
> **Registries → Add registry**, then **Test** before relying on it.

> [tab] API
>
> `POST /api/registries` creates one, `POST /api/registries/{id}/test` runs the push probe, `POST /api/registries/{id}/test-charts` checks the chart side specifically.

> [tab] MCP
>
> `create_registry`, `update_registry`, `list_registries`, `test_registry`, `test_registry_charts`. Deleting a registry has no tool.

### What the form asks

| Field | What it decides |
| - | - |
| **Chart registry** | Serve the platform's third-party Helm charts (Cilium, Rook, cert-manager, kube-prometheus-stack, …) from this registry instead of their public upstreams. Only one chart registry is active: turning it on here turns it off on the registry that had it. |
| **Image registry** | Rewrite the platform's own container images (the cluster agent, …) to this registry, and pull Nuvira's own charts from it. Also one at a time. |
| **Name** | The label supervisors refer to it by. |
| **Project / push prefix** | The Harbor project the platform's images land under. It doubles as the OCI path for Nuvira's own charts (`oci://<host>/<project>`); left empty, they resolve from `oci://<host>/charts`. |
| **URL** | The registry host; `https://` is assumed. |
| **Site** | Bind the registry to a site: clusters on that site install charts and images from it. A registry with no site serves every site that has none of its own. |
| **Username, Password / token** | A robot account or user with **push** rights to the project — see the warning above. |
| **Skip TLS verification**, **CA certificate (PEM)** | Trust a private CA by pasting it, rather than skipping verification. |
| **Pre-pull all images in the background** | On add only: start mirroring every required platform image as soon as the registry exists. It runs server-side. |

Each row then offers **Test** (the push probe), **Check charts** (which of the chart versions the platform needs are stocked; read-only, copies nothing), **Mirror charts** and **Pre-pull images**.

> [!NOTE]
>
> **Registries are referenced by name, not by id.** A supervisor declares which registry it uses by naming it, so the credentials stay in the catalogue Celum reads server-side rather than on a cluster-scoped resource anyone with read access could see. A name that matches no registered registry is normally rejected — because the resolver would otherwise fall back silently and a saved-but-inert choice is invisible to whoever saved it.

## Mirroring an estate that cannot reach the internet

Two halves, and they are separate because charts and images travel differently.

**Charts.** `POST /api/registries/{id}/mirror-charts` copies the platform catalogue's charts into the registry. A chart is stocked on demand at install time too, but only when the stock check *succeeded and found it missing* — on a read error Celum deliberately does **not** push, and lets Flux pull instead. That asymmetry exists because a read failure once forced a write, and a pull-only credential then turned a recoverable "version not found" loop into a hard install failure.

**Images.** `GET /api/registries/required-images` lists every image the platform needs to bring a cluster up, with a count — the list to mirror before onboarding an air-gapped supervisor. `POST /api/registries/{id}/prepull` pulls them into the registry, asynchronously; poll the job.

Pointing the **nodes** at a mirror is a third thing again, configured per supervisor rather than here: the containerd mirror declaration maps each upstream to a proxy-cache project. The credential for it is matched **by host** against these registered registries, so register the mirror here first — an unmatched host silently yields an anonymous pull, which works on a registry whose proxy projects allow anonymous read and fails on the first one that does not.

> [!NOTE]
>
> **Guest clusters inherit all of this, and nothing about it is declared twice.** What a guest's nodes and add-ons resolve to, which charts are redirected and which are deliberately withheld, and why "pull through local Harbor" being supervisor-only does not contradict any of it — [Registry mirroring in depth](https://docs.celum.io/gitops/registry-mirroring.md) maps every channel end to end.

## Image buckets

The page's second tab, **Image buckets**, holds the S3 / MinIO bucket connections the [Image library](https://docs.celum.io/vms/image-library.md) imports disk images and ISOs from. A connection has:

* a **supervisor**, which gets the connection's credentials as a Secret in its image-library namespace;
* a **name**, and optionally a **site**, which makes it the default bucket for supervisors on that site;
* a **content** label, free text shown on the row and used to pre-filter the object picker (it enforces nothing);
* the **endpoint URL**, the **bucket**, and an **access key ID** and **secret key**, held by the platform.

Over MCP: `create_image_bucket`, `update_image_bucket`.

## What commonly goes wrong

| Symptom | Cause |
| - | - |
| The registry tests as reachable and mirroring fails | the credential is pull-only. Read the push result, not reachability |
| The version picker says every version will be fetched | the chart-tag read failed — usually the same credential. The picker carries a note saying so |
| An install fails immediately on a supervisor with a mirror | the same, one layer down: nothing could be read, so nothing could be confirmed stocked |
| A declared registry is ignored | the name matches no registered registry, so resolution fell back |
| Nodes pull from the internet despite a mirror | the containerd mirror is declared per supervisor and is a separate setting from this catalogue |
| An anonymous pull works in one project and not another | the mirror host did not match a registered registry, so no credential was attached |

## Related

> [card] [Charts & the mirror](https://docs.celum.io/gitops/charts.md)
>
> Which registry a supervisor resolves to, and the audit for releases installed before it was declared.

> [card] [Platform onboarding](https://docs.celum.io/get-started/platform-onboarding.md)
>
> Where a supervisor declares its chart and image sources — the first step, before anything is installed.

> [card] [App catalog](https://docs.celum.io/gitops/app-catalog.md)
>
> Third-party charts, which carry their own repository URL.

> [card] [Image library](https://docs.celum.io/vms/image-library.md)
>
> VM golden images — a different kind of artefact, stored as PVCs rather than in a registry.

> [card] [Registry mirroring in depth](https://docs.celum.io/gitops/registry-mirroring.md)
>
> Every channel end to end — what guests inherit, what is Harbor-specific, and the two credential traps.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.