CRD Generation

These markers describe how to construct a custom resource definition from a series of Go types and packages. Generation of the actual validation schema is described by the validation markers.

See Generating CRDs for examples.

Show Detailed Argument Help

// +versionName

: string

overrides the API group version for this package (defaults to the package name). Example: +versionName=v1beta1

: string

// +kubebuilder:unservedversion

does not serve this version.

This is useful if you need to drop support for a version in favor of a newer version. The version will still be stored in etcd if it's the storage version, but won't be served via the API.

Example:

// +kubebuilder:unservedversion
type MyCRDv1alpha1 struct {
    // This version is no longer served
}

// +kubebuilder:subresource:status

enables the "/status" subresource on a CRD.

The status subresource allows you to update the status field separately from the rest of the resource spec, and prevents updates to the status subresource when updating the root object. This is useful for separating user-provided spec from system-provided status.

Example:

// +kubebuilder:subresource:status
type MyCRD struct {
    metav1.TypeMeta
    metav1.ObjectMeta
    Spec   MyCRDSpec
    Status MyCRDStatus
}

// +kubebuilder:subresource:scale

selectorpath: string
specpath: string
statuspath: string

enables the "/scale" subresource on a CRD.

The scale subresource allows you to use kubectl scale and the HorizontalPodAutoscaler with your CRD.

Example:

// +kubebuilder:subresource:scale:specpath=.spec.replicas,statuspath=.status.replicas,selectorpath=.status.selector
type MyCRD struct {
    metav1.TypeMeta
    metav1.ObjectMeta
    Spec MyCRDSpec
    Status MyCRDStatus
}

selectorpath: string; specifies the jsonpath to the pod label selector field for the scale's status.

The selector field must be the string form (serialized form) of a selector. Setting a pod label selector is necessary for your type to work with the HorizontalPodAutoscaler. This is typically .status.selector.
specpath: string; specifies the jsonpath to the replicas field for the scale's spec.

This is where the desired number of replicas is stored (typically .spec.replicas).
statuspath: string; specifies the jsonpath to the replicas field for the scale's status.

This is where the actual number of replicas is stored (typically .status.replicas).

// +kubebuilder:storageversion

marks this version as the "storage version" for the CRD for conversion.

