helm/v2-alpha: network-policy not included as optional value unlike prometheus

[asergeant01]

What broke? What's expected?

The helm/v2-alpha plugin handles prometheus and network-policy inconsistently when they are commented out in kustomization.yaml.

Expected behavior:
Both optional features (prometheus and network-policy) should generate conditional templates with enable/disable values when commented out.

Actual behavior:

• prometheus (commented out) → generates prometheus.enable: false in values.yaml and a conditional ServiceMonitor template with {{- if .Values.prometheus.enable }}

• network-policy (commented out) → generates nothing, no value, no conditional template

This inconsistency means users cannot enable network-policy via helm values without modifying the kustomization.yaml and regenerating.

Reproducing this issue

# Initialize project with helm/v2-alpha
kubebuilder init --plugins=helm/v2-alpha --domain example.com --repo github.com/example/test

# Verify both are commented in config/default/kustomization.yaml:
# - ../prometheus
# - ../network-policy

# Generate helm chart
kubebuilder edit --plugins=helm/v2-alpha

# Check values.yaml - prometheus exists, networkPolicy does not
grep -E "prometheus|networkPolicy|network" dist/chart/values.yaml
# Output: prometheus:
#         enable: false

# Check templates - monitoring exists, no network-policy
ls dist/chart/templates/
# No extras directory

KubeBuilder (CLI) Version

4.11.1

PROJECT version

3

Plugin versions

- go.kubebuilder.io/v4
- helm.kubebuilder.io/v2-alpha

Other versions

Go version: 1.24
controller-runtime: v0.21.0

Extra Labels

/kind regression

[camilamacedo86]

Hi @asergeant01,

If the NetworkPolicies aren’t included in the kustomize, they won’t make it into the chart output.

Given that, this doesn’t seem like something end users can realistically opt in/out of via Helm values—right? It’s effectively a maintainer decision whether we ship them by default.

So for this case, the maintainer would need to:

• Update config/default/kustomization.yaml to enable the NetworkPolicies; and then

They’ll be included in the generated chart output.

Does it make sense?
If not, why do think that end users of the chart itself should be able to opt-in for it or not?
What would be the use case?

[asergeant01]

@camilamacedo86

Yes, I understand that NetworkPolicies won’t make it into the chart unless they’re enabled in config/default/kustomization.yaml. But I think saying “end users can’t realistically opt in/out via Helm values” is a product decision, not a technical limitation. There are valid cases where operators should let chart consumers toggle NetworkPolicies.

A simple example is development vs production. While the goal of mirroring the kustomize output makes sense, the structure under config/ naturally lends itself to different overlays for different scenarios (e.g. dev, qa, prod). Helm, unlike kustomize, can express these kinds of conditionals inside a single chart without requiring overlays or forks.

This actually raises a broader question about how maintainers can provide optional components to chart consumers—NetworkPolicies are just one case. Others might include optional Services, ingress objects, or other resources that some environments need and others don’t.

[camilamacedo86]

Hi @asergeant01,

