Skip to content

Commit 9c7fbe8

Browse files
author
frolov.so
committed
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 2c2c030 commit 9c7fbe8

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
@@ -135,15 +135,15 @@ func NewCommandStartCozyServer(ctx context.Context, defaults *CozyServerOptions)
135135
"same cadence.")
136136
flags.StringVar(&o.HelmReleaseInstallTimeout, "helmrelease-install-timeout", o.HelmReleaseInstallTimeout,
137137
"Default timeout for the Helm install action of HelmReleases generated from Application "+
138-
"resources (Spec.Install.Timeout). Overridden per-Application by the "+
139-
"release.cozystack.io/helm-install-timeout annotation on the ApplicationDefinition; the "+
138+
"resources (Spec.Install.Timeout). Overridden for an Application kind by the "+
139+
"release.cozystack.io/helm-install-timeout annotation on its ApplicationDefinition; the "+
140140
"same annotation also overrides --helmrelease-upgrade-timeout.")
141141
flags.StringVar(&o.HelmReleaseUpgradeTimeout, "helmrelease-upgrade-timeout", o.HelmReleaseUpgradeTimeout,
142142
"Default timeout for the Helm upgrade action of HelmReleases generated from Application "+
143-
"resources (Spec.Upgrade.Timeout). Overridden per-Application by the "+
144-
"release.cozystack.io/helm-install-timeout annotation (which sets both install and "+
145-
"upgrade), or by release.cozystack.io/helm-upgrade-timeout to override only the upgrade "+
146-
"side for a kind that needs an asymmetric budget.")
143+
"resources (Spec.Upgrade.Timeout). Overridden for an Application kind by the "+
144+
"release.cozystack.io/helm-install-timeout annotation on its ApplicationDefinition (which "+
145+
"sets both install and upgrade), or with higher precedence by "+
146+
"release.cozystack.io/helm-upgrade-timeout to override only the upgrade side.")
147147
flags.IntVar(&o.HelmReleaseMaxHistory, "helmrelease-max-history", o.HelmReleaseMaxHistory,
148148
"Number of release revisions Helm keeps for HelmReleases generated from Application "+
149149
"resources (Spec.MaxHistory). 0 means unlimited; 5 matches Helm's default.")
@@ -307,11 +307,11 @@ func buildResourceFromCRD(crd v1alpha1.ApplicationDefinition, hrFlags helmReleas
307307
Name: crd.Spec.Release.ChartRef.Name,
308308
Namespace: crd.Spec.Release.ChartRef.Namespace,
309309
},
310-
// Per-Application HelmRelease generation defaults from server
311-
// flags. The same five values are applied to every Resource,
312-
// matching cozystack-operator's PackageReconciler. The
313-
// per-Application HelmInstallTimeout annotation populated below
314-
// still wins over HelmReleaseInstallTimeout/UpgradeTimeout.
310+
// HelmRelease generation defaults from server flags. The same five
311+
// values are applied to every Resource, matching cozystack-operator's
312+
// PackageReconciler. The kind-wide HelmInstallTimeout and
313+
// HelmUpgradeTimeout overrides from the ApplicationDefinition
314+
// populated below still take precedence over these defaults.
315315
HelmReleaseInterval: hrFlags.interval,
316316
HelmReleaseRetryInterval: hrFlags.retryInterval,
317317
HelmReleaseInstallTimeout: hrFlags.installTimeout,
@@ -324,11 +324,11 @@ func buildResourceFromCRD(crd v1alpha1.ApplicationDefinition, hrFlags helmReleas
324324
WaitStrategy: crd.Spec.Release.WaitStrategy,
325325
HealthCheckExprs: crd.Spec.Release.HealthCheckExprs,
326326
}
327-
// Per-Application HelmRelease Install/Upgrade timeout. Applications
328-
// whose parent chart contains asynchronously-provisioned resources
329-
// the chart itself depends on (for example, the Kamaji-provisioned
330-
// admin-kubeconfig Secret for Kubernetes tenants) need a longer
331-
// wait budget than the Flux default. Consumed by the REST storage
327+
// Kind-wide HelmRelease Install/Upgrade timeout from this
328+
// ApplicationDefinition. Kinds whose parent chart contains asynchronously-
329+
// provisioned resources the chart itself depends on (for example, the
330+
// Kamaji-provisioned admin-kubeconfig Secret for Kubernetes tenants) need a
331+
// longer wait budget than the Flux default. Consumed by the REST storage
332332
// layer when building the HelmRelease Spec. The parser rejects
333333
// units Flux would reject at webhook time, so a bad annotation
334334
// 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
@@ -1660,8 +1660,9 @@ func latestMonitorTime(m *cozyv1alpha1.WorkloadMonitor) metav1.Time {
16601660
// from Spec.Interval — the previous coupling caused failed installs to
16611661
// retry only every 5m, exceeding E2E budgets.
16621662
func (r *REST) convertApplicationToHelmRelease(app *appsv1alpha1.Application) (*helmv2.HelmRelease, error) {
1663-
// Per-Application annotation overrides win over the global defaults
1664-
// (HelmReleaseInstallTimeout / HelmReleaseUpgradeTimeout):
1663+
// Kind-wide annotation overrides from this kind's ApplicationDefinition
1664+
// win over the global defaults (HelmReleaseInstallTimeout /
1665+
// HelmReleaseUpgradeTimeout):
16651666
// - HelmInstallTimeout (release.cozystack.io/helm-install-timeout)
16661667
// sets both Install.Timeout and Upgrade.Timeout;
16671668
// - 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)