Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

CRD Validation

These markers modify how the CRD validation schema is produced for the types and fields they modify. Each corresponds roughly to an OpenAPI/JSON schema option.

See Generating CRDs for examples.

// +required
specifies that this field is required.
// +optional
specifies that this field is optional.
// +nullable
marks this field as allowing the "null" value.

This is often not necessary, but may be helpful with custom serialization.

// +kubebuilder:validation:items:XValidation
fieldPath
string
message
string
messageExpression
string
optionalOldSelf
bool
reason
string
rule
string
for array items marks a field as requiring a value for which a given

expression evaluates to true.

This marker may be repeated to specify multiple expressions, all of which must evaluate to true.

fieldPath
string
message
string
messageExpression
string
optionalOldSelf
bool
reason
string
rule
string
// +kubebuilder:validation:items:XValidation
fieldPath
string
message
string
messageExpression
string
optionalOldSelf
bool
reason
string
rule
string
for array items marks a field as requiring a value for which a given

expression evaluates to true.

This marker may be repeated to specify multiple expressions, all of which must evaluate to true.

fieldPath
string
message
string
messageExpression
string
optionalOldSelf
bool
reason
string
rule
string
// +kubebuilder:validation:items:XIntOrString
for array items marks a fields as an IntOrString.

This is required when applying patterns or other validations to an IntOrString field. Known information about the type is applied during the collapse phase and as such is not normally available during marker application.

// +kubebuilder:validation:items:XIntOrString
for array items marks a fields as an IntOrString.

This is required when applying patterns or other validations to an IntOrString field. Known information about the type is applied during the collapse phase and as such is not normally available during marker application.

// +kubebuilder:validation:items:XEmbeddedResource
for array items marks a fields as an embedded resource with apiVersion, kind and metadata fields.

An embedded resource is a value that has apiVersion, kind and metadata fields. They are validated implicitly according to the semantics of the currently running apiserver. It is not necessary to add any additional schema for these field, yet it is possible. This can be combined with PreserveUnknownFields.

// +kubebuilder:validation:items:XEmbeddedResource
for array items marks a fields as an embedded resource with apiVersion, kind and metadata fields.

An embedded resource is a value that has apiVersion, kind and metadata fields. They are validated implicitly according to the semantics of the currently running apiserver. It is not necessary to add any additional schema for these field, yet it is possible. This can be combined with PreserveUnknownFields.

// +kubebuilder:validation:items:UniqueItems
bool
for array items specifies that all items in this list must be unique.
bool
// +kubebuilder:validation:items:UniqueItems
bool
for array items specifies that all items in this list must be unique.
bool
// +kubebuilder:validation:items:Type
string
for array items overrides the type for this field (which defaults to the equivalent of the Go type).

This generally must be paired with custom serialization. For example, the metav1.Time field would be marked as "type: string" and "format: date-time".

string
// +kubebuilder:validation:items:Type
string
for array items overrides the type for this field (which defaults to the equivalent of the Go type).

This generally must be paired with custom serialization. For example, the metav1.Time field would be marked as "type: string" and "format: date-time".

string
// +kubebuilder:validation:items:Pattern
string
for array items specifies that this string must match the given regular expression.
string
// +kubebuilder:validation:items:Pattern
string
for array items specifies that this string must match the given regular expression.
string
// +kubebuilder:validation:items:MultipleOf
for array items specifies that this field must have a numeric value that's a multiple of this one.
// +kubebuilder:validation:items:MultipleOf
for array items specifies that this field must have a numeric value that's a multiple of this one.
// +kubebuilder:validation:items:Minimum
for array items specifies the minimum numeric value that this field can have. Negative numbers are supported.
// +kubebuilder:validation:items:Minimum
for array items specifies the minimum numeric value that this field can have. Negative numbers are supported.
// +kubebuilder:validation:items:MinProperties
int
for array items restricts the number of keys in an object
int
// +kubebuilder:validation:items:MinProperties
int
for array items restricts the number of keys in an object
int
// +kubebuilder:validation:items:MinLength
int
for array items specifies the minimum length for this string.
int
// +kubebuilder:validation:items:MinLength
int
for array items specifies the minimum length for this string.
int
// +kubebuilder:validation:items:MinItems
int
for array items specifies the minimum length for this list.
int
// +kubebuilder:validation:items:MinItems
int
for array items specifies the minimum length for this list.
int
// +kubebuilder:validation:items:Maximum
for array items specifies the maximum numeric value that this field can have.
// +kubebuilder:validation:items:Maximum
for array items specifies the maximum numeric value that this field can have.
// +kubebuilder:validation:items:MaxProperties
int
for array items restricts the number of keys in an object
int
// +kubebuilder:validation:items:MaxProperties
int
for array items restricts the number of keys in an object
int
// +kubebuilder:validation:items:MaxLength
int
for array items specifies the maximum length for this string.
int
// +kubebuilder:validation:items:MaxLength
int
for array items specifies the maximum length for this string.
int
// +kubebuilder:validation:items:MaxItems
int
for array items specifies the maximum length for this list.
int
// +kubebuilder:validation:items:MaxItems
int
for array items specifies the maximum length for this list.
int
// +kubebuilder:validation:items:Format
string
for array items specifies additional "complex" formatting for this field.

