markers

package
v0.4.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 30, 2022 License: Apache-2.0 Imports: 5 Imported by: 0

Documentation

Overview

Package markers defines markers for generating schema valiation and CRD structure.

All markers related to CRD generation live in AllDefinitions.

Validation Markers

Validation markers have values that implement ApplyToSchema (crd.SchemaMarker). Any marker implementing this will automatically be run after the rest of a given schema node has been generated. Markers that need to be run before any other markers can also implement ApplyFirst, but this is discouraged and may change in the future.

All validation markers start with "+kubebuilder:validation", and have the same name as their type name.

CRD Markers

Markers that modify anything in the CRD itself *except* for the schema implement ApplyToCRD (crd.CRDMarker). They are expected to detect whether they should apply themselves to a specific version in the CRD (as passed to them), or to the root-level CRD for legacy cases. They are applied *after* the rest of the CRD is computed.

Misc

This package also defines the "+groupName" and "+versionName" package-level markers, for defining package<->group-version mappings.

Index

Constants

This section is empty.

Variables

View Source 
var AllDefinitions []*definitionWithHelp

AllDefinitions contains all marker definitions for this package.

View Source 
var CRDMarkers = []*definitionWithHelp{

	must(markers.MakeDefinition("kubebuilder:subresource:status", markers.DescribesType, SubresourceStatus{})).
		WithHelp(SubresourceStatus{}.Help()),

	must(markers.MakeDefinition("kubebuilder:subresource:scale", markers.DescribesType, SubresourceScale{})).
		WithHelp(SubresourceScale{}.Help()),

	must(markers.MakeDefinition("kubebuilder:printcolumn", markers.DescribesType, PrintColumn{})).
		WithHelp(PrintColumn{}.Help()),

	must(markers.MakeDefinition("kubebuilder:resource", markers.DescribesType, Resource{})).
		WithHelp(Resource{}.Help()),

	must(markers.MakeDefinition("kubebuilder:storageversion", markers.DescribesType, StorageVersion{})).
		WithHelp(StorageVersion{}.Help()),

	must(markers.MakeDefinition("kubebuilder:skipversion", markers.DescribesType, SkipVersion{})).
		WithHelp(SkipVersion{}.Help()),

	must(markers.MakeDefinition("kubebuilder:unservedversion", markers.DescribesType, UnservedVersion{})).
		WithHelp(UnservedVersion{}.Help()),
}

CRDMarkers lists all markers that directly modify the CRD (not validation schemas).

View Source 
var FieldOnlyMarkers = []*definitionWithHelp{
	must(markers.MakeDefinition("kubebuilder:validation:Required", markers.DescribesField, struct{}{})).
		WithHelp(markers.SimpleHelp("CRD validation", "specifies that this field is required, if fields are optional by default.")),
	must(markers.MakeDefinition("kubebuilder:validation:Optional", markers.DescribesField, struct{}{})).
		WithHelp(markers.SimpleHelp("CRD validation", "specifies that this field is optional, if fields are required by default.")),
	must(markers.MakeDefinition("optional", markers.DescribesField, struct{}{})).
		WithHelp(markers.SimpleHelp("CRD validation", "specifies that this field is optional, if fields are required by default.")),

	must(markers.MakeDefinition("nullable", markers.DescribesField, Nullable{})).
		WithHelp(Nullable{}.Help()),

	must(markers.MakeAnyTypeDefinition("kubebuilder:default", markers.DescribesField, Default{})).
		WithHelp(Default{}.Help()),

	must(markers.MakeDefinition("kubebuilder:validation:EmbeddedResource", markers.DescribesField, XEmbeddedResource{})).
		WithHelp(XEmbeddedResource{}.Help()),
}

FieldOnlyMarkers list field-specific validation markers (i.e. those markers that don't make sense on a type, and thus aren't in ValidationMarkers).

View Source 
var TopologyMarkers = []*definitionWithHelp{
	must(markers.MakeDefinition("listMapKey", markers.DescribesField, ListMapKey(""))).
		WithHelp(ListMapKey("").Help()),
	must(markers.MakeDefinition("listType", markers.DescribesField, ListType(""))).
		WithHelp(ListType("").Help()),
	must(markers.MakeDefinition("mapType", markers.DescribesField, MapType(""))).
		WithHelp(MapType("").Help()),
	must(markers.MakeDefinition("structType", markers.DescribesField, StructType(""))).
		WithHelp(StructType("").Help()),
}

