Skip to content

Commit 65a038c

Browse files
committed
docs(api): separate the healthCheckExprs failure modes
The field doc filed every mistake under one outcome, a HelmRelease that hangs until its timeout. helm-controller treats them differently. An expression that does not parse is rejected before any Helm action and stalls the release at once, with a named reason. One that parses but errors on the object keeps the wait polling with the CEL error attached, and a current expression that evaluates cleanly but never turns true runs the wait out with no error at all. A read of status errors until the CR's controller writes one, even inside has(), but the wait survives it. A wrong group or kind silently falls back to the built-in readiness rules, and a CR whose CRD is missing fails the Helm action before the wait starts. The text ships in the CRDs and is what kubectl explain shows, so a reader who cannot check it against the controller source was sent to the wrong place for the parse error and the missing CRD. Assisted-by: LLM Signed-off-by: Aleksei Sviridkin <[email protected]>
1 parent a759190 commit 65a038c

4 files changed

Lines changed: 82 additions & 16 deletions

File tree

‎api/v1alpha1/applicationdefinitions_types.go‎

Lines changed: 21 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -99,10 +99,27 @@ type ApplicationDefinitionRelease struct {
9999
// HealthCheckExprs maps to HelmReleaseSpec.HealthCheckExprs — CEL health
100100
// expressions for the custom resource(s) this application renders, so the
101101
// HelmRelease reports Ready only when the CR is actually healthy instead of
102-
// as soon as helm applies it. OpenAPI validates only the struct shape, not
103-
// that the CEL compiles or that the referenced apiVersion/kind CRD is
104-
// installed; a bad expression or a not-yet-installed CRD makes the
105-
// HelmRelease hang until its timeout (the backstop).
102+
// as soon as helm applies it. OpenAPI validates only the struct shape, so
103+
// mistakes surface in helm-controller, and they do not all fail the same
104+
// way:
105+
// - An expression that does not parse, an empty current expression, or
106+
// two entries for the same group and kind stall the HelmRelease with
107+
// reason InvalidCELExpression before any Helm action runs.
108+
// - An expression that errors on the object, such as a read of a
109+
// misspelled field or a non-boolean result, does not end the wait: the
110+
// CR reads as Unknown on every poll, and the Helm action waits out its
111+
// timeout with the CEL error in the message. Reading a status field
112+
// errors this way, even inside has(), until the CR's controller writes
113+
// a status; the wait goes on and can still succeed once it does.
114+
// - A current expression that evaluates cleanly but never becomes true,
115+
// such as a comparison against the wrong value, leaves the CR
116+
// InProgress, and the Helm action waits out its timeout with no CEL
117+
// error to point at the expression.
118+
// - A group or kind that does not match the CR the chart renders leaves
119+
// the expressions unused, and that CR is judged by the built-in
120+
// kstatus rules instead.
121+
// A CR whose CRD is not installed fails the Helm action before any wait,
122+
// whatever these expressions say.
106123
// Upstream evaluates these only when the Helm action itself has wait
107124
// enabled, so the release.cozystack.io/helm-install-disable-wait annotation
108125
// makes them a silent no-op whatever waitStrategy says: the HelmRelease

‎api/v1alpha1/packagesource_types.go‎

Lines changed: 20 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -156,10 +156,26 @@ type ComponentInstall struct {
156156
// HealthCheckExprs maps to HelmReleaseSpec.HealthCheckExprs — CEL health
157157
// expressions for the custom resource(s) this component renders, so the
158158
// HelmRelease reports Ready only when the CR is actually healthy. OpenAPI
159-
// validates only the struct shape, not that the CEL compiles or that the
160-
// referenced apiVersion/kind CRD is installed; a bad expression or a
161-
// not-yet-installed CRD makes the HelmRelease hang until its timeout (the
162-
// backstop).
159+
// validates only the struct shape, so mistakes surface in helm-controller,
160+
// and they do not all fail the same way:
161+
// - An expression that does not parse, an empty current expression, or
162+
// two entries for the same group and kind stall the HelmRelease with
163+
// reason InvalidCELExpression before any Helm action runs.
164+
// - An expression that errors on the object, such as a read of a
165+
// misspelled field or a non-boolean result, does not end the wait: the
166+
// CR reads as Unknown on every poll, and the Helm action waits out its
167+
// timeout with the CEL error in the message. Reading a status field
168+
// errors this way, even inside has(), until the CR's controller writes
169+
// a status; the wait goes on and can still succeed once it does.
170+
// - A current expression that evaluates cleanly but never becomes true,
171+
// such as a comparison against the wrong value, leaves the CR
172+
// InProgress, and the Helm action waits out its timeout with no CEL
173+
// error to point at the expression.
174+
// - A group or kind that does not match the CR the chart renders leaves
175+
// the expressions unused, and that CR is judged by the built-in
176+
// kstatus rules instead.
177+
// A CR whose CRD is not installed fails the Helm action before any wait,
178+
// whatever these expressions say.
163179
// +optional
164180
HealthCheckExprs []kustomize.CustomHealthCheck `json:"healthCheckExprs,omitempty"`
165181
}

‎internal/crdinstall/manifests/cozystack.io_packagesources.yaml‎

Lines changed: 20 additions & 4 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎packages/system/application-definition-crd/definition/cozystack.io_applicationdefinitions.yaml‎

Lines changed: 21 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -316,10 +316,27 @@ spec:
316316
HealthCheckExprs maps to HelmReleaseSpec.HealthCheckExprs — CEL health
317317
expressions for the custom resource(s) this application renders, so the
318318
HelmRelease reports Ready only when the CR is actually healthy instead of
319-
as soon as helm applies it. OpenAPI validates only the struct shape, not
320-
that the CEL compiles or that the referenced apiVersion/kind CRD is
321-
installed; a bad expression or a not-yet-installed CRD makes the
322-
HelmRelease hang until its timeout (the backstop).
319+
as soon as helm applies it. OpenAPI validates only the struct shape, so
320+
mistakes surface in helm-controller, and they do not all fail the same
321+
way:
322+
- An expression that does not parse, an empty current expression, or
323+
two entries for the same group and kind stall the HelmRelease with
324+
reason InvalidCELExpression before any Helm action runs.
325+
- An expression that errors on the object, such as a read of a
326+
misspelled field or a non-boolean result, does not end the wait: the
327+
CR reads as Unknown on every poll, and the Helm action waits out its
328+
timeout with the CEL error in the message. Reading a status field
329+
errors this way, even inside has(), until the CR's controller writes
330+
a status; the wait goes on and can still succeed once it does.
331+
- A current expression that evaluates cleanly but never becomes true,
332+
such as a comparison against the wrong value, leaves the CR
333+
InProgress, and the Helm action waits out its timeout with no CEL
334+
error to point at the expression.
335+
- A group or kind that does not match the CR the chart renders leaves
336+
the expressions unused, and that CR is judged by the built-in
337+
kstatus rules instead.
338+
A CR whose CRD is not installed fails the Helm action before any wait,
339+
whatever these expressions say.
323340
Upstream evaluates these only when the Helm action itself has wait
324341
enabled, so the release.cozystack.io/helm-install-disable-wait annotation
325342
makes them a silent no-op whatever waitStrategy says: the HelmRelease

0 commit comments

Comments
 (0)