For example, a date-time field would be marked as "type: string" and "format: date-time".

string
// +kubebuilder:validation:items:Format
string
for array items specifies additional "complex" formatting for this field.

For example, a date-time field would be marked as "type: string" and "format: date-time".

string
// +kubebuilder:validation:items:ExclusiveMinimum
bool
for array items indicates that the minimum is "up to" but not including that value.
bool
// +kubebuilder:validation:items:ExclusiveMinimum
bool
for array items indicates that the minimum is "up to" but not including that value.
bool
// +kubebuilder:validation:items:ExclusiveMaximum
bool
for array items indicates that the maximum is "up to" but not including that value.
bool
// +kubebuilder:validation:items:ExclusiveMaximum
bool
for array items indicates that the maximum is "up to" but not including that value.
bool
// +kubebuilder:validation:items:Enum
any
for array items specifies that this (scalar) field is restricted to the *exact* values specified here.
any
// +kubebuilder:validation:items:Enum
any
for array items specifies that this (scalar) field is restricted to the *exact* values specified here.
any
// +kubebuilder:validation:XValidation
fieldPath
string
message
string
messageExpression
string
optionalOldSelf
bool
reason
string
rule
string
marks a field as requiring a value for which a given

expression evaluates to true.

This marker may be repeated to specify multiple expressions, all of which must evaluate to true.

fieldPath
string
message
string
messageExpression
string
optionalOldSelf
bool
reason
string
rule
string
// +kubebuilder:validation:XValidation
fieldPath
string
message
string
messageExpression
string
optionalOldSelf
bool
reason
string
rule
string
marks a field as requiring a value for which a given

expression evaluates to true.

This marker may be repeated to specify multiple expressions, all of which must evaluate to true.

fieldPath
string
message
string
messageExpression
string
optionalOldSelf
bool
reason
string
rule
string
// +kubebuilder:validation:XIntOrString
marks a fields as an IntOrString.

This is required when applying patterns or other validations to an IntOrString field. Known information about the type is applied during the collapse phase and as such is not normally available during marker application.

// +kubebuilder:validation:XIntOrString
marks a fields as an IntOrString.

This is required when applying patterns or other validations to an IntOrString field. Known information about the type is applied during the collapse phase and as such is not normally available during marker application.

// +kubebuilder:validation:XEmbeddedResource
marks a fields as an embedded resource with apiVersion, kind and metadata fields.

An embedded resource is a value that has apiVersion, kind and metadata fields. They are validated implicitly according to the semantics of the currently running apiserver. It is not necessary to add any additional schema for these field, yet it is possible. This can be combined with PreserveUnknownFields.

// +kubebuilder:validation:XEmbeddedResource
marks a fields as an embedded resource with apiVersion, kind and metadata fields.

An embedded resource is a value that has apiVersion, kind and metadata fields. They are validated implicitly according to the semantics of the currently running apiserver. It is not necessary to add any additional schema for these field, yet it is possible. This can be combined with PreserveUnknownFields.

// +kubebuilder:validation:UniqueItems
bool
specifies that all items in this list must be unique.
bool
// +kubebuilder:validation:UniqueItems
bool
specifies that all items in this list must be unique.
bool
// +kubebuilder:validation:Type
string
overrides the type for this field (which defaults to the equivalent of the Go type).

This generally must be paired with custom serialization. For example, the metav1.Time field would be marked as "type: string" and "format: date-time".

string
// +kubebuilder:validation:Type
string
overrides the type for this field (which defaults to the equivalent of the Go type).

This generally must be paired with custom serialization. For example, the metav1.Time field would be marked as "type: string" and "format: date-time".

string
// +kubebuilder:validation:Schemaless
marks a field as being a schemaless object.

Schemaless objects are not introspected, so you must provide any type and validation information yourself. One use for this tag is for embedding fields that hold JSONSchema typed objects. Because this field disables all type checking, it is recommended to be used only as a last resort.