TopologyMarkers specify topology markers (i.e. markers that describe if a list behaves as an associative-list or a set, if a map is atomic or not).

View Source 
var ValidationIshMarkers = []*definitionWithHelp{
	must(markers.MakeDefinition("kubebuilder:pruning:PreserveUnknownFields", markers.DescribesField, XPreserveUnknownFields{})).
		WithHelp(XPreserveUnknownFields{}.Help()),
	must(markers.MakeDefinition("kubebuilder:pruning:PreserveUnknownFields", markers.DescribesType, XPreserveUnknownFields{})).
		WithHelp(XPreserveUnknownFields{}.Help()),
}

ValidationIshMarkers are field-and-type markers that don't fall under the :validation: prefix, and/or don't have a name that directly matches their type.

View Source 
var ValidationMarkers = mustMakeAllWithPrefix("kubebuilder:validation", markers.DescribesField,

	Maximum(0),
	Minimum(0),
	ExclusiveMaximum(false),
	ExclusiveMinimum(false),
	MultipleOf(0),
	MinProperties(0),
	MaxProperties(0),

	MaxLength(0),
	MinLength(0),
	Pattern(""),

	MaxItems(0),
	MinItems(0),
	UniqueItems(false),

	Enum(nil),
	Format(""),
	Type(""),
	XPreserveUnknownFields{},
	XEmbeddedResource{},
)

ValidationMarkers lists all available markers that affect CRD schema generation, except for the few that don't make sense as type-level markers (see FieldOnlyMarkers). All markers start with `+kubebuilder:validation:`, and continue with their type name. A copy is produced of all markers that describes types as well, for making types reusable and writing complex validations on slice items.

Functions

func Register 

func Register(reg *markers.Registry) error

Register registers all definitions for CRD generation to the given registry.

Types

type Default 

type Default struct {
	Value interface{}
}

+controllertools:marker:generateHelp:category="CRD validation" Default 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.

func (Default) ApplyToSchema 

func (m Default) ApplyToSchema(schema *apiext.JSONSchemaProps) error

Defaults are only valid CRDs created with the v1 API

func (Default) Help 

func (Default) Help() *markers.DefinitionHelp

type Enum 

type Enum []interface{}

+controllertools:marker:generateHelp:category="CRD validation" Enum specifies that this (scalar) field is restricted to the *exact* values specified here.

func (Enum) ApplyToSchema 

func (m Enum) ApplyToSchema(schema *apiext.JSONSchemaProps) error

func (Enum) Help 

func (Enum) Help() *markers.DefinitionHelp

type ExclusiveMaximum 

type ExclusiveMaximum bool

+controllertools:marker:generateHelp:category="CRD validation" ExclusiveMaximum indicates that the maximum is "up to" but not including that value.

func (ExclusiveMaximum) ApplyToSchema 

func (m ExclusiveMaximum) ApplyToSchema(schema *apiext.JSONSchemaProps) error

func (ExclusiveMaximum) Help 

func (ExclusiveMaximum) Help() *markers.DefinitionHelp

type ExclusiveMinimum 

type ExclusiveMinimum bool

+controllertools:marker:generateHelp:category="CRD validation" ExclusiveMinimum indicates that the minimum is "up to" but not including that value.

func (ExclusiveMinimum) ApplyToSchema 

func (m ExclusiveMinimum) ApplyToSchema(schema *apiext.JSONSchemaProps) error

func (ExclusiveMinimum) Help 

func (ExclusiveMinimum) Help() *markers.DefinitionHelp

type Format 

type Format string

+controllertools:marker:generateHelp:category="CRD validation" Format specifies additional "complex" formatting for this field.

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

func (Format) ApplyToSchema 

func (m Format) ApplyToSchema(schema *apiext.JSONSchemaProps) error

func (Format) Help 

func (Format) Help() *markers.DefinitionHelp

type ListMapKey 

