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`.

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

Assisted-by: OpenAI

Author: camilamacedo86

.github/workflows/test-helm-samples.yml

@@ -20,11 +20,30 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@v5
 
+      - name: Enable Prometheus in kustomize (testdata sample)
+        run: |
+          sed -i 's/^#- \.\.\/prometheus/- ..\/prometheus/' testdata/project-v4-with-plugins/config/default/kustomization.yaml
+
+      - name: Build kubebuilder CLI
+        run: make build
+
       - name: Setup Go
         uses: actions/setup-go@v6
         with:
           go-version-file: go.mod
 
+      - name: Prepare project-v4-with-plugins
+        run: |
+          cd testdata/project-v4-with-plugins/
+          go mod tidy
+          make all
+
+      - name: Rebuild installer and regenerate Helm chart (v2-alpha)
+        working-directory: testdata/project-v4-with-plugins
+        run: |
+          make build-installer
+          ../../bin/kubebuilder edit --plugins=helm/v2-alpha --force
+
       - name: Install the latest version of kind
         run: |
           curl -Lo ./kind https://kind.sigs.k8s.io/dl/latest/kind-linux-amd64
@@ -37,13 +56,6 @@ jobs:
       - name: Create kind cluster
         run: kind create cluster
 
-      - name: Prepare project-v4-with-plugins
-        run: |
-          cd testdata/project-v4-with-plugins/
-          go mod tidy
-          make docker-build IMG=project-v4-with-plugins:v0.1.0
-          kind load docker-image project-v4-with-plugins:v0.1.0
-
       - name: Install Helm
         run: |
           curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash
@@ -55,39 +67,50 @@ jobs:
         run: |
           helm lint testdata/project-v4-with-plugins/dist/chart
 
+      - name: Build project-v4-with-plugins
+        run: |
+          cd testdata/project-v4-with-plugins/
+          go mod tidy
+          make docker-build IMG=project-v4-with-plugins:v0.1.0
+          kind load docker-image project-v4-with-plugins:v0.1.0
+
       - name: Install Prometheus Operator CRDs
         run: |
           helm repo add prometheus-community https://prometheus-community.github.io/helm-charts
           helm repo update
           helm install prometheus-crds prometheus-community/prometheus-operator-crds
 
-      - name: Install cert-manager via Helm
+      - name: Install cert-manager via Helm (wait for readiness)
         run: |
           helm repo add jetstack https://charts.jetstack.io
           helm repo update
-          helm install cert-manager jetstack/cert-manager --namespace cert-manager --create-namespace --set crds.enabled=true
-
-      - name: Wait for cert-manager to be ready
-        run: |
-          kubectl wait --namespace cert-manager --for=condition=available --timeout=300s deployment/cert-manager
-          kubectl wait --namespace cert-manager --for=condition=available --timeout=300s deployment/cert-manager-cainjector
-          kubectl wait --namespace cert-manager --for=condition=available --timeout=300s deployment/cert-manager-webhook
+          helm install cert-manager jetstack/cert-manager \
+            --namespace cert-manager \
+            --create-namespace \
+            --set crds.enabled=true \
+            --wait \
+            --timeout 300s
 
       - name: Render Helm chart for project-v4-with-plugins
         run: |
           helm template testdata/project-v4-with-plugins/dist/chart --namespace=project-v4-with-plugins-system
 
       - name: Install Helm chart for project-v4-with-plugins
         run: |
-          helm install my-release testdata/project-v4-with-plugins/dist/chart --create-namespace --namespace project-v4-with-plugins-system --set prometheus.enable=true
+          helm install my-release \
+            testdata/project-v4-with-plugins/dist/chart \
+            --namespace project-v4-with-plugins-system \
+            --create-namespace \
+            --set prometheus.enable=true
 
       - name: Check Helm release status
         run: |
           helm status my-release --namespace project-v4-with-plugins-system
 
-      - name: Check Presence of ServiceMonitor
+      - name: Delete kind cluster
+        if: always()
         run: |
-          kubectl wait --namespace project-v4-with-plugins-system --for=jsonpath='{.kind}'=ServiceMonitor servicemonitor/project-v4-with-plugins-controller-manager-metrics-monitor
+          kind delete cluster || true
 
   # Test scenario: 
   # - scaffold project without creating webhooks, 
@@ -97,7 +120,7 @@ jobs:
   # Command to use to scaffold project without creating webhooks and so no need to install cert manager:
   # - kubebuilder init
   # - kubebuilder create api --group example.com --version v1 --kind App --controller=true --resource=true
-  # - kubebuilder edit --plugins=helm.kubebuilder.io/v1-alpha
+  # - kubebuilder edit --plugins=helm.kubebuilder.io/v2-alpha
   test-helm-no-webhooks:
     runs-on: ubuntu-latest
     if: github.event_name == 'push' || github.event.pull_request.head.repo.full_name != github.repository
@@ -149,9 +172,18 @@ jobs:
 
       - name: Deploy Helm chart without cert-manager
         working-directory: test-helm-no-webhooks
-        run: helm install my-release ./dist/chart --create-namespace --namespace test-helm-no-webhooks-system
+        run: |
+          helm install my-release \
+            ./dist/chart \
+            --create-namespace \
+            --namespace test-helm-no-webhooks-system
 
       - name: Verify deployment is working
         working-directory: test-helm-no-webhooks
         run: |
           helm status my-release --namespace test-helm-no-webhooks-system
+
+      - name: Delete kind cluster
+        if: always()
+        run: |
+          kind delete cluster || true

Makefile

@@ -103,10 +103,11 @@ generate-charts: build ## Re-generate the helm chart testdata and docs samples
 	rm -rf docs/book/src/cronjob-tutorial/testdata/project/dist/chart
 	rm -rf docs/book/src/multiversion-tutorial/testdata/project/dist/chart
 
-	(cd testdata/project-v4-with-plugins && ../../bin/kubebuilder edit --plugins=helm/v1-alpha)
-	(cd docs/book/src/getting-started/testdata/project && ../../../../../../bin/kubebuilder edit --plugins=helm/v1-alpha)
-	(cd docs/book/src/cronjob-tutorial/testdata/project && ../../../../../../bin/kubebuilder edit --plugins=helm/v1-alpha)
-	(cd docs/book/src/multiversion-tutorial/testdata/project && ../../../../../../bin/kubebuilder edit --plugins=helm/v1-alpha)
+	# Generate helm charts from kustomize manifests using v2-alpha plugin
+	(cd testdata/project-v4-with-plugins && make build-installer && ../../bin/kubebuilder edit --plugins=helm/v2-alpha)
+	(cd docs/book/src/getting-started/testdata/project && make build-installer && ../../../../../../bin/kubebuilder edit --plugins=helm/v2-alpha)
+	(cd docs/book/src/cronjob-tutorial/testdata/project && make build-installer && ../../../../../../bin/kubebuilder edit --plugins=helm/v2-alpha)
+	(cd docs/book/src/multiversion-tutorial/testdata/project && make build-installer && ../../../../../../bin/kubebuilder edit --plugins=helm/v2-alpha)
 
 .PHONY: check-docs
 check-docs: ## Run the script to ensure that the docs are updated

cmd/cmd.go

@@ -34,6 +34,7 @@ import (
 	autoupdatev1alpha1 "sigs.k8s.io/kubebuilder/v4/pkg/plugins/optional/autoupdate/v1alpha"
 	grafanav1alpha1 "sigs.k8s.io/kubebuilder/v4/pkg/plugins/optional/grafana/v1alpha"
 	helmv1alpha1 "sigs.k8s.io/kubebuilder/v4/pkg/plugins/optional/helm/v1alpha"
+	helmv2alpha1 "sigs.k8s.io/kubebuilder/v4/pkg/plugins/optional/helm/v2alpha"
 )
 
 // Run bootstraps & runs the CLI
@@ -72,6 +73,7 @@ func Run() {
 			&deployimagev1alpha1.Plugin{},
 			&grafanav1alpha1.Plugin{},
 			&helmv1alpha1.Plugin{},
+			&helmv2alpha1.Plugin{},
 			&autoupdatev1alpha1.Plugin{},
 		),
 		cli.WithPlugins(externalPlugins...),

docs/book/src/SUMMARY.md

@@ -125,6 +125,7 @@
     - [go/v4](./plugins/available/go-v4-plugin.md)
     - [grafana/v1-alpha](./plugins/available/grafana-v1-alpha.md)
     - [helm/v1-alpha](./plugins/available/helm-v1-alpha.md)
+    - [helm/v2-alpha](./plugins/available/helm-v2-alpha.md)
     - [kustomize/v2](./plugins/available/kustomize-v2.md)
   - [Extending](./plugins/extending.md)
     - [CLI and Plugins](./plugins/extending/extending_cli_features_and_plugins.md)

docs/book/src/cronjob-tutorial/testdata/project/.github/workflows/test-chart.yml

@@ -46,35 +46,24 @@ jobs:
         run: |
           helm lint ./dist/chart
 
-# TODO: Uncomment if cert-manager is enabled
-      - name: Install cert-manager via Helm
+
+      - name: Install cert-manager via Helm (wait for readiness)
         run: |
           helm repo add jetstack https://charts.jetstack.io
           helm repo update
-          helm install cert-manager jetstack/cert-manager --namespace cert-manager --create-namespace --set crds.enabled=true
-
-      - name: Wait for cert-manager to be ready
-        run: |
-          kubectl wait --namespace cert-manager --for=condition=available --timeout=300s deployment/cert-manager
-          kubectl wait --namespace cert-manager --for=condition=available --timeout=300s deployment/cert-manager-cainjector
-          kubectl wait --namespace cert-manager --for=condition=available --timeout=300s deployment/cert-manager-webhook
+          helm install cert-manager jetstack/cert-manager \
+            --namespace cert-manager \
+            --create-namespace \
+            --set crds.enabled=true \
+            --wait \
+            --timeout 300s
 
 # TODO: Uncomment if Prometheus is enabled
 #      - name: Install Prometheus Operator CRDs
 #        run: |
 #          helm repo add prometheus-community https://prometheus-community.github.io/helm-charts
 #          helm repo update
 #          helm install prometheus-crds prometheus-community/prometheus-operator-crds
-#
-#      - name: Install Prometheus via Helm
-#        run: |
-#          helm repo add prometheus-community https://prometheus-community.github.io/helm-charts
-#          helm repo update
-#          helm install prometheus prometheus-community/prometheus --namespace monitoring --create-namespace
-#
-#      - name: Wait for Prometheus to be ready
-#        run: |
-#          kubectl wait --namespace monitoring --for=condition=available --timeout=300s deployment/prometheus-server
 
       - name: Install Helm chart for project
         run: |
@@ -83,8 +72,3 @@ jobs:
       - name: Check Helm release status
         run: |
           helm status my-release --namespace project-system
-
-# TODO: Uncomment if prometheus.enabled is set to true to confirm that the ServiceMonitor gets created
-#      - name: Check Presence of ServiceMonitor
-#        run: |
-#          kubectl wait --namespace project-system --for=jsonpath='{.kind}'=ServiceMonitor servicemonitor/project-controller-manager-metrics-monitor

docs/book/src/cronjob-tutorial/testdata/project/PROJECT

@@ -7,7 +7,9 @@ domain: tutorial.kubebuilder.io
 layout:
 - go.kubebuilder.io/v4
 plugins:
-  helm.kubebuilder.io/v1-alpha: {}
+  helm.kubebuilder.io/v2-alpha:
+    manifests: dist/install.yaml
+    output: dist
 projectName: project
 repo: tutorial.kubebuilder.io/project
 resources:

docs/book/src/cronjob-tutorial/testdata/project/README.md

@@ -97,7 +97,7 @@ kubectl apply -f https://raw.githubusercontent.com/<org>/project/<tag or branch>
 1. Build the chart using the optional helm plugin
 
 ```sh
