Question: helm - CRDs for first installation

[emirot]

I read the doc https://book.kubebuilder.io/plugins/available/helm-v2-alpha.html and Why CRD are under templates sections and it explains why it is done like so.

However by doing that a simple helm install my-chart ./charts/chart -n my-ns won't work.

It will fail with the issue saying CRDs are missing

Error: INSTALLATION FAILED: unable to build kubernetes objects from release manifest: ... ensure CRDs are installed first

So should I copy the CRD one level up so it is installed the first time and then it will also be update because they are under template.

I will be happy to add in the documentation what's the recommended way

Shouldn't it create something like or should the cli do it

/chart
  /crds
  /tempaltes
    /crd

But even with that it won't work I would get another issue

Error: INSTALLATION FAILED: Unable to continue with install: CustomResourceDefinition "argocdcommitstatuses.promoter.argoproj.io" in namespace "" exists and cannot be imported into the current release: invalid ownership metadata; label validation error: missing key "app.kubernetes.io/managed-by": must be set to "Helm"; annotation validation error: missing key "meta.helm.sh/release-name": must be set to "promoter"; annotation validation error: missing key "meta.helm.sh/release-namespace": must be set to "promoter-system"

[camilamacedo86]

Hi @emirot 👋

Thanks for the report — and also for taking time to check the docs and suggest improvements.

About the Helm chart layout (CRDs under templates)

This is intentional. The Helm layout we generate follows the design adopted by Kubebuilder for this plugin:
https://github.com/kubernetes-sigs/kubebuilder/blob/master/designs/helm-chart-autogenerate-plugin.md

We keep CRDs under templates/ (ex: templates/crd/) because for Operators this is a common practice and it works better with Helm upgrades. Helm’s top-level crds/ folder has important limitations (for example, CRDs there are not upgraded by Helm).

Important note about CRs (Custom Resources)

A key Helm limitation is ordering:

• If a chart installs a CRD and also installs CRs of that type, Kubernetes needs the CRD to be registered first.
• Helm does not guarantee “wait until CRD is registered, then apply CRs”.

Because of that:

• Kubebuilder does not generate CRs in this plugin (we generate CRDs + controller/operator manifests).
• If you want to ship CRs in the same Helm chart, you will usually need Helm hooks (for example post-install / post-upgrade) or a separate step to apply CRs after the chart is installed.

Why I think your error is not caused by the CRD folder location

Given the tests above, it is more likely one of these is happening:

1. The CRD argocdcommitstatuses.promoter.argoproj.io is not present in the generated manifests (install.yaml or chart), OR
2. The CRD already exists in the cluster (installed by something else or a previous run), and Helm refuses to “adopt” it due to missing/invalid Helm ownership metadata (this often matches the “cannot be imported” / “invalid ownership metadata” error), OR
3. There is a CR (Custom Resource) in the chart or in your pipeline being applied too early (before the CRD is registered). In that case, the CR should be applied after install (or via hooks).

Quick checks (so we can confirm)

Could you please share:

• a link to your project (or a minimal repro),
• your generated dist/install.yaml,
• and the rendered chart output (for example helm template ...) or the chart folder?

Also, can you confirm:

• Is argocdcommitstatuses.promoter.argoproj.io present in dist/install.yaml?
• Is it present in the Helm chart templates (after rendering)?
• Does this CRD already exist in the cluster before you run helm install?
• Are you also trying to install a CR instance (Custom Resource) as part of the chart or right after running Helm?
  If yes, can you share that CR YAML too? (This helps confirm ordering/hook needs.)

With that info, we can analyse better what is happing and try to help you out.

Proof that the current layout works today (tests + CI)

We have good coverage to ensure this scenario works end-to-end:

✅ E2E tests: we mock a project, generate dist/install.yaml, generate the chart, and then install it using Helm:

• kubebuilder/test/e2e/helm/plugin_cluster_test.go

  Line 205 in 8d8c1a8

  err = kbc.HelmInstallRelease()

• kubebuilder/test/e2e/utils/test_context.go

  Lines 428 to 434 in 8d8c1a8

  	func (t *TestContext) HelmInstallRelease() error {
  	releaseName := fmt.Sprintf("e2e-%s", t.TestSuffix)
  	cmd := exec.Command("helm", "install", releaseName, "dist/chart",
  	"--namespace", fmt.Sprintf("e2e-%s-system", t.TestSuffix))
  	_, err := t.Run(cmd)
  	return err
  	}

✅ GitHub Actions: we continuously validate the Helm samples + tutorial projects:

• https://github.com/kubernetes-sigs/kubebuilder/blob/master/.github/workflows/test-helm-book.yml
• https://github.com/kubernetes-sigs/kubebuilder/blob/master/.github/workflows/test-helm-samples.yml

Common Users feedbacks when they understand how Helm handle CRDs and why it is not good for Operators

Example: https://kubernetes.slack.com/archives/CAR30FCJZ/p1752753804202589?thread_ts=1752732217.829249&cid=CAR30FCJZ

Thanks again!

[emirot]

Hey @camilamacedo86,

Thanks for your detailed answer.

Here is the project: https://github.com/argoproj-labs/gitops-promoter/tree/main

What I did

kubebuilder edit --plugins=helm/v2-alpha --output-dir=charts

