✨ Add helm/v2-alpha addressing all feedbacks and aiming maintainability. Deprecated helm/v1-alpha in favor of helm/v2-alpha

[camilamacedo86]

Introduce helm/v2-alpha Plugin: Dynamic Helm Chart Generation

This PR introduces a completely rewritten Helm plugin (helm/v2-alpha) that dynamically generates Helm charts based on the actual kustomize output from make build-installer, replacing the previous hardcoded template approach in helm/v1-alpha.

The existing helm/v1-alpha plugin used static templates that didn't reflect user customizations (environment variables, labels, annotations, security contexts, etc.) made in their kustomize configuration. This led to inconsistencies between kubectl apply -f dist/install.yaml and helm install.

Key Features

• Dynamic generation: Charts generated from actual kustomize output (dist/install.yaml)
• Smart organization: Resources split into logical directories (metrics/, webhook/, cert-manager/, rbac/, crd/)
• Conditional logic: Only includes resources that actually exist (certManager, webhooks, metrics)
• Individual files: CRDs, RBAC, and certificates as separate files for better maintainability
• Enhanced values.yaml: Dynamic configuration based on detected project features

Changes

• Deprecated Helm v1-alpha in favour of v2
• Add docs and tests for Helm v2
• Update all samples
• Address all feedback raised so far

Documentation

📖 Preview docs: https://deploy-preview-5058--kubebuilder.netlify.app/plugins/available/helm-v2-alpha

How to Review

• Documentation: Check the docs link above for complete feature overview
• Core implementation: Focus on pkg/plugins/optional/helm/v2alpha/ for the actual code changes
• File changes context: Most changes under testdata/ and docs/ are sample updates with helm/v2-alpha
• Test coverage: Comprehensive unit tests added with GitHub workflow integration for e2e testing via Prow
• Play with in your solutions 🙏

Usage

# Generate Helm chart from kustomize output
kubebuilder edit --plugins=helm.kubebuilder.io/v2-alpha

# Custom output directory  
kubebuilder edit --plugins=helm.kubebuilder.io/v2-alpha --output=charts

Closes:

• kubebuilder-helm does not support per resource labels #5051
• target helm chart directory should be configurable #4320
• Generated helm chart should align with other charts from ecosystem #4912
• target helm chart directory should be configurable #4320
• (helm/v1-alpha) Nameprefix is missing in editor/viewer ClusterRoles after scaffolding #4566
• (helm/v1-alpha) --force flag does not update values.yaml when kustomize manager spec has changed #4625
• Helm ServiceAccount scaffolding NIL pointers #4562
• Improve Helm plugin by generating chart from install.yaml (via Kustomize build) #4833
• (helm/v1-alpha) --force flag does not update values.yaml when kustomize manager spec has changed #4625
• 🛠️ add ignore flags for selective scaffolding in edit command #4889

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: camilamacedo86

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

• OWNERS [camilamacedo86]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[bavarianbidi]

shouldn't the flag called output-dir?
as you suggested in my initial PR here: #4891 (comment)

[camilamacedo86]

fixed.

[bavarianbidi]

returned from PTO this week, will do a deeper review, starting next week, if wanted.

[mkarlheim]

@camilamacedo86 many thanks for the PR. I've tested this version and it already looks very promising to my prior issues.

I just found some things to improve:

1. The CRDs should be placed in the helm v3 suggested way: https://helm.sh/docs/chart_best_practices/custom_resource_definitions/. Just move the templates/crd folder to the root of the chart and name it "crds" and remove the flow control crd.enable.

This a special directory introduced especially for crds in helm. By doing this, helm will install these crds if not exists by default and you can skip this with --skip-diff

2. Missing labels in manager.yaml
   The deployment is missing the include "chart.labels" in labels section and the include "chart.selectorLabels" in matchLabels section. The podTemplate is also missing "chart.labels".

3. Missing labels in RBAC ClusterRoles (editor, viewer, admin);
   In the previous version there was this label section in editor-, viewer-, and admin-roles:
   labels: {{- include "chart.labels" . | nindent 4 }}
   This has now been replaced by fixed labels:
   labels: app.kubernetes.io/managed-by: {{ .Release.Service }} app.kubernetes.io/name: xxx
   and leads to differences in helm diff

I think using chart.labels defined in _helpers.tpl would be the preferred way.

4. The following resources are missing labels section completely:

• manager-role.yaml
• metrics-auth-role.yaml
• metrics-auth-rolebinding.yaml
• metrics-reader.yaml

Besides these small findings I think the new plugin version helm/v2-alpha is a huge improvement!

Thank you

[camilamacedo86]

Hi @mkarlheim

The chart. labels were added 👍 to allow adding extra labels.
However, note that these are the labels defined in Kustomize, and we should retain them.
The goal of Helm charts is to package the solution, so the labels should be identical.

Regards the CRDs, see:

Although Helm best practices recommend placing CRDs under a top-level crds/ directory, the Kubebuilder Helm plugin intentionally places them under templates/crd.**

This was a conscious design decision aafter lengthydiscussions in the design proposal and community threads (Slack discussion link).

The reason: CRDs in crds/ are not upgraded by Helm. Keeping them under templates/ ensures CRDs are correctly managed and updated together with releases, avoiding drift. While this means you cannot bundle custom resources directly in the chart (a current Helm limitation), it provides a more straightforward and more reliable workflow for projects generated by Kubebuilder. See; #3632 (comment)

Alternatively, here we could create a chart only for the CRDs, such as a two-chart flow (API first, then operator/app), with a simple readiness/wait check. However, if we change it, it would be better in a follow-up discussion where we can address it. Let's keep the cards under the templates, which is the most adopted approach.

[bavarianbidi]

WDYT about enforcing this import-pattern via golangci-lint by the importas section (https://golangci-lint.run/docs/linters/configuration/#importas).
With that we get a consistent import section ...

I'm fine if we do this in a dedicated PR (have it on my list and happy to raise a PR after that)

[bavarianbidi]

Suggested change

	hemlv2alpha "sigs.k8s.io/kubebuilder/v4/pkg/plugins/optional/helm/v2alpha"
	helmv2alpha "sigs.k8s.io/kubebuilder/v4/pkg/plugins/optional/helm/v2alpha"

• the line above

enforcing import-names might help here as well (see #5058 (comment))

[mkarlheim]

Hi @mkarlheim

The chart. labels were added 👍 to allow adding extra labels. However, note that these are the labels defined in Kustomize, and we should retain them. The goal of Helm charts is to package the solution, so the labels should be identical.

Regards the CRDs, see:

Although Helm best practices recommend placing CRDs under a top-level crds/ directory, the Kubebuilder Helm plugin intentionally places them under templates/crd.**

This was a conscious design decision aafter lengthydiscussions in the design proposal and community threads (Slack discussion link).

The reason: CRDs in crds/ are not upgraded by Helm. Keeping them under templates/ ensures CRDs are correctly managed and updated together with releases, avoiding drift. While this means you cannot bundle custom resources directly in the chart (a current Helm limitation), it provides a more straightforward and more reliable workflow for projects generated by Kubebuilder. See; #3632 (comment)

Alternatively, here we could create a chart only for the CRDs, such as a two-chart flow (API first, then operator/app), with a simple readiness/wait check. However, if we change it, it would be better in a follow-up discussion where we can address it. Let's keep the cards under the templates, which is the most adopted approach.

Thanks for clarifying.