Everything in install.yaml ends up in the Helm Chart (except CRs/samples — we still need to decide what the right behavior is there. See: #5391). That said, the Helm Chart is meant to package the existing solution for distribution. It is not meant to become a separate project with its own set of features and options.

About your question (“how can maintainers provide optional components to chart users?”):

It is possible, but the idea is:

• If the extra configuration exists in Kustomize, it will be included in the generated Chart.
• If something is not part of the default scaffold (so we can’t recognize it as “default”), it will go under the extras/ directory.

Now, specifically about NetworkPolicies: should we include them in the Helm Chart even if they are not part of the project’s default setup and they don’t exist in Kustomize?

One possible RFE here is: ship NetworkPolicies as optional (off by default), for example:

• Generate the NP templates, but keep them disabled by default with networkPolicy.enabled: false.
• If NetworkPolicies exist in the Kustomize input, then we enable them by default (or at least set the generated defaults accordingly).

I need a bit more time to think it through, but I think this could make sense — we just need to confirm we’re aligning with common Helm chart patterns and that it won’t create confusing defaults.

Regarding the dev/prod example: I’m not sure we can support that as built-in chart options, because the default scaffold does not provide dev/prod variants today. We can try to keep the Helm Chart plugin flexible, but we don’t want it to turn into another solution. The goal is to package the Operator for distribution, and there are some technical limits. In most cases, maintainers can still override or extend things by adding their own customizations on top of the generated chart.

That’s also why some directories/files are not overwritten when you regenerate the chart unless you use --force: so maintainers can keep their custom changes and still re-generate the chart later without losing them.

Thanks!

[asergeant01]

@camilamacedo86

Now, specifically about NetworkPolicies: should we include them in the Helm Chart even if they are not part of the project’s default setup and they don’t exist in Kustomize

I might be doing something wrong, but if I run kubebuilder init --domain example.com --owner "Test" --repo github.com/yourname/my-operator and check the config directory, the NP is there by default for metrics at least so I would say it is part of the projects default setup. Obviously running kubebuilder create webhook then scaffolds in the web hook NP.

About your question (“how can maintainers provide optional components to chart users?”):

It is possible, but the idea is:

• If the extra configuration exists in Kustomize, it will be included in the generated Chart.
• If something is not part of the default scaffold (so we can’t recognize it as “default”), it will go under the extras/ directory.

the first point is the current behaviour, if I create a new service, I add it to the kustomization.yaml as a resource, it correctly gets added to the extras directory of a chart. However, if that service should be something optional, there is no way to define that.

Assuming a kustomization file in default looks like this:

resources:
  - ../crd
  - ../rbac
  - ../manager
  # [WEBHOOK] To enable webhook, uncomment all the sections with [WEBHOOK] prefix including the one in
  # crd/kustomization.yaml
  - ../webhook
  # [CERTMANAGER] To enable cert-manager, uncomment all sections with 'CERTMANAGER'. 'WEBHOOK' components are required.
  - ../certmanager
  # [PROMETHEUS] To enable prometheus monitor, uncomment all sections with 'PROMETHEUS'.
  #- ../prometheus
  # [METRICS] Expose the controller manager metrics service.
  - metrics_service.yaml
  # [NETWORK POLICY] Protect the /metrics endpoint and Webhook Server with NetworkPolicy.
  # Only Pod(s) running a namespace labeled with 'metrics: enabled' will be able to gather the metrics.
  # Only CR(s) which requires webhooks and are applied on namespaces labeled with 'webhooks: enabled' will
  # be able to communicate with the Webhook Server.
  #- ../network-policy
  #- ../my-optional-service

whereby there are resources commented out, you could interpret those as resources which should be added but be wrapped with a enabled toggle in the values file.

If we keep the current behaviour, and I force upon the end user the optional service, there will be variables within that such as the port of that service which I will want the end user to be able to parameterise which isn't handled by the current implementation.

Perhaps something could be added to the PROJECT file to list optional_resources and which fields should be interpreted as configurable parameters?

[camilamacedo86]

Hi @asergeant01,

We MAY be able to do this

One possible RFE is to ship NetworkPolicies as optional (off by default), for example:

• Generate the NetworkPolicy templates, but keep them disabled by default with networkPolicy.enabled: false.
• If NetworkPolicies exist in the Kustomize input, then enable them by default (or at least set the generated defaults accordingly).

However, we cannot do this

Add an enabled/disabled toggle in values.yaml for any unknown resource.

We can’t do that programmatically, and it has no relation to the PROJECT file.
It’s not possible for the Helm plugin to parse arbitrary YAML and automatically decide: “this resource is 100% unknown to us, but the author wants a toggle for it”.
We cannot address it with flags / UX.

How project authors should handle these scenarios

• a) Put all custom logic under config/, so your bundle installer uses Kustomize with all their custom project configuration. Authors can also distribute the project this way.
• b) Run the Helm plugin to generate the Helm chart.
• c) Then the author can customize the Helm chart/values as they like. The values.yaml is not overwritten when we re-running the Helm plugin.
• d) Also: Customizations are preserved by the AutoUpdate plugin (GitHub Actions) and by kubebuilder alpha update locally — both use the same update logic.

Caveat: if anything under config/ changes, authors should re-run the Helm plugin.

When they do, some key files will never be overwritten (see: https://book.kubebuilder.io/plugins/available/helm-v2-alpha).
But some custom changes on top may still be affected. In those cases, the best approach is to compare with Git and restore (e.g., compare local branch vs main in the IDE and re-apply the custom layer). This check could also be automated (even with AI tooling) as part of a Makefile target like verify

About the PROJECT file idea

“Perhaps something could be added to the PROJECT file to list optional_resources and which fields should be interpreted as configurable parameters?”

The PROJECT file only records the inputs given to the tool. It does not define behavior.
So we cannot solve this via the PROJECT file, and users should not edit it manually in normal circumstances.

Hope that clarifies.

[camilamacedo86]

Hi @asergeant01! 👋

As we explore more AI-assisted workflows, this Kubebuilder thread feels relevant: #5325.

It made me wonder if we could offer a similar option on our side—using AI to handle “unknown/customs lile” user needs (e.g., when the intent is “create X”, we generate it), and ensure the result isn’t lost by recording what was produced in a reproducible format in the PROJECT file. We track like input config. That way we can re-create it later

One of our main goals this year is to push the tooling to take better advantage of AI so it becomes smarter and more flexible: that should allow us handling more customisations, reducing manual steps, and making the experience simpler for end users.