-kubebuilder edit --plugins=helm/v1-alpha
+kubebuilder edit --plugins=helm/v2-alpha
 ```
 
 2. See that a chart was generated under 'dist/chart', and users

docs/book/src/cronjob-tutorial/testdata/project/dist/chart/templates/_helpers.tpl

@@ -1,9 +1,11 @@
+{{/*
+Chart name based on project name.
+Truncated to 63 characters for Kubernetes compatibility.
+*/}}
 {{- define "chart.name" -}}
 {{- if .Chart }}
   {{- if .Chart.Name }}
     {{- .Chart.Name | trunc 63 | trimSuffix "-" }}
-  {{- else if .Values.nameOverride }}
-    {{ .Values.nameOverride | trunc 63 | trimSuffix "-" }}
   {{- else }}
     project
   {{- end }}
@@ -12,7 +14,48 @@
 {{- end }}
 {{- end }}
 
+{{/*
+Full name of the chart (with release name prefix).
+Combines release name with chart name.
+Truncated to 63 characters for Kubernetes compatibility.
+*/}}
+{{- define "chart.fullname" -}}
+{{- $name := include "chart.name" . }}
+{{- if contains $name .Release.Name }}
+{{- .Release.Name | trunc 63 | trimSuffix "-" }}
+{{- else }}
+{{- printf "%s-%s" .Release.Name $name | trunc 63 | trimSuffix "-" }}
+{{- end }}
+{{- end }}
+
+{{/*
+Namespace for generated references.
+Always uses the Helm release namespace.
+*/}}
+{{- define "chart.namespaceName" -}}
+{{ .Release.Namespace }}
+{{- end }}
+
+
+
+{{/*
+Service name with proper truncation for Kubernetes 63-character limit.
+Takes a context with .suffix for the service type (e.g., "webhook-service").
+If fullname + suffix exceeds 63 chars, truncates fullname to 45 chars.
+*/}}
+{{- define "chart.serviceName" -}}
+{{- $fullname := include "chart.fullname" .context -}}
+{{- if gt (len $fullname) 45 -}}
+{{- printf "%s-%s" (trunc 45 $fullname | trimSuffix "-") .suffix | trunc 63 | trimSuffix "-" -}}
+{{- else -}}
+{{- printf "%s-%s" $fullname .suffix | trunc 63 | trimSuffix "-" -}}
+{{- end -}}
+{{- end }}
 
+{{/*
+Common labels for Helm charts.
+Includes app version, chart version, app name, instance, and managed-by labels.
+*/}}
 {{- define "chart.labels" -}}
 {{- if .Chart.AppVersion -}}
 app.kubernetes.io/version: {{ .Chart.AppVersion | quote }}
@@ -25,26 +68,11 @@ app.kubernetes.io/instance: {{ .Release.Name }}
 app.kubernetes.io/managed-by: {{ .Release.Service }}
 {{- end }}
 
-
+{{/*
+Selector labels for matching pods and services.
+Only includes name and instance for consistent selection.
+*/}}
 {{- define "chart.selectorLabels" -}}
 app.kubernetes.io/name: {{ include "chart.name" . }}
 app.kubernetes.io/instance: {{ .Release.Name }}
 {{- end }}
-
-
-{{- define "chart.hasMutatingWebhooks" -}}
-{{- $hasMutating := false }}
-{{- range . }}
-  {{- if eq .type "mutating" }}
-    $hasMutating = true }}{{- end }}
-{{- end }}
-{{ $hasMutating }}}}{{- end }}
-
-
-{{- define "chart.hasValidatingWebhooks" -}}
-{{- $hasValidating := false }}
-{{- range . }}
-  {{- if eq .type "validating" }}
-    $hasValidating = true }}{{- end }}
-{{- end }}
-{{ $hasValidating }}}}{{- end }}

docs/book/src/cronjob-tutorial/testdata/project/dist/chart/templates/cert-manager/metrics-certs.yaml

@@ -0,0 +1,18 @@
+{{- if and .Values.certManager.enable .Values.metrics.enable }}
+apiVersion: cert-manager.io/v1
+kind: Certificate
+metadata:
+    labels:
+        app.kubernetes.io/managed-by: {{ .Release.Service }}
+        app.kubernetes.io/name: project
+    name: project-metrics-certs
+    namespace: {{ .Release.Namespace }}
+spec:
+    dnsNames:
+        - {{ include "chart.serviceName" (dict "suffix" "controller-manager-metrics-service" "context" .) }}.{{ .Release.Namespace }}.svc
+        - {{ include "chart.serviceName" (dict "suffix" "controller-manager-metrics-service" "context" .) }}.{{ .Release.Namespace }}.svc.cluster.local
+    issuerRef:
+        kind: Issuer
+        name: {{ include "chart.name" . }}-selfsigned-issuer
+    secretName: metrics-server-cert
+{{- end }}

docs/book/src/cronjob-tutorial/testdata/project/dist/chart/templates/cert-manager/selfsigned-issuer.yaml

@@ -0,0 +1,12 @@
+{{- if .Values.certManager.enable }}
+apiVersion: cert-manager.io/v1
+kind: Issuer
+metadata:
+    labels:
+        app.kubernetes.io/managed-by: {{ .Release.Service }}
+        app.kubernetes.io/name: project
+    name: project-selfsigned-issuer
+    namespace: {{ .Release.Namespace }}
+spec:
+    selfSigned: {}
+{{- end }}