Browse Docs
Catalog
Config
Stacks
Operate
Docs

Shared fork vocabulary + current→canonical mapping

Every chart today has exactly 2 bases (a default:true + one fork), but the names are ad-hoc. The same dimension is named many ways, so a user can't predict the menu: View source markdown.

Status: working reference. Built from the actual bases of all 20 top-20 catalog charts, not invented.

The problem, in one table

  • default role is named 6 ways: default (×11), static-passwords (×5 secret charts), single-binary-filesystem (loki), http-clusterip (nginx), local-persistent (tempo), default-control-plane (consul).
  • existing-secret is named 5 ways across 7 charts: reuse-existing-secret, existing-secret, existing-secret-replicaset, existing-secret-ingress, secure-mesh-existing-secrets.
  • ingress is named 3 ways: ui-ingress, existing-tls-ingress, …-ingress.
  • no-crds vs crds: 3 charts ship no-crds, cert-manager ships the inverse crds-enabled.

Canonical fork vocabulary (proposed)

dimensionmeaningcomposes?
defaulthonest OOTB base (role = default:true); zero placeholders where possible-
parameterizedsame shape as default; fill-safe fields exposed as placeholders-
existing-secretBYO secret instead of generated (the F3 fix-path)yes
ingress-tlsexternally exposed via ingress (+ TLS)yes
hahigh-availability / scalable deployment modeyes
no-crdsCRDs owned externally (GitOps/controller)yes
minimallean: drop optional components / persistenceyes
tlsBYO TLS material / CAyes

Forks compose (e.g. existing-secret + ingress-tls). The catalog should name a fork by its canonical dimension(s), not a bespoke string.

Current → canonical mapping (all 20)

chartdefault base (current)fork (current)→ canonical
redisdefaultreuse-existing-secretexisting-secret
postgresqlstatic-passwordsexisting-secretexisting-secret
rabbitmqstatic-passwordsexisting-secretexisting-secret
mysqlstatic-passwordsexisting-secretexisting-secret
mongodbstatic-passwordsexisting-secret-replicasetexisting-secret + ha
grafanastatic-passwordsexisting-secret-ingressexisting-secret + ingress-tls
consuldefault-control-planesecure-mesh-existing-secretsexisting-secret (+ mesh)
external-secretsdefaultno-crdsno-crds ✓
argo-cddefaultno-crdsno-crds ✓
kube-prometheus-stackdefaultno-crdsno-crds ✓
cert-managerdefaultcrds-enabledcrds (inverse - default should be no-crds for GitOps)
longhorndefaultui-ingressingress-tls
nginxhttp-clusteripexisting-tls-ingressingress-tls (+ existing-secret for TLS)
metrics-serverdefaultexternal-tls-catls
vaultdefaultha-raft-uiha
lokisingle-binary-filesystemsimple-scalable-minioha (scalable + object store)
tempolocal-persistents3-query-observabilityha (object store)
prometheusdefaultserver-only-ephemeralminimal
ingress-nginxdefaultadmission-disabledminimal
secrets-store-csi-driverdefaultsync-secret-rotation(chart feature: rotation)

What the data shows

  • No chart has a parameterized base yet - the doctrine's explicit fill-surface is net-new across the catalog.
  • The catalog is under-forked: every chart has only 2 bases; the doctrine allows default + parameterized + ≤4 forks. Most charts have obvious additional standard forks they don't yet ship (e.g. the secret charts could all offer ingress-tls and ha).
  • Secret-chart defaults are the F3 hazard: all 5 static-passwords defaults are the silently-broken-over-GitOps case. Under the doctrine their honest default either declares the required secret fill or ships existing-secret as the recommended base.

Migration recommendation

  1. Adopt the canonical dimension names; keep bespoke shape names only as descriptive suffixes where they add meaning (e.g. ha for vault, with raft an implementation detail, not the fork name).
  2. Alias old names → canonical for one release so existing references don't break.
  3. Normalize the default role: the menu always presents the default:true base as "default" regardless of its underlying descriptive name.
  4. Flip cert-manager's default to no-crds (GitOps-consistent), with crds as the fork.

Sources

The current top-20 package bases, Catalog Doctrine, and the generated status and outcome data under data/.

Generated from the committed markdown file docs/reference/fork-vocabulary.md. The source file is the authoritative version.