// +kubebuilder:validation:Required
specifies that all fields in this package are required by default.
// +kubebuilder:validation:Required
specifies that this field is required.
// +kubebuilder:validation:Pattern
string
specifies that this string must match the given regular expression.
string
// +kubebuilder:validation:Pattern
string
specifies that this string must match the given regular expression.
string
// +kubebuilder:validation:Optional
specifies that all fields in this package are optional by default.
// +kubebuilder:validation:Optional
specifies that this field is optional.
// +kubebuilder:validation:MultipleOf
specifies that this field must have a numeric value that's a multiple of this one.
// +kubebuilder:validation:MultipleOf
specifies that this field must have a numeric value that's a multiple of this one.
// +kubebuilder:validation:Minimum
specifies the minimum numeric value that this field can have. Negative numbers are supported.
// +kubebuilder:validation:Minimum
specifies the minimum numeric value that this field can have. Negative numbers are supported.
// +kubebuilder:validation:MinProperties
int
restricts the number of keys in an object
int
// +kubebuilder:validation:MinProperties
int
restricts the number of keys in an object
int
// +kubebuilder:validation:MinLength
int
specifies the minimum length for this string.
int
// +kubebuilder:validation:MinLength
int
specifies the minimum length for this string.
int
// +kubebuilder:validation:MinItems
int
specifies the minimum length for this list.
int
// +kubebuilder:validation:MinItems
int
specifies the minimum length for this list.
int
// +kubebuilder:validation:Maximum
specifies the maximum numeric value that this field can have.
// +kubebuilder:validation:Maximum
specifies the maximum numeric value that this field can have.
// +kubebuilder:validation:MaxProperties
int
restricts the number of keys in an object
int
// +kubebuilder:validation:MaxProperties
int
restricts the number of keys in an object
int
// +kubebuilder:validation:MaxLength
int
specifies the maximum length for this string.
int
// +kubebuilder:validation:MaxLength
int
specifies the maximum length for this string.
int
// +kubebuilder:validation:MaxItems
int
specifies the maximum length for this list.
int
// +kubebuilder:validation:MaxItems
int
specifies the maximum length for this list.
int
// +kubebuilder:validation:Format
string
specifies additional "complex" formatting for this field.

For example, a date-time field would be marked as "type: string" and "format: date-time".

string
// +kubebuilder:validation:Format
string
specifies additional "complex" formatting for this field.

For example, a date-time field would be marked as "type: string" and "format: date-time".

string
// +kubebuilder:validation:ExclusiveMinimum
bool
indicates that the minimum is "up to" but not including that value.
bool
// +kubebuilder:validation:ExclusiveMinimum
bool
indicates that the minimum is "up to" but not including that value.
bool
// +kubebuilder:validation:ExclusiveMaximum
bool
indicates that the maximum is "up to" but not including that value.
bool
// +kubebuilder:validation:ExclusiveMaximum
bool
indicates that the maximum is "up to" but not including that value.
bool
// +kubebuilder:validation:ExactlyOneOf
string
specifies a list of field names that must conform to the ExactlyOneOf constraint.
string
// +kubebuilder:validation:Enum
any
specifies that this (scalar) field is restricted to the *exact* values specified here.
any
// +kubebuilder:validation:Enum
any
specifies that this (scalar) field is restricted to the *exact* values specified here.
any
// +kubebuilder:validation:EmbeddedResource
marks a fields as an embedded resource with apiVersion, kind and metadata fields.

An embedded resource is a value that has apiVersion, kind and metadata fields. They are validated implicitly according to the semantics of the currently running apiserver. It is not necessary to add any additional schema for these field, yet it is possible. This can be combined with PreserveUnknownFields.

// +kubebuilder:validation:AtMostOneOf
string
specifies a list of field names that must conform to the AtMostOneOf constraint.
string
// +kubebuilder:validation:AtLeastOneOf
string
specifies a list of field names that must conform to the AtLeastOneOf constraint.
string
// +kubebuilder:title
any
sets the title for this field.

The title is metadata that makes the OpenAPI documentation more user-friendly, making the schema more understandable when viewed in documentation tools. It's a metadata field that doesn't affect validation but provides important context about what the schema represents.

any
// +kubebuilder:title
any
sets the title for this field.

The title is metadata that makes the OpenAPI documentation more user-friendly, making the schema more understandable when viewed in documentation tools. It's a metadata field that doesn't affect validation but provides important context about what the schema represents.

any
// +kubebuilder:example
any
sets the example value for this field.

An example value will be accepted as any value valid for the field. Formatting for common types include: boolean: true, string: Cluster, numerical: 1.24, array: {1,2}, object: {policy: "delete"}). Examples should be defined in pruned form, and only best-effort validation will be performed. Full validation of an example requires submission of the containing CRD to an apiserver.

any
// +kubebuilder:default
any
sets the default value for this field.

A default value will be accepted as any value valid for the field. Formatting for common types include: boolean: true, string: Cluster, numerical: 1.24, array: {1,2}, object: {policy: "delete"}). Defaults should be defined in pruned form, and only best-effort validation will be performed. Full validation of a default requires submission of the containing CRD to an apiserver.

any
// +k8s:required
specifies that this field is required.
// +k8s:optional
specifies that this field is optional.
// +default
value
any
sets the default value for this field.

A default value will be accepted as any value valid for the field. Only JSON-formatted values are accepted. ref(...) values are ignored. Formatting for common types include: boolean: true, string: "Cluster", numerical: 1.24, array: [1,2], object: {"policy": "delete"}). Defaults should be defined in pruned form, and only best-effort validation will be performed. Full validation of a default requires submission of the containing CRD to an apiserver.

value
any