When conversion is enabled for a CRD (i.e. it's not a trivial-versions/single-version CRD), one version is set as the "storage version" to be stored in etcd. Attempting to store any other version will result in conversion to the storage version via a conversion webhook.

Example:

// +kubebuilder:storageversion
type MyCRDv2 struct {
    metav1.TypeMeta
    metav1.ObjectMeta
    Spec MyCRDSpec
}

// +kubebuilder:skipversion

removes the particular version of the CRD from the CRDs spec.

This is useful if you need to skip generating and listing version entries for 'internal' resource versions, which typically exist if using the Kubernetes upstream conversion-gen tool.

Example:

// +kubebuilder:skipversion
type MyCRDInternal struct {
    // internal version not served by API
}

// +kubebuilder:skip

don't consider this package as an API version. Use this to exclude internal or helper packages from CRD generation.

// +kubebuilder:selectablefield

JSONPath: string

adds a field that may be used with field selectors.

Field selectors allow users to filter resources based on field values when listing. For example, kubectl get mycrds --field-selector status.phase=Running.

Example:

// +kubebuilder:selectablefield:JSONPath=&#34;.status.phase&#34;
type MyCRD struct {
    metav1.TypeMeta
    metav1.ObjectMeta
    Status MyCRDStatus
}

JSONPath: string; specifies the jsonpath expression which is used to produce a field selector value.

The path is relative to the resource root. Example: .status.phase.

// +kubebuilder:resource

categories: string
path: string
scope: string
shortName: string
singular: string

configures naming and scope for a CRD.

Example:

// +kubebuilder:resource:path=mycrdplural,singular=mycrdsingular,shortName=mc;mcrd,categories=all,scope=Namespaced
type MyCRD struct {
    metav1.TypeMeta
    metav1.ObjectMeta
}

categories: string; specifies which group aliases this resource is part of.

Group aliases are used to work with groups of resources at once. The most common one is "all" which covers about a third of the base resources in Kubernetes, and is generally used for "user-facing" resources. This allows users to run commands like kubectl get all to include your CRD.
path: string; specifies the plural "resource" for this CRD.

It generally corresponds to a plural, lower-cased version of the Kind. For example, if the Kind is "MyCRD", the path might be "mycrds". See https://book.kubebuilder.io/cronjob-tutorial/gvks.html.
scope: string; overrides the scope of the CRD (Cluster vs Namespaced).

Scope defaults to "Namespaced". Cluster-scoped ("Cluster") resources don't exist in namespaces and are accessible from anywhere in the cluster.
shortName: string; specifies aliases for this CRD.

Short names are often used when people have work with your resource over and over again. For instance, "rs" for "replicaset" or "crd" for customresourcedefinition. Multiple short names can be specified separated by semicolons.
singular: string; overrides the singular form of your resource.

The singular form is otherwise defaulted off the plural (path). This is used in API responses and kubectl output.

// +kubebuilder:printcolumn

JSONPath: string
description: string
format: string
name: string
priority: int
type: string

adds a column to "kubectl get" output for this CRD.

This allows you to customize which columns are shown when users run kubectl get on your CRD.

Example:

// +kubebuilder:printcolumn:name=&#34;Status&#34;,type=string,JSONPath=`.status.phase`
// +kubebuilder:printcolumn:name=&#34;Age&#34;,type=date,JSONPath=`.metadata.creationTimestamp`
type MyCRD struct {
    metav1.TypeMeta
    metav1.ObjectMeta
}

JSONPath: string; specifies the jsonpath expression used to extract the value of the column.

The path is relative to the resource root. Example: .status.phase or .spec.replicas.
description: string; specifies optional help text for this column.

Display behavior is client-dependent; see CustomResourceColumnDefinition in the Kubernetes API docs.
format: string; specifies the format of the column.

It may be any OpenAPI data format corresponding to the type, listed at https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#data-types.
name: string; specifies the name of the column as it will appear in the header.
priority: int; indicates how important it is that this column be displayed.

Lower priority (higher numbered) columns will be hidden if the terminal width is too small. Priority 0 columns are always shown.
type: string; indicates the type of the column.

It may be any OpenAPI data type listed at https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#data-types. Common values: "string", "integer", "number", "boolean", "date".

// +kubebuilder:metadata

annotations: string
labels: string

configures the additional annotations or labels for this CRD.

For example adding annotation "api-approved.kubernetes.io" for a CRD with Kubernetes groups, or annotation "cert-manager.io/inject-ca-from-secret" for a CRD that needs CA injection.

Example:

// +kubebuilder:metadata:annotations=&#34;api-approved.kubernetes.io/v1=https://github.com/myorg/myrepo/pull/123&#34;
// +kubebuilder:metadata:labels=&#34;app=myapp&#34;
type MyCRD struct {
    metav1.TypeMeta
    metav1.ObjectMeta
}

annotations: string; will be added into the annotations of this CRD.

Format: "key=value". Multiple annotations can be specified by repeating the marker.
labels: string; will be added into the labels of this CRD.

Format: "key=value". Multiple labels can be specified by repeating the marker.

// +kubebuilder:externalDocs

description: string
url: string

specifies external documentation for this field or type.

The url is required and must be a valid URL. The description is optional and provides a short description of the external documentation.

description: string; is a short description of the target documentation.
url: string; specifies the URL for the target documentation.

// +kubebuilder:externalDocs

description: string
url: string

specifies external documentation for this field or type.

The url is required and must be a valid URL. The description is optional and provides a short description of the external documentation.

description: string; is a short description of the target documentation.
url: string; specifies the URL for the target documentation.

// +kubebuilder:deprecatedversion

warning: string

marks this version as deprecated.

Deprecated versions show a warning message when used. This is useful for communicating to users that they should migrate to a newer version.

Example:

// +kubebuilder:deprecatedversion:warning=&#34;v1alpha1 is deprecated; use v1 instead&#34;
type MyCRDv1alpha1 struct {
    metav1.TypeMeta
    metav1.ObjectMeta
}

warning: string; message to be shown on the deprecated version.

This message is displayed to users when they interact with the deprecated version.

// +k8s:enum

indicates that the given type is an enum; all const values of this type are considered values in the enum

// +groupName

: string

specifies the API group name for this package. Example: +groupName=mygroup.example.com

: string

Keyboard shortcuts

CRD Generation