Then (after fixing #5387) manually

helm install promoter ./charts/chart --namespace promoter-system --create-namespace  --set crds.enabled=true
=> Error: INSTALLATION FAILED: unable to build kubernetes objects from release manifest: resource mapping not found for name: "promoter-controller-configuration" namespace: "promoter-system" from "": no matches for kind "ControllerConfiguration" in version "promoter.argoproj.io/v1alpha1"
ensure CRDs are installed first

So my question is what is the preferred way?

From your answer looks like there is two, helm hooks or applying the manifest before.

For the later should It be

kubectl apply -f charts/chart/template/crd/*.yaml

and run helm install ? but kubectl would fail because the .yaml file contains {{- if .Values.crd.enable }}

I believe users won't be able to do helm install my-chart, but the helm chart will work if they use ArgoCD or Flux.
Or if they do helm template chart | kubectl -f - twice.

[camilamacedo86]

Hi @emirot 👋

Sorry — could you please share what you fixed manually?

You mentioned:

Then (after fixing #5387) manually

What exactly did you change after that? For example:

• did you move the CRDs to a different folder or into another chart?
• did you split CRDs into a separate “CRDs chart”?

I’m asking because if you move the CRDs away from the default scaffold, then this condition can become wrong for your new layout:

  {{- if .Values.crd.enable }}

If the CRDs are no longer rendered from this chart, then Values.crd.enable does not really make sense anymore, and you would likely need to:

• update/remove that if condition, and/or
• adjust the chart values and templates to match your new structure.

About this point:

I believe users won't be able to do helm install my-chart, but the helm chart will work if they use ArgoCD or Flux.
Or if they do helm template chart | kubectl apply -f - twice.

With the default Kubebuilder scaffold, helm install my-chart should work (it is how we test it). We also have e2e tests and CI validating that flow.

So if helm install is not working in your case, I suspect it’s because the chart was customized (for example, CRDs moved to another chart or applied separately). In that scenario, you would need to update the scaffold accordingly (remove/adjust Values.crd.enable, and make sure CRDs are applied in the right step).

If the goal is to support “CRDs as a separate chart” as an official option, then we probably need a proper solution in the generator (like a flag/option) so the scaffold is generated differently for that mode.

Does that match what you are doing? Or am I missing something?
Are you saying that the way that it is does not work with ArgoCD or Flux?

[emirot]

@camilamacedo86 Sorry about the confusion, what I have done is easy to reproduce

git clone https://github.com/argoproj-labs/gitops-promoter.git
cd gitops-promoter
kubebuilder edit --plugins=helm/v2-alpha --output-dir=charts 
# just need to remove extra templating manually 
# Fresh kind cluster is used
helm install promoter ./charts/chart --namespace promoter-system --create-namespace  --set crds.enabled=true
Error: INSTALLATION FAILED: unable to build kubernetes objects from release manifest: resource mapping not found for name: "promoter-controller-configuration" namespace: "promoter-system" from "": no matches for kind "ControllerConfiguration" in version "promoter.argoproj.io/v1alpha1"
ensure CRDs are installed first

So my question is what is the preferred way of installing. Is that failure expected?

My chart was kustomize
As you can see in the bash above it was not kustomize, ( I did move them at some point to see if I could pass that error)

I am not sure to understand helm install my-chart do I do something wrong in my command then?

Are you saying that the way that it is does not work with ArgoCD or Flux?
If I remember correctly ArgoCD is more intelligent than Helm and would install the CRDs first. So even if the crds are inside the template folder it should work I will try.

[camilamacedo86]

See that in the extras you have the CRs.
If you remove the CRs or add hooks on it as post-install will work.
That is why it is failing for you

Important note about CRs (Custom Resources)

A key Helm limitation is ordering:

• If a chart installs a CRD and also installs CRs of that type, Kubernetes needs the CRD to be registered first.
• Helm does not guarantee “wait until CRD is registered, then apply CRs”.

Because of that:

• Kubebuilder does not generate CRs in this plugin (we generate CRDs + controller/operator manifests).
• If you want to ship CRs in the same Helm chart, you will usually need Helm hooks (for example post-install / post-upgrade) or a separate step to apply CRs after the chart is installed.

I will push some fixes that will solve your use case and when those get merged we do a new release.
Thank you for raise that. But for now just remove the extra dir generate and all should work fine.

[camilamacedo86]

Hi @emirot

See;

• (fix) for now: 🐛 (helm/v2-alpha): Prevent Custom Resource instances from being added to extras directory #5389 (we should ignore CRs)

Then, for discussion new features:

• helm/v2-alpha: Should the generated chart support installing Custom Resources (CRs)? If so, what is the recommended mechanism? #5390
• helm/v2-alpha: Add optional flag to generate a separate CRD chart (subchart/sibling chart) following Helm best practices #5391

So, I am marking this one as sorted out and closing it.

[camilamacedo86]

Hi @emirot

You can test it out with the latest release; https://github.com/kubernetes-sigs/kubebuilder/releases/tag/v4.11.1

The issue is fixed.

[emirot]

Hi @camilamacedo86,

Thanks a lot for your help!! Yes I have tested and it works.

The interpolation works and the extra folders is not present anymore.

➜  gitops-promoter git:(main) ✗ kubebuilder version
KubeBuilder:          v4.11.1
Kubernetes:           1.35.0
Git Commit:           4fbe8f6c63c6eb9a2a5cc440acbedad6b60d3225
Build Date:           2026-01-27T16:16:09Z
Go OS/Arch:           darwin/arm64
kubebuilder edit --plugins=helm/v2-alpha --output-dir=charts 
...
helm install promoter ./charts/chart --namespace promoter-system --create-namespace  --set crds.enabled=true
NAME: promoter
LAST DEPLOYED: Tue Jan 27 08:56:04 2026
NAMESPACE: promoter-system
STATUS: deployed
REVISION: 1
TEST SUITE: None

Just need to handle the example in the crd but that's an issue on us not Kubebuilder as we have an example in argocdcommitstatuses that helm wants to render I need to comment it out or remove it.