type ListMapKey string

ListMapKey specifies the keys to map listTypes.

It indicates the index of a map list. They can be repeated if multiple keys must be used. It can only be used when ListType is set to map, and the keys should be scalar types.

func (ListMapKey) ApplyToSchema 

func (l ListMapKey) ApplyToSchema(schema *apiext.JSONSchemaProps) error

func (ListMapKey) Help 

func (ListMapKey) Help() *markers.DefinitionHelp

type ListType 

type ListType string

ListType specifies the type of data-structure that the list represents (map, set, atomic).

Possible data-structure types of a list are:

  • "map": it needs to have a key field, which will be used to build an associative list. A typical example is a the pod container list, which is indexed by the container name.
  • "set": Fields need to be "scalar", and there can be only one occurrence of each.
  • "atomic": All the fields in the list are treated as a single value, are typically manipulated together by the same actor.

func (ListType) ApplyFirst 

func (l ListType) ApplyFirst()

func (ListType) ApplyToSchema 

func (l ListType) ApplyToSchema(schema *apiext.JSONSchemaProps) error

func (ListType) Help 

func (ListType) Help() *markers.DefinitionHelp

type MapType 

type MapType string

MapType specifies the level of atomicity of the map; i.e. whether each item in the map is independent of the others, or all fields are treated as a single unit.

Possible values:

  • "granular": items in the map are independent of each other, and can be manipulated by different actors. This is the default behavior.
  • "atomic": all fields are treated as one unit. Any changes have to replace the entire map.

func (MapType) ApplyToSchema 

func (m MapType) ApplyToSchema(schema *apiext.JSONSchemaProps) error

func (MapType) Help 

func (MapType) Help() *markers.DefinitionHelp

type MaxItems 

type MaxItems int

+controllertools:marker:generateHelp:category="CRD validation" MaxItems specifies the maximum length for this list.

func (MaxItems) ApplyToSchema 

func (m MaxItems) ApplyToSchema(schema *apiext.JSONSchemaProps) error

func (MaxItems) Help 

func (MaxItems) Help() *markers.DefinitionHelp

type MaxLength 

type MaxLength int

+controllertools:marker:generateHelp:category="CRD validation" MaxLength specifies the maximum length for this string.

func (MaxLength) ApplyToSchema 

func (m MaxLength) ApplyToSchema(schema *apiext.JSONSchemaProps) error

func (MaxLength) Help 

func (MaxLength) Help() *markers.DefinitionHelp

type MaxProperties 

type MaxProperties int

+controllertools:marker:generateHelp:category="CRD validation" MaxProperties restricts the number of keys in an object

func (MaxProperties) ApplyToSchema 

func (m MaxProperties) ApplyToSchema(schema *apiext.JSONSchemaProps) error

func (MaxProperties) Help 

func (MaxProperties) Help() *markers.DefinitionHelp

type Maximum 

type Maximum int

+controllertools:marker:generateHelp:category="CRD validation" Maximum specifies the maximum numeric value that this field can have.

func (Maximum) ApplyToSchema 

func (m Maximum) ApplyToSchema(schema *apiext.JSONSchemaProps) error

func (Maximum) Help 

func (Maximum) Help() *markers.DefinitionHelp

type MinItems 

type MinItems int

+controllertools:marker:generateHelp:category="CRD validation" MinItems specifies the minimun length for this list.

func (MinItems) ApplyToSchema 

func (m MinItems) ApplyToSchema(schema *apiext.JSONSchemaProps) error

func (MinItems) Help 

func (MinItems) Help() *markers.DefinitionHelp

type MinLength 

type MinLength int

+controllertools:marker:generateHelp:category="CRD validation" MinLength specifies the minimum length for this string.

func (MinLength) ApplyToSchema 

func (m MinLength) ApplyToSchema(schema *apiext.JSONSchemaProps) error

func (MinLength) Help 

func (MinLength) Help() *markers.DefinitionHelp

type MinProperties 

type MinProperties int

+controllertools:marker:generateHelp:category="CRD validation" MinProperties restricts the number of keys in an object

func (MinProperties) ApplyToSchema 

func (m MinProperties) ApplyToSchema(schema *apiext.JSONSchemaProps) error

