Helm Render Intents

UNOFFICIAL/EXPERIMENTAL

This page explains how the catalog records a Helm render. A HelmRenderIntent is the Helm-specific source and intent record: it says where the rendered objects came from, which Helm choices produced them, and which prerequisites or lifecycle work belong with them.

If you are reading the public website, the first word you see is preset. In this repo, that same supported chart choice is usually called a base variant. A preset/base variant is a named way to render one chart version, such as default, no-crds, reuse-existing-secret, server-only, or ha.

Start with these questions:

For this chart, which named Helm render did we use?
What exact Kubernetes objects did it produce?
What extra work does the chart need around those objects?
Can ConfigHub keep managing those objects after that?

The Short Model

chart version
  base variant: named Helm render choice
    render intent: inputs needed to repeat the render
    render variant: Kubernetes objects captured from that render
  managed variant: ConfigHub version made after the render

A component is an application or platform package: Redis, Prometheus, ingress-nginx, a payments API, or a custom app.

The terms mean:

Do not stop at release-objects.yaml when you need the full record. That file is the Kubernetes object output. The render intent, revision, lifecycle routes, target facts, receipts, and chart page explain the Helm inputs and any hook, CRD, setup-job, Secret, or target-prerequisite work around that output.

Values, ConfigHub Changes, And Live State

Every intent has a spec.settingSources section:

This is the machine-readable form of the table shown on every chart page and in every demo Space README. It does not claim that every rendered field can be traced back to one exact Helm value key; arbitrary chart templates make that claim unsafe. It does show which layer supplied the base and which changes happened later in ConfigHub.

Render Variant Examples

These examples are current catalog rows:

The default and reuse-existing-secret Redis rows are different base variants because they ask Helm to render different security choices. Each one has its own render intent and its own captured output.

The Kube Prometheus Stack no-crds intent links the exact Argo CD and Flux receipt. Both controllers installed 85.3.3, upgraded to 86.1.0, replaced the two completed setup Jobs, and passed the recorded runtime checks. Direct apply has not run that upgrade, and ConfigHub does not select the route automatically. Read the controller result.

The Full Model Underneath

chart/version
  recipe
    base variant
      render intent
        render variant / rendered revision
          package base
            ConfigHub Units
              managed variants
                promotions / targets / observations

The full model matters because Helm charts often need work outside normal rendered objects: CRDs, hooks, generated facts, target facts, webhook certificates, namespaces, cloud identity, external Secrets, or setup jobs.

A render intent records:

• which chart and version are used;
• which preset/base variant is being rendered;
• which values profile, namespace, release name, capability profile, and source lock are part of the render;
• which installer package OCI ref users pull for that chart version;
• where the full rendered YAML is stored;
• where the revision/checksum record is stored;
• which evidence lanes exist for the row;
• which lifecycle routes and target prerequisites are known.

The target-prerequisite section has two parts:

• targetFacts.declared is the original declaration copied from the base variant. When the installer package carries the exact CRDs, each CRD also gets a packageSource and repository packagePath.
• targetFacts.requirements turns that declaration into a consistent list of Secrets, CRDs, namespaces, values, storage, DNS names, or topology. Each item says whether it must be checked before render or before apply. The default freshness rule is one render or one apply, so a previous check is not reused for the next operation. Its check field uses the packaged CRD file instead of a placeholder command when that file exists.
• targetFacts.actions contains follow-up work derived from an observed failed or blocked run. A base can have declared facts even when no failure has produced an action record.

For a chart with lifecycle routes, each route names the version that supplied its evidence. It has separate records for direct commands, Argo CD, and Flux. pass means that exact path ran. mapping-only explains how the controller would handle the work but does not claim that it ran.

If a route is carried forward from another chart version, the route remains visible as a useful starting point, but the lifecycle coverage state becomes actionable-gap. The kube-prometheus-stack 86.1.0 intent now points to its own packaged CRDs and records that it passed as the target of the 85.3.3 to 86.1.0 controller upgrade. Its inherited route descriptions still point to 85.3.3 evidence, so the intent does not present that bounded upgrade result as a fresh 86.1.0 install or as proof for a different version pair.

Coverage For Every Base

Every generated render intent has two coverage states:

no-route-required and no-target-facts-required are explicit decisions. A missing declaration does not receive either state.

The current work list is generated here:

• human-readable gap list
• CSV gap list

The gap list currently includes bases whose hooks still need a route, bases whose route evidence comes from another chart version, and bases that have not yet said what the target must provide.

Why We Generate It

The render intent gives people and agents one file that names the render inputs and the matching output.

For a chart with CRDs, hooks, setup jobs, or external Secrets, it also points to the recipe, captured render variant, package base, receipts, and matrix row.

We do not generate render intents for candidate or custom-discussion rows yet. Those rows stay visible in the matrix, but they are not treated as runnable configs until the underlying base path is real.

Current Generated Surface

The generated surface is here:

• summary
• CSV
• JSON
• per-intent YAML files under data/helm-render-intents/intents/
• contract
• contract gaps

The verifier is:

npm run helm-render-intents:verify
npm run helm-render-intents:contracts:verify

That verifier checks the generated objects against the master matrix, the base variant's declared target facts, lifecycle-route data, GitOps route mappings, and target-prerequisite action data. It also fails when an evidence path is missing, a route hides chart-version drift, a prerequisite lacks a check point or freshness rule, or the generated gap list omits an incomplete base.

What This Does Not Claim

A render intent is not a production promise. It does not say every live lane is green. It does not make hooks automatic. It does not create ConfigHub server state by itself.

It says something narrower: this Helm preset/base variant has a real catalog path, and the inputs, captured output, evidence links, and known extra work are recorded in one machine-readable object.