feat(installer): add variant-aware templates for generic Kubernetes support - #2010

The values cozystack.rootHost, cozystack.apiServerEndpoint, and cozystack.apiServerHost are given empty string defaults, but they appear to be required for a successful deployment in generic mode. Deploying with empty values for these settings will likely lead to a non-functional operator and related components, with failures occurring at runtime.

To improve the user experience and prevent misconfigurations, it's a best practice to use Helm's required function to fail fast during templating if a necessary value is not provided.

I suggest adding required checks in the templates where these values are used when mode is generic. For example:

In packages/core/installer/templates/configmap-cozystack.yaml:

{{- if eq .Values.mode "generic" }}
{{- required "A value for .Values.cozystack.rootHost is required in generic mode" .Values.cozystack.rootHost }}
{{- required "A value for .Values.cozystack.apiServerEndpoint is required in generic mode" .Values.cozystack.apiServerEndpoint }}
...

And in packages/core/installer/templates/configmap-operator-config.yaml:

{{- if eq .Values.mode "generic" }}
{{- required "A value for .Values.cozystack.apiServerHost is required in generic mode" .Values.cozystack.apiServerHost }}
...

This will provide a clear error message to the user if they forget to set these mandatory values.

We intentionally avoid required here because this chart uses helm template --show-only to render individual variant manifests (see Makefile manifests target). Helm evaluates ALL templates regardless of -s filtering, so required in generic-mode templates would break helm template -s templates/cozystack-operator.yaml --set mode=talos (the talos build path). Empty defaults are the trade-off for -s compatibility. Users get a clear runtime error (empty ConfigMap values → operator pod fails to start) rather than a silent success.

This is not applicable here — the Makefile uses helm template -s to selectively render templates for different modes. Helm evaluates all templates regardless of -s filtering, so required checks in mode-specific templates would break the build for other modes.

The mode value determines which set of resources are rendered. Currently, if an invalid mode is provided (e.g., a typo like generc), Helm will silently produce an empty manifest for the operator, which can be confusing.

To make the chart more robust, consider adding validation to ensure mode is one of the expected values (talos, generic, hosted). You can use Helm's fail function to stop the installation with a clear error message if an invalid mode is used.

You could add a check like this, perhaps in a helper template or at the top of a main template:

{{- $validModes := list "talos" "generic" "hosted" -}}
{{- if not (has .Values.mode $validModes) -}}
{{-   fail (printf "Invalid mode: %q. Must be one of %v" .Values.mode $validModes) -}}
{{- end -}}

This will improve the chart's usability and prevent silent failures due to misconfiguration.

Good catch. Added mode validation via fail in packagesource.yaml (rendered for all modes). Invalid mode now produces: Invalid mode "generc": must be one of talos, generic, hosted. Fixed in a226b55.

Mode validation was added in packagesource.yaml — it will fail fast with a clear error message if someone sets an invalid mode value.

⚠️ Potential issue | 🟡 Minor

# Search for all Package CRs in the repo and check namespace patterns
rg -A 5 'kind: Package' packages/ --type yaml

# Check the specific file context
cat -n packages/core/installer/templates/package-platform.yaml

# Search for other Package resource definitions to understand the pattern
fd -e yaml -path '*/templates/*' packages/core/ -exec grep -l 'kind: Package' {} \;

cat -n packages/core/installer/example/platform.yaml

# Search for any operator code that might indicate where it watches for Package resources
rg -i 'namespace.*package\|package.*namespace' packages/core/installer/ --type yaml

# Check if there's any documentation or comments about namespace expectations
rg -B 3 -A 3 'cozy-system' packages/core/installer/templates/

Add namespace: cozy-system to the Package CR metadata.

The Package resource lacks an explicit namespace and will be created in the Helm release namespace. The related PackageSource resource explicitly specifies namespace: cozy-system for all components, and the operator runs in cozy-system. This should be made consistent:

 metadata:
   name: cozystack.cozystack-platform
+  namespace: cozy-system

In `@packages/core/installer/templates/package-platform.yaml` around lines 5 - 6,
The Package CR metadata (metadata: / name: cozystack.cozystack-platform) is
missing a namespace and will be created in the Helm release namespace; add a
metadata field "namespace: cozy-system" to the Package manifest so it matches
the PackageSource and operator namespace (i.e., update the Package resource's
metadata block to include namespace: cozy-system alongside name:
cozystack.cozystack-platform).

✅ Addressed in commit a226b55

Added namespace: cozy-system. Fixed in a226b55.

@lexfrei Thank you for adding the namespace! This ensures the Package CR will be created in the correct cozy-system namespace consistently with the operator and PackageSource resources. 🎉

If you found this review helpful, would you consider giving us a shout-out on X?