func (MinProperties) Help 

func (MinProperties) Help() *markers.DefinitionHelp

type Minimum 

type Minimum int

+controllertools:marker:generateHelp:category="CRD validation" Minimum specifies the minimum numeric value that this field can have. Negative integers are supported.

func (Minimum) ApplyToSchema 

func (m Minimum) ApplyToSchema(schema *apiext.JSONSchemaProps) error

func (Minimum) Help 

func (Minimum) Help() *markers.DefinitionHelp

type MultipleOf 

type MultipleOf int

+controllertools:marker:generateHelp:category="CRD validation" MultipleOf specifies that this field must have a numeric value that's a multiple of this one.

func (MultipleOf) ApplyToSchema 

func (m MultipleOf) ApplyToSchema(schema *apiext.JSONSchemaProps) error

func (MultipleOf) Help 

func (MultipleOf) Help() *markers.DefinitionHelp

type Nullable 

type Nullable struct{}

+controllertools:marker:generateHelp:category="CRD validation" Nullable marks this field as allowing the "null" value.

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

func (Nullable) ApplyToSchema 

func (m Nullable) ApplyToSchema(schema *apiext.JSONSchemaProps) error

func (Nullable) Help 

func (Nullable) Help() *markers.DefinitionHelp

type Pattern 

type Pattern string

+controllertools:marker:generateHelp:category="CRD validation" Pattern specifies that this string must match the given regular expression.

func (Pattern) ApplyToSchema 

func (m Pattern) ApplyToSchema(schema *apiext.JSONSchemaProps) error

func (Pattern) Help 

func (Pattern) Help() *markers.DefinitionHelp

type PrintColumn 

type PrintColumn struct {
	// Name specifies the name of the column.
	Name string

	// Type 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.
	Type string

	// JSONPath specifies the jsonpath expression used to extract the value of the column.
	JSONPath string `marker:"JSONPath"` // legacy cruft

	// Description specifies the help/description for this column.
	Description string `marker:",optional"`

	// Format 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.
	Format string `marker:",optional"`

	// Priority 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 int32 `marker:",optional"`
}

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

func (PrintColumn) ApplyToCRD 

func (s PrintColumn) ApplyToCRD(crd *apiext.CustomResourceDefinitionSpec, version string) error

func (PrintColumn) Help 

func (PrintColumn) Help() *markers.DefinitionHelp

type Resource 

type Resource struct {
	// Path specifies the plural "resource" for this CRD.
	//
	// It generally corresponds to a plural, lower-cased version of the Kind.
	// See https://book.kubebuilder.io/cronjob-tutorial/gvks.html.
	Path string `marker:",optional"`

	// ShortName 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.
	ShortName []string `marker:",optional"`

	// Categories 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.
	Categories []string `marker:",optional"`

	// Singular overrides the singular form of your resource.
	//
	// The singular form is otherwise defaulted off the plural (path).
	Singular string `marker:",optional"`

	// Scope overrides the scope of the CRD (Cluster vs Namespaced).
	//
	// Scope defaults to "Namespaced".  Cluster-scoped ("Cluster") resources
	// don't exist in namespaces.
	Scope string `marker:",optional"`
}

Resource configures naming and scope for a CRD.

func (Resource) ApplyToCRD 

func (s Resource) ApplyToCRD(crd *apiext.CustomResourceDefinitionSpec, version string) error

func (Resource) Help 

func (Resource) Help() *markers.DefinitionHelp

type SkipVersion 

type SkipVersion struct{}

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.

func (SkipVersion) ApplyToCRD 

func (s SkipVersion) ApplyToCRD(crd *apiext.CustomResourceDefinitionSpec, version string) error

func (SkipVersion) Help 

func (SkipVersion) Help() *markers.DefinitionHelp

type StorageVersion 

type StorageVersion struct{}

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.

func (StorageVersion) ApplyToCRD 

func (s StorageVersion) ApplyToCRD(crd *apiext.CustomResourceDefinitionSpec, version string) error

func (StorageVersion) Help 

func (StorageVersion) Help() *markers.DefinitionHelp

type StructType 

type StructType string

