App catalog

An app definition is a reusable blueprint for one piece of software: where its chart lives, which version to install, which namespace it belongs in, and a values file written as a Go template so the same definition produces cluster-appropriate values on every cluster. Definitions are stored in Celum’s database, so they are supervisor-agnostic — the catalog is one list for the whole platform. GET /api/apps returns all of them; GET /api/apps/enabled returns only the enabled ones.

What the catalog feeds. It is the curated chart source for installs onto a cluster: the Install App flow reads /api/apps/enabled for its chart picker and installs through POST /api/clusters/<cluster>/helm-releases, which becomes a Flux HelmRelease on a supervisor or a CAAPH HelmChartProxy on a guest cluster. The upgrade path uses the same list to resolve a release’s chart source.Nothing goes through Git: the ArgoCD Applications and committed files earlier releases generated are gone — see Repositories & manifests.

What a definition holds

[
  { "id": "447bd7ac-d53d-4cba-bbe3-aac7b15e6faa",
    "name": "blackbox-exporter", "displayName": "Blackbox exporter",
    "description": "Probes HTTP, TCP and ICMP endpoints for Prometheus",
    "helmRepoUrl": "https://prometheus-community.github.io/helm-charts",
    "chartName": "prometheus-blackbox-exporter", "chartVersion": "9.1.0",
    "chartRegistry": "", "category": "exporter",
    "targetNamespace": "monitoring",
    "rawValues": false, "params": [],
    "isTanzuPackage": false, "sortOrder": 0, "enabled": true },

  { "id": "fca8d01c-0f94-45bf-9b7c-cdce6152c723",
    "name": "external-dns", "displayName": "External DNS",
    "description": "Synchronizes exposed Kubernetes Services and Ingresses with DNS providers",
    "helmRepoUrl": "https://kubernetes-sigs.github.io/external-dns",
    "chartName": "external-dns", "chartVersion": "1.16.1",
    "targetNamespace": "external-dns",
    "isTanzuPackage": false, "sortOrder": 3, "enabled": true }
]

Field	Meaning
`name`	The stable key, and what `POST /api/apps/import` upserts on — treat it as immutable once in use.
`displayName`, `description`	What the picker shows.
`helmRepoUrl`, `chartName`, `chartVersion`	The chart source. An `https://` repo is read through its `index.yaml`; an `oci://` URL is read through the OCI registry’s tag list. An empty `chartVersion` means “whatever the source resolves to”.
`chartRegistry`	Optional: a registered registry the chart is pulled with, so the install takes its credentials. Empty means the chart URL is pulled as it is.
`category`	A grouping shown in the catalog (`exporter`, …).
`targetNamespace`	Where the release lands in the destination cluster. The install flow offers a create-namespace toggle for it.
`valuesTemplate`	The per-cluster values file, as a Go template. See below.
`rawValues`	”Values as written”: the values are installed exactly as typed, `{{ }}` included, for a chart that renders its own templates.
`params`	Values the operator supplies at install time, referenced as `{{.Params.<name>}}` — each with a `description`, optional `required`, `example` and `pattern`.
`isTanzuPackage`	Switches delivery from “Helm chart + values” to “commit these package files” — see Tanzu packages.
`sortOrder`	Ordering in the picker.
`enabled`	Whether the definition is offered at all.
`packageFiles`, `extraResources`	Legacy: named YAML files that were committed alongside the app. Stored and exported, never installed — see Tanzu packages.

The values template

valuesTemplate is plain Go text/template. The definition stays generic and the substitution makes it specific:

# params: [{ "name": "domain", "required": true, "example": "apps.example.com" }]
ingress:
  enabled: true
  hostname: grafana.{{.ClusterName}}.{{.Params.domain}}

provider: pdns

domainFilters:
  - {{.Params.domain}}

policy: sync
txtOwnerId: {{.ClusterName}}

The rendered result is what the chart receives — a normal values file, with no templating surviving into the cluster. The template is rendered when the app is installed, with this context:

Variable	Value
`ClusterName`	the cluster the app is installed on
`Supervisor`	the supervisor that cluster lives on
`Namespace`, `ClusterNamespace`	the namespace the release is installed into
`ReleaseName`	the Helm release name
`Params.<name>`	the values supplied for the app’s declared `params`

Domain, Environment, Region and StorageClass are always empty at install time. They belonged to a cluster-creation form that no longer renders catalog apps, so a template that depends on {{.Domain}} installs those lines blank. Declare a param instead ({{.Params.domain}}) and the install asks for it.A required param that is missing, or a value that does not match its pattern, is refused with 400 before anything renders. A param the template uses but the install does not supply renders empty.

