Skip to content

Commit 9b35fa0

Browse files
frolov.solexfrei
authored andcommitted
docs(api): clarify kind-wide Helm timeout overrides
Timeout annotations are read from an ApplicationDefinition and therefore affect every Application of that kind. Describing them as per-Application hides their actual scope and the upgrade override precedence. Fixes cozystack#4382 Assisted-by: LLM Signed-off-by: frolov.so <[email protected]>
1 parent f4bde9e commit 9b35fa0

5 files changed

Lines changed: 43 additions & 40 deletions

File tree

‎pkg/cmd/server/start.go‎

Lines changed: 16 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -157,15 +157,15 @@ func NewCommandStartCozyServer(ctx context.Context, defaults *CozyServerOptions)
157157
"same cadence.")
158158
flags.StringVar(&o.HelmReleaseInstallTimeout, "helmrelease-install-timeout", o.HelmReleaseInstallTimeout,
159159
"Default timeout for the Helm install action of HelmReleases generated from Application "+
160-
"resources (Spec.Install.Timeout). Overridden per-Application by the "+
161-
"release.cozystack.io/helm-install-timeout annotation on the ApplicationDefinition; the "+
160+
"resources (Spec.Install.Timeout). Overridden for an Application kind by the "+
161+
"release.cozystack.io/helm-install-timeout annotation on its ApplicationDefinition; the "+
162162
"same annotation also overrides --helmrelease-upgrade-timeout.")
163163
flags.StringVar(&o.HelmReleaseUpgradeTimeout, "helmrelease-upgrade-timeout", o.HelmReleaseUpgradeTimeout,
164164
"Default timeout for the Helm upgrade action of HelmReleases generated from Application "+
165-
"resources (Spec.Upgrade.Timeout). Overridden per-Application by the "+
166-
"release.cozystack.io/helm-install-timeout annotation (which sets both install and "+
167-
"upgrade), or by release.cozystack.io/helm-upgrade-timeout to override only the upgrade "+
168-
"side for a kind that needs an asymmetric budget.")
165+
"resources (Spec.Upgrade.Timeout). Overridden for an Application kind by the "+
166+
"release.cozystack.io/helm-install-timeout annotation on its ApplicationDefinition (which "+
167+
"sets both install and upgrade), or with higher precedence by "+
168+
"release.cozystack.io/helm-upgrade-timeout to override only the upgrade side.")
169169
flags.IntVar(&o.HelmReleaseMaxHistory, "helmrelease-max-history", o.HelmReleaseMaxHistory,
170170
"Number of release revisions Helm keeps for HelmReleases generated from Application "+
171171
"resources (Spec.MaxHistory). 0 means unlimited; 5 matches Helm's default.")
@@ -331,11 +331,11 @@ func buildResourceFromCRD(crd v1alpha1.ApplicationDefinition, hrFlags helmReleas
331331
Name: crd.Spec.Release.ChartRef.Name,
332332
Namespace: crd.Spec.Release.ChartRef.Namespace,
333333
},
334-
// Per-Application HelmRelease generation defaults from server
335-
// flags. The same five values are applied to every Resource,
336-
// matching cozystack-operator's PackageReconciler. The
337-
// per-Application HelmInstallTimeout annotation populated below
338-
// still wins over HelmReleaseInstallTimeout/UpgradeTimeout.
334+
// HelmRelease generation defaults from server flags. The same five
335+
// values are applied to every Resource, matching cozystack-operator's
336+
// PackageReconciler. The kind-wide HelmInstallTimeout and
337+
// HelmUpgradeTimeout overrides from the ApplicationDefinition
338+
// populated below still take precedence over these defaults.
339339
HelmReleaseInterval: hrFlags.interval,
340340
HelmReleaseRetryInterval: hrFlags.retryInterval,
341341
HelmReleaseInstallTimeout: hrFlags.installTimeout,
@@ -348,11 +348,11 @@ func buildResourceFromCRD(crd v1alpha1.ApplicationDefinition, hrFlags helmReleas
348348
WaitStrategy: crd.Spec.Release.WaitStrategy,
349349
HealthCheckExprs: crd.Spec.Release.HealthCheckExprs,
350350
}
351-
// Per-Application HelmRelease Install/Upgrade timeout. Applications
352-
// whose parent chart contains asynchronously-provisioned resources
353-
// the chart itself depends on (for example, the Kamaji-provisioned
354-
// admin-kubeconfig Secret for Kubernetes tenants) need a longer
355-
// wait budget than the Flux default. Consumed by the REST storage
351+
// Kind-wide HelmRelease Install/Upgrade timeout from this
352+
// ApplicationDefinition. Kinds whose parent chart contains asynchronously-
353+
// provisioned resources the chart itself depends on (for example, the
354+
// Kamaji-provisioned admin-kubeconfig Secret for Kubernetes tenants) need a
355+
// longer wait budget than the Flux default. Consumed by the REST storage
356356
// layer when building the HelmRelease Spec. The parser rejects
357357
// units Flux would reject at webhook time, so a bad annotation
358358
// surfaces as a loud startup failure instead of a silent drop to