Thank you for using CodeRabbit!

Guys, Packages are cluster-scoped resources.

Seems like the humans are having a chat. I'll hop back into my burrow for now. If you need me again, just tag CodeRabbit (@coderabbitai) in a new comment, and I'll come hopping out!

Good catch — Package is indeed cluster-scoped (+kubebuilder:resource:scope=Cluster). Removed namespace: cozy-system from the Package CR metadata. Fixed in c7a4fa4.

⚠️ Potential issue | 🟠 Major

Empty defaults for required generic-mode fields will cause silent failures.

apiServerHost, apiServerEndpoint, and rootHost all default to "". When mode=generic, these flow into ConfigMaps and Package CRs, producing resources with empty/broken values. Consider adding required checks in the templates that consume these values so users get a clear error at render time rather than a broken deployment.

For example, in configmap-operator-config.yaml:

KUBERNETES_SERVICE_HOST: {{ required "cozystack.apiServerHost is required when mode=generic" .Values.cozystack.apiServerHost | quote }}

In `@packages/core/installer/values.yaml` around lines 10 - 26, The values.yaml
defines empty defaults for cozystack.rootHost, cozystack.apiServerEndpoint, and
cozystack.apiServerHost which cause silent failures in generic mode; update the
Helm templates that consume these values (e.g., configmap-operator-config.yaml,
Package CR templates) to use the Helm required function with clear messages (for
example reference .Values.cozystack.apiServerHost,
.Values.cozystack.apiServerEndpoint, .Values.cozystack.rootHost) so chart
rendering fails with a helpful error when mode=generic and these fields are
missing; ensure the error messages reference "mode=generic" and the specific
field name to guide users.

Same as above — required is incompatible with the helm template -s workflow used by the Makefile. Helm evaluates all templates regardless of -s filtering, so required in generic-mode templates breaks the talos/hosted build paths.

@lexfrei, thank you for clarifying! That's a valid constraint—since helm template evaluates all templates regardless of -s, placing required checks in mode-specific templates would indeed break the other build variants in your Makefile.

Given that workflow, the current approach of conditional rendering with empty defaults is appropriate. Users will need to supply the required values when deploying with mode=generic, and runtime errors (e.g., from the operator trying to connect with an empty host) will surface the issue. You might consider documenting the required fields in the chart README or adding a note in the values.yaml comments to guide users, but that's entirely optional.

Learnt from: lexfrei
Repo: cozystack/cozystack PR: 2010
File: packages/core/installer/values.yaml:10-26
Timestamp: 2026-02-10T10:44:25.314Z
Learning: In the cozystack/cozystack repository, the Makefile uses `helm template -s` to selectively render templates for different modes (talos, generic, hosted). Because Helm evaluates all templates regardless of `-s` filtering, using `required` checks in mode-specific templates (e.g., generic-mode templates) would break the build for other modes. Therefore, avoid suggesting `required` validation for mode-specific values in Helm templates in this repository.

Why isn't this required?

Already mentioned above #2010 (comment)

Wouldn't it be better to defer to the label selector approach with the "MASTER_NODES_LABEL" env?

Agreed — switched to MASTER_NODES_LABEL: "node-role.kubernetes.io/control-plane=true" which matches how the isp-full-generic variant configures kube-ovn in the platform chart. This lets kube-ovn auto-discover control plane nodes by label rather than relying on an explicit IP. Fixed in 750a7e1.

This config map is deprecated since v1.0 and replaced by values in platform Package

Already removed in 5c35bc2 — values are now passed directly through spec.components.platform.values in package-platform.yaml.

Originally this was designed to install manually.

What is proposed way now?

User might change some settings in this Package later, eg enable oidc, change hostname and so on.

We need to avoid cases when helm overriding them

This is standard Helm behavior — any helm upgrade applies the values you provide, potentially overriding manual changes. Users are expected to maintain their values file, same as with any other Helm chart.

For a more robust workflow, we can recommend Helmfile in the docs — it keeps the chart reference and values together as a single declarative unit, making upgrades reproducible and safe.

The Package CR with platform.enabled=true is an optional convenience for initial bootstrap. Users who prefer full control can skip it (platform.enabled=false, the default) and create the Package CR manually.

It might have potential race condition, add CRD for this CR are installed in a same helm chart

No race condition here — Helm's built-in InstallOrder guarantees CRDs (position 13) are applied before unknown kinds (custom resources like Package, which go last).

See kind_sorter.go — the Less() method explicitly states "unknown kind is last."

In the current make manifests workflow, CRDs are rendered to a separate file (cozystack-crds.yaml) and applied independently, so ordering is also guaranteed there.

Aleksei Sviridkin (@lexfrei) please take attention here