With Values as written (rawValues: true) none of this applies: the values are installed exactly as typed. A values file with no {{ is installed as it is either way.

Preview and validate before you save

Three endpoints let you check a definition without creating anything.

Render — see the values a cluster would get

POST /api/apps/render takes { "template": "...", "formData": { ... } } and returns { "rendered": "..." }, rendered with exactly the formData you send. To preview an install, send the install context above. A malformed template comes back as 400 with the parser’s own message, so a typo is caught in the editor rather than at install. Action: app:Render.

Helm check — does that chart and version exist?

POST /api/apps/helm-check takes { "helmRepoUrl", "chartName", "chartVersion" } and answers each question separately:

{ "repoReachable": true, "chartFound": true, "versionFound": false,
  "latestVersion": "1.17.2",
  "availableVersions": ["1.17.2", "1.17.1", "1.17.0"] }

repoReachable: false with an error string is a URL or network problem; chartFound: false on a reachable repo means the chart name is wrong; versionFound: false means the version is. At most 20 versions come back, newest first. Both https:// and oci:// sources are supported. Action: app:HelmCheck.

Helm values — start from the chart's own defaults

POST /api/apps/helm-values takes the same body and returns { "values": "..." } — the chart’s default values.yaml. Use it as the starting point for a values template instead of guessing key names. Same action, app:HelmCheck.

The enabled flag

enabled: false keeps a definition in the catalog but out of every picker that reads GET /api/apps/enabled. Use it to retire an app without deleting its definition — nothing already installed is affected, because a running release does not consult the catalog. Deleting a definition does not uninstall anything. It removes the blueprint only; releases installed from it keep running, and the cluster’s Helm state is where they are visible afterwards.

Tanzu packages

isTanzuPackage and extraResources are legacy fields. They described how a definition was turned into committed files — package manifests under an apps/packages/ directory, extra resources under apps/resources/ — and that commit path no longer exists. The fields are still stored and still round-trip through export and import, so an old catalog imports without loss, but nothing consumes them.Treat a Tanzu-flagged definition as inert rather than broken. To deliver something that is not a Helm chart, wrap it in a chart and add that to the catalog.

Import and export

The whole catalog moves between installations as one JSON document.

GET /api/apps/export returns every definition with id, createdAt and updatedAt stripped, served as an attachment. Action: app:Export.
POST /api/apps/import accepts that array and upserts by name — matching names are updated in place, new ones created. The response counts both and lists per-app failures rather than aborting the batch:

{ "created": 3, "updated": 8, "errors": [] }

Because the key is name, an export/import round-trip is idempotent, and renaming an app in the source installation creates a second definition in the target rather than renaming the existing one.

Permissions

Task	Action	KRN
List the catalog (all or enabled)	`app:List`	`krn:celum:app:*`
Read one definition	`app:Get`	`krn:celum:app:<id>`
Create / update / delete	`app:Create` / `app:Update` / `app:Delete`	`krn:celum:app:*` · `krn:celum:app:<id>`
Render a values template	`app:Render`	`krn:celum:app:*`
Validate a chart or fetch its values	`app:HelmCheck`	`krn:celum:app:*`
Export / import the catalog	`app:Export` / `app:Import`	`krn:celum:app:*`

Note that app:Delete is scoped per definition while app:Create is not — you can grant deletion of specific apps without granting creation.

Repositories & manifests

Where the GitOps repositories went, and what replaced them.

Charts & the mirror

Finding a chart to point a definition at, and why a version list can come back empty.

Cluster templates

The same Go-template model applied to whole clusters rather than single apps.

Day-2 operations

The Helm view of what a definition eventually becomes on the cluster.

Celum AI reads this catalog directly — list_apps returns the definitions (with kind=enabled for the creation-time subset), get_app returns one in full including its values template, and search_helm_charts covers the discovery step before you add one.

Get Started

Concepts

Clusters

GitOps & Apps

Virtual machines

Networking

Security

Platform Health

Storage

Reference

Administration

What a definition holds

The values template

Preview and validate before you save

The enabled flag

Tanzu packages

Import and export

Permissions

Repositories & manifests

Charts & the mirror

Cluster templates

Day-2 operations

​What a definition holds

​The values template

​Preview and validate before you save

​The enabled flag

​Tanzu packages

​Import and export

​Permissions

​Related

Repositories & manifests

Charts & the mirror

Cluster templates

Day-2 operations

What a definition holds

The values template

Preview and validate before you save

The enabled flag

Tanzu packages

Import and export

Permissions

Related