Handle hooks and CRDs

1. Do the six steps

A plan names the work a chart needs. These six steps take it from named to observed for your target.

1. Choose the chart preset. Start from the chart page, not a generated package folder.
2. Read the chart extras. Look for hooks, CRDs, setup jobs, webhooks, generated Secrets, and target facts.
3. Check the disposition. observed has a receipt for the supported scope. routed, blocked, or per-target means the work is named but still needs setup, target input, or more evidence.
4. Supply the required target facts such as Secrets, CRDs, storage, hosted zones, or cloud accounts.
5. Run only the actions that are supported for that chart and target. A placeholder command is not a support claim.
6. The behavior becomes observed for your scope once a passing receipt covers it.

A known step is not an executed one. Every lifecycle action packet stays automatic: false today, while the declarative certified-bundle steps can be automatic. The value now is clear chart-specific guidance: you, a reviewer, or an agent can see where each hidden behavior goes and what it needs, instead of reverse-engineering Helm during an install.

Making the product execute observed or routed steps is separate, continuing work (issue 688).

2. Follow the worked examples through hooks and CRDs

Kube Prometheus Stack: the install order, and what stays manual

For the default preset, where the package owns the CRDs, the install order is fixed:

1. Apply the CRDs.
2. Wait until Kubernetes reports that every CRD is established.
3. Prepare the admission-webhook certificate Secret.
4. Apply the ordinary Kubernetes objects.
5. Check the webhook and workloads after the apply.
6. Record the result.

The order matters. A live CRD test showed that applying a custom resource before its CRD is established fails on a new cluster. Applying the CRD first, waiting, and then applying the custom resource works.

The no-crds render leaves CRDs out of the chart object set, but the installer package still carries the ten checked CRDs as a separate prerequisite. Its direct script keeps compatible CRDs that are already present, or applies the packaged copies on a new cluster, then waits before applying the workload.

These are the receipted steps for that same install order, by delivery path:

The Argo CD sync-wave order and the Flux dependsOn chain in that table are generated by the catalog's staged OCI packaging for the no-crds base. The direct-apply sequence above it is advice: you run those steps yourself with kubectl.

ConfigHub does not yet select the Kube Prometheus Stack route automatically. A person or automation still chooses the delivery mechanism and confirms that the chart version, target Kubernetes version, CRDs, and webhook behavior match the recorded plan. Direct apply has fresh-install evidence for both bases and 85.3.3-to-86.1.0 upgrade evidence for the default package route; Argo CD and Flux add fresh-install and the same upgrade for no-crds.

Read the full Kube Prometheus Stack walkthrough, including the apply check and every cited receipt.

Argo Workflows: install the right CRDs before the workloads

Argo Workflows is a useful example of work that Helm normally performs outside the rendered release. The chart's default configuration keeps its full CRDs out of the ordinary manifest output.

During install and upgrade, a Helm hook downloads eight CRD files from GitHub and applies them before the controller and server start. It uses forced server-side apply because the full schemas are too large for client-side apply.

The catalog's default package base keeps that behavior without an install-time download:

• The package contains the eight full CRD files used by argo-workflows@1.0.14.
• Each source URL and SHA-256 digest is recorded in the base variant.
• The generated no-account script applies the CRDs with kubectl apply --server-side --force-conflicts before the controller and server objects.
• Running the same step before an upgrade refreshes the CRDs in the same phase as Helm's pre-upgrade hook.
• The script waits for every CRD to become established before it applies the workloads.

This is a chart-specific replacement for one Helm hook, not a claim that one generic hook translator can safely handle every chart. The live comparison used two clean kind clusters, matched all eight CRDs by SHA-256, and matched the 19 ordinary chart objects. Read the receipt.

Read the full Argo Workflows walkthrough, including the smaller minimal-crds base.

Three more dispositions, in brief

3. Decide who owns each CRD

CRDs show up in three shapes across the catalog. A chart can ship its own CRDs and apply them itself, the way the Argo Workflows default base does. A chart can split CRDs into a separate no-crds base and leave the target cluster or another controller to own them, the way Kube Prometheus Stack does. Or a subchart inside an umbrella chart can carry an object that only works once the platform around it exists.

Kubara's generated umbrella charts assume the whole platform exists: they guard their ServiceMonitor behind the Prometheus-operator CRD, and cert-manager's ClusterIssuer is a custom resource that needs its CRD established first. So the bring-up order is CRDs, then controllers, then custom resources.

A CRD-guarded object is one the chart only applies once its CRD already exists, the way a ServiceMonitor needs the Prometheus-operator CRD and a ClusterIssuer needs the cert-manager CRD. Install the CRD, wait for Kubernetes to report it established, and only then apply the guarded object.

A hard chart carries one or more signals from the catalog's own matrix: CRDs, webhooks, cluster RBAC, stateful storage, generated values, cluster lookups, or Helm hooks. Kube Prometheus Stack and cert-manager carry several at once, which is why they anchor the harder-chart examples.

The required-setup vocabulary stays the same across the catalog. A target prerequisite, also called a target fact, is something the cluster must already provide. A lifecycle step is the recorded way a hook-like requirement gets handled. A disposition is one of the five words above. See how target prerequisites are staged.

Across the catalog, an Argo CD sync wave or a Flux dependsOn chain is generated only where a staged OCI package proves the ordering. Everywhere else, a CRD-first sequence like the one above is advice for you to encode yourself.

4. Stage target prerequisites before you apply

Some charts need cluster resources or facts that are not in the rendered YAML. For easy charts, matching Helm's own rendered objects is enough to start. Serious charts also depend on things that must already be true in the target cluster.

This repo calls those requirements target prerequisites. For example:

• CRDs must already exist before a CRDs-off base is applied.
• A Secret must exist when the chart is configured to reuse one.
• A webhook certificate may be generated by a controller after apply.
• An APIService may only become healthy after the backing service is ready.
• A Helm startup check may need to become a post-apply observation.

Before deploying a base, check the per-chart catalog page and the variant file. The chart page links the render intent that keeps the declaration, rendered objects, lifecycle steps, and Argo CD or Flux handling together.

If the base lists target prerequisites:

1. Stage them before applying the base, or choose a base that includes them.
2. Keep the prerequisite source visible in the pull request or ticket.
3. Run the relevant live check after apply.
4. Do not call the install production-supported until the target scope has a production support decision.

The routing rule sorts a change or requirement into one place:

Read the full guide, including the cert-manager, Vertical Pod Autoscaler, and OpenTelemetry Operator examples.