‎pkg/config/config.go‎

Lines changed: 9 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -211,14 +211,14 @@ type ReleaseConfig struct {
211211
Prefix string `yaml:"prefix"`
212212
Labels map[string]string `yaml:"labels"`
213213
ChartRef ChartRefConfig `yaml:"chartRef"`
214-
// HelmInstallTimeout is a per-Application override of Install.Timeout
215-
// and Upgrade.Timeout. When non-zero, it wins over
214+
// HelmInstallTimeout is a per-kind override of Install.Timeout and
215+
// Upgrade.Timeout. When non-zero, it wins over
216216
// HelmReleaseInstallTimeout / HelmReleaseUpgradeTimeout below.
217217
// Populated from the release.cozystack.io/helm-install-timeout
218218
// annotation on the ApplicationDefinition at start-up.
219219
HelmInstallTimeout time.Duration `yaml:"helmInstallTimeout,omitempty"`
220-
// HelmUpgradeTimeout is a per-Application override of Upgrade.Timeout
221-
// only. When non-zero, it wins over both HelmReleaseUpgradeTimeout and
220+
// HelmUpgradeTimeout is a per-kind override of Upgrade.Timeout only.
221+
// When non-zero, it wins over both HelmReleaseUpgradeTimeout and
222222
// the Upgrade.Timeout value HelmInstallTimeout would otherwise apply,
223223
// so a kind can carry an asymmetric install/upgrade budget. Populated
224224
// from the release.cozystack.io/helm-upgrade-timeout annotation on the
@@ -236,12 +236,13 @@ type ReleaseConfig struct {
236236
// without polling healthy releases at the same cadence.
237237
HelmReleaseRetryInterval time.Duration `yaml:"helmReleaseRetryInterval,omitempty"`
238238
// HelmReleaseInstallTimeout is the global default for
239-
// Spec.Install.Timeout. Overridden per-Application by HelmInstallTimeout
240-
// when the annotation is set.
239+
// Spec.Install.Timeout. Overridden for this Application kind by
240+
// HelmInstallTimeout from its ApplicationDefinition.
241241
HelmReleaseInstallTimeout time.Duration `yaml:"helmReleaseInstallTimeout,omitempty"`
242242
// HelmReleaseUpgradeTimeout is the global default for
243-
// Spec.Upgrade.Timeout. Overridden per-Application by HelmInstallTimeout
244-
// when the annotation is set.
243+
// Spec.Upgrade.Timeout. Overridden for this Application kind by
244+
// HelmInstallTimeout, or by HelmUpgradeTimeout with higher precedence,
245+
// from its ApplicationDefinition.
245246
HelmReleaseUpgradeTimeout time.Duration `yaml:"helmReleaseUpgradeTimeout,omitempty"`
246247
// HelmReleaseMaxHistory is the global default for Spec.MaxHistory.
247248
// 0 means unlimited per Helm semantics; matches the cozystack-operator

‎pkg/registry/apps/application/rest.go‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1789,8 +1789,9 @@ func latestMonitorTime(m *cozyv1alpha1.WorkloadMonitor) metav1.Time {
17891789
// from Spec.Interval — the previous coupling caused failed installs to
17901790
// retry only every 5m, exceeding E2E budgets.
17911791
func (r *REST) convertApplicationToHelmRelease(app *appsv1alpha1.Application) (*helmv2.HelmRelease, error) {
1792-
// Per-Application annotation overrides win over the global defaults
1793-
// (HelmReleaseInstallTimeout / HelmReleaseUpgradeTimeout):
1792+
// Kind-wide annotation overrides from this kind's ApplicationDefinition
1793+
// win over the global defaults (HelmReleaseInstallTimeout /
1794+
// HelmReleaseUpgradeTimeout):
17941795
// - HelmInstallTimeout (release.cozystack.io/helm-install-timeout)
17951796
// sets both Install.Timeout and Upgrade.Timeout;
17961797
// - HelmUpgradeTimeout (release.cozystack.io/helm-upgrade-timeout)

‎pkg/registry/apps/application/rest_helmrelease_spec_test.go‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -204,11 +204,11 @@ func TestConvertApplicationToHelmRelease_ZeroMaxHistory(t *testing.T) {
204204
}
205205
}
206206

207-
// HelmInstallTimeout (the per-Application annotation override) wins over the
208-
// global HelmReleaseInstallTimeout / HelmReleaseUpgradeTimeout defaults. This
209-
// is the contract that lets ApplicationDefinitions like Kubernetes (with its
210-
// long Kamaji bootstrap) opt out of the global default without operators
211-
// having to widen the global flag for every kind.
207+
// HelmInstallTimeout (the kind-wide ApplicationDefinition annotation override)
208+
// wins over the global HelmReleaseInstallTimeout / HelmReleaseUpgradeTimeout
209+
// defaults. This is the contract that lets ApplicationDefinitions like
210+
// Kubernetes (with its long Kamaji bootstrap) opt out of the global default
211+
// without operators having to widen the global flag for every kind.
212212
//
213213
// The asymmetric-globals case pins that the override wipes both install and
214214
// upgrade timeouts to the same value, even when the globals differ — a

‎pkg/registry/apps/application/rest_timeout_test.go‎

Lines changed: 10 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -19,11 +19,11 @@ const (
1919
testGlobalUpgradeTimeout = 10 * time.Minute
2020
)
2121

22-
// newRESTForTimeout builds a REST struct focused on the per-Application
23-
// HelmInstallTimeout annotation override path. Global HelmRelease* defaults
24-
// are populated with production-shaped values so the unset-annotation case
25-
// exercises "global default applies". The full spec contract is covered by
26-
// rest_helmrelease_spec_test.go.
22+
// newRESTForTimeout builds a REST struct focused on the kind-wide
23+
// ApplicationDefinition HelmInstallTimeout override path. Global HelmRelease*
24+
// defaults are populated with production-shaped values so the unset-annotation
25+
// case exercises "global default applies". The full spec contract is covered
26+
// by rest_helmrelease_spec_test.go.
2727
func newRESTForTimeout(kind, prefix string, helmInstallTimeout time.Duration) *REST {
2828
return &REST{
2929
kindName: kind,
@@ -137,10 +137,11 @@ func TestConvertApplicationToHelmRelease_AppliesReleaseConfigTimeout(t *testing.
137137
}
138138
}
139139

140-
// HelmUpgradeTimeout (the per-Application release.cozystack.io/helm-upgrade-timeout
141-
// annotation override) overrides only Upgrade.Timeout, and wins over the
142-
// Upgrade.Timeout value HelmInstallTimeout would otherwise apply. This lets a
143-
// kind carry an asymmetric budget — e.g. a short install but a long upgrade.
140+
// HelmUpgradeTimeout (the kind-wide ApplicationDefinition
141+
// release.cozystack.io/helm-upgrade-timeout override) changes only
142+
// Upgrade.Timeout and wins over the value HelmInstallTimeout would otherwise
143+
// apply. This lets a kind carry an asymmetric budget — e.g. a short install but
144+
// a long upgrade.
144145
func TestConvertApplicationToHelmRelease_UpgradeTimeoutAnnotation(t *testing.T) {
145146
cases := []struct {
146147
name string

0 commit comments

Comments
 (0)