Enhancement: Support custom boilerplate license content via file path and improve `--license` UX/docs

[camilamacedo86]

Kubebuilder currently uses hack/boilerplate.go.txt as the boilerplate header for generated files, but kubebuilder init --license <value> is limited to small predefined templates and requires users to pass an internal key (e.g. mit) rather than an SPDX ID (e.g. Apache-2.0), which is confusing UX.

Goals

• Allow users to provide large/custom boilerplate header content (via a file path) for init/edit.
• Ensure regeneration (alpha generate) reuses existing boilerplate header to preserve custom license headers.
• Improve UX/docs around the --license flag and how boilerplate works.

Background

Anything added to hack/boilerplate.go.txt will be used as the boilerplate header for newly generated files.

Current --license behavior:

• kubebuilder init --license Apache-2.0 is not supported because Kubebuilder expects a simple key (map/enum value), e.g. mit (not an SPDX string like Apache-2.0).
• ⚠️ Changing this behavior directly would be a breaking change.

Supported license keys are defined here:

• kubebuilder/pkg/plugins/golang/v4/init.go

  Lines 88 to 90 in d0c8fc7

  	fs.StringVar(&p.license, "license", "apache2",
  	"license to use to boilerplate, may be one of 'apache2', 'none'")
  	fs.StringVar(&p.owner, "owner", "", "owner to add to the copyright")

• kubebuilder/pkg/plugins/golang/v4/scaffolds/internal/templates/hack/boilerplate.go

  Lines 97 to 122 in d0c8fc7

  	const boilerplateTemplate = `/*
  	{{ if .Owner -}}
  	Copyright {{ .Year }} {{ .Owner }}.
  	{{- else -}}
  	Copyright {{ .Year }}.
  	{{- end }}
  	{{ index .Licenses .License }}*/`
  	var knownLicenses = map[string]string{
  	"apache2": apache2,
  	"copyright": "",
  	}
  	const apache2 = `
  	Licensed under the Apache License, Version 2.0 (the "License");
  	you may not use this file except in compliance with the License.
  	You may obtain a copy of the License at
  	http://www.apache.org/licenses/LICENSE-2.0
  	Unless required by applicable law or agreed to in writing, software
  	distributed under the License is distributed on an "AS IS" BASIS,
  	WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  	See the License for the specific language governing permissions and
  	limitations under the License.
  	`

Proposal

1. Add a new flag to accept a file path for boilerplate content, e.g.:

   • kubebuilder init --boilerplate-file /path/to/header.txt
   • kubebuilder edit --boilerplate-file /path/to/header.txt
     Behavior:
   • Copy the provided content into hack/boilerplate.go.txt during init/edit.
   • If the file is large, this remains ergonomic and avoids long CLI arguments.

2. Update alpha generate to prefer the existing hack/boilerplate.go.txt if present, so re-generation preserves custom headers.

3. Improve docs/help output:

   • Add references to a “Header / License Boilerplate” Reference doc section explaining:
     • What hack/boilerplate.go.txt is
     • How to customize it
     • How init/edit flags interact with it
   • Clarify --license accepts Kubebuilder keys (enum/map values), not SPDX IDs, and provide examples.

[camilamacedo86]

c/c @vitorfloriano

[sayan1112]

Hi, I’m new to contributing and would like to work on this issue.
Can you please assign it to me?

[camilamacedo86]

Hi @sayan1112

That is great !!

But see that we have a PR for that already: #5456

However, we really need help to review.
Would you like to help us?