controller-tools: sigs.k8s.io/controller-tools/pkg/crd/markers Index | Files

package markers

import "sigs.k8s.io/controller-tools/pkg/crd/markers"

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

Package Files

crd.go doc.go package.go register.go validation.go zz_generated.markerhelp.go

Variables

var AllDefinitions []*definitionWithHelp

AllDefinitions contains all marker definitions for this package.

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()),
}

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

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()),
}

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

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

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

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

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

    Enum(nil),
    Format(""),
    Type(""),
)

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.

func Register Uses

func Register(reg *markers.Registry) error

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

type Default Uses

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 Uses

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

Defaults are only valid CRDs created with the v1 API

func (Default) Help Uses

func (Default) Help() *markers.DefinitionHelp

type Enum Uses

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 Uses

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

func (Enum) Help Uses

func (Enum) Help() *markers.DefinitionHelp

type ExclusiveMaximum Uses

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 Uses

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

func (ExclusiveMaximum) Help Uses

func (ExclusiveMaximum) Help() *markers.DefinitionHelp

type ExclusiveMinimum Uses

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 Uses

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

func (ExclusiveMinimum) Help Uses

func (ExclusiveMinimum) Help() *markers.DefinitionHelp

type Format Uses

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 Uses

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

func (Format) Help Uses

func (Format) Help() *markers.DefinitionHelp

type MaxItems Uses

type MaxItems int

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

func (MaxItems) ApplyToSchema Uses

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

func (MaxItems) Help Uses

func (MaxItems) Help() *markers.DefinitionHelp

type MaxLength Uses

type MaxLength int

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

func (MaxLength) ApplyToSchema Uses

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

func (MaxLength) Help Uses

func (MaxLength) Help() *markers.DefinitionHelp

type Maximum Uses

type Maximum int

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

func (Maximum) ApplyToSchema Uses

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

func (Maximum) Help Uses

func (Maximum) Help() *markers.DefinitionHelp

type MinItems Uses

type MinItems int

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

func (MinItems) ApplyToSchema Uses

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

func (MinItems) Help Uses

func (MinItems) Help() *markers.DefinitionHelp

type MinLength Uses

type MinLength int

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

func (MinLength) ApplyToSchema Uses

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

func (MinLength) Help Uses

func (MinLength) Help() *markers.DefinitionHelp

type Minimum Uses

type Minimum int

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

func (Minimum) ApplyToSchema Uses

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

func (Minimum) Help Uses

func (Minimum) Help() *markers.DefinitionHelp

type MultipleOf Uses

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 Uses

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

func (MultipleOf) Help Uses

func (MultipleOf) Help() *markers.DefinitionHelp

type Nullable Uses

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 Uses

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

func (Nullable) Help Uses

func (Nullable) Help() *markers.DefinitionHelp

type Pattern Uses

type Pattern string

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

func (Pattern) ApplyToSchema Uses

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

func (Pattern) Help Uses

func (Pattern) Help() *markers.DefinitionHelp

type PrintColumn Uses

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 Uses

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

func (PrintColumn) Help Uses

func (PrintColumn) Help() *markers.DefinitionHelp

type Resource Uses

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 Uses

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

func (Resource) Help Uses

func (Resource) Help() *markers.DefinitionHelp

type SkipVersion Uses

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 Uses

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

func (SkipVersion) Help Uses

func (SkipVersion) Help() *markers.DefinitionHelp

type StorageVersion Uses

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 Uses

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

func (StorageVersion) Help Uses

func (StorageVersion) Help() *markers.DefinitionHelp

type SubresourceScale Uses

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 Uses

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

func (SubresourceScale) Help Uses

func (SubresourceScale) Help() *markers.DefinitionHelp

type SubresourceStatus Uses

type SubresourceStatus struct{}

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

func (SubresourceStatus) ApplyToCRD Uses

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

func (SubresourceStatus) Help Uses

func (SubresourceStatus) Help() *markers.DefinitionHelp

type Type Uses

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 Uses

func (m Type) ApplyFirst()

func (Type) ApplyToSchema Uses

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

func (Type) Help Uses

func (Type) Help() *markers.DefinitionHelp

type UniqueItems Uses

type UniqueItems bool

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

func (UniqueItems) ApplyToSchema Uses

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

func (UniqueItems) Help Uses

func (UniqueItems) Help() *markers.DefinitionHelp

Package markers imports 5 packages (graph) and is imported by 4 packages. Updated 2019-10-20. Refresh now. Tools for package owners.