StructType specifies the level of atomicity of the struct; i.e. whether each field in the struct is independent of the others, or all fields are treated as a single unit.

Possible values:

  • "granular": fields in the struct are independent of each other, and can be manipulated by different actors. This is the default behavior.
  • "atomic": all fields are treated as one unit. Any changes have to replace the entire struct.

func (StructType) ApplyToSchema 

func (s StructType) ApplyToSchema(schema *apiext.JSONSchemaProps) error

func (StructType) Help 

func (StructType) Help() *markers.DefinitionHelp

type SubresourceScale 

type SubresourceScale struct {

	// SpecPath specifies the jsonpath to the replicas field for the scale's spec.
	SpecPath string `marker:"specpath"`

	// StatusPath specifies the jsonpath to the replicas field for the scale's status.
	StatusPath string `marker:"statuspath"`

	// SelectorPath 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.
	SelectorPath *string `marker:"selectorpath"`
}

SubresourceScale enables the "/scale" subresource on a CRD.

func (SubresourceScale) ApplyToCRD 

func (s SubresourceScale) ApplyToCRD(crd *apiext.CustomResourceDefinitionSpec, version string) error

func (SubresourceScale) Help 

func (SubresourceScale) Help() *markers.DefinitionHelp

type SubresourceStatus 

type SubresourceStatus struct{}

SubresourceStatus enables the "/status" subresource on a CRD.

func (SubresourceStatus) ApplyToCRD 

func (s SubresourceStatus) ApplyToCRD(crd *apiext.CustomResourceDefinitionSpec, version string) error

func (SubresourceStatus) Help 

func (SubresourceStatus) Help() *markers.DefinitionHelp

type Type 

type Type string

+controllertools:marker:generateHelp:category="CRD validation" Type 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".

func (Type) ApplyFirst 

func (m Type) ApplyFirst()

func (Type) ApplyToSchema 

func (m Type) ApplyToSchema(schema *apiext.JSONSchemaProps) error

func (Type) Help 

func (Type) Help() *markers.DefinitionHelp

type UniqueItems 

type UniqueItems bool

+controllertools:marker:generateHelp:category="CRD validation" UniqueItems specifies that all items in this list must be unique.

func (UniqueItems) ApplyToSchema 

func (m UniqueItems) ApplyToSchema(schema *apiext.JSONSchemaProps) error

func (UniqueItems) Help 

func (UniqueItems) Help() *markers.DefinitionHelp

type UnservedVersion 

type UnservedVersion struct{}

UnservedVersion does not serve this version.

This is useful if you need to drop support for a version in favor of a newer version.

func (UnservedVersion) ApplyToCRD 

func (s UnservedVersion) ApplyToCRD(crd *apiext.CustomResourceDefinitionSpec, version string) error

func (UnservedVersion) Help 

func (UnservedVersion) Help() *markers.DefinitionHelp

type XEmbeddedResource 

type XEmbeddedResource struct{}

+controllertools:marker:generateHelp:category="CRD 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.

func (XEmbeddedResource) ApplyToSchema 

func (m XEmbeddedResource) ApplyToSchema(schema *apiext.JSONSchemaProps) error

func (XEmbeddedResource) Help 

func (XEmbeddedResource) Help() *markers.DefinitionHelp

type XPreserveUnknownFields 

type XPreserveUnknownFields struct{}

+controllertools:marker:generateHelp:category="CRD processing" PreserveUnknownFields stops the apiserver from pruning fields which are not specified.

By default the apiserver drops unknown fields from the request payload during the decoding step. This marker stops the API server from doing so. It affects fields recursively, but switches back to normal pruning behaviour if nested properties or additionalProperties are specified in the schema. This can either be true or undefined. False is forbidden.

NB: The kubebuilder:validation:XPreserveUnknownFields variant is deprecated in favor of the kubebuilder:pruning:PreserveUnknownFields variant. They function identically.

func (XPreserveUnknownFields) ApplyToSchema 

func (m XPreserveUnknownFields) ApplyToSchema(schema *apiext.JSONSchemaProps) error

func (XPreserveUnknownFields) Help 

func (XPreserveUnknownFields) Help() *markers.DefinitionHelp

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.