Residue Families - what a non-green row actually means

Generated at: 2026-07-30T12:38:02.000Z UTC · source: committed helm-expt evidence for this rendered repository document.

UNOFFICIAL/EXPERIMENTAL

When the master catalog matrix shows a row as watch or blocked instead of pass, the decision surfaces tag it with a residue category - the kind of gap that stopped the row from being green. This page is the plain-English vocabulary for those categories: what each family means for a Helm user, who has to fix it, the next action, and where the rows live.

It is reference only. The authoritative per-row classifications are generated into the decision surfaces - this page names the families behind them.

For the matrix itself (lanes, the G/P/K shorthands, the cell states), read reading-the-matrix.
For the live per-row decisions, read live-parity-decisions (G/P-lane) and kind-parity-decisions (K-lane).
To pick the next row to work, read live-parity-rerun-plan.

How to read a residue, honestly

A watch row is known evidence with a named residue. The semantic Helm-vs-ConfigHub parity already passed - the delivered objects match regular Helm - but a runtime, controller-health, image, or operational condition still needs review. It is not a pass and not a failure.
A blocked row did not reach the lane result. Its residue names why and who owns the fix.
A residue category never turns a watch into a pass or a failure. It explains the gap and routes the fix. Nothing here is automatic or "solved" by tagging it - a family is a decision, not a repair.

The families

Family names are grouped by theme. The same theme can carry a slightly different category key (and a different owner) in the G/P-lane vs the K-lane, because the two lanes prove different things; both keys are listed.

Family	What it means for a Helm user	Who fixes it	Usable today?	Lane · category key
Target prerequisite	The rendered objects matched regular Helm; a named prerequisite (Namespace, Secret, or CRD) is missing on the target. The prerequisite is missing, not the configuration.	user	Yes, after you stage the prerequisite	G/P · `target-prerequisite` - K · `target-prerequisite-crds` / `-secret` / `-namespace`
Remote image	Parity passed, but the chart references a container image the target cannot pull (removed/renamed tag, private or paid registry, rate-limited pull). The workload can't start until the image is reachable.	catalog or image publisher	Watch - until the image reference is resolved	G/P · `remote-image`
Render input	Required Helm input values are missing, so the base renders incomplete or invalid objects. Regular Helm and ConfigHub block on the same validation.	catalog (G/P: needs a better base) · user (K: supply values)	No on the default base - until inputs are supplied or a better base is chosen	G/P · `render-input` - K · `render-input`
Capability profile	Parity passed, but the base rendered for a Kubernetes capability the target does not serve (e.g. an APIService version a newer cluster dropped). A render-profile / base-selection issue, not a semantic diff.	catalog	Depends - use or promote the base rendered for the target's API set	G/P · `capability-profile` - K · `capability-profile-diff`
Hook / lifecycle	The chart relies on a Helm hook or controller-populated lifecycle behavior (e.g. a certgen Job) that config-only delivery does not run. Needs a lifecycle route or staged equivalent.	catalog	No - until a lifecycle route is decided	K · `hook-lifecycle` (see lifecycle-route-actions)
Platform target fit	Parity passed, but the target does not provide the platform shape required by the base (for example AWS/EKS metadata, provider identity, schedulable node count, or load-balancer behavior).	user or catalog	Watch - use a target that satisfies the base, or create a target-scoped base	G/P · `target-fit`
Target runtime	The rendered config matched regular Helm, but the workload did not reach the expected runtime state on the target. Runtime residue to review.	needs runtime review	Watch - config correct, runtime unconfirmed	G/P · `target-runtime` - K · `target-runtime`
GitOps controller health	Synced through ConfigHub OCI/Argo and converged, parity passed - but Argo's aggregate health reads Progressing, or a resource reads OutOfSync while Healthy.	needs GitOps controller-health review	Watch - synced and converged; aggregate health needs explanation	G/P · `gitops-runtime`
Operate policy	Parity passed, but an operational readiness step (for example init/unseal) is required before the workload is fully ready.	needs operate review	Watch - needs an operational step	G/P · `operate-policy`
Model / semantic gap	The ConfigHub delivery did not match the live Helm result (a semantic/model difference, a missing target fact, or a render difference). Not a user action.	catalog	No - needs catalog/model work	G/P · `semantic-model-gap` - K · `model-gap-render` / `model-gap-target-fact`

Live counts per family change as the live lane runs; read the decision surfaces above for the current rows - this page deliberately does not hard-code numbers.

Remote image, in detail (worked example: Contour)

remote-image is the family a Helm user is most likely to hit first, because it looks like a chart failure but is really an image-availability problem on your target.

Worked example - bitnami/contour@21.1.4 (default and no-crds):

Regular Helm itself blocks: the pre-install certgen Job can't start because the pinned docker.io/bitnami/contour image is not pullable (ImagePullBackOff).
ConfigHub direct apply and ConfigHub OCI/Argo preserve semantic parity - the delivered objects match regular Helm - but the row stays watch because the hook-generated TLS Secrets (contourcert, envoycert) are absent and the pods do not become ready. (That second half is a hook/lifecycle residue layered on top - see the hook/lifecycle family.)

So the row is honest: parity is proven, but the chart can't run on a target that can't pull its image. The same family covers Apache, OpenSearch, and the Istio gateway rows.

What a user or the catalog can do - none of these is applied automatically:

Catalog refresh - move the base to a currently-published image tag.
Digest pin - pin a digest that is still retained in the registry.
Registry mirror / pull secret - point the target at a mirror, or supply an imagePullSecret for a private/paid registry.
Image override - override the image reference to one your target can pull.
Registry policy - accept a private/paid-registry requirement as a scoped support boundary.

This is a decision family, not a fix. Tagging a row remote-image does not make the image pullable; it tells you the parity question is already answered and the open question is image retention/access on your target.

Distinguish it from neighbours: target-runtime means the image pulled but the workload misbehaved; render-input means values were missing before any image mattered; hook/lifecycle means a hook action (not an image) is the gap.

Platform target fit, in detail (worked example: AWS EBS CSI)

Some charts need a specific platform identity rather than a generic Kubernetes target. The committed AWS EBS CSI receipt is the concrete example:

Regular Helm, ConfigHub direct apply, and ConfigHub OCI/Argo all preserve semantic object parity.
The workloads crash-loop on vanilla kind because the driver cannot read AWS instance metadata (IMDS), cannot find an AWS instance id in node providerID, and has no AWS region.
Argo pulls and applies the ConfigHub OCI payload, then reports the application as Synced / Degraded because the workload cannot run on that target.

That is platform target fit, not a render defect. A useful base needs an AWS/EKS-like target profile, or an explicit target-scoped base/refusal for non-AWS clusters. The chart-local support artifact is target-topology.yaml.

From a non-green row to a support decision

A residue category answers why a row isn't green and who fixes it. It does not by itself decide whether a chart/base is production-supported. To move a chart/base from watch/todo toward supported, target-scoped support, rejected, or superseded, the residue has to be resolved or explicitly accepted for a named scope, backed by fresh evidence. That decision and its required evidence are recorded separately:

production-support-decisions - the product states and how to work the queue.
production support decision contract - the required decision fields (supported base, target scope, delivery path, scan/image/lifecycle decisions, live evidence, support boundary).
capability-profile-catalog - for the capability-profile family, the named profiles a base can render against.

Boundaries

Reference only. The per-row classifications are generated into the decision surfaces; this page names the vocabulary behind them and does not assert any row's state itself.
A residue family is a routed decision, never an automatic repair, and never a reclassification of a watch as a pass.