Skip to content

Commit ce35da4

Browse files
authored
docs(api): separate the healthCheckExprs failure modes (cozystack#4387)
## What this PR does The `healthCheckExprs` field doc said any bad expression makes the HelmRelease hang until its timeout. That is true for some mistakes and wrong for others, and the text ships in the CRDs, so `kubectl explain` sends people to the wrong place. The doc now lists the cases separately, checked against the controller versions this repo installs (helm-controller v1.5.0, fluxcd/pkg runtime v0.100.2, Helm v4.1.1). An expression that does not parse, an empty `current`, or a duplicate group and kind stall the release right away with reason `InvalidCELExpression`, and no Helm action runs. An expression that errors on the object keeps the wait polling until the timeout with the CEL error in the message. A `current` expression that evaluates but never turns true also runs the timeout out, with no error to point at it. A wrong group or kind leaves the expressions unused. Two details go against the issue text. Reading `status` before the CR's controller writes one errors even inside `has()`, as the issue says, but the object is only Unknown on that poll, and the wait still succeeds once a status shows up. A CRD that is not installed does not hang the wait: Helm fails to build the manifest and the action fails before any wait starts. Doc comments and the regenerated CRD YAML only, no behaviour change. Closes cozystack#4154 ### Screenshots No UI change. ### Downstream repositories - [x] No downstream repository is affected by this change - [ ] [cozystack/website](https://github.com/cozystack/website) - follow-up: - [ ] [cozystack/terraform-provider-cozystack](https://github.com/cozystack/terraform-provider-cozystack) - follow-up: - [ ] [cozystack/ansible-cozystack](https://github.com/cozystack/ansible-cozystack) - follow-up: - [ ] [cozystack/ccp](https://github.com/cozystack/ccp) - follow-up: - [ ] [cozystack/talm](https://github.com/cozystack/talm) - follow-up: - [ ] [cozystack/cozyhr](https://github.com/cozystack/cozyhr) - follow-up: - [ ] [cozystack/cozy-proxy](https://github.com/cozystack/cozy-proxy) - follow-up: - [ ] [cozystack/cozystack-telemetry-server](https://github.com/cozystack/cozystack-telemetry-server) - follow-up: - [ ] [cozystack/external-apps-example](https://github.com/cozystack/external-apps-example) - follow-up: - [ ] [cozystack/examples](https://github.com/cozystack/examples) - follow-up: - [ ] [cozystack/community](https://github.com/cozystack/community) - follow-up: ### Release note ```release-note docs(api): describe each healthCheckExprs failure mode separately in the ApplicationDefinition and PackageSource field docs. ``` <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Documentation** * Expanded the health-check expression guidance to explain how invalid or duplicate expressions, evaluation errors, expressions that remain false, unmatched resource types, and missing CRDs affect Helm releases. * Clarified that health-check expressions are not evaluated when Helm action waiting is disabled. <!-- end of auto-generated comment: release notes by coderabbit.ai -->
2 parents ddcc317 + 65a038c commit ce35da4

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)