controller-gen CLI

Kubebuilder makes use of a tool called controller-gen for generating utility code and Kubernetes YAML. This code and config generation is controlled by the presence of special “marker comments” in Go code.

controller-gen is built out of different “generators” (which specify what to generate) and “output rules” (which specify how and where to write the results).

Both are configured through command line options specified in marker format.

For instance, the following command:

controller-gen paths=./... crd:trivialVersions=true rbac:roleName=controller-perms output:crd:artifacts:config=config/crd/bases

generates CRDs and RBAC, and specifically stores the generated CRD YAML in config/crd/bases. For the RBAC, it uses the default output rules (config/rbac). It considers every package in the current directory tree (as per the normal rules of the go ... wildcard).

Generators

Each different generator is configured through a CLI option. Multiple generators may be used in a single invocation of controller-gen.

// +webhook
headerFile
string
year
string
generates (partial) {Mutating,Validating}WebhookConfiguration objects.
headerFile
string
specifies the header text (e.g. license) to prepend to generated files.
year
string
specifies the year to substitute for " YEAR" in the header file.
// +schemapatch
generateEmbeddedObjectMeta
bool
manifests
string
maxDescLen
int
patches existing CRDs with new schemata.

It will generate output for each "CRD Version" (API version of the CRD type itself) , e.g. apiextensions/v1) available.

generateEmbeddedObjectMeta
bool
specifies if any embedded ObjectMeta in the CRD should be generated
manifests
string
contains the CustomResourceDefinition YAML files.
maxDescLen
int
specifies the maximum description length for fields in CRD's OpenAPI schema.

0 indicates drop the description for all fields completely. n indicates limit the description to at most n characters and truncate the description to closest sentence boundary if it exceeds n characters.

// +rbac
headerFile
string
roleName
string
year
string
generates ClusterRole objects.
headerFile
string
specifies the header text (e.g. license) to prepend to generated files.
roleName
string
sets the name of the generated ClusterRole.
year
string
specifies the year to substitute for " YEAR" in the header file.
// +object
headerFile
string
year
string
generates code containing DeepCopy, DeepCopyInto, and DeepCopyObject method implementations.
headerFile
string
specifies the header text (e.g. license) to prepend to generated files.
year
string
specifies the year to substitute for " YEAR" in the header file.
// +crd
allowDangerousTypes
bool
crdVersions
string
generateEmbeddedObjectMeta
bool
headerFile
string
ignoreUnexportedFields
bool
maxDescLen
int
year
string
generates CustomResourceDefinition objects.
allowDangerousTypes
bool
allows types which are usually omitted from CRD generation because they are not recommended.

Currently the following additional types are allowed when this is true: float32 float64 Left unspecified, the default is false

crdVersions
string
specifies the target API versions of the CRD type itself to generate. Defaults to v1.

Currently, the only supported value is v1. The first version listed will be assumed to be the "default" version and will not get a version suffix in the output filename. You'll need to use "v1" to get support for features like defaulting, along with an API server that supports it (Kubernetes 1.16+).

generateEmbeddedObjectMeta
bool
specifies if any embedded ObjectMeta in the CRD should be generated
headerFile
string
specifies the header text (e.g. license) to prepend to generated files.
ignoreUnexportedFields
bool
indicates that we should skip unexported fields.

Left unspecified, the default is false.

maxDescLen
int
specifies the maximum description length for fields in CRD's OpenAPI schema.

0 indicates drop the description for all fields completely. n indicates limit the description to at most n characters and truncate the description to closest sentence boundary if it exceeds n characters.

year
string
specifies the year to substitute for " YEAR" in the header file.

Output Rules

Output rules configure how a given generator outputs its results. There is always one global “fallback” output rule (specified as output:<rule>), plus per-generator overrides (specified as output:<generator>:<rule>).

For brevity, the per-generator output rules (output:<generator>:<rule>) are omitted below. They are equivalent to the global fallback options listed here.

// +output:artifacts
code
string
config
string
outputs artifacts to different locations, depending on whether they're package-associated or not.

Non-package associated artifacts are output to the Config directory, while package-associated ones are output to their package's source files' directory, unless an alternate path is specified in Code.

code
string
overrides the directory in which to write new code (defaults to where the existing code lives).
config
string
points to the directory to which to write configuration.
// +output:dir
string
outputs each artifact to the given directory, regardless of if it's package-associated or not.
string
// +output:none
skips outputting anything.
// +output:stdout
outputs everything to standard-out, with no separation.

Generally useful for single-artifact outputs.

Other Options

// +paths
string
represents paths and go-style path patterns to use as package roots.

Multiple paths can be specified using "{path1, path2, path3}".

string