helm/v2-alpha: Should the generated chart support installing Custom Resources (CRs)? If so, what is the recommended mechanism?

[camilamacedo86]

Users want to ship sample/default CRs with the operator chart (e.g. config/samples/ or CRs provided via an install.yaml input to the Helm plugin).
But helm/v2-alpha intentionally generates CRDs + controller/operator manifests, and Helm has known CRD/CR ordering limitations.

Refs:

• Question: helm - CRDs for first installation #5386
• https://book.kubebuilder.io/plugins/available/helm-v2-alpha.html
• https://helm.sh/docs/chart_best_practices/custom_resource_definitions/

Questions

1. Should helm/v2-alpha support CRs at all?
2. If yes, what’s the preferred mechanism that is maintainable and explicit (opt-in)?
3. How could we do that if we cannot generate a bundle make install-builder with the CRs by default since it would not be an valid install? What would be the best approach? How the community work with in the common cases?

Options (discussion)

A) Support CRs only in an advanced/explicit setup (e.g. when using the CRD split approach in #5391): #5391
B) Do not install CRs, but include them for users and print instructions in templates/NOTES.txt (e.g. “kubectl apply -f samples/...”). Example

package charttemplates

import (
	"path/filepath"

	"sigs.k8s.io/kubebuilder/v4/pkg/machinery"
)

var _ machinery.Template = &Notes{}

// Notes scaffolds the NOTES.txt file for Helm chart
type Notes struct {
	machinery.TemplateMixin
	machinery.ProjectNameMixin

	// HasCustomResources indicates if the project has Custom Resource samples
	HasCustomResources bool

	// CustomResourceKinds is a list of unique CR kinds found in samples
	CustomResourceKinds []string

	// OutputDir specifies the output directory for the chart
	OutputDir string
}

// SetTemplateDefaults implements machinery.Template
func (f *Notes) SetTemplateDefaults() error {
	if f.Path == "" {
		outputDir := f.OutputDir
		if outputDir == "" {
			outputDir = "dist"
		}
		f.Path = filepath.Join(outputDir, "chart", "templates", "NOTES.txt")
	}

	f.TemplateBody = notesTemplate

	return nil
}

const notesTemplate = `{{- if .HasCustomResources }}
Thank you for installing {{ .Chart.Name }}!

Your release is named {{ .Release.Name }}.

1. The controller and CRDs have been installed in namespace {{ .Release.Namespace }}.

2. Sample Custom Resources are available in the chart's samples/ directory.
   These are NOT automatically installed and should be reviewed before applying.

3. To apply a sample Custom Resource:

   kubectl apply -f samples/<kind>_<name>.yaml -n {{ .Release.Namespace }}

   Example:
     kubectl apply -f samples/cronjob_sample.yaml -n {{ .Release.Namespace }}

4. Verify the installation:

   kubectl get pods -n {{ .Release.Namespace }}
   kubectl get customresourcedefinitions

To learn more about the release, try:

  $ helm status {{ .Release.Name }} -n {{ .Release.Namespace }}
  $ helm get all {{ .Release.Name }} -n {{ .Release.Namespace }}
{{- else }}
Thank you for installing {{ .Chart.Name }}!

Your release is named {{ .Release.Name }}.

The controller and CRDs have been installed in namespace {{ .Release.Namespace }}.

To verify the installation:

  kubectl get pods -n {{ .Release.Namespace }}
  kubectl get customresourcedefinitions

To learn more about the release, try:

  $ helm status {{ .Release.Name }} -n {{ .Release.Namespace }}
  $ helm get all {{ .Release.Name }} -n {{ .Release.Namespace }}
{{- end }}
`

C) Add a flag to generate a separate chart for CRs to be installed after CRDs/operator (explicit extra step).
D) Never support CRs in the plugin; document “apply CRs after install” as the only workflow.

[Shubhamag12]

Hi @camilamacedo86, thank you for the detailed context.

1. From my understanding, helm/v2-alpha can support CRs, but indirectly. Including sample CRs for reference would be useful, but should not be installed automatically, due to helm CRD/CR ordering constraint and best practices.
2. Option B fits best here: shipping sample CRs with the chart and providing post-install instructions (as mentioned above). This keeps install valid and predictable, also it would be easy to maintain while still supporting common user workflows.

[camilamacedo86]

Hi @Shubhamag12

Thanks for your input. I feel the same way, but my concern with Option B is that the samples won’t be easy to manage with automated lifecycle workflows in GitOps solutions.

I think we should look at how others solve this—what’s the common approach here? Ideally, I’d like the sample/CR values to be exposed via Helm chart values (or something similar) so they can be managed declaratively.