API Reference

API Reference

API Reference

Packages

cluster.x-k8s.io/v1beta1

Package v1beta1 contains API Schema definitions for the cluster v1beta1 API group

Deprecated: This package is deprecated and is going to be removed when support for v1beta1 will be dropped.

Resource Types

APIEndpoint

APIEndpoint represents a reachable Kubernetes API endpoint.

Appears In:
Field Description Default Validation

host string

host is the hostname on which the API server is serving.

MaxLength: 512

port integer

port is the port on which the API server is serving.

Bootstrap

Bootstrap encapsulates fields to configure the Machine’s bootstrapping mechanism.

Appears In:
Field Description Default Validation

configRef ObjectReference

configRef is a reference to a bootstrap provider-specific resource
that holds configuration details. The reference is optional to
allow users/operators to specify Bootstrap.DataSecretName without
the need of a controller.

dataSecretName string

dataSecretName is the name of the secret that stores the bootstrap data script.
If nil, the Machine should remain in the Pending state.

MaxLength: 253
MinLength: 0

Cluster

Cluster is the Schema for the clusters API.

Field Description Default Validation

apiVersion string

cluster.x-k8s.io/v1beta1

kind string

Cluster

metadata ObjectMeta

Refer to Kubernetes API documentation for fields of metadata.

MinProperties: 1

spec ClusterSpec

spec is the desired state of Cluster.

status ClusterStatus

status is the observed state of Cluster.

ClusterAvailabilityGate

ClusterAvailabilityGate contains the type of a Cluster condition to be used as availability gate.

Appears In:
Field Description Default Validation

conditionType string

conditionType refers to a condition with matching type in the Cluster’s condition list.
If the conditions doesn’t exist, it will be treated as unknown.
Note: Both Cluster API conditions or conditions added by 3rd party controllers can be used as availability gates.

MaxLength: 316
MinLength: 1
Pattern: ^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$

polarity ConditionPolarity

polarity of the conditionType specified in this availabilityGate.
Valid values are Positive, Negative and omitted.
When omitted, the default behaviour will be Positive.
A positive polarity means that the condition should report a true status under normal conditions.
A negative polarity means that the condition should report a false status under normal conditions.

Enum: [Positive Negative]

ClusterClass

ClusterClass is a template which can be used to create managed topologies.

Field Description Default Validation

apiVersion string

cluster.x-k8s.io/v1beta1

kind string

ClusterClass

metadata ObjectMeta

Refer to Kubernetes API documentation for fields of metadata.

MinProperties: 1

spec ClusterClassSpec

spec is the desired state of ClusterClass.

status ClusterClassStatus

status is the observed state of ClusterClass.

ClusterClassPatch

ClusterClassPatch defines a patch which is applied to customize the referenced templates.

Appears In:
Field Description Default Validation

name string

name of the patch.

MaxLength: 256
MinLength: 1

description string

description is a human-readable description of this patch.

MaxLength: 1024
MinLength: 1

enabledIf string

enabledIf is a Go template to be used to calculate if a patch should be enabled.
It can reference variables defined in .spec.variables and builtin variables.
The patch will be enabled if the template evaluates to true, otherwise it will
be disabled.
If EnabledIf is not set, the patch will be enabled per default.

MaxLength: 256
MinLength: 1

definitions PatchDefinition array

definitions define inline patches.
Note: Patches will be applied in the order of the array.
Note: Exactly one of Definitions or External must be set.

MaxItems: 100

external ExternalPatchDefinition

external defines an external patch.
Note: Exactly one of Definitions or External must be set.

ClusterClassSpec

ClusterClassSpec describes the desired state of the ClusterClass.

Appears In:
Field Description Default Validation

availabilityGates ClusterAvailabilityGate array

availabilityGates specifies additional conditions to include when evaluating Cluster Available condition.

Note
 this field is considered only for computing v1beta2 conditions.
NOTE: If a Cluster is using this ClusterClass, and this Cluster defines a custom list of availabilityGates,
such list overrides availabilityGates defined in this field.

MaxItems: 32

infrastructure LocalObjectTemplate

infrastructure is a reference to a provider-specific template that holds
the details for provisioning infrastructure specific cluster
for the underlying provider.
The underlying provider is responsible for the implementation
of the template to an infrastructure cluster.

infrastructureNamingStrategy InfrastructureNamingStrategy

infrastructureNamingStrategy allows changing the naming pattern used when creating the infrastructure object.

controlPlane ControlPlaneClass

controlPlane is a reference to a local struct that holds the details
for provisioning the Control Plane for the Cluster.

workers WorkersClass

workers describes the worker nodes for the cluster.
It is a collection of node types which can be used to create
the worker nodes of the cluster.

variables ClusterClassVariable array

variables defines the variables which can be configured
in the Cluster topology and are then used in patches.

MaxItems: 1000

patches ClusterClassPatch array

patches defines the patches which are applied to customize
referenced templates of a ClusterClass.
Note: Patches will be applied in the order of the array.

MaxItems: 1000

ClusterClassStatus

ClusterClassStatus defines the observed state of the ClusterClass.

Appears In:
Field Description Default Validation

variables ClusterClassStatusVariable array

variables is a list of ClusterClassStatusVariable that are defined for the ClusterClass.

MaxItems: 1000

conditions Conditions

conditions defines current observed state of the ClusterClass.

observedGeneration integer

observedGeneration is the latest generation observed by the controller.

v1beta2 ClusterClassV1Beta2Status

v1beta2 groups all the fields that will be added or modified in ClusterClass’s status with the V1Beta2 version.

ClusterClassStatusVariable

ClusterClassStatusVariable defines a variable which appears in the status of a ClusterClass.

Appears In:
Field Description Default Validation

name string

name is the name of the variable.

MaxLength: 256
MinLength: 1

definitionsConflict boolean

definitionsConflict specifies whether or not there are conflicting definitions for a single variable name.

definitions ClusterClassStatusVariableDefinition array

definitions is a list of definitions for a variable.

MaxItems: 100

ClusterClassStatusVariableDefinition

ClusterClassStatusVariableDefinition defines a variable which appears in the status of a ClusterClass.

Appears In:
Field Description Default Validation

from string

from specifies the origin of the variable definition.
This will be inline for variables defined in the ClusterClass or the name of a patch defined in the ClusterClass
for variables discovered from a DiscoverVariables runtime extensions.

MaxLength: 256
MinLength: 1

required boolean

required specifies if the variable is required.
Note: this applies to the variable as a whole and thus the
top-level object defined in the schema. If nested fields are
required, this will be specified inside the schema.

metadata ClusterClassVariableMetadata

Refer to Kubernetes API documentation for fields of metadata.

schema VariableSchema

schema defines the schema of the variable.

ClusterClassV1Beta2Status

ClusterClassV1Beta2Status groups all the fields that will be added or modified in ClusterClass with the V1Beta2 version. See https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/proposals/20240916-improve-status-in-CAPI-resources.md for more context.

Appears In:
Field Description Default Validation

conditions Condition array

conditions represents the observations of a ClusterClass’s current state.
Known condition types are VariablesReady, RefVersionsUpToDate, Paused.

MaxItems: 32

ClusterClassVariable

ClusterClassVariable defines a variable which can be configured in the Cluster topology and used in patches.

Appears In:
Field Description Default Validation

name string

name of the variable.

MaxLength: 256
MinLength: 1

required boolean

required specifies if the variable is required.
Note: this applies to the variable as a whole and thus the
top-level object defined in the schema. If nested fields are
required, this will be specified inside the schema.

metadata ClusterClassVariableMetadata

Refer to Kubernetes API documentation for fields of metadata.

schema VariableSchema

schema defines the schema of the variable.

ClusterClassVariableMetadata

ClusterClassVariableMetadata is the metadata of a variable. It can be used to add additional data for higher level tools to a ClusterClassVariable.

Deprecated: This struct is deprecated and is going to be removed in the next apiVersion.

Appears In:
Field Description Default Validation

labels object (keys:string, values:string)

labels is a map of string keys and values that can be used to organize and categorize
(scope and select) variables.

annotations object (keys:string, values:string)

annotations is an unstructured key value map that can be used to store and
retrieve arbitrary metadata.
They are not queryable.

ClusterControlPlaneStatus

ClusterControlPlaneStatus groups all the observations about control plane current state.

Appears In:
Field Description Default Validation

desiredReplicas integer

desiredReplicas is the total number of desired control plane machines in this cluster.

replicas integer

replicas is the total number of control plane machines in this cluster.
NOTE: replicas also includes machines still being provisioned or being deleted.

upToDateReplicas integer

upToDateReplicas is the number of up-to-date control plane machines in this cluster. A machine is considered up-to-date when Machine’s UpToDate condition is true.

readyReplicas integer

readyReplicas is the total number of ready control plane machines in this cluster. A machine is considered ready when Machine’s Ready condition is true.

availableReplicas integer

availableReplicas is the total number of available control plane machines in this cluster. A machine is considered available when Machine’s Available condition is true.

ClusterNetwork

ClusterNetwork specifies the different networking parameters for a cluster.

Appears In:
Field Description Default Validation

apiServerPort integer

apiServerPort specifies the port the API Server should bind to.
Defaults to 6443.

services NetworkRanges

services is the network ranges from which service VIPs are allocated.

pods NetworkRanges

pods is the network ranges from which Pod networks are allocated.

serviceDomain string

serviceDomain is the domain name for services.

MaxLength: 253
MinLength: 1

ClusterSpec

ClusterSpec defines the desired state of Cluster.

Appears In:
Field Description Default Validation

paused boolean

paused can be used to prevent controllers from processing the Cluster and all its associated objects.

clusterNetwork ClusterNetwork

clusterNetwork represents the cluster network configuration.

controlPlaneEndpoint APIEndpoint

controlPlaneEndpoint represents the endpoint used to communicate with the control plane.

controlPlaneRef ObjectReference

controlPlaneRef is an optional reference to a provider-specific resource that holds
the details for provisioning the Control Plane for a Cluster.

infrastructureRef ObjectReference

infrastructureRef is a reference to a provider-specific resource that holds the details
for provisioning infrastructure for a cluster in said provider.

topology Topology

topology encapsulates the topology for the cluster.
NOTE: It is required to enable the ClusterTopology
feature gate flag to activate managed topologies support;
this feature is highly experimental, and parts of it might still be not implemented.

availabilityGates ClusterAvailabilityGate array

availabilityGates specifies additional conditions to include when evaluating Cluster Available condition.

If this field is not defined and the Cluster implements a managed topology, availabilityGates
from the corresponding ClusterClass will be used, if any.

Note
 this field is considered only for computing v1beta2 conditions.

MaxItems: 32

ClusterStatus

ClusterStatus defines the observed state of Cluster.

Appears In:
Field Description Default Validation

failureDomains FailureDomains

failureDomains is a slice of failure domain objects synced from the infrastructure provider.

failureReason ClusterStatusError

failureReason indicates that there is a fatal problem reconciling the
state, and will be set to a token value suitable for
programmatic interpretation.

Deprecated: This field is deprecated and is going to be removed when support for v1beta1 will be dropped. Please see https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/proposals/20240916-improve-status-in-CAPI-resources.md for more details.

failureMessage string

failureMessage indicates that there is a fatal problem reconciling the
state, and will be set to a descriptive error message.

Deprecated: This field is deprecated and is going to be removed when support for v1beta1 will be dropped. Please see https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/proposals/20240916-improve-status-in-CAPI-resources.md for more details.

MaxLength: 10240
MinLength: 1

phase string

phase represents the current phase of cluster actuation.

Enum: [Pending Provisioning Provisioned Deleting Failed Unknown]

infrastructureReady boolean

infrastructureReady is the state of the infrastructure provider.

controlPlaneReady boolean

controlPlaneReady denotes if the control plane became ready during initial provisioning
to receive requests.
NOTE: this field is part of the Cluster API contract and it is used to orchestrate provisioning.
The value of this field is never updated after provisioning is completed. Please use conditions
to check the operational state of the control plane.

conditions Conditions

conditions defines current service state of the cluster.

observedGeneration integer

observedGeneration is the latest generation observed by the controller.

v1beta2 ClusterV1Beta2Status

v1beta2 groups all the fields that will be added or modified in Cluster’s status with the V1Beta2 version.

ClusterV1Beta2Status

ClusterV1Beta2Status groups all the fields that will be added or modified in Cluster with the V1Beta2 version. See https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/proposals/20240916-improve-status-in-CAPI-resources.md for more context.

Appears In:
Field Description Default Validation

conditions Condition array

conditions represents the observations of a Cluster’s current state.
Known condition types are Available, InfrastructureReady, ControlPlaneInitialized, ControlPlaneAvailable, WorkersAvailable, MachinesReady
MachinesUpToDate, RemoteConnectionProbe, ScalingUp, ScalingDown, Remediating, Deleting, Paused.
Additionally, a TopologyReconciled condition will be added in case the Cluster is referencing a ClusterClass / defining a managed Topology.

MaxItems: 32

controlPlane ClusterControlPlaneStatus

controlPlane groups all the observations about Cluster’s ControlPlane current state.

workers WorkersStatus

workers groups all the observations about Cluster’s Workers current state.

ClusterVariable

ClusterVariable can be used to customize the Cluster through patches. Each ClusterVariable is associated with a Variable definition in the ClusterClass status variables.

Appears In:
Field Description Default Validation

name string

name of the variable.

MaxLength: 256
MinLength: 1

definitionFrom string

definitionFrom specifies where the definition of this Variable is from.

Deprecated: This field is deprecated, must not be set anymore and is going to be removed in the next apiVersion.

MaxLength: 256

value JSON

value of the variable.
Note: the value will be validated against the schema of the corresponding ClusterClassVariable
from the ClusterClass.
Note: We have to use apiextensionsv1.JSON instead of a custom JSON type, because controller-tools has a
hard-coded schema for apiextensionsv1.JSON which cannot be produced by another type via controller-tools,
i.e. it is not possible to have no type field.
Ref: https://github.com/kubernetes-sigs/controller-tools/blob/d0e03a142d0ecdd5491593e941ee1d6b5d91dba6/pkg/crd/known_types.go#L106-L111

Condition

Condition defines an observation of a Cluster API resource operational state.

Appears In:
Field Description Default Validation

type ConditionType

type of condition in CamelCase or in foo.example.com/CamelCase.
Many .condition.type values are consistent across resources like Available, but because arbitrary conditions
can be useful (see .node.status.conditions), the ability to deconflict is important.

MaxLength: 256
MinLength: 1

status ConditionStatus

status of the condition, one of True, False, Unknown.

severity ConditionSeverity

severity provides an explicit classification of Reason code, so the users or machines can immediately
understand the current situation and act accordingly.
The Severity field MUST be set only when Status=False.

MaxLength: 32

lastTransitionTime Time

lastTransitionTime is the last time the condition transitioned from one status to another.
This should be when the underlying condition changed. If that is not known, then using the time when
the API field changed is acceptable.

reason string

reason is the reason for the condition’s last transition in CamelCase.
The specific API may choose whether or not this field is considered a guaranteed API.
This field may be empty.

MaxLength: 256
MinLength: 1

message string

message is a human readable message indicating details about the transition.
This field may be empty.

MaxLength: 10240
MinLength: 1

ConditionPolarity

Underlying type: string

ConditionPolarity defines the polarity for a metav1.Condition.

Appears In:

ConditionSeverity

Underlying type: string

ConditionSeverity expresses the severity of a Condition Type failing.

Validation:

  • MaxLength: 32

Appears In:

ConditionType

Underlying type: string

ConditionType is a valid value for Condition.Type.

Validation:

  • MaxLength: 256

  • MinLength: 1

Appears In:

Conditions

Underlying type: Condition

Conditions provide observations of the operational state of a Cluster API resource.

Appears In:
Field Description Default Validation

type ConditionType

type of condition in CamelCase or in foo.example.com/CamelCase.
Many .condition.type values are consistent across resources like Available, but because arbitrary conditions
can be useful (see .node.status.conditions), the ability to deconflict is important.

MaxLength: 256
MinLength: 1

status ConditionStatus

status of the condition, one of True, False, Unknown.

severity ConditionSeverity

severity provides an explicit classification of Reason code, so the users or machines can immediately
understand the current situation and act accordingly.
The Severity field MUST be set only when Status=False.

MaxLength: 32

lastTransitionTime Time

lastTransitionTime is the last time the condition transitioned from one status to another.
This should be when the underlying condition changed. If that is not known, then using the time when
the API field changed is acceptable.

reason string

reason is the reason for the condition’s last transition in CamelCase.
The specific API may choose whether or not this field is considered a guaranteed API.
This field may be empty.

MaxLength: 256
MinLength: 1

message string

message is a human readable message indicating details about the transition.
This field may be empty.

MaxLength: 10240
MinLength: 1

ControlPlaneClass

ControlPlaneClass defines the class for the control plane.

Appears In:
Field Description Default Validation

metadata ObjectMeta

Refer to Kubernetes API documentation for fields of metadata.

ref ObjectReference

ref is a required reference to a custom resource
offered by a provider.

machineInfrastructure LocalObjectTemplate

machineInfrastructure defines the metadata and infrastructure information
for control plane machines.

This field is supported if and only if the control plane provider template
referenced above is Machine based and supports setting replicas.

machineHealthCheck MachineHealthCheckClass

machineHealthCheck defines a MachineHealthCheck for this ControlPlaneClass.
This field is supported if and only if the ControlPlane provider template
referenced above is Machine based and supports setting replicas.

namingStrategy ControlPlaneClassNamingStrategy

namingStrategy allows changing the naming pattern used when creating the control plane provider object.

nodeDrainTimeout Duration

nodeDrainTimeout is the total amount of time that the controller will spend on draining a node.
The default value is 0, meaning that the node can be drained without any time limitations.
NOTE: NodeDrainTimeout is different from kubectl drain --timeout
NOTE: This value can be overridden while defining a Cluster.Topology.

nodeVolumeDetachTimeout Duration

nodeVolumeDetachTimeout is the total amount of time that the controller will spend on waiting for all volumes
to be detached. The default value is 0, meaning that the volumes can be detached without any time limitations.
NOTE: This value can be overridden while defining a Cluster.Topology.

nodeDeletionTimeout Duration

nodeDeletionTimeout defines how long the controller will attempt to delete the Node that the Machine
hosts after the Machine is marked for deletion. A duration of 0 will retry deletion indefinitely.
Defaults to 10 seconds.
NOTE: This value can be overridden while defining a Cluster.Topology.

readinessGates MachineReadinessGate array

readinessGates specifies additional conditions to include when evaluating Machine Ready condition.

This field can be used e.g. to instruct the machine controller to include in the computation for Machine’s ready
computation a condition, managed by an external controllers, reporting the status of special software/hardware installed on the Machine.

Note
 This field is considered only for computing v1beta2 conditions.
NOTE: If a Cluster defines a custom list of readinessGates for the control plane,
such list overrides readinessGates defined in this field.
NOTE: Specific control plane provider implementations might automatically extend the list of readinessGates;
e.g. the kubeadm control provider adds ReadinessGates for the APIServerPodHealthy, SchedulerPodHealthy conditions, etc.

MaxItems: 32

ControlPlaneClassNamingStrategy

ControlPlaneClassNamingStrategy defines the naming strategy for control plane objects.

Appears In:
Field Description Default Validation

template string

template defines the template to use for generating the name of the ControlPlane object.
If not defined, it will fallback to {{ .cluster.name }}-{{ .random }}.
If the templated string exceeds 63 characters, it will be trimmed to 58 characters and will
get concatenated with a random suffix of length 5.
The templating mechanism provides the following arguments:
* .cluster.name: The name of the cluster object.
* .random: A random alphanumeric string, without vowels, of length 5.

MaxLength: 1024
MinLength: 1

ControlPlaneTopology

ControlPlaneTopology specifies the parameters for the control plane nodes in the cluster.

Appears In:
Field Description Default Validation

metadata ObjectMeta

Refer to Kubernetes API documentation for fields of metadata.

replicas integer

replicas is the number of control plane nodes.
If the value is nil, the ControlPlane object is created without the number of Replicas
and it’s assumed that the control plane controller does not implement support for this field.
When specified against a control plane provider that lacks support for this field, this value will be ignored.

machineHealthCheck MachineHealthCheckTopology

machineHealthCheck allows to enable, disable and override
the MachineHealthCheck configuration in the ClusterClass for this control plane.

nodeDrainTimeout Duration

nodeDrainTimeout is the total amount of time that the controller will spend on draining a node.
The default value is 0, meaning that the node can be drained without any time limitations.
NOTE: NodeDrainTimeout is different from kubectl drain --timeout

nodeVolumeDetachTimeout Duration

nodeVolumeDetachTimeout is the total amount of time that the controller will spend on waiting for all volumes
to be detached. The default value is 0, meaning that the volumes can be detached without any time limitations.

nodeDeletionTimeout Duration

nodeDeletionTimeout defines how long the controller will attempt to delete the Node that the Machine
hosts after the Machine is marked for deletion. A duration of 0 will retry deletion indefinitely.
Defaults to 10 seconds.

readinessGates MachineReadinessGate array

readinessGates specifies additional conditions to include when evaluating Machine Ready condition.

This field can be used e.g. to instruct the machine controller to include in the computation for Machine’s ready
computation a condition, managed by an external controllers, reporting the status of special software/hardware installed on the Machine.

If this field is not defined, readinessGates from the corresponding ControlPlaneClass will be used, if any.

Note
 This field is considered only for computing v1beta2 conditions.
NOTE: Specific control plane provider implementations might automatically extend the list of readinessGates;
e.g. the kubeadm control provider adds ReadinessGates for the APIServerPodHealthy, SchedulerPodHealthy conditions, etc.

MaxItems: 32

variables ControlPlaneVariables

variables can be used to customize the ControlPlane through patches.

ControlPlaneVariables

ControlPlaneVariables can be used to provide variables for the ControlPlane.

Appears In:
Field Description Default Validation

overrides ClusterVariable array

overrides can be used to override Cluster level variables.

MaxItems: 1000

ExternalPatchDefinition

ExternalPatchDefinition defines an external patch. Note: At least one of GenerateExtension or ValidateExtension must be set.

Appears In:
Field Description Default Validation

generateExtension string

generateExtension references an extension which is called to generate patches.

MaxLength: 512
MinLength: 1

validateExtension string

validateExtension references an extension which is called to validate the topology.

MaxLength: 512
MinLength: 1

discoverVariablesExtension string

discoverVariablesExtension references an extension which is called to discover variables.

MaxLength: 512
MinLength: 1

settings object (keys:string, values:string)

settings defines key value pairs to be passed to the extensions.
Values defined here take precedence over the values defined in the
corresponding ExtensionConfig.

FailureDomainSpec

FailureDomainSpec is the Schema for Cluster API failure domains. It allows controllers to understand how many failure domains a cluster can optionally span across.

Appears In:
Field Description Default Validation

controlPlane boolean

controlPlane determines if this failure domain is suitable for use by control plane machines.

attributes object (keys:string, values:string)

attributes is a free form map of attributes an infrastructure provider might use or require.

FailureDomains

Underlying type: map[string]FailureDomainSpec

FailureDomains is a slice of FailureDomains.

Appears In:

FieldValueErrorReason

Underlying type: string

FieldValueErrorReason is a machine-readable value providing more detail about why a field failed the validation.

Appears In:

InfrastructureNamingStrategy

InfrastructureNamingStrategy defines the naming strategy for infrastructure objects.

Appears In:
Field Description Default Validation

template string

template defines the template to use for generating the name of the Infrastructure object.
If not defined, it will fallback to {{ .cluster.name }}-{{ .random }}.
If the templated string exceeds 63 characters, it will be trimmed to 58 characters and will
get concatenated with a random suffix of length 5.
The templating mechanism provides the following arguments:
* .cluster.name: The name of the cluster object.
* .random: A random alphanumeric string, without vowels, of length 5.

MaxLength: 1024
MinLength: 1

JSONPatch

JSONPatch defines a JSON patch.

Appears In:
Field Description Default Validation

op string

op defines the operation of the patch.
Note: Only add, replace and remove are supported.

Enum: [add replace remove]

path string

path defines the path of the patch.
Note: Only the spec of a template can be patched, thus the path has to start with /spec/.
Note: For now the only allowed array modifications are append and prepend, i.e.:
* for op: add: only index 0 (prepend) and - (append) are allowed
* for op: replace or remove: no indexes are allowed

MaxLength: 512
MinLength: 1

value JSON

value defines the value of the patch.
Note: Either Value or ValueFrom is required for add and replace
operations. Only one of them is allowed to be set at the same time.
Note: We have to use apiextensionsv1.JSON instead of our JSON type,
because controller-tools has a hard-coded schema for apiextensionsv1.JSON
which cannot be produced by another type (unset type field).
Ref: https://github.com/kubernetes-sigs/controller-tools/blob/d0e03a142d0ecdd5491593e941ee1d6b5d91dba6/pkg/crd/known_types.go#L106-L111

valueFrom JSONPatchValue

valueFrom defines the value of the patch.
Note: Either Value or ValueFrom is required for add and replace
operations. Only one of them is allowed to be set at the same time.

JSONPatchValue

JSONPatchValue defines the value of a patch. Note: Only one of the fields is allowed to be set at the same time.

Appears In:
Field Description Default Validation

variable string

variable is the variable to be used as value.
Variable can be one of the variables defined in .spec.variables or a builtin variable.

MaxLength: 256
MinLength: 1

template string

template is the Go template to be used to calculate the value.
A template can reference variables defined in .spec.variables and builtin variables.
Note: The template must evaluate to a valid YAML or JSON value.

MaxLength: 10240
MinLength: 1

JSONSchemaProps

JSONSchemaProps is a JSON-Schema following Specification Draft 4 (http://json-schema.org/). This struct has been initially copied from apiextensionsv1.JSONSchemaProps, but all fields which are not supported in CAPI have been removed.

Appears In:
Field Description Default Validation

description string

description is a human-readable description of this variable.

MaxLength: 4096
MinLength: 1

example JSON

example is an example for this variable.

type string

type is the type of the variable.
Valid values are: object, array, string, integer, number or boolean.

Enum: [object array string integer number boolean]

properties object (keys:string, values:JSONSchemaProps)

properties specifies fields of an object.
NOTE: Can only be set if type is object.
NOTE: Properties is mutually exclusive with AdditionalProperties.
NOTE: This field uses PreserveUnknownFields and Schemaless,
because recursive validation is not possible.

Schemaless: \{}

additionalProperties JSONSchemaProps

additionalProperties specifies the schema of values in a map (keys are always strings).
NOTE: Can only be set if type is object.
NOTE: AdditionalProperties is mutually exclusive with Properties.
NOTE: This field uses PreserveUnknownFields and Schemaless,
because recursive validation is not possible.

Schemaless: \{}

maxProperties integer

maxProperties is the maximum amount of entries in a map or properties in an object.
NOTE: Can only be set if type is object.

minProperties integer

minProperties is the minimum amount of entries in a map or properties in an object.
NOTE: Can only be set if type is object.

required string array

required specifies which fields of an object are required.
NOTE: Can only be set if type is object.

MaxItems: 1000
items:MaxLength: 256
items:MinLength: 1

items JSONSchemaProps

items specifies fields of an array.
NOTE: Can only be set if type is array.
NOTE: This field uses PreserveUnknownFields and Schemaless,
because recursive validation is not possible.

Schemaless: \{}

maxItems integer

maxItems is the max length of an array variable.
NOTE: Can only be set if type is array.

minItems integer

minItems is the min length of an array variable.
NOTE: Can only be set if type is array.

uniqueItems boolean

uniqueItems specifies if items in an array must be unique.
NOTE: Can only be set if type is array.

format string

format is an OpenAPI v3 format string. Unknown formats are ignored.
For a list of supported formats please see: (of the k8s.io/apiextensions-apiserver version we’re currently using)
https://github.com/kubernetes/apiextensions-apiserver/blob/master/pkg/apiserver/validation/formats.go
NOTE: Can only be set if type is string.

MaxLength: 32
MinLength: 1

maxLength integer

maxLength is the max length of a string variable.
NOTE: Can only be set if type is string.

minLength integer

minLength is the min length of a string variable.
NOTE: Can only be set if type is string.

pattern string

pattern is the regex which a string variable must match.
NOTE: Can only be set if type is string.

MaxLength: 512
MinLength: 1

maximum integer

maximum is the maximum of an integer or number variable.
If ExclusiveMaximum is false, the variable is valid if it is lower than, or equal to, the value of Maximum.
If ExclusiveMaximum is true, the variable is valid if it is strictly lower than the value of Maximum.
NOTE: Can only be set if type is integer or number.

exclusiveMaximum boolean

exclusiveMaximum specifies if the Maximum is exclusive.
NOTE: Can only be set if type is integer or number.

minimum integer

minimum is the minimum of an integer or number variable.
If ExclusiveMinimum is false, the variable is valid if it is greater than, or equal to, the value of Minimum.
If ExclusiveMinimum is true, the variable is valid if it is strictly greater than the value of Minimum.
NOTE: Can only be set if type is integer or number.

exclusiveMinimum boolean

exclusiveMinimum specifies if the Minimum is exclusive.
NOTE: Can only be set if type is integer or number.

x-kubernetes-preserve-unknown-fields boolean

x-kubernetes-preserve-unknown-fields allows setting fields in a variable object
which are not defined in the variable schema. This affects fields recursively,
except if nested properties or additionalProperties are specified in the schema.

enum JSON array

enum is the list of valid values of the variable.
NOTE: Can be set for all types.

MaxItems: 100

default JSON

default is the default value of the variable.
NOTE: Can be set for all types.

x-kubernetes-validations ValidationRule array

x-kubernetes-validations describes a list of validation rules written in the CEL expression language.

MaxItems: 100

x-metadata VariableSchemaMetadata

x-metadata is the metadata of a variable or a nested field within a variable.
It can be used to add additional data for higher level tools.

x-kubernetes-int-or-string boolean

x-kubernetes-int-or-string specifies that this value is
either an integer or a string. If this is true, an empty
type is allowed and type as child of anyOf is permitted
if following one of the following patterns:

1) anyOf:
- type: integer
- type: string
2) allOf:
- anyOf:
- type: integer
- type: string
- …​ zero or more

allOf JSONSchemaProps array

allOf specifies that the variable must validate against all of the subschemas in the array.
NOTE: This field uses PreserveUnknownFields and Schemaless,
because recursive validation is not possible.

Schemaless: \{}

oneOf JSONSchemaProps array

oneOf specifies that the variable must validate against exactly one of the subschemas in the array.
NOTE: This field uses PreserveUnknownFields and Schemaless,
because recursive validation is not possible.

Schemaless: \{}

anyOf JSONSchemaProps array

anyOf specifies that the variable must validate against one or more of the subschemas in the array.
NOTE: This field uses PreserveUnknownFields and Schemaless,
because recursive validation is not possible.

Schemaless: \{}

not JSONSchemaProps

not specifies that the variable must not validate against the subschema.
NOTE: This field uses PreserveUnknownFields and Schemaless,
because recursive validation is not possible.

Schemaless: \{}

LocalObjectTemplate

LocalObjectTemplate defines a template for a topology Class.

Appears In:
Field Description Default Validation

ref ObjectReference

ref is a required reference to a custom resource
offered by a provider.

Machine

Machine is the Schema for the machines API.

Field Description Default Validation

apiVersion string

cluster.x-k8s.io/v1beta1

kind string

Machine

metadata ObjectMeta

Refer to Kubernetes API documentation for fields of metadata.

MinProperties: 1

spec MachineSpec

spec is the desired state of Machine.

status MachineStatus

status is the observed state of Machine.

MachineAddress

MachineAddress contains information for the node’s address.

Appears In:
Field Description Default Validation

type MachineAddressType

type is the machine address type, one of Hostname, ExternalIP, InternalIP, ExternalDNS or InternalDNS.

Enum: [Hostname ExternalIP InternalIP ExternalDNS InternalDNS]

address string

address is the machine address.

MaxLength: 256
MinLength: 1

MachineAddressType

Underlying type: string

MachineAddressType describes a valid MachineAddress type.

Validation:

  • Enum: [Hostname ExternalIP InternalIP ExternalDNS InternalDNS]

Appears In:

MachineAddresses

Underlying type: MachineAddress

MachineAddresses is a slice of MachineAddress items to be used by infrastructure providers.

Appears In:
Field Description Default Validation

type MachineAddressType

type is the machine address type, one of Hostname, ExternalIP, InternalIP, ExternalDNS or InternalDNS.

Enum: [Hostname ExternalIP InternalIP ExternalDNS InternalDNS]

address string

address is the machine address.

MaxLength: 256
MinLength: 1

MachineDeletionStatus

MachineDeletionStatus is the deletion state of the Machine.

Appears In:
Field Description Default Validation

nodeDrainStartTime Time

nodeDrainStartTime is the time when the drain of the node started and is used to determine
if the NodeDrainTimeout is exceeded.
Only present when the Machine has a deletionTimestamp and draining the node had been started.

waitForNodeVolumeDetachStartTime Time

waitForNodeVolumeDetachStartTime is the time when waiting for volume detachment started
and is used to determine if the NodeVolumeDetachTimeout is exceeded.
Detaching volumes from nodes is usually done by CSI implementations and the current state
is observed from the node’s .Status.VolumesAttached field.
Only present when the Machine has a deletionTimestamp and waiting for volume detachments had been started.

MachineDeployment

MachineDeployment is the Schema for the machinedeployments API.

Field Description Default Validation

apiVersion string

cluster.x-k8s.io/v1beta1

kind string

MachineDeployment

metadata ObjectMeta

Refer to Kubernetes API documentation for fields of metadata.

MinProperties: 1

spec MachineDeploymentSpec

spec is the desired state of MachineDeployment.

status MachineDeploymentStatus

status is the observed state of MachineDeployment.

MachineDeploymentClass

MachineDeploymentClass serves as a template to define a set of worker nodes of the cluster provisioned using the ClusterClass.

Appears In:
Field Description Default Validation

class string

class denotes a type of worker node present in the cluster,
this name MUST be unique within a ClusterClass and can be referenced
in the Cluster to create a managed MachineDeployment.

MaxLength: 256
MinLength: 1

template MachineDeploymentClassTemplate

template is a local struct containing a collection of templates for creation of
MachineDeployment objects representing a set of worker nodes.

machineHealthCheck MachineHealthCheckClass

machineHealthCheck defines a MachineHealthCheck for this MachineDeploymentClass.

failureDomain string

failureDomain is the failure domain the machines will be created in.
Must match a key in the FailureDomains map stored on the cluster object.
NOTE: This value can be overridden while defining a Cluster.Topology using this MachineDeploymentClass.

MaxLength: 256
MinLength: 1

namingStrategy MachineDeploymentClassNamingStrategy

namingStrategy allows changing the naming pattern used when creating the MachineDeployment.

nodeDrainTimeout Duration

nodeDrainTimeout is the total amount of time that the controller will spend on draining a node.
The default value is 0, meaning that the node can be drained without any time limitations.
NOTE: NodeDrainTimeout is different from kubectl drain --timeout
NOTE: This value can be overridden while defining a Cluster.Topology using this MachineDeploymentClass.

nodeVolumeDetachTimeout Duration

nodeVolumeDetachTimeout is the total amount of time that the controller will spend on waiting for all volumes
to be detached. The default value is 0, meaning that the volumes can be detached without any time limitations.
NOTE: This value can be overridden while defining a Cluster.Topology using this MachineDeploymentClass.

nodeDeletionTimeout Duration

nodeDeletionTimeout defines how long the controller will attempt to delete the Node that the Machine
hosts after the Machine is marked for deletion. A duration of 0 will retry deletion indefinitely.
Defaults to 10 seconds.
NOTE: This value can be overridden while defining a Cluster.Topology using this MachineDeploymentClass.

minReadySeconds integer

minReadySeconds is the minimum number of seconds for which a newly created machine should
be ready.
Defaults to 0 (machine will be considered available as soon as it
is ready)
NOTE: This value can be overridden while defining a Cluster.Topology using this MachineDeploymentClass.

readinessGates MachineReadinessGate array

readinessGates specifies additional conditions to include when evaluating Machine Ready condition.

This field can be used e.g. to instruct the machine controller to include in the computation for Machine’s ready
computation a condition, managed by an external controllers, reporting the status of special software/hardware installed on the Machine.

Note
 This field is considered only for computing v1beta2 conditions.
NOTE: If a Cluster defines a custom list of readinessGates for a MachineDeployment using this MachineDeploymentClass,
such list overrides readinessGates defined in this field.

MaxItems: 32

strategy MachineDeploymentStrategy

strategy is the deployment strategy to use to replace existing machines with
new ones.
NOTE: This value can be overridden while defining a Cluster.Topology using this MachineDeploymentClass.

MachineDeploymentClassNamingStrategy

MachineDeploymentClassNamingStrategy defines the naming strategy for machine deployment objects.

Appears In:
Field Description Default Validation

template string

template defines the template to use for generating the name of the MachineDeployment object.
If not defined, it will fallback to {{ .cluster.name }}-{{ .machineDeployment.topologyName }}-{{ .random }}.
If the templated string exceeds 63 characters, it will be trimmed to 58 characters and will
get concatenated with a random suffix of length 5.
The templating mechanism provides the following arguments:
* .cluster.name: The name of the cluster object.
* .random: A random alphanumeric string, without vowels, of length 5.
* .machineDeployment.topologyName: The name of the MachineDeployment topology (Cluster.spec.topology.workers.machineDeployments[].name).

MaxLength: 1024
MinLength: 1

MachineDeploymentClassTemplate

MachineDeploymentClassTemplate defines how a MachineDeployment generated from a MachineDeploymentClass should look like.

Appears In:
Field Description Default Validation

metadata ObjectMeta

Refer to Kubernetes API documentation for fields of metadata.

bootstrap LocalObjectTemplate

bootstrap contains the bootstrap template reference to be used
for the creation of worker Machines.

infrastructure LocalObjectTemplate

infrastructure contains the infrastructure template reference to be used
for the creation of worker Machines.

MachineDeploymentSpec

MachineDeploymentSpec defines the desired state of MachineDeployment.

Appears In:
Field Description Default Validation

clusterName string

clusterName is the name of the Cluster this object belongs to.

MaxLength: 63
MinLength: 1

replicas integer

replicas is the number of desired machines.
This is a pointer to distinguish between explicit zero and not specified.

Defaults to:
* if the Kubernetes autoscaler min size and max size annotations are set:
- if it’s a new MachineDeployment, use min size
- if the replicas field of the old MachineDeployment is < min size, use min size
- if the replicas field of the old MachineDeployment is > max size, use max size
- if the replicas field of the old MachineDeployment is in the (min size, max size) range, keep the value from the oldMD
* otherwise use 1
Note: Defaulting will be run whenever the replicas field is not set:
* A new MachineDeployment is created with replicas not set.
* On an existing MachineDeployment the replicas field was first set and is now unset.
Those cases are especially relevant for the following Kubernetes autoscaler use cases:
* A new MachineDeployment is created and replicas should be managed by the autoscaler
* An existing MachineDeployment which initially wasn’t controlled by the autoscaler
should be later controlled by the autoscaler

rolloutAfter Time

rolloutAfter is a field to indicate a rollout should be performed
after the specified time even if no changes have been made to the
MachineDeployment.
Example: In the YAML the time can be specified in the RFC3339 format.
To specify the rolloutAfter target as March 9, 2023, at 9 am UTC
use "2023-03-09T09:00:00Z".

selector LabelSelector

selector is the label selector for machines. Existing MachineSets whose machines are
selected by this will be the ones affected by this deployment.
It must match the machine template’s labels.

template MachineTemplateSpec

template describes the machines that will be created.

strategy MachineDeploymentStrategy

strategy is the deployment strategy to use to replace existing machines with
new ones.

machineNamingStrategy MachineNamingStrategy

machineNamingStrategy allows changing the naming pattern used when creating Machines.
Note: InfraMachines & BootstrapConfigs will use the same name as the corresponding Machines.

minReadySeconds integer

minReadySeconds is the minimum number of seconds for which a Node for a newly created machine should be ready before considering the replica available.
Defaults to 0 (machine will be considered available as soon as the Node is ready)

revisionHistoryLimit integer

revisionHistoryLimit is the number of old MachineSets to retain to allow rollback.
This is a pointer to distinguish between explicit zero and not specified.
Defaults to 1.

Deprecated: This field is deprecated and is going to be removed in the next apiVersion. Please see https://github.com/kubernetes-sigs/cluster-api/issues/10479 for more details.

paused boolean

paused indicates that the deployment is paused.

progressDeadlineSeconds integer

progressDeadlineSeconds is the maximum time in seconds for a deployment to make progress before it
is considered to be failed. The deployment controller will continue to
process failed deployments and a condition with a ProgressDeadlineExceeded
reason will be surfaced in the deployment status. Note that progress will
not be estimated during the time a deployment is paused. Defaults to 600s.

Deprecated: This field is deprecated and is going to be removed in the next apiVersion. Please see https://github.com/kubernetes-sigs/cluster-api/issues/11470 for more details.

MachineDeploymentStatus

MachineDeploymentStatus defines the observed state of MachineDeployment.

Appears In:
Field Description Default Validation

observedGeneration integer

observedGeneration is the generation observed by the deployment controller.

selector string

selector is the same as the label selector but in the string format to avoid introspection
by clients. The string will be in the same format as the query-param syntax.
More info about label selectors: http://kubernetes.io/docs/user-guide/labels#label-selectors

MaxLength: 4096
MinLength: 1

replicas integer

replicas is the total number of non-terminated machines targeted by this deployment
(their labels match the selector).

updatedReplicas integer

updatedReplicas is the total number of non-terminated machines targeted by this deployment
that have the desired template spec.

readyReplicas integer

readyReplicas is the total number of ready machines targeted by this deployment.

availableReplicas integer

availableReplicas is the total number of available machines (ready for at least minReadySeconds)
targeted by this deployment.

unavailableReplicas integer

unavailableReplicas is the total number of unavailable machines targeted by this deployment.
This is the total number of machines that are still required for
the deployment to have 100% available capacity. They may either
be machines that are running but not yet available or machines
that still have not been created.

Deprecated: This field is deprecated and is going to be removed when support for v1beta1 will be dropped. Please see https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/proposals/20240916-improve-status-in-CAPI-resources.md for more details.

phase string

phase represents the current phase of a MachineDeployment (ScalingUp, ScalingDown, Running, Failed, or Unknown).

Enum: [ScalingUp ScalingDown Running Failed Unknown]

conditions Conditions

conditions defines current service state of the MachineDeployment.

v1beta2 MachineDeploymentV1Beta2Status

v1beta2 groups all the fields that will be added or modified in MachineDeployment’s status with the V1Beta2 version.

MachineDeploymentStrategy

MachineDeploymentStrategy describes how to replace existing machines with new ones.

Appears In:
Field Description Default Validation

type MachineDeploymentStrategyType

type of deployment. Allowed values are RollingUpdate and OnDelete.
The default is RollingUpdate.

Enum: [RollingUpdate OnDelete]

rollingUpdate MachineRollingUpdateDeployment

rollingUpdate is the rolling update config params. Present only if
MachineDeploymentStrategyType = RollingUpdate.

remediation RemediationStrategy

remediation controls the strategy of remediating unhealthy machines
and how remediating operations should occur during the lifecycle of the dependant MachineSets.

MachineDeploymentStrategyType

Underlying type: string

MachineDeploymentStrategyType defines the type of MachineDeployment rollout strategies.

Appears In:

MachineDeploymentTopology

MachineDeploymentTopology specifies the different parameters for a set of worker nodes in the topology. This set of nodes is managed by a MachineDeployment object whose lifecycle is managed by the Cluster controller.

Appears In:
Field Description Default Validation

metadata ObjectMeta

Refer to Kubernetes API documentation for fields of metadata.

class string

class is the name of the MachineDeploymentClass used to create the set of worker nodes.
This should match one of the deployment classes defined in the ClusterClass object
mentioned in the Cluster.Spec.Class field.

MaxLength: 256
MinLength: 1

name string

name is the unique identifier for this MachineDeploymentTopology.
The value is used with other unique identifiers to create a MachineDeployment’s Name
(e.g. cluster’s name, etc). In case the name is greater than the allowed maximum length,
the values are hashed together.

MaxLength: 63
MinLength: 1

failureDomain string

failureDomain is the failure domain the machines will be created in.
Must match a key in the FailureDomains map stored on the cluster object.

MaxLength: 256
MinLength: 1

replicas integer

replicas is the number of worker nodes belonging to this set.
If the value is nil, the MachineDeployment is created without the number of Replicas (defaulting to 1)
and it’s assumed that an external entity (like cluster autoscaler) is responsible for the management
of this value.

machineHealthCheck MachineHealthCheckTopology

machineHealthCheck allows to enable, disable and override
the MachineHealthCheck configuration in the ClusterClass for this MachineDeployment.

nodeDrainTimeout Duration

nodeDrainTimeout is the total amount of time that the controller will spend on draining a node.
The default value is 0, meaning that the node can be drained without any time limitations.
NOTE: NodeDrainTimeout is different from kubectl drain --timeout

nodeVolumeDetachTimeout Duration

nodeVolumeDetachTimeout is the total amount of time that the controller will spend on waiting for all volumes
to be detached. The default value is 0, meaning that the volumes can be detached without any time limitations.

nodeDeletionTimeout Duration

nodeDeletionTimeout defines how long the controller will attempt to delete the Node that the Machine
hosts after the Machine is marked for deletion. A duration of 0 will retry deletion indefinitely.
Defaults to 10 seconds.

minReadySeconds integer

minReadySeconds is the minimum number of seconds for which a newly created machine should
be ready.
Defaults to 0 (machine will be considered available as soon as it
is ready)

readinessGates MachineReadinessGate array

readinessGates specifies additional conditions to include when evaluating Machine Ready condition.

This field can be used e.g. to instruct the machine controller to include in the computation for Machine’s ready
computation a condition, managed by an external controllers, reporting the status of special software/hardware installed on the Machine.

If this field is not defined, readinessGates from the corresponding MachineDeploymentClass will be used, if any.

Note
 This field is considered only for computing v1beta2 conditions.

MaxItems: 32

strategy MachineDeploymentStrategy

strategy is the deployment strategy to use to replace existing machines with
new ones.

variables MachineDeploymentVariables

variables can be used to customize the MachineDeployment through patches.

MachineDeploymentV1Beta2Status

MachineDeploymentV1Beta2Status groups all the fields that will be added or modified in MachineDeployment with the V1Beta2 version. See https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/proposals/20240916-improve-status-in-CAPI-resources.md for more context.

Appears In:
Field Description Default Validation

conditions Condition array

conditions represents the observations of a MachineDeployment’s current state.
Known condition types are Available, MachinesReady, MachinesUpToDate, ScalingUp, ScalingDown, Remediating, Deleting, Paused.

MaxItems: 32

readyReplicas integer

readyReplicas is the number of ready replicas for this MachineDeployment. A machine is considered ready when Machine’s Ready condition is true.

availableReplicas integer

availableReplicas is the number of available replicas for this MachineDeployment. A machine is considered available when Machine’s Available condition is true.

upToDateReplicas integer

upToDateReplicas is the number of up-to-date replicas targeted by this deployment. A machine is considered up-to-date when Machine’s UpToDate condition is true.

MachineDeploymentVariables

MachineDeploymentVariables can be used to provide variables for a specific MachineDeployment.

Appears In:
Field Description Default Validation

overrides ClusterVariable array

overrides can be used to override Cluster level variables.

MaxItems: 1000

MachineDrainRule

MachineDrainRule is the Schema for the MachineDrainRule API.

Field Description Default Validation

apiVersion string

cluster.x-k8s.io/v1beta1

kind string

MachineDrainRule

metadata ObjectMeta

Refer to Kubernetes API documentation for fields of metadata.

MinProperties: 1

spec MachineDrainRuleSpec

spec defines the spec of a MachineDrainRule.

MachineDrainRuleDrainBehavior

Underlying type: string

MachineDrainRuleDrainBehavior defines the drain behavior. Can be either "Drain", "Skip", or "WaitCompleted".

Validation:

  • Enum: [Drain Skip WaitCompleted]

Appears In:

MachineDrainRuleDrainConfig

MachineDrainRuleDrainConfig configures if and how Pods are drained.

Appears In:
Field Description Default Validation

behavior MachineDrainRuleDrainBehavior

behavior defines the drain behavior.
Can be either "Drain", "Skip", or "WaitCompleted".
"Drain" means that the Pods to which this MachineDrainRule applies will be drained.
If behavior is set to "Drain" the order in which Pods are drained can be configured
with the order field. When draining Pods of a Node the Pods will be grouped by order
and one group after another will be drained (by increasing order). Cluster API will
wait until all Pods of a group are terminated / removed from the Node before starting
with the next group.
"Skip" means that the Pods to which this MachineDrainRule applies will be skipped during drain.
"WaitCompleted" means that the pods to which this MachineDrainRule applies will never be evicted
and we wait for them to be completed, it is enforced that pods marked with this behavior always have Order=0.

Enum: [Drain Skip WaitCompleted]

order integer

order defines the order in which Pods are drained.
Pods with higher order are drained after Pods with lower order.
order can only be set if behavior is set to "Drain".
If order is not set, 0 will be used.
Valid values for order are from -2147483648 to 2147483647 (inclusive).

MachineDrainRuleMachineSelector

MachineDrainRuleMachineSelector defines to which Machines this MachineDrainRule should be applied.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

selector LabelSelector

selector is a label selector which selects Machines by their labels.
This field follows standard label selector semantics; if not present or
empty, it selects all Machines.

If clusterSelector is also set, then the selector as a whole selects
Machines matching selector belonging to Clusters selected by clusterSelector.
If clusterSelector is not set, it selects all Machines matching selector in
all Clusters.

clusterSelector LabelSelector

clusterSelector is a label selector which selects Machines by the labels of
their Clusters.
This field follows standard label selector semantics; if not present or
empty, it selects Machines of all Clusters.

If selector is also set, then the selector as a whole selects
Machines matching selector belonging to Clusters selected by clusterSelector.
If selector is not set, it selects all Machines belonging to Clusters
selected by clusterSelector.

MachineDrainRulePodSelector

MachineDrainRulePodSelector defines to which Pods this MachineDrainRule should be applied.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

selector LabelSelector

selector is a label selector which selects Pods by their labels.
This field follows standard label selector semantics; if not present or
empty, it selects all Pods.

If namespaceSelector is also set, then the selector as a whole selects
Pods matching selector in Namespaces selected by namespaceSelector.
If namespaceSelector is not set, it selects all Pods matching selector in
all Namespaces.

namespaceSelector LabelSelector

namespaceSelector is a label selector which selects Pods by the labels of
their Namespaces.
This field follows standard label selector semantics; if not present or
empty, it selects Pods of all Namespaces.

If selector is also set, then the selector as a whole selects
Pods matching selector in Namespaces selected by namespaceSelector.
If selector is not set, it selects all Pods in Namespaces selected by
namespaceSelector.

MachineDrainRuleSpec

MachineDrainRuleSpec defines the spec of a MachineDrainRule.

Appears In:
Field Description Default Validation

drain MachineDrainRuleDrainConfig

drain configures if and how Pods are drained.

machines MachineDrainRuleMachineSelector array

machines defines to which Machines this MachineDrainRule should be applied.

If machines is not set, the MachineDrainRule applies to all Machines in the Namespace.
If machines contains multiple selectors, the results are ORed.
Within a single Machine selector the results of selector and clusterSelector are ANDed.
Machines will be selected from all Clusters in the Namespace unless otherwise
restricted with the clusterSelector.

Example: Selects control plane Machines in all Clusters or
Machines with label "os" == "linux" in Clusters with label
"stage" == "production".

  • selector:
    matchExpressions:

  • key: cluster.x-k8s.io/control-plane
    operator: Exists

  • selector:
    matchLabels:
    os: linux
    clusterSelector:
    matchExpressions:

  • key: stage
    operator: In
    values:

  • production

MaxItems: 32
MinItems: 1
MinProperties: 1

pods MachineDrainRulePodSelector array

pods defines to which Pods this MachineDrainRule should be applied.

If pods is not set, the MachineDrainRule applies to all Pods in all Namespaces.
If pods contains multiple selectors, the results are ORed.
Within a single Pod selector the results of selector and namespaceSelector are ANDed.
Pods will be selected from all Namespaces unless otherwise
restricted with the namespaceSelector.

Example: Selects Pods with label "app" == "logging" in all Namespaces or
Pods with label "app" == "prometheus" in the "monitoring"
Namespace.

  • selector:
    matchExpressions:

  • key: app
    operator: In
    values:

  • logging

  • selector:
    matchLabels:
    app: prometheus
    namespaceSelector:
    matchLabels:
    kubernetes.io/metadata.name: monitoring

MaxItems: 32
MinItems: 1
MinProperties: 1

MachineHealthCheck

MachineHealthCheck is the Schema for the machinehealthchecks API.

Field Description Default Validation

apiVersion string

cluster.x-k8s.io/v1beta1

kind string

MachineHealthCheck

metadata ObjectMeta

Refer to Kubernetes API documentation for fields of metadata.

MinProperties: 1

spec MachineHealthCheckSpec

spec is the specification of machine health check policy

status MachineHealthCheckStatus

status is the most recently observed status of MachineHealthCheck resource

MachineHealthCheckClass

MachineHealthCheckClass defines a MachineHealthCheck for a group of Machines.

Appears In:
Field Description Default Validation

unhealthyConditions UnhealthyCondition array

unhealthyConditions contains a list of the conditions that determine
whether a node is considered unhealthy. The conditions are combined in a
logical OR, i.e. if any of the conditions is met, the node is unhealthy.

MaxItems: 100

maxUnhealthy IntOrString

maxUnhealthy specifies the maximum number of unhealthy machines allowed.
Any further remediation is only allowed if at most "maxUnhealthy" machines selected by
"selector" are not healthy.

unhealthyRange string

unhealthyRange specifies the range of unhealthy machines allowed.
Any further remediation is only allowed if the number of machines selected by "selector" as not healthy
is within the range of "unhealthyRange". Takes precedence over maxUnhealthy.
Eg. "[3-5]" - This means that remediation will be allowed only when:
(a) there are at least 3 unhealthy machines (and)
(b) there are at most 5 unhealthy machines

MaxLength: 32
MinLength: 1
Pattern: ^\[[0-9]+-[0-9]+\]$

nodeStartupTimeout Duration

nodeStartupTimeout allows to set the maximum time for MachineHealthCheck
to consider a Machine unhealthy if a corresponding Node isn’t associated
through a Spec.ProviderID field.

The duration set in this field is compared to the greatest of:
- Cluster’s infrastructure ready condition timestamp (if and when available)
- Control Plane’s initialized condition timestamp (if and when available)
- Machine’s infrastructure ready condition timestamp (if and when available)
- Machine’s metadata creation timestamp

Defaults to 10 minutes.
If you wish to disable this feature, set the value explicitly to 0.

remediationTemplate ObjectReference

remediationTemplate is a reference to a remediation template
provided by an infrastructure provider.

This field is completely optional, when filled, the MachineHealthCheck controller
creates a new object from the template referenced and hands off remediation of the machine to
a controller that lives outside of Cluster API.

MachineHealthCheckSpec

MachineHealthCheckSpec defines the desired state of MachineHealthCheck.

Appears In:
Field Description Default Validation

clusterName string

clusterName is the name of the Cluster this object belongs to.

MaxLength: 63
MinLength: 1

selector LabelSelector

selector is a label selector to match machines whose health will be exercised

unhealthyConditions UnhealthyCondition array

unhealthyConditions contains a list of the conditions that determine
whether a node is considered unhealthy. The conditions are combined in a
logical OR, i.e. if any of the conditions is met, the node is unhealthy.

MaxItems: 100

maxUnhealthy IntOrString

maxUnhealthy specifies the maximum number of unhealthy machines allowed.
Any further remediation is only allowed if at most "maxUnhealthy" machines selected by
"selector" are not healthy.

Deprecated: This field is deprecated and is going to be removed in the next apiVersion. Please see https://github.com/kubernetes-sigs/cluster-api/issues/10722 for more details.

unhealthyRange string

unhealthyRange specifies the range of unhealthy machines allowed.
Any further remediation is only allowed if the number of machines selected by "selector" as not healthy
is within the range of "unhealthyRange". Takes precedence over maxUnhealthy.
Eg. "[3-5]" - This means that remediation will be allowed only when:
(a) there are at least 3 unhealthy machines (and)
(b) there are at most 5 unhealthy machines

Deprecated: This field is deprecated and is going to be removed in the next apiVersion. Please see https://github.com/kubernetes-sigs/cluster-api/issues/10722 for more details.

MaxLength: 32
MinLength: 1
Pattern: ^\[[0-9]+-[0-9]+\]$

nodeStartupTimeout Duration

nodeStartupTimeout allows to set the maximum time for MachineHealthCheck
to consider a Machine unhealthy if a corresponding Node isn’t associated
through a Spec.ProviderID field.

The duration set in this field is compared to the greatest of:
- Cluster’s infrastructure ready condition timestamp (if and when available)
- Control Plane’s initialized condition timestamp (if and when available)
- Machine’s infrastructure ready condition timestamp (if and when available)
- Machine’s metadata creation timestamp

Defaults to 10 minutes.
If you wish to disable this feature, set the value explicitly to 0.

remediationTemplate ObjectReference

remediationTemplate is a reference to a remediation template
provided by an infrastructure provider.

This field is completely optional, when filled, the MachineHealthCheck controller
creates a new object from the template referenced and hands off remediation of the machine to
a controller that lives outside of Cluster API.

MachineHealthCheckStatus

MachineHealthCheckStatus defines the observed state of MachineHealthCheck.

Appears In:
Field Description Default Validation

expectedMachines integer

expectedMachines is the total number of machines counted by this machine health check

Minimum: 0

currentHealthy integer

currentHealthy is the total number of healthy machines counted by this machine health check

Minimum: 0

remediationsAllowed integer

remediationsAllowed is the number of further remediations allowed by this machine health check before
maxUnhealthy short circuiting will be applied

Minimum: 0

observedGeneration integer

observedGeneration is the latest generation observed by the controller.

targets string array

targets shows the current list of machines the machine health check is watching

MaxItems: 10000
items:MaxLength: 253
items:MinLength: 1

conditions Conditions

conditions defines current service state of the MachineHealthCheck.

v1beta2 MachineHealthCheckV1Beta2Status

v1beta2 groups all the fields that will be added or modified in MachineHealthCheck’s status with the V1Beta2 version.

MachineHealthCheckTopology

MachineHealthCheckTopology defines a MachineHealthCheck for a group of machines.

Appears In:
Field Description Default Validation

enable boolean

enable controls if a MachineHealthCheck should be created for the target machines.

If false: No MachineHealthCheck will be created.

If not set(default): A MachineHealthCheck will be created if it is defined here or
in the associated ClusterClass. If no MachineHealthCheck is defined then none will be created.

If true: A MachineHealthCheck is guaranteed to be created. Cluster validation will
block if enable is true and no MachineHealthCheck definition is available.

unhealthyConditions UnhealthyCondition array

unhealthyConditions contains a list of the conditions that determine
whether a node is considered unhealthy. The conditions are combined in a
logical OR, i.e. if any of the conditions is met, the node is unhealthy.

MaxItems: 100

maxUnhealthy IntOrString

maxUnhealthy specifies the maximum number of unhealthy machines allowed.
Any further remediation is only allowed if at most "maxUnhealthy" machines selected by
"selector" are not healthy.

unhealthyRange string

unhealthyRange specifies the range of unhealthy machines allowed.
Any further remediation is only allowed if the number of machines selected by "selector" as not healthy
is within the range of "unhealthyRange". Takes precedence over maxUnhealthy.
Eg. "[3-5]" - This means that remediation will be allowed only when:
(a) there are at least 3 unhealthy machines (and)
(b) there are at most 5 unhealthy machines

MaxLength: 32
MinLength: 1
Pattern: ^\[[0-9]+-[0-9]+\]$

nodeStartupTimeout Duration

nodeStartupTimeout allows to set the maximum time for MachineHealthCheck
to consider a Machine unhealthy if a corresponding Node isn’t associated
through a Spec.ProviderID field.

The duration set in this field is compared to the greatest of:
- Cluster’s infrastructure ready condition timestamp (if and when available)
- Control Plane’s initialized condition timestamp (if and when available)
- Machine’s infrastructure ready condition timestamp (if and when available)
- Machine’s metadata creation timestamp

Defaults to 10 minutes.
If you wish to disable this feature, set the value explicitly to 0.

remediationTemplate ObjectReference

remediationTemplate is a reference to a remediation template
provided by an infrastructure provider.

This field is completely optional, when filled, the MachineHealthCheck controller
creates a new object from the template referenced and hands off remediation of the machine to
a controller that lives outside of Cluster API.

MachineHealthCheckV1Beta2Status

MachineHealthCheckV1Beta2Status groups all the fields that will be added or modified in MachineHealthCheck with the V1Beta2 version. See https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/proposals/20240916-improve-status-in-CAPI-resources.md for more context.

Appears In:
Field Description Default Validation

conditions Condition array

conditions represents the observations of a MachineHealthCheck’s current state.
Known condition types are RemediationAllowed, Paused.

MaxItems: 32

MachineNamingStrategy

MachineNamingStrategy allows changing the naming pattern used when creating Machines. Note: InfraMachines & BootstrapConfigs will use the same name as the corresponding Machines.

Appears In:
Field Description Default Validation

template string

template defines the template to use for generating the names of the
Machine objects.
If not defined, it will fallback to {{ .machineSet.name }}-{{ .random }}.
If the generated name string exceeds 63 characters, it will be trimmed to
58 characters and will
get concatenated with a random suffix of length 5.
Length of the template string must not exceed 256 characters.
The template allows the following variables .cluster.name,
.machineSet.name and .random.
The variable .cluster.name retrieves the name of the cluster object
that owns the Machines being created.
The variable .machineSet.name retrieves the name of the MachineSet
object that owns the Machines being created.
The variable .random is substituted with random alphanumeric string,
without vowels, of length 5. This variable is required part of the
template. If not provided, validation will fail.

MaxLength: 256
MinLength: 1

MachineReadinessGate

MachineReadinessGate contains the type of a Machine condition to be used as a readiness gate.

Appears In:
Field Description Default Validation

conditionType string

conditionType refers to a condition with matching type in the Machine’s condition list.
If the conditions doesn’t exist, it will be treated as unknown.
Note: Both Cluster API conditions or conditions added by 3rd party controllers can be used as readiness gates.

MaxLength: 316
MinLength: 1
Pattern: ^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$

polarity ConditionPolarity

polarity of the conditionType specified in this readinessGate.
Valid values are Positive, Negative and omitted.
When omitted, the default behaviour will be Positive.
A positive polarity means that the condition should report a true status under normal conditions.
A negative polarity means that the condition should report a false status under normal conditions.

Enum: [Positive Negative]

MachineRollingUpdateDeployment

Underlying type: struct{MaxUnavailable *k8s.io/apimachinery/pkg/util/intstr.IntOrString "json:\"maxUnavailable,omitempty\""; MaxSurge *k8s.io/apimachinery/pkg/util/intstr.IntOrString "json:\"maxSurge,omitempty\""; DeletePolicy *string "json:\"deletePolicy,omitempty\""}

MachineRollingUpdateDeployment is used to control the desired behavior of rolling update.

Appears In:

MachineSet

MachineSet is the Schema for the machinesets API.

Field Description Default Validation

apiVersion string

cluster.x-k8s.io/v1beta1

kind string

MachineSet

metadata ObjectMeta

Refer to Kubernetes API documentation for fields of metadata.

MinProperties: 1

spec MachineSetSpec

spec is the desired state of MachineSet.

status MachineSetStatus

status is the observed state of MachineSet.

MachineSetSpec

MachineSetSpec defines the desired state of MachineSet.

Appears In:
Field Description Default Validation

clusterName string

clusterName is the name of the Cluster this object belongs to.

MaxLength: 63
MinLength: 1

replicas integer

replicas is the number of desired replicas.
This is a pointer to distinguish between explicit zero and unspecified.

Defaults to:
* if the Kubernetes autoscaler min size and max size annotations are set:
- if it’s a new MachineSet, use min size
- if the replicas field of the old MachineSet is < min size, use min size
- if the replicas field of the old MachineSet is > max size, use max size
- if the replicas field of the old MachineSet is in the (min size, max size) range, keep the value from the oldMS
* otherwise use 1
Note: Defaulting will be run whenever the replicas field is not set:
* A new MachineSet is created with replicas not set.
* On an existing MachineSet the replicas field was first set and is now unset.
Those cases are especially relevant for the following Kubernetes autoscaler use cases:
* A new MachineSet is created and replicas should be managed by the autoscaler
* An existing MachineSet which initially wasn’t controlled by the autoscaler
should be later controlled by the autoscaler

minReadySeconds integer

minReadySeconds is the minimum number of seconds for which a Node for a newly created machine should be ready before considering the replica available.
Defaults to 0 (machine will be considered available as soon as the Node is ready)

deletePolicy string

deletePolicy defines the policy used to identify nodes to delete when downscaling.
Defaults to "Random". Valid values are "Random, "Newest", "Oldest"

Enum: [Random Newest Oldest]

selector LabelSelector

selector is a label query over machines that should match the replica count.
Label keys and values that must match in order to be controlled by this MachineSet.
It must match the machine template’s labels.
More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#label-selectors

template MachineTemplateSpec

template is the object that describes the machine that will be created if
insufficient replicas are detected.
Object references to custom resources are treated as templates.

machineNamingStrategy MachineNamingStrategy

machineNamingStrategy allows changing the naming pattern used when creating Machines.
Note: InfraMachines & BootstrapConfigs will use the same name as the corresponding Machines.

MachineSetStatus

MachineSetStatus defines the observed state of MachineSet.

Appears In:
Field Description Default Validation

selector string

selector is the same as the label selector but in the string format to avoid introspection
by clients. The string will be in the same format as the query-param syntax.
More info about label selectors: http://kubernetes.io/docs/user-guide/labels#label-selectors

MaxLength: 4096
MinLength: 1

replicas integer

replicas is the most recently observed number of replicas.

fullyLabeledReplicas integer

fullyLabeledReplicas is the number of replicas that have labels matching the labels of the machine template of the MachineSet.

Deprecated: This field is deprecated and is going to be removed when support for v1beta1 will be dropped. Please see https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/proposals/20240916-improve-status-in-CAPI-resources.md for more details.

readyReplicas integer

readyReplicas is the number of ready replicas for this MachineSet. A machine is considered ready when the node has been created and is "Ready".

availableReplicas integer

availableReplicas is the number of available replicas (ready for at least minReadySeconds) for this MachineSet.

observedGeneration integer

observedGeneration reflects the generation of the most recently observed MachineSet.

failureReason MachineSetStatusError

failureReason will be set in the event that there is a terminal problem
reconciling the Machine and will contain a succinct value suitable
for machine interpretation.

In the event that there is a terminal problem reconciling the
replicas, both FailureReason and FailureMessage will be set. FailureReason
will be populated with a succinct value suitable for machine
interpretation, while FailureMessage will contain a more verbose
string suitable for logging and human consumption.

These fields should not be set for transitive errors that a
controller faces that are expected to be fixed automatically over
time (like service outages), but instead indicate that something is
fundamentally wrong with the MachineTemplate’s spec or the configuration of
the machine controller, and that manual intervention is required. Examples
of terminal errors would be invalid combinations of settings in the
spec, values that are unsupported by the machine controller, or the
responsible machine controller itself being critically misconfigured.

Any transient errors that occur during the reconciliation of Machines
can be added as events to the MachineSet object and/or logged in the
controller’s output.

Deprecated: This field is deprecated and is going to be removed when support for v1beta1 will be dropped. Please see https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/proposals/20240916-improve-status-in-CAPI-resources.md for more details.

failureMessage string

failureMessage will be set in the event that there is a terminal problem
reconciling the Machine and will contain a more verbose string suitable
for logging and human consumption.

Deprecated: This field is deprecated and is going to be removed when support for v1beta1 will be dropped. Please see https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/proposals/20240916-improve-status-in-CAPI-resources.md for more details.

MaxLength: 10240
MinLength: 1

conditions Conditions

conditions defines current service state of the MachineSet.

v1beta2 MachineSetV1Beta2Status

v1beta2 groups all the fields that will be added or modified in MachineSet’s status with the V1Beta2 version.

MachineSetV1Beta2Status

MachineSetV1Beta2Status groups all the fields that will be added or modified in MachineSetStatus with the V1Beta2 version. See https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/proposals/20240916-improve-status-in-CAPI-resources.md for more context.

Appears In:
Field Description Default Validation

conditions Condition array

conditions represents the observations of a MachineSet’s current state.
Known condition types are MachinesReady, MachinesUpToDate, ScalingUp, ScalingDown, Remediating, Deleting, Paused.

MaxItems: 32

readyReplicas integer

readyReplicas is the number of ready replicas for this MachineSet. A machine is considered ready when Machine’s Ready condition is true.

availableReplicas integer

availableReplicas is the number of available replicas for this MachineSet. A machine is considered available when Machine’s Available condition is true.

upToDateReplicas integer

upToDateReplicas is the number of up-to-date replicas for this MachineSet. A machine is considered up-to-date when Machine’s UpToDate condition is true.

MachineSpec

MachineSpec defines the desired state of Machine.

Appears In:
Field Description Default Validation

clusterName string

clusterName is the name of the Cluster this object belongs to.

MaxLength: 63
MinLength: 1

bootstrap Bootstrap

bootstrap is a reference to a local struct which encapsulates
fields to configure the Machine’s bootstrapping mechanism.

infrastructureRef ObjectReference

infrastructureRef is a required reference to a custom resource
offered by an infrastructure provider.

version string

version defines the desired Kubernetes version.
This field is meant to be optionally used by bootstrap providers.

MaxLength: 256
MinLength: 1

providerID string

providerID is the identification ID of the machine provided by the provider.
This field must match the provider ID as seen on the node object corresponding to this machine.
This field is required by higher level consumers of cluster-api. Example use case is cluster autoscaler
with cluster-api as provider. Clean-up logic in the autoscaler compares machines to nodes to find out
machines at provider which could not get registered as Kubernetes nodes. With cluster-api as a
generic out-of-tree provider for autoscaler, this field is required by autoscaler to be
able to have a provider view of the list of machines. Another list of nodes is queried from the k8s apiserver
and then a comparison is done to find out unregistered machines and are marked for delete.
This field will be set by the actuators and consumed by higher level entities like autoscaler that will
be interfacing with cluster-api as generic provider.

MaxLength: 512
MinLength: 1

failureDomain string

failureDomain is the failure domain the machine will be created in.
Must match a key in the FailureDomains map stored on the cluster object.

MaxLength: 256
MinLength: 1

readinessGates MachineReadinessGate array

readinessGates specifies additional conditions to include when evaluating Machine Ready condition.

This field can be used e.g. by Cluster API control plane providers to extend the semantic of the
Ready condition for the Machine they control, like the kubeadm control provider adding ReadinessGates
for the APIServerPodHealthy, SchedulerPodHealthy conditions, etc.

Another example are external controllers, e.g. responsible to install special software/hardware on the Machines;
they can include the status of those components with a new condition and add this condition to ReadinessGates.

Note
 This field is considered only for computing v1beta2 conditions.
NOTE: In case readinessGates conditions start with the APIServer, ControllerManager, Scheduler prefix, and all those
readiness gates condition are reporting the same message, when computing the Machine’s Ready condition those
readinessGates will be replaced by a single entry reporting "Control plane components: " + message.
This helps to improve readability of conditions bubbling up to the Machine’s owner resource / to the Cluster).

MaxItems: 32

nodeDrainTimeout Duration

nodeDrainTimeout is the total amount of time that the controller will spend on draining a node.
The default value is 0, meaning that the node can be drained without any time limitations.
NOTE: NodeDrainTimeout is different from kubectl drain --timeout

nodeVolumeDetachTimeout Duration

nodeVolumeDetachTimeout is the total amount of time that the controller will spend on waiting for all volumes
to be detached. The default value is 0, meaning that the volumes can be detached without any time limitations.

nodeDeletionTimeout Duration

nodeDeletionTimeout defines how long the controller will attempt to delete the Node that the Machine
hosts after the Machine is marked for deletion. A duration of 0 will retry deletion indefinitely.
Defaults to 10 seconds.

MachineStatus

MachineStatus defines the observed state of Machine.

Appears In:
Field Description Default Validation

nodeRef ObjectReference

nodeRef will point to the corresponding Node if it exists.

nodeInfo NodeSystemInfo

nodeInfo is a set of ids/uuids to uniquely identify the node.
More info: https://kubernetes.io/docs/concepts/nodes/node/#info

lastUpdated Time

lastUpdated identifies when the phase of the Machine last transitioned.

failureReason MachineStatusError

failureReason will be set in the event that there is a terminal problem
reconciling the Machine and will contain a succinct value suitable
for machine interpretation.

This field should not be set for transitive errors that a controller
faces that are expected to be fixed automatically over
time (like service outages), but instead indicate that something is
fundamentally wrong with the Machine’s spec or the configuration of
the controller, and that manual intervention is required. Examples
of terminal errors would be invalid combinations of settings in the
spec, values that are unsupported by the controller, or the
responsible controller itself being critically misconfigured.

Any transient errors that occur during the reconciliation of Machines
can be added as events to the Machine object and/or logged in the
controller’s output.

Deprecated: This field is deprecated and is going to be removed when support for v1beta1 will be dropped. Please see https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/proposals/20240916-improve-status-in-CAPI-resources.md for more details.

failureMessage string

failureMessage will be set in the event that there is a terminal problem
reconciling the Machine and will contain a more verbose string suitable
for logging and human consumption.

This field should not be set for transitive errors that a controller
faces that are expected to be fixed automatically over
time (like service outages), but instead indicate that something is
fundamentally wrong with the Machine’s spec or the configuration of
the controller, and that manual intervention is required. Examples
of terminal errors would be invalid combinations of settings in the
spec, values that are unsupported by the controller, or the
responsible controller itself being critically misconfigured.

Any transient errors that occur during the reconciliation of Machines
can be added as events to the Machine object and/or logged in the
controller’s output.

Deprecated: This field is deprecated and is going to be removed when support for v1beta1 will be dropped. Please see https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/proposals/20240916-improve-status-in-CAPI-resources.md for more details.

MaxLength: 10240
MinLength: 1

addresses MachineAddresses

addresses is a list of addresses assigned to the machine.
This field is copied from the infrastructure provider reference.

phase string

phase represents the current phase of machine actuation.

Enum: [Pending Provisioning Provisioned Running Deleting Deleted Failed Unknown]

certificatesExpiryDate Time

certificatesExpiryDate is the expiry date of the machine certificates.
This value is only set for control plane machines.

bootstrapReady boolean

bootstrapReady is the state of the bootstrap provider.

infrastructureReady boolean

infrastructureReady is the state of the infrastructure provider.

observedGeneration integer

observedGeneration is the latest generation observed by the controller.

conditions Conditions

conditions defines current service state of the Machine.

deletion MachineDeletionStatus

deletion contains information relating to removal of the Machine.
Only present when the Machine has a deletionTimestamp and drain or wait for volume detach started.

v1beta2 MachineV1Beta2Status

v1beta2 groups all the fields that will be added or modified in Machine’s status with the V1Beta2 version.

MachineTemplateSpec

MachineTemplateSpec describes the data needed to create a Machine from a template.

Appears In:
Field Description Default Validation

metadata ObjectMeta

Refer to Kubernetes API documentation for fields of metadata.

spec MachineSpec

spec is the specification of the desired behavior of the machine.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status

MachineV1Beta2Status

MachineV1Beta2Status groups all the fields that will be added or modified in MachineStatus with the V1Beta2 version. See https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/proposals/20240916-improve-status-in-CAPI-resources.md for more context.

Appears In:
Field Description Default Validation

conditions Condition array

conditions represents the observations of a Machine’s current state.
Known condition types are Available, Ready, UpToDate, BootstrapConfigReady, InfrastructureReady, NodeReady,
NodeHealthy, Deleting, Paused.
If a MachineHealthCheck is targeting this machine, also HealthCheckSucceeded, OwnerRemediated conditions are added.
Additionally control plane Machines controlled by KubeadmControlPlane will have following additional conditions:
APIServerPodHealthy, ControllerManagerPodHealthy, SchedulerPodHealthy, EtcdPodHealthy, EtcdMemberHealthy.

MaxItems: 32

NetworkRanges

NetworkRanges represents ranges of network addresses.

Appears In:
Field Description Default Validation

cidrBlocks string array

cidrBlocks is a list of CIDR blocks.

MaxItems: 100
items:MaxLength: 43
items:MinLength: 1

ObjectMeta

ObjectMeta is metadata that all persisted resources must have, which includes all objects users must create. This is a copy of customizable fields from metav1.ObjectMeta.

ObjectMeta is embedded in Machine.Spec, MachineDeployment.Template and MachineSet.Template, which are not top-level Kubernetes objects. Given that metav1.ObjectMeta has lots of special cases and read-only fields which end up in the generated CRD validation, having it as a subset simplifies the API and some issues that can impact user experience.

During the [upgrade to controller-tools@v2](https://github.com/kubernetes-sigs/cluster-api/pull/1054) for v1alpha2, we noticed a failure would occur running Cluster API test suite against the new CRDs, specifically spec.metadata.creationTimestamp in body must be of type string: "null". The investigation showed that controller-tools@v2 behaves differently than its previous version when handling types from [metav1](k8s.io/apimachinery/pkg/apis/meta/v1) package.

In more details, we found that embedded (non-top level) types that embedded metav1.ObjectMeta had validation properties, including for creationTimestamp (metav1.Time). The metav1.Time type specifies a custom json marshaller that, when IsZero() is true, returns null which breaks validation because the field isn’t marked as nullable.

In future versions, controller-tools@v2 might allow overriding the type and validation for embedded types. When that happens, this hack should be revisited.

Appears In:
Field Description Default Validation

labels object (keys:string, values:string)

labels is a map of string keys and values that can be used to organize and categorize
(scope and select) objects. May match selectors of replication controllers
and services.
More info: http://kubernetes.io/docs/user-guide/labels

annotations object (keys:string, values:string)

annotations is an unstructured key value map stored with a resource that may be
set by external tools to store and retrieve arbitrary metadata. They are not
queryable and should be preserved when modifying objects.
More info: http://kubernetes.io/docs/user-guide/annotations

PatchDefinition

PatchDefinition defines a patch which is applied to customize the referenced templates.

Appears In:
Field Description Default Validation

selector PatchSelector

selector defines on which templates the patch should be applied.

jsonPatches JSONPatch array

jsonPatches defines the patches which should be applied on the templates
matching the selector.
Note: Patches will be applied in the order of the array.

MaxItems: 100

PatchSelector

PatchSelector defines on which templates the patch should be applied. Note: Matching on APIVersion and Kind is mandatory, to enforce that the patches are written for the correct version. The version of the references in the ClusterClass may be automatically updated during reconciliation if there is a newer version for the same contract. Note: The results of selection based on the individual fields are ANDed.

Appears In:
Field Description Default Validation

apiVersion string

apiVersion filters templates by apiVersion.

MaxLength: 512
MinLength: 1

kind string

kind filters templates by kind.

MaxLength: 256
MinLength: 1

matchResources PatchSelectorMatch

matchResources selects templates based on where they are referenced.

PatchSelectorMatch

PatchSelectorMatch selects templates based on where they are referenced. Note: The selector must match at least one template. Note: The results of selection based on the individual fields are ORed.

Appears In:
Field Description Default Validation

controlPlane boolean

controlPlane selects templates referenced in .spec.ControlPlane.
Note: this will match the controlPlane and also the controlPlane
machineInfrastructure (depending on the kind and apiVersion).

infrastructureCluster boolean

infrastructureCluster selects templates referenced in .spec.infrastructure.

machineDeploymentClass PatchSelectorMatchMachineDeploymentClass

machineDeploymentClass selects templates referenced in specific MachineDeploymentClasses in
.spec.workers.machineDeployments.

PatchSelectorMatchMachineDeploymentClass

PatchSelectorMatchMachineDeploymentClass selects templates referenced in specific MachineDeploymentClasses in .spec.workers.machineDeployments.

Appears In:
Field Description Default Validation

names string array

names selects templates by class names.

MaxItems: 100
items:MaxLength: 256
items:MinLength: 1

RemediationStrategy

Underlying type: struct{MaxInFlight *k8s.io/apimachinery/pkg/util/intstr.IntOrString "json:\"maxInFlight,omitempty\""}

RemediationStrategy allows to define how the MachineSet can control scaling operations.

Appears In:

Topology

Topology encapsulates the information of the managed resources.

Appears In:
Field Description Default Validation

class string

class is the name of the ClusterClass object to create the topology.

MaxLength: 253
MinLength: 1

classNamespace string

classNamespace is the namespace of the ClusterClass that should be used for the topology.
If classNamespace is empty or not set, it is defaulted to the namespace of the Cluster object.
classNamespace must be a valid namespace name and because of that be at most 63 characters in length
and it must consist only of lower case alphanumeric characters or hyphens (-), and must start
and end with an alphanumeric character.

MaxLength: 63
MinLength: 1
Pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?$

version string

version is the Kubernetes version of the cluster.

MaxLength: 256
MinLength: 1

rolloutAfter Time

rolloutAfter performs a rollout of the entire cluster one component at a time,
control plane first and then machine deployments.

Deprecated: This field has no function and is going to be removed in the next apiVersion.

controlPlane ControlPlaneTopology

controlPlane describes the cluster control plane.

workers WorkersTopology

workers encapsulates the different constructs that form the worker nodes
for the cluster.

variables ClusterVariable array

variables can be used to customize the Cluster through
patches. They must comply to the corresponding
VariableClasses defined in the ClusterClass.

MaxItems: 1000

UnhealthyCondition

UnhealthyCondition represents a Node condition type and value with a timeout specified as a duration. When the named condition has been in the given status for at least the timeout value, a node is considered unhealthy.

Appears In:
Field Description Default Validation

type NodeConditionType

type of Node condition

MinLength: 1
Type: string

status ConditionStatus

status of the condition, one of True, False, Unknown.

MinLength: 1
Type: string

timeout Duration

timeout is the duration that a node must be in a given status for,
after which the node is considered unhealthy.
For example, with a value of "1h", the node must match the status
for at least 1 hour before being considered unhealthy.

VariableSchema

VariableSchema defines the schema of a variable.

Appears In:
Field Description Default Validation

openAPIV3Schema JSONSchemaProps

openAPIV3Schema defines the schema of a variable via OpenAPI v3
schema. The schema is a subset of the schema used in
Kubernetes CRDs.

WorkersClass

WorkersClass is a collection of deployment classes.

Appears In:
Field Description Default Validation

machineDeployments MachineDeploymentClass array

machineDeployments is a list of machine deployment classes that can be used to create
a set of worker nodes.

MaxItems: 100

WorkersStatus

WorkersStatus groups all the observations about workers current state.

Appears In:
Field Description Default Validation

desiredReplicas integer

desiredReplicas is the total number of desired worker machines in this cluster.

replicas integer

replicas is the total number of worker machines in this cluster.
NOTE: replicas also includes machines still being provisioned or being deleted.

upToDateReplicas integer

upToDateReplicas is the number of up-to-date worker machines in this cluster. A machine is considered up-to-date when Machine’s UpToDate condition is true.

readyReplicas integer

readyReplicas is the total number of ready worker machines in this cluster. A machine is considered ready when Machine’s Ready condition is true.

availableReplicas integer

availableReplicas is the total number of available worker machines in this cluster. A machine is considered available when Machine’s Available condition is true.

WorkersTopology

WorkersTopology represents the different sets of worker nodes in the cluster.

Appears In:
Field Description Default Validation

machineDeployments MachineDeploymentTopology array

machineDeployments is a list of machine deployments in the cluster.

MaxItems: 2000

cluster.x-k8s.io/v1beta2

Package v1beta2 contains API Schema definitions for the cluster v1beta2 API group

Resource Types

APIEndpoint

APIEndpoint represents a reachable Kubernetes API endpoint.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

host string

host is the hostname on which the API server is serving.

MaxLength: 512
MinLength: 1

port integer

port is the port on which the API server is serving.

Maximum: 65535
Minimum: 1

Bootstrap

Bootstrap encapsulates fields to configure the Machine’s bootstrapping mechanism.

Appears In:
Field Description Default Validation

configRef ContractVersionedObjectReference

configRef is a reference to a bootstrap provider-specific resource
that holds configuration details. The reference is optional to
allow users/operators to specify Bootstrap.DataSecretName without
the need of a controller.

dataSecretName string

dataSecretName is the name of the secret that stores the bootstrap data script.
If nil, the Machine should remain in the Pending state.

MaxLength: 253
MinLength: 0

Cluster

Cluster is the Schema for the clusters API.

Field Description Default Validation

apiVersion string

cluster.x-k8s.io/v1beta2

kind string

Cluster

metadata ObjectMeta

Refer to Kubernetes API documentation for fields of metadata.

MinProperties: 1

spec ClusterSpec

spec is the desired state of Cluster.

MinProperties: 1

status ClusterStatus

status is the observed state of Cluster.

MinProperties: 1

ClusterAvailabilityGate

ClusterAvailabilityGate contains the type of a Cluster condition to be used as availability gate.

Appears In:
Field Description Default Validation

conditionType string

conditionType refers to a condition with matching type in the Cluster’s condition list.
If the conditions doesn’t exist, it will be treated as unknown.
Note: Both Cluster API conditions or conditions added by 3rd party controllers can be used as availability gates.

MaxLength: 316
MinLength: 1
Pattern: ^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$

polarity ConditionPolarity

polarity of the conditionType specified in this availabilityGate.
Valid values are Positive, Negative and omitted.
When omitted, the default behaviour will be Positive.
A positive polarity means that the condition should report a true status under normal conditions.
A negative polarity means that the condition should report a false status under normal conditions.

Enum: [Positive Negative]

ClusterClass

ClusterClass is a template which can be used to create managed topologies. NOTE: This CRD can only be used if the ClusterTopology feature gate is enabled.

Field Description Default Validation

apiVersion string

cluster.x-k8s.io/v1beta2

kind string

ClusterClass

metadata ObjectMeta

Refer to Kubernetes API documentation for fields of metadata.

MinProperties: 1

spec ClusterClassSpec

spec is the desired state of ClusterClass.

status ClusterClassStatus

status is the observed state of ClusterClass.

MinProperties: 1

ClusterClassDeprecatedStatus

ClusterClassDeprecatedStatus groups all the status fields that are deprecated and will be removed in a future version. See https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/proposals/20240916-improve-status-in-CAPI-resources.md for more context.

Appears In:
Field Description Default Validation

v1beta1 ClusterClassV1Beta1DeprecatedStatus

v1beta1 groups all the status fields that are deprecated and will be removed when support for v1beta1 will be dropped.

ClusterClassPatch

ClusterClassPatch defines a patch which is applied to customize the referenced templates.

Appears In:
Field Description Default Validation

name string

name of the patch.

MaxLength: 256
MinLength: 1

description string

description is a human-readable description of this patch.

MaxLength: 1024
MinLength: 1

enabledIf string

enabledIf is a Go template to be used to calculate if a patch should be enabled.
It can reference variables defined in .spec.variables and builtin variables.
The patch will be enabled if the template evaluates to true, otherwise it will
be disabled.
If EnabledIf is not set, the patch will be enabled per default.

MaxLength: 256
MinLength: 1

definitions PatchDefinition array

definitions define inline patches.
Note: Patches will be applied in the order of the array.
Note: Exactly one of Definitions or External must be set.

MaxItems: 100

external ExternalPatchDefinition

external defines an external patch.
Note: Exactly one of Definitions or External must be set.

ClusterClassRef

ClusterClassRef is the ref to the ClusterClass that should be used for the topology.

Appears In:
Field Description Default Validation

name string

name is the name of the ClusterClass that should be used for the topology.
name must be a valid ClusterClass name and because of that be at most 253 characters in length
and it must consist only of lower case alphanumeric characters, hyphens (-) and periods (.), and must start
and end with an alphanumeric character.

MaxLength: 253
MinLength: 1
Pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$

namespace string

namespace is the namespace of the ClusterClass that should be used for the topology.
If namespace is empty or not set, it is defaulted to the namespace of the Cluster object.
namespace must be a valid namespace name and because of that be at most 63 characters in length
and it must consist only of lower case alphanumeric characters or hyphens (-), and must start
and end with an alphanumeric character.

MaxLength: 63
MinLength: 1
Pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?$

ClusterClassSpec

ClusterClassSpec describes the desired state of the ClusterClass.

Appears In:
Field Description Default Validation

availabilityGates ClusterAvailabilityGate array

availabilityGates specifies additional conditions to include when evaluating Cluster Available condition.

Note
 If a Cluster is using this ClusterClass, and this Cluster defines a custom list of availabilityGates,
such list overrides availabilityGates defined in this field.

MaxItems: 32
MinItems: 1

infrastructure InfrastructureClass

infrastructure is a reference to a local struct that holds the details
for provisioning the infrastructure cluster for the Cluster.

controlPlane ControlPlaneClass

controlPlane is a reference to a local struct that holds the details
for provisioning the Control Plane for the Cluster.

workers WorkersClass

workers describes the worker nodes for the cluster.
It is a collection of node types which can be used to create
the worker nodes of the cluster.

MinProperties: 1

variables ClusterClassVariable array

variables defines the variables which can be configured
in the Cluster topology and are then used in patches.

MaxItems: 1000
MinItems: 1

patches ClusterClassPatch array

patches defines the patches which are applied to customize
referenced templates of a ClusterClass.
Note: Patches will be applied in the order of the array.

MaxItems: 1000
MinItems: 1

upgrade ClusterClassUpgrade

upgrade defines the upgrade configuration for clusters using this ClusterClass.

MinProperties: 1

kubernetesVersions string array

kubernetesVersions is the list of Kubernetes versions that can be
used for clusters using this ClusterClass.
The list of version must be ordered from the older to the newer version, and there should be
at least one version for every minor in between the first and the last version.

MaxItems: 100
MinItems: 1
items:MaxLength: 256
items:MinLength: 1

ClusterClassStatus

ClusterClassStatus defines the observed state of the ClusterClass.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

conditions Condition array

conditions represents the observations of a ClusterClass’s current state.
Known condition types are VariablesReady, RefVersionsUpToDate, Paused.

MaxItems: 32

variables ClusterClassStatusVariable array

variables is a list of ClusterClassStatusVariable that are defined for the ClusterClass.

MaxItems: 1000

observedGeneration integer

observedGeneration is the latest generation observed by the controller.

Minimum: 1

deprecated ClusterClassDeprecatedStatus

deprecated groups all the status fields that are deprecated and will be removed when all the nested field are removed.

ClusterClassStatusVariable

ClusterClassStatusVariable defines a variable which appears in the status of a ClusterClass.

Appears In:
Field Description Default Validation

name string

name is the name of the variable.

MaxLength: 256
MinLength: 1

definitionsConflict boolean

definitionsConflict specifies whether or not there are conflicting definitions for a single variable name.

definitions ClusterClassStatusVariableDefinition array

definitions is a list of definitions for a variable.

MaxItems: 100
MinItems: 1

ClusterClassStatusVariableDefinition

ClusterClassStatusVariableDefinition defines a variable which appears in the status of a ClusterClass.

Appears In:
Field Description Default Validation

from string

from specifies the origin of the variable definition.
This will be inline for variables defined in the ClusterClass or the name of a patch defined in the ClusterClass
for variables discovered from a DiscoverVariables runtime extensions.

MaxLength: 256
MinLength: 1

required boolean

required specifies if the variable is required.
Note: this applies to the variable as a whole and thus the
top-level object defined in the schema. If nested fields are
required, this will be specified inside the schema.

deprecatedV1Beta1Metadata ClusterClassVariableMetadata

deprecatedV1Beta1Metadata is the metadata of a variable.
It can be used to add additional data for higher level tools to
a ClusterClassVariable.

Deprecated: This field is deprecated and will be removed when support for v1beta1 will be dropped. Please use XMetadata in JSONSchemaProps instead.

MinProperties: 1

schema VariableSchema

schema defines the schema of the variable.

ClusterClassTemplateReference

ClusterClassTemplateReference is a reference to a ClusterClass template.

Appears In:
Field Description Default Validation

kind string

kind of the template.
kind must consist of alphanumeric characters or '-', start with an alphabetic character, and end with an alphanumeric character.

MaxLength: 63
MinLength: 1
Pattern: ^[a-zA-Z]([-a-zA-Z0-9]*[a-zA-Z0-9])?$

name string

name of the template.
name must consist of lower case alphanumeric characters, '-' or '.', and must start and end with an alphanumeric character.

MaxLength: 253
MinLength: 1
Pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$

apiVersion string

apiVersion of the template.
apiVersion must be fully qualified domain name followed by / and a version.

MaxLength: 317
MinLength: 1
Pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*\/[a-z]([-a-z0-9]*[a-z0-9])?$

ClusterClassUpgrade

ClusterClassUpgrade defines the upgrade configuration for clusters using the ClusterClass.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

external ClusterClassUpgradeExternal

external defines external runtime extensions for upgrade operations.

MinProperties: 1

ClusterClassUpgradeExternal

ClusterClassUpgradeExternal defines external runtime extensions for upgrade operations.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

generateUpgradePlanExtension string

generateUpgradePlanExtension references an extension which is called to generate upgrade plan.

MaxLength: 512
MinLength: 1

ClusterClassV1Beta1DeprecatedStatus

ClusterClassV1Beta1DeprecatedStatus groups all the status fields that are deprecated and will be removed when support for v1beta1 will be dropped. See https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/proposals/20240916-improve-status-in-CAPI-resources.md for more context.

Appears In:
Field Description Default Validation

conditions Conditions

conditions defines current observed state of the ClusterClass.

Deprecated: This field is deprecated and is going to be removed when support for v1beta1 will be dropped. Please see https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/proposals/20240916-improve-status-in-CAPI-resources.md for more details.

ClusterClassVariable

ClusterClassVariable defines a variable which can be configured in the Cluster topology and used in patches.

Appears In:
Field Description Default Validation

name string

name of the variable.

MaxLength: 256
MinLength: 1

required boolean

required specifies if the variable is required.
Note: this applies to the variable as a whole and thus the
top-level object defined in the schema. If nested fields are
required, this will be specified inside the schema.

deprecatedV1Beta1Metadata ClusterClassVariableMetadata

deprecatedV1Beta1Metadata is the metadata of a variable.
It can be used to add additional data for higher level tools to
a ClusterClassVariable.

Deprecated: This field is deprecated and will be removed when support for v1beta1 will be dropped. Please use XMetadata in JSONSchemaProps instead.

MinProperties: 1

schema VariableSchema

schema defines the schema of the variable.

ClusterClassVariableMetadata

ClusterClassVariableMetadata is the metadata of a variable. It can be used to add additional data for higher level tools to a ClusterClassVariable.

Deprecated: This struct is deprecated and is going to be removed in the next apiVersion.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

labels object (keys:string, values:string)

labels is a map of string keys and values that can be used to organize and categorize
(scope and select) variables.

annotations object (keys:string, values:string)

annotations is an unstructured key value map that can be used to store and
retrieve arbitrary metadata.
They are not queryable.

ClusterControlPlaneStatus

ClusterControlPlaneStatus groups all the observations about control plane current state.

Appears In:
Field Description Default Validation

desiredReplicas integer

desiredReplicas is the total number of desired control plane machines in this cluster.

replicas integer

replicas is the total number of control plane machines in this cluster.
NOTE: replicas also includes machines still being provisioned or being deleted.

upToDateReplicas integer

upToDateReplicas is the number of up-to-date control plane machines in this cluster. A machine is considered up-to-date when Machine’s UpToDate condition is true.

readyReplicas integer

readyReplicas is the total number of ready control plane machines in this cluster. A machine is considered ready when Machine’s Ready condition is true.

availableReplicas integer

availableReplicas is the total number of available control plane machines in this cluster. A machine is considered available when Machine’s Available condition is true.

ClusterDeprecatedStatus

ClusterDeprecatedStatus groups all the status fields that are deprecated and will be removed in a future version. See https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/proposals/20240916-improve-status-in-CAPI-resources.md for more context.

Appears In:
Field Description Default Validation

v1beta1 ClusterV1Beta1DeprecatedStatus

v1beta1 groups all the status fields that are deprecated and will be removed when support for v1beta1 will be dropped.

ClusterInitializationStatus

ClusterInitializationStatus provides observations of the Cluster initialization process. NOTE: Fields in this struct are part of the Cluster API contract and are used to orchestrate initial Cluster provisioning.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

infrastructureProvisioned boolean

infrastructureProvisioned is true when the infrastructure provider reports that Cluster’s infrastructure is fully provisioned.
NOTE: this field is part of the Cluster API contract, and it is used to orchestrate provisioning.
The value of this field is never updated after provisioning is completed.

controlPlaneInitialized boolean

controlPlaneInitialized denotes when the control plane is functional enough to accept requests.
This information is usually used as a signal for starting all the provisioning operations that depends on
a functional API server, but do not require a full HA control plane to exists, like e.g. join worker Machines,
install core addons like CNI, CPI, CSI etc.
NOTE: this field is part of the Cluster API contract, and it is used to orchestrate provisioning.
The value of this field is never updated after initialization is completed.

ClusterNetwork

ClusterNetwork specifies the different networking parameters for a cluster.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

apiServerPort integer

apiServerPort specifies the port the API Server should bind to.
Defaults to 6443.

Maximum: 65535
Minimum: 1

services NetworkRanges

services is the network ranges from which service VIPs are allocated.

pods NetworkRanges

pods is the network ranges from which Pod networks are allocated.

serviceDomain string

serviceDomain is the domain name for services.

MaxLength: 253
MinLength: 1

ClusterSpec

ClusterSpec defines the desired state of Cluster.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

paused boolean

paused can be used to prevent controllers from processing the Cluster and all its associated objects.

clusterNetwork ClusterNetwork

clusterNetwork represents the cluster network configuration.

MinProperties: 1

controlPlaneEndpoint APIEndpoint

controlPlaneEndpoint represents the endpoint used to communicate with the control plane.

MinProperties: 1

controlPlaneRef ContractVersionedObjectReference

controlPlaneRef is an optional reference to a provider-specific resource that holds
the details for provisioning the Control Plane for a Cluster.

infrastructureRef ContractVersionedObjectReference

infrastructureRef is a reference to a provider-specific resource that holds the details
for provisioning infrastructure for a cluster in said provider.

topology Topology

topology encapsulates the topology for the cluster.
NOTE: It is required to enable the ClusterTopology
feature gate flag to activate managed topologies support;
this feature is highly experimental, and parts of it might still be not implemented.

availabilityGates ClusterAvailabilityGate array

availabilityGates specifies additional conditions to include when evaluating Cluster Available condition.

If this field is not defined and the Cluster implements a managed topology, availabilityGates
from the corresponding ClusterClass will be used, if any.

MaxItems: 32
MinItems: 1

ClusterStatus

ClusterStatus defines the observed state of Cluster.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

conditions Condition array

conditions represents the observations of a Cluster’s current state.
Known condition types are Available, InfrastructureReady, ControlPlaneInitialized, ControlPlaneAvailable, WorkersAvailable, MachinesReady
MachinesUpToDate, RemoteConnectionProbe, ScalingUp, ScalingDown, Remediating, Deleting, Paused.
Additionally, a TopologyReconciled condition will be added in case the Cluster is referencing a ClusterClass / defining a managed Topology.

MaxItems: 32

initialization ClusterInitializationStatus

initialization provides observations of the Cluster initialization process.
NOTE: Fields in this struct are part of the Cluster API contract and are used to orchestrate initial Cluster provisioning.

MinProperties: 1

controlPlane ClusterControlPlaneStatus

controlPlane groups all the observations about Cluster’s ControlPlane current state.

workers WorkersStatus

workers groups all the observations about Cluster’s Workers current state.

failureDomains FailureDomain array

failureDomains is a slice of failure domain objects synced from the infrastructure provider.

MaxItems: 100
MinItems: 1

phase string

phase represents the current phase of cluster actuation.

Enum: [Pending Provisioning Provisioned Deleting Failed Unknown]

observedGeneration integer

observedGeneration is the latest generation observed by the controller.

Minimum: 1

deprecated ClusterDeprecatedStatus

deprecated groups all the status fields that are deprecated and will be removed when all the nested field are removed.

ClusterV1Beta1DeprecatedStatus

ClusterV1Beta1DeprecatedStatus groups all the status fields that are deprecated and will be removed when support for v1beta1 will be dropped. See https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/proposals/20240916-improve-status-in-CAPI-resources.md for more context.

Appears In:
Field Description Default Validation

conditions Conditions

conditions defines current service state of the cluster.

Deprecated: This field is deprecated and is going to be removed when support for v1beta1 will be dropped. Please see https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/proposals/20240916-improve-status-in-CAPI-resources.md for more details.

failureReason ClusterStatusError

failureReason indicates that there is a fatal problem reconciling the
state, and will be set to a token value suitable for
programmatic interpretation.

Deprecated: This field is deprecated and is going to be removed when support for v1beta1 will be dropped. Please see https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/proposals/20240916-improve-status-in-CAPI-resources.md for more details.

failureMessage string

failureMessage indicates that there is a fatal problem reconciling the
state, and will be set to a descriptive error message.

Deprecated: This field is deprecated and is going to be removed when support for v1beta1 will be dropped. Please see https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/proposals/20240916-improve-status-in-CAPI-resources.md for more details.

MaxLength: 10240
MinLength: 1

ClusterVariable

ClusterVariable can be used to customize the Cluster through patches. Each ClusterVariable is associated with a Variable definition in the ClusterClass status variables.

Appears In:
Field Description Default Validation

name string

name of the variable.

MaxLength: 256
MinLength: 1

value JSON

value of the variable.
Note: the value will be validated against the schema of the corresponding ClusterClassVariable
from the ClusterClass.
Note: We have to use apiextensionsv1.JSON instead of a custom JSON type, because controller-tools has a
hard-coded schema for apiextensionsv1.JSON which cannot be produced by another type via controller-tools,
i.e. it is not possible to have no type field.
Ref: https://github.com/kubernetes-sigs/controller-tools/blob/d0e03a142d0ecdd5491593e941ee1d6b5d91dba6/pkg/crd/known_types.go#L106-L111

Condition

Condition defines an observation of a Cluster API resource operational state.

Appears In:
Field Description Default Validation

type ConditionType

type of condition in CamelCase or in foo.example.com/CamelCase.
Many .condition.type values are consistent across resources like Available, but because arbitrary conditions
can be useful (see .node.status.conditions), the ability to deconflict is important.

MaxLength: 256
MinLength: 1

status ConditionStatus

status of the condition, one of True, False, Unknown.

severity ConditionSeverity

severity provides an explicit classification of Reason code, so the users or machines can immediately
understand the current situation and act accordingly.
The Severity field MUST be set only when Status=False.

MaxLength: 32

lastTransitionTime Time

lastTransitionTime is the last time the condition transitioned from one status to another.
This should be when the underlying condition changed. If that is not known, then using the time when
the API field changed is acceptable.

reason string

reason is the reason for the condition’s last transition in CamelCase.
The specific API may choose whether or not this field is considered a guaranteed API.
This field may be empty.

MaxLength: 256
MinLength: 1

message string

message is a human readable message indicating details about the transition.
This field may be empty.

MaxLength: 10240
MinLength: 1

ConditionPolarity

Underlying type: string

ConditionPolarity defines the polarity for a metav1.Condition.

Validation:

  • Enum: [Positive Negative]

Appears In:

ConditionSeverity

Underlying type: string

ConditionSeverity expresses the severity of a Condition Type failing.

Validation:

  • MaxLength: 32

Appears In:

ConditionType

Underlying type: string

ConditionType is a valid value for Condition.Type.

Validation:

  • MaxLength: 256

  • MinLength: 1

Appears In:

Conditions

Underlying type: Condition

Conditions provide observations of the operational state of a Cluster API resource.

Appears In:
Field Description Default Validation

type ConditionType

type of condition in CamelCase or in foo.example.com/CamelCase.
Many .condition.type values are consistent across resources like Available, but because arbitrary conditions
can be useful (see .node.status.conditions), the ability to deconflict is important.

MaxLength: 256
MinLength: 1

status ConditionStatus

status of the condition, one of True, False, Unknown.

severity ConditionSeverity

severity provides an explicit classification of Reason code, so the users or machines can immediately
understand the current situation and act accordingly.
The Severity field MUST be set only when Status=False.

MaxLength: 32

lastTransitionTime Time

lastTransitionTime is the last time the condition transitioned from one status to another.
This should be when the underlying condition changed. If that is not known, then using the time when
the API field changed is acceptable.

reason string

reason is the reason for the condition’s last transition in CamelCase.
The specific API may choose whether or not this field is considered a guaranteed API.
This field may be empty.

MaxLength: 256
MinLength: 1

message string

message is a human readable message indicating details about the transition.
This field may be empty.

MaxLength: 10240
MinLength: 1

ContractVersionedObjectReference

ContractVersionedObjectReference is a reference to a resource for which the version is inferred from contract labels.

Appears In:
Field Description Default Validation

kind string

kind of the resource being referenced.
kind must consist of alphanumeric characters or '-', start with an alphabetic character, and end with an alphanumeric character.

MaxLength: 63
MinLength: 1
Pattern: ^[a-zA-Z]([-a-zA-Z0-9]*[a-zA-Z0-9])?$

name string

name of the resource being referenced.
name must consist of lower case alphanumeric characters, '-' or '.', and must start and end with an alphanumeric character.

MaxLength: 253
MinLength: 1
Pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$

apiGroup string

apiGroup is the group of the resource being referenced.
apiGroup must be fully qualified domain name.
The corresponding version for this reference will be looked up from the contract
labels of the corresponding CRD of the resource being referenced.

MaxLength: 253
MinLength: 1
Pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$

ControlPlaneClass

ControlPlaneClass defines the class for the control plane.

Appears In:
Field Description Default Validation

metadata ObjectMeta

Refer to Kubernetes API documentation for fields of metadata.

MinProperties: 1

templateRef ClusterClassTemplateReference

templateRef contains the reference to a provider-specific control plane template.

machineInfrastructure ControlPlaneClassMachineInfrastructureTemplate

machineInfrastructure defines the metadata and infrastructure information
for control plane machines.

This field is supported if and only if the control plane provider template
referenced above is Machine based and supports setting replicas.

healthCheck ControlPlaneClassHealthCheck

healthCheck defines a MachineHealthCheck for this ControlPlaneClass.
This field is supported if and only if the ControlPlane provider template
referenced above is Machine based and supports setting replicas.

MinProperties: 1

naming ControlPlaneClassNamingSpec

naming allows changing the naming pattern used when creating the control plane provider object.

MinProperties: 1

deletion ControlPlaneClassMachineDeletionSpec

deletion contains configuration options for Machine deletion.

MinProperties: 1

readinessGates MachineReadinessGate array

readinessGates specifies additional conditions to include when evaluating Machine Ready condition.

This field can be used e.g. to instruct the machine controller to include in the computation for Machine’s ready
computation a condition, managed by an external controllers, reporting the status of special software/hardware installed on the Machine.

Note
 If a Cluster defines a custom list of readinessGates for the control plane,
such list overrides readinessGates defined in this field.
NOTE: Specific control plane provider implementations might automatically extend the list of readinessGates;
e.g. the kubeadm control provider adds ReadinessGates for the APIServerPodHealthy, SchedulerPodHealthy conditions, etc.

MaxItems: 32
MinItems: 1

ControlPlaneClassHealthCheck

ControlPlaneClassHealthCheck defines a MachineHealthCheck for control plane machines.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

checks ControlPlaneClassHealthCheckChecks

checks are the checks that are used to evaluate if a Machine is healthy.

Independent of this configuration the MachineHealthCheck controller will always
flag Machines with cluster.x-k8s.io/remediate-machine annotation and
Machines with deleted Nodes as unhealthy.

Furthermore, if checks.nodeStartupTimeoutSeconds is not set it
is defaulted to 10 minutes and evaluated accordingly.

MinProperties: 1

remediation ControlPlaneClassHealthCheckRemediation

remediation configures if and how remediations are triggered if a Machine is unhealthy.

If remediation or remediation.triggerIf is not set,
remediation will always be triggered for unhealthy Machines.

If remediation or remediation.templateRef is not set,
the OwnerRemediated condition will be set on unhealthy Machines to trigger remediation via
the owner of the Machines, for example a MachineSet or a KubeadmControlPlane.

MinProperties: 1

ControlPlaneClassHealthCheckChecks

ControlPlaneClassHealthCheckChecks are the checks that are used to evaluate if a control plane Machine is healthy.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

nodeStartupTimeoutSeconds integer

nodeStartupTimeoutSeconds allows to set the maximum time for MachineHealthCheck
to consider a Machine unhealthy if a corresponding Node isn’t associated
through a Spec.ProviderID field.

The duration set in this field is compared to the greatest of:
- Cluster’s infrastructure ready condition timestamp (if and when available)
- Control Plane’s initialized condition timestamp (if and when available)
- Machine’s infrastructure ready condition timestamp (if and when available)
- Machine’s metadata creation timestamp

Defaults to 10 minutes.
If you wish to disable this feature, set the value explicitly to 0.

Minimum: 0

unhealthyNodeConditions UnhealthyNodeCondition array

unhealthyNodeConditions contains a list of conditions that determine
whether a node is considered unhealthy. The conditions are combined in a
logical OR, i.e. if any of the conditions is met, the node is unhealthy.

MaxItems: 100
MinItems: 1

unhealthyMachineConditions UnhealthyMachineCondition array

unhealthyMachineConditions contains a list of the machine conditions that determine
whether a machine is considered unhealthy. The conditions are combined in a
logical OR, i.e. if any of the conditions is met, the machine is unhealthy.

MaxItems: 100
MinItems: 1

ControlPlaneClassHealthCheckRemediation

ControlPlaneClassHealthCheckRemediation configures if and how remediations are triggered if a control plane Machine is unhealthy.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

triggerIf ControlPlaneClassHealthCheckRemediationTriggerIf

triggerIf configures if remediations are triggered.
If this field is not set, remediations are always triggered.

MinProperties: 1

templateRef MachineHealthCheckRemediationTemplateReference

templateRef is a reference to a remediation template
provided by an infrastructure provider.

This field is completely optional, when filled, the MachineHealthCheck controller
creates a new object from the template referenced and hands off remediation of the machine to
a controller that lives outside of Cluster API.

ControlPlaneClassHealthCheckRemediationTriggerIf

ControlPlaneClassHealthCheckRemediationTriggerIf configures if remediations are triggered.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

unhealthyLessThanOrEqualTo IntOrString

unhealthyLessThanOrEqualTo specifies that remediations are only triggered if the number of
unhealthy Machines is less than or equal to the configured value.
unhealthyInRange takes precedence if set.

unhealthyInRange string

unhealthyInRange specifies that remediations are only triggered if the number of
unhealthy Machines is in the configured range.
Takes precedence over unhealthyLessThanOrEqualTo.
Eg. "[3-5]" - This means that remediation will be allowed only when:
(a) there are at least 3 unhealthy Machines (and)
(b) there are at most 5 unhealthy Machines

MaxLength: 32
MinLength: 1
Pattern: ^\[[0-9]+-[0-9]+\]$

ControlPlaneClassMachineDeletionSpec

ControlPlaneClassMachineDeletionSpec contains configuration options for Machine deletion.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

nodeDrainTimeoutSeconds integer

nodeDrainTimeoutSeconds is the total amount of time that the controller will spend on draining a node.
The default value is 0, meaning that the node can be drained without any time limitations.
NOTE: nodeDrainTimeoutSeconds is different from kubectl drain --timeout
NOTE: This value can be overridden while defining a Cluster.Topology.

Minimum: 0

nodeVolumeDetachTimeoutSeconds integer

nodeVolumeDetachTimeoutSeconds is the total amount of time that the controller will spend on waiting for all volumes
to be detached. The default value is 0, meaning that the volumes can be detached without any time limitations.
NOTE: This value can be overridden while defining a Cluster.Topology.

Minimum: 0

nodeDeletionTimeoutSeconds integer

nodeDeletionTimeoutSeconds defines how long the controller will attempt to delete the Node that the Machine
hosts after the Machine is marked for deletion. A duration of 0 will retry deletion indefinitely.
Defaults to 10 seconds.
NOTE: This value can be overridden while defining a Cluster.Topology.

Minimum: 0

ControlPlaneClassMachineInfrastructureTemplate

ControlPlaneClassMachineInfrastructureTemplate defines the template for a MachineInfrastructure of a ControlPlane.

Appears In:
Field Description Default Validation

templateRef ClusterClassTemplateReference

templateRef is a required reference to the template for a MachineInfrastructure of a ControlPlane.

ControlPlaneClassNamingSpec

ControlPlaneClassNamingSpec defines the naming strategy for control plane objects.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

template string

template defines the template to use for generating the name of the ControlPlane object.
If not defined, it will fallback to {{ .cluster.name }}-{{ .random }}.
If the templated string exceeds 63 characters, it will be trimmed to 58 characters and will
get concatenated with a random suffix of length 5.
The templating mechanism provides the following arguments:
* .cluster.name: The name of the cluster object.
* .random: A random alphanumeric string, without vowels, of length 5.

MaxLength: 1024
MinLength: 1

ControlPlaneTopology

ControlPlaneTopology specifies the parameters for the control plane nodes in the cluster.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

metadata ObjectMeta

Refer to Kubernetes API documentation for fields of metadata.

MinProperties: 1

replicas integer

replicas is the number of control plane nodes.
If the value is not set, the ControlPlane object is created without the number of Replicas
and it’s assumed that the control plane controller does not implement support for this field.
When specified against a control plane provider that lacks support for this field, this value will be ignored.

healthCheck ControlPlaneTopologyHealthCheck

healthCheck allows to enable, disable and override control plane health check
configuration from the ClusterClass for this control plane.

MinProperties: 1

deletion ControlPlaneTopologyMachineDeletionSpec

deletion contains configuration options for Machine deletion.

MinProperties: 1

readinessGates MachineReadinessGate array

readinessGates specifies additional conditions to include when evaluating Machine Ready condition.

This field can be used e.g. to instruct the machine controller to include in the computation for Machine’s ready
computation a condition, managed by an external controllers, reporting the status of special software/hardware installed on the Machine.

If this field is not defined, readinessGates from the corresponding ControlPlaneClass will be used, if any.

Note
 Specific control plane provider implementations might automatically extend the list of readinessGates;
e.g. the kubeadm control provider adds ReadinessGates for the APIServerPodHealthy, SchedulerPodHealthy conditions, etc.

MaxItems: 32
MinItems: 1

variables ControlPlaneVariables

variables can be used to customize the ControlPlane through patches.

MinProperties: 1

ControlPlaneTopologyHealthCheck

ControlPlaneTopologyHealthCheck defines a MachineHealthCheck for control plane machines.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

enabled boolean

enabled controls if a MachineHealthCheck should be created for the target machines.

If false: No MachineHealthCheck will be created.

If not set(default): A MachineHealthCheck will be created if it is defined here or
in the associated ClusterClass. If no MachineHealthCheck is defined then none will be created.

If true: A MachineHealthCheck is guaranteed to be created. Cluster validation will
block if enable is true and no MachineHealthCheck definition is available.

checks ControlPlaneTopologyHealthCheckChecks

checks are the checks that are used to evaluate if a Machine is healthy.

If one of checks and remediation fields are set, the system assumes that an healthCheck override is defined,
and as a consequence the checks and remediation fields from Cluster will be used instead of the
corresponding fields in ClusterClass.

Independent of this configuration the MachineHealthCheck controller will always
flag Machines with cluster.x-k8s.io/remediate-machine annotation and
Machines with deleted Nodes as unhealthy.

Furthermore, if checks.nodeStartupTimeoutSeconds is not set it
is defaulted to 10 minutes and evaluated accordingly.

MinProperties: 1

remediation ControlPlaneTopologyHealthCheckRemediation

remediation configures if and how remediations are triggered if a Machine is unhealthy.

If one of checks and remediation fields are set, the system assumes that an healthCheck override is defined,
and as a consequence the checks and remediation fields from cluster will be used instead of the
corresponding fields in ClusterClass.

If an health check override is defined and remediation or remediation.triggerIf is not set,
remediation will always be triggered for unhealthy Machines.

If an health check override is defined and remediation or remediation.templateRef is not set,
the OwnerRemediated condition will be set on unhealthy Machines to trigger remediation via
the owner of the Machines, for example a MachineSet or a KubeadmControlPlane.

MinProperties: 1

ControlPlaneTopologyHealthCheckChecks

ControlPlaneTopologyHealthCheckChecks are the checks that are used to evaluate if a control plane Machine is healthy.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

nodeStartupTimeoutSeconds integer

nodeStartupTimeoutSeconds allows to set the maximum time for MachineHealthCheck
to consider a Machine unhealthy if a corresponding Node isn’t associated
through a Spec.ProviderID field.

The duration set in this field is compared to the greatest of:
- Cluster’s infrastructure ready condition timestamp (if and when available)
- Control Plane’s initialized condition timestamp (if and when available)
- Machine’s infrastructure ready condition timestamp (if and when available)
- Machine’s metadata creation timestamp

Defaults to 10 minutes.
If you wish to disable this feature, set the value explicitly to 0.

Minimum: 0

unhealthyNodeConditions UnhealthyNodeCondition array

unhealthyNodeConditions contains a list of conditions that determine
whether a node is considered unhealthy. The conditions are combined in a
logical OR, i.e. if any of the conditions is met, the node is unhealthy.

MaxItems: 100
MinItems: 1

unhealthyMachineConditions UnhealthyMachineCondition array

unhealthyMachineConditions contains a list of the machine conditions that determine
whether a machine is considered unhealthy. The conditions are combined in a
logical OR, i.e. if any of the conditions is met, the machine is unhealthy.

MaxItems: 100
MinItems: 1

ControlPlaneTopologyHealthCheckRemediation

ControlPlaneTopologyHealthCheckRemediation configures if and how remediations are triggered if a control plane Machine is unhealthy.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

triggerIf ControlPlaneTopologyHealthCheckRemediationTriggerIf

triggerIf configures if remediations are triggered.
If this field is not set, remediations are always triggered.

MinProperties: 1

templateRef MachineHealthCheckRemediationTemplateReference

templateRef is a reference to a remediation template
provided by an infrastructure provider.

This field is completely optional, when filled, the MachineHealthCheck controller
creates a new object from the template referenced and hands off remediation of the machine to
a controller that lives outside of Cluster API.

ControlPlaneTopologyHealthCheckRemediationTriggerIf

ControlPlaneTopologyHealthCheckRemediationTriggerIf configures if remediations are triggered.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

unhealthyLessThanOrEqualTo IntOrString

unhealthyLessThanOrEqualTo specifies that remediations are only triggered if the number of
unhealthy Machines is less than or equal to the configured value.
unhealthyInRange takes precedence if set.

unhealthyInRange string

unhealthyInRange specifies that remediations are only triggered if the number of
unhealthy Machines is in the configured range.
Takes precedence over unhealthyLessThanOrEqualTo.
Eg. "[3-5]" - This means that remediation will be allowed only when:
(a) there are at least 3 unhealthy Machines (and)
(b) there are at most 5 unhealthy Machines

MaxLength: 32
MinLength: 1
Pattern: ^\[[0-9]+-[0-9]+\]$

ControlPlaneTopologyMachineDeletionSpec

ControlPlaneTopologyMachineDeletionSpec contains configuration options for Machine deletion.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

nodeDrainTimeoutSeconds integer

nodeDrainTimeoutSeconds is the total amount of time that the controller will spend on draining a node.
The default value is 0, meaning that the node can be drained without any time limitations.
NOTE: nodeDrainTimeoutSeconds is different from kubectl drain --timeout

Minimum: 0

nodeVolumeDetachTimeoutSeconds integer

nodeVolumeDetachTimeoutSeconds is the total amount of time that the controller will spend on waiting for all volumes
to be detached. The default value is 0, meaning that the volumes can be detached without any time limitations.

Minimum: 0

nodeDeletionTimeoutSeconds integer

nodeDeletionTimeoutSeconds defines how long the controller will attempt to delete the Node that the Machine
hosts after the Machine is marked for deletion. A duration of 0 will retry deletion indefinitely.
Defaults to 10 seconds.

Minimum: 0

ControlPlaneVariables

ControlPlaneVariables can be used to provide variables for the ControlPlane.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

overrides ClusterVariable array

overrides can be used to override Cluster level variables.

MaxItems: 1000
MinItems: 1

ExternalPatchDefinition

ExternalPatchDefinition defines an external patch. Note: At least one of GeneratePatchesExtension or ValidateTopologyExtension must be set.

Appears In:
Field Description Default Validation

generatePatchesExtension string

generatePatchesExtension references an extension which is called to generate patches.

MaxLength: 512
MinLength: 1

validateTopologyExtension string

validateTopologyExtension references an extension which is called to validate the topology.

MaxLength: 512
MinLength: 1

discoverVariablesExtension string

discoverVariablesExtension references an extension which is called to discover variables.

MaxLength: 512
MinLength: 1

settings object (keys:string, values:string)

settings defines key value pairs to be passed to the extensions.
Values defined here take precedence over the values defined in the
corresponding ExtensionConfig.

FailureDomain

FailureDomain is the Schema for Cluster API failure domains. It allows controllers to understand how many failure domains a cluster can optionally span across.

Appears In:
Field Description Default Validation

name string

name is the name of the failure domain.

MaxLength: 256
MinLength: 1

controlPlane boolean

controlPlane determines if this failure domain is suitable for use by control plane machines.

attributes object (keys:string, values:string)

attributes is a free form map of attributes an infrastructure provider might use or require.

FieldValueErrorReason

Underlying type: string

FieldValueErrorReason is a machine-readable value providing more detail about why a field failed the validation.

Appears In:

InfrastructureClass

InfrastructureClass defines the class for the infrastructure cluster.

Appears In:
Field Description Default Validation

templateRef ClusterClassTemplateReference

templateRef contains the reference to a provider-specific infrastructure cluster template.

naming InfrastructureClassNamingSpec

naming allows changing the naming pattern used when creating the infrastructure cluster object.

MinProperties: 1

InfrastructureClassNamingSpec

InfrastructureClassNamingSpec defines the naming strategy for infrastructure objects.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

template string

template defines the template to use for generating the name of the Infrastructure object.
If not defined, it will fallback to {{ .cluster.name }}-{{ .random }}.
If the templated string exceeds 63 characters, it will be trimmed to 58 characters and will
get concatenated with a random suffix of length 5.
The templating mechanism provides the following arguments:
* .cluster.name: The name of the cluster object.
* .random: A random alphanumeric string, without vowels, of length 5.

MaxLength: 1024
MinLength: 1

JSONPatch

JSONPatch defines a JSON patch.

Appears In:
Field Description Default Validation

op string

op defines the operation of the patch.
Note: Only add, replace and remove are supported.

Enum: [add replace remove]

path string

path defines the path of the patch.
Note: Only the spec of a template can be patched, thus the path has to start with /spec/.
Note: For now the only allowed array modifications are append and prepend, i.e.:
* for op: add: only index 0 (prepend) and - (append) are allowed
* for op: replace or remove: no indexes are allowed

MaxLength: 512
MinLength: 1

value JSON

value defines the value of the patch.
Note: Either Value or ValueFrom is required for add and replace
operations. Only one of them is allowed to be set at the same time.
Note: We have to use apiextensionsv1.JSON instead of our JSON type,
because controller-tools has a hard-coded schema for apiextensionsv1.JSON
which cannot be produced by another type (unset type field).
Ref: https://github.com/kubernetes-sigs/controller-tools/blob/d0e03a142d0ecdd5491593e941ee1d6b5d91dba6/pkg/crd/known_types.go#L106-L111

valueFrom JSONPatchValue

valueFrom defines the value of the patch.
Note: Either Value or ValueFrom is required for add and replace
operations. Only one of them is allowed to be set at the same time.

JSONPatchValue

JSONPatchValue defines the value of a patch. Note: Only one of the fields is allowed to be set at the same time.

Appears In:
Field Description Default Validation

variable string

variable is the variable to be used as value.
Variable can be one of the variables defined in .spec.variables or a builtin variable.

MaxLength: 256
MinLength: 1

template string

template is the Go template to be used to calculate the value.
A template can reference variables defined in .spec.variables and builtin variables.
Note: The template must evaluate to a valid YAML or JSON value.

MaxLength: 10240
MinLength: 1

JSONSchemaProps

JSONSchemaProps is a JSON-Schema following Specification Draft 4 (http://json-schema.org/). This struct has been initially copied from apiextensionsv1.JSONSchemaProps, but all fields which are not supported in CAPI have been removed.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

description string

description is a human-readable description of this variable.

MaxLength: 4096
MinLength: 1

example JSON

example is an example for this variable.

type string

type is the type of the variable.
Valid values are: object, array, string, integer, number or boolean.

Enum: [object array string integer number boolean]

properties object (keys:string, values:JSONSchemaProps)

properties specifies fields of an object.
NOTE: Can only be set if type is object.
NOTE: Properties is mutually exclusive with AdditionalProperties.
NOTE: This field uses PreserveUnknownFields and Schemaless,
because recursive validation is not possible.

Schemaless: \{}

additionalProperties JSONSchemaProps

additionalProperties specifies the schema of values in a map (keys are always strings).
NOTE: Can only be set if type is object.
NOTE: AdditionalProperties is mutually exclusive with Properties.
NOTE: This field uses PreserveUnknownFields and Schemaless,
because recursive validation is not possible.

MinProperties: 1
Schemaless: \{}

maxProperties integer

maxProperties is the maximum amount of entries in a map or properties in an object.
NOTE: Can only be set if type is object.

minProperties integer

minProperties is the minimum amount of entries in a map or properties in an object.
NOTE: Can only be set if type is object.

required string array

required specifies which fields of an object are required.
NOTE: Can only be set if type is object.

MaxItems: 1000
MinItems: 1
items:MaxLength: 256
items:MinLength: 1

items JSONSchemaProps

items specifies fields of an array.
NOTE: Can only be set if type is array.
NOTE: This field uses PreserveUnknownFields and Schemaless,
because recursive validation is not possible.

MinProperties: 1
Schemaless: \{}

maxItems integer

maxItems is the max length of an array variable.
NOTE: Can only be set if type is array.

minItems integer

minItems is the min length of an array variable.
NOTE: Can only be set if type is array.

uniqueItems boolean

uniqueItems specifies if items in an array must be unique.
NOTE: Can only be set if type is array.

format string

format is an OpenAPI v3 format string. Unknown formats are ignored.
For a list of supported formats please see: (of the k8s.io/apiextensions-apiserver version we’re currently using)
https://github.com/kubernetes/apiextensions-apiserver/blob/master/pkg/apiserver/validation/formats.go
NOTE: Can only be set if type is string.

MaxLength: 32
MinLength: 1

maxLength integer

maxLength is the max length of a string variable.
NOTE: Can only be set if type is string.

minLength integer

minLength is the min length of a string variable.
NOTE: Can only be set if type is string.

pattern string

pattern is the regex which a string variable must match.
NOTE: Can only be set if type is string.

MaxLength: 512
MinLength: 1

maximum integer

maximum is the maximum of an integer or number variable.
If ExclusiveMaximum is false, the variable is valid if it is lower than, or equal to, the value of Maximum.
If ExclusiveMaximum is true, the variable is valid if it is strictly lower than the value of Maximum.
NOTE: Can only be set if type is integer or number.

exclusiveMaximum boolean

exclusiveMaximum specifies if the Maximum is exclusive.
NOTE: Can only be set if type is integer or number.

minimum integer

minimum is the minimum of an integer or number variable.
If ExclusiveMinimum is false, the variable is valid if it is greater than, or equal to, the value of Minimum.
If ExclusiveMinimum is true, the variable is valid if it is strictly greater than the value of Minimum.
NOTE: Can only be set if type is integer or number.

exclusiveMinimum boolean

exclusiveMinimum specifies if the Minimum is exclusive.
NOTE: Can only be set if type is integer or number.

x-kubernetes-preserve-unknown-fields boolean

x-kubernetes-preserve-unknown-fields allows setting fields in a variable object
which are not defined in the variable schema. This affects fields recursively,
except if nested properties or additionalProperties are specified in the schema.

enum JSON array

enum is the list of valid values of the variable.
NOTE: Can be set for all types.

MaxItems: 100

default JSON

default is the default value of the variable.
NOTE: Can be set for all types.

x-kubernetes-validations ValidationRule array

x-kubernetes-validations describes a list of validation rules written in the CEL expression language.

MaxItems: 100
MinItems: 1

x-metadata VariableSchemaMetadata

x-metadata is the metadata of a variable or a nested field within a variable.
It can be used to add additional data for higher level tools.

MinProperties: 1

x-kubernetes-int-or-string boolean

x-kubernetes-int-or-string specifies that this value is
either an integer or a string. If this is true, an empty
type is allowed and type as child of anyOf is permitted
if following one of the following patterns:

1) anyOf:
- type: integer
- type: string
2) allOf:
- anyOf:
- type: integer
- type: string
- …​ zero or more

allOf JSONSchemaProps array

allOf specifies that the variable must validate against all of the subschemas in the array.
NOTE: This field uses PreserveUnknownFields and Schemaless,
because recursive validation is not possible.

MinProperties: 1
Schemaless: \{}

oneOf JSONSchemaProps array

oneOf specifies that the variable must validate against exactly one of the subschemas in the array.
NOTE: This field uses PreserveUnknownFields and Schemaless,
because recursive validation is not possible.

MinProperties: 1
Schemaless: \{}

anyOf JSONSchemaProps array

anyOf specifies that the variable must validate against one or more of the subschemas in the array.
NOTE: This field uses PreserveUnknownFields and Schemaless,
because recursive validation is not possible.

MinProperties: 1
Schemaless: \{}

not JSONSchemaProps

not specifies that the variable must not validate against the subschema.
NOTE: This field uses PreserveUnknownFields and Schemaless,
because recursive validation is not possible.

MinProperties: 1
Schemaless: \{}

Machine

Machine is the Schema for the machines API.

Field Description Default Validation

apiVersion string

cluster.x-k8s.io/v1beta2

kind string

Machine

metadata ObjectMeta

Refer to Kubernetes API documentation for fields of metadata.

MinProperties: 1

spec MachineSpec

spec is the desired state of Machine.

status MachineStatus

status is the observed state of Machine.

MinProperties: 1

MachineAddress

MachineAddress contains information for the node’s address.

Appears In:
Field Description Default Validation

type MachineAddressType

type is the machine address type, one of Hostname, ExternalIP, InternalIP, ExternalDNS or InternalDNS.

Enum: [Hostname ExternalIP InternalIP ExternalDNS InternalDNS]

address string

address is the machine address.

MaxLength: 256
MinLength: 1

MachineAddressType

Underlying type: string

MachineAddressType describes a valid MachineAddress type.

Validation:

  • Enum: [Hostname ExternalIP InternalIP ExternalDNS InternalDNS]

Appears In:

MachineAddresses

Underlying type: MachineAddress

MachineAddresses is a slice of MachineAddress items to be used by infrastructure providers.

Validation:

  • MaxItems: 128

Appears In:
Field Description Default Validation

type MachineAddressType

type is the machine address type, one of Hostname, ExternalIP, InternalIP, ExternalDNS or InternalDNS.

Enum: [Hostname ExternalIP InternalIP ExternalDNS InternalDNS]

address string

address is the machine address.

MaxLength: 256
MinLength: 1

MachineDeletionSpec

MachineDeletionSpec contains configuration options for Machine deletion.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

nodeDrainTimeoutSeconds integer

nodeDrainTimeoutSeconds is the total amount of time that the controller will spend on draining a node.
The default value is 0, meaning that the node can be drained without any time limitations.
NOTE: nodeDrainTimeoutSeconds is different from kubectl drain --timeout

Minimum: 0

nodeVolumeDetachTimeoutSeconds integer

nodeVolumeDetachTimeoutSeconds is the total amount of time that the controller will spend on waiting for all volumes
to be detached. The default value is 0, meaning that the volumes can be detached without any time limitations.

Minimum: 0

nodeDeletionTimeoutSeconds integer

nodeDeletionTimeoutSeconds defines how long the controller will attempt to delete the Node that the Machine
hosts after the Machine is marked for deletion. A duration of 0 will retry deletion indefinitely.
Defaults to 10 seconds.

Minimum: 0

MachineDeletionStatus

MachineDeletionStatus is the deletion state of the Machine.

Appears In:
Field Description Default Validation

nodeDrainStartTime Time

nodeDrainStartTime is the time when the drain of the node started and is used to determine
if the nodeDrainTimeoutSeconds is exceeded.
Only present when the Machine has a deletionTimestamp and draining the node had been started.

waitForNodeVolumeDetachStartTime Time

waitForNodeVolumeDetachStartTime is the time when waiting for volume detachment started
and is used to determine if the nodeVolumeDetachTimeoutSeconds is exceeded.
Detaching volumes from nodes is usually done by CSI implementations and the current state
is observed from the node’s .Status.VolumesAttached field.
Only present when the Machine has a deletionTimestamp and waiting for volume detachments had been started.

MachineDeployment

MachineDeployment is the Schema for the machinedeployments API.

Field Description Default Validation

apiVersion string

cluster.x-k8s.io/v1beta2

kind string

MachineDeployment

metadata ObjectMeta

Refer to Kubernetes API documentation for fields of metadata.

MinProperties: 1

spec MachineDeploymentSpec

spec is the desired state of MachineDeployment.

status MachineDeploymentStatus

status is the observed state of MachineDeployment.

MinProperties: 1

MachineDeploymentClass

MachineDeploymentClass serves as a template to define a set of worker nodes of the cluster provisioned using the ClusterClass.

Appears In:
Field Description Default Validation

metadata ObjectMeta

Refer to Kubernetes API documentation for fields of metadata.

MinProperties: 1

class string

class denotes a type of worker node present in the cluster,
this name MUST be unique within a ClusterClass and can be referenced
in the Cluster to create a managed MachineDeployment.

MaxLength: 256
MinLength: 1

bootstrap MachineDeploymentClassBootstrapTemplate

bootstrap contains the bootstrap template reference to be used
for the creation of worker Machines.

infrastructure MachineDeploymentClassInfrastructureTemplate

infrastructure contains the infrastructure template reference to be used
for the creation of worker Machines.

healthCheck MachineDeploymentClassHealthCheck

healthCheck defines a MachineHealthCheck for this MachineDeploymentClass.

MinProperties: 1

failureDomain string

failureDomain is the failure domain the machines will be created in.
Must match the name of a FailureDomain from the Cluster status.
NOTE: This value can be overridden while defining a Cluster.Topology using this MachineDeploymentClass.

MaxLength: 256
MinLength: 1

naming MachineDeploymentClassNamingSpec

naming allows changing the naming pattern used when creating the MachineDeployment.

MinProperties: 1

deletion MachineDeploymentClassMachineDeletionSpec

deletion contains configuration options for Machine deletion.

MinProperties: 1

minReadySeconds integer

minReadySeconds is the minimum number of seconds for which a newly created machine should
be ready.
Defaults to 0 (machine will be considered available as soon as it
is ready)
NOTE: This value can be overridden while defining a Cluster.Topology using this MachineDeploymentClass.

Minimum: 0

readinessGates MachineReadinessGate array

readinessGates specifies additional conditions to include when evaluating Machine Ready condition.

This field can be used e.g. to instruct the machine controller to include in the computation for Machine’s ready
computation a condition, managed by an external controllers, reporting the status of special software/hardware installed on the Machine.

Note
 If a Cluster defines a custom list of readinessGates for a MachineDeployment using this MachineDeploymentClass,
such list overrides readinessGates defined in this field.

MaxItems: 32
MinItems: 1

rollout MachineDeploymentClassRolloutSpec

rollout allows you to configure the behaviour of rolling updates to the MachineDeployment Machines.
It allows you to define the strategy used during rolling replacements.

MinProperties: 1

MachineDeploymentClassBootstrapTemplate

MachineDeploymentClassBootstrapTemplate defines the BootstrapTemplate for a MachineDeployment.

Appears In:
Field Description Default Validation

templateRef ClusterClassTemplateReference

templateRef is a required reference to the BootstrapTemplate for a MachineDeployment.

MachineDeploymentClassHealthCheck

MachineDeploymentClassHealthCheck defines a MachineHealthCheck for MachineDeployment machines.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

checks MachineDeploymentClassHealthCheckChecks

checks are the checks that are used to evaluate if a Machine is healthy.

Independent of this configuration the MachineHealthCheck controller will always
flag Machines with cluster.x-k8s.io/remediate-machine annotation and
Machines with deleted Nodes as unhealthy.

Furthermore, if checks.nodeStartupTimeoutSeconds is not set it
is defaulted to 10 minutes and evaluated accordingly.

MinProperties: 1

remediation MachineDeploymentClassHealthCheckRemediation

remediation configures if and how remediations are triggered if a Machine is unhealthy.

If remediation or remediation.triggerIf is not set,
remediation will always be triggered for unhealthy Machines.

If remediation or remediation.templateRef is not set,
the OwnerRemediated condition will be set on unhealthy Machines to trigger remediation via
the owner of the Machines, for example a MachineSet or a KubeadmControlPlane.

MinProperties: 1

MachineDeploymentClassHealthCheckChecks

MachineDeploymentClassHealthCheckChecks are the checks that are used to evaluate if a MachineDeployment Machine is healthy.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

nodeStartupTimeoutSeconds integer

nodeStartupTimeoutSeconds allows to set the maximum time for MachineHealthCheck
to consider a Machine unhealthy if a corresponding Node isn’t associated
through a Spec.ProviderID field.

The duration set in this field is compared to the greatest of:
- Cluster’s infrastructure ready condition timestamp (if and when available)
- Control Plane’s initialized condition timestamp (if and when available)
- Machine’s infrastructure ready condition timestamp (if and when available)
- Machine’s metadata creation timestamp

Defaults to 10 minutes.
If you wish to disable this feature, set the value explicitly to 0.

Minimum: 0

unhealthyNodeConditions UnhealthyNodeCondition array

unhealthyNodeConditions contains a list of conditions that determine
whether a node is considered unhealthy. The conditions are combined in a
logical OR, i.e. if any of the conditions is met, the node is unhealthy.

MaxItems: 100
MinItems: 1

unhealthyMachineConditions UnhealthyMachineCondition array

unhealthyMachineConditions contains a list of the machine conditions that determine
whether a machine is considered unhealthy. The conditions are combined in a
logical OR, i.e. if any of the conditions is met, the machine is unhealthy.

MaxItems: 100
MinItems: 1

MachineDeploymentClassHealthCheckRemediation

MachineDeploymentClassHealthCheckRemediation configures if and how remediations are triggered if a MachineDeployment Machine is unhealthy.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

maxInFlight IntOrString

maxInFlight determines how many in flight remediations should happen at the same time.

Remediation only happens on the MachineSet with the most current revision, while
older MachineSets (usually present during rollout operations) aren’t allowed to remediate.

Note: In general (independent of remediations), unhealthy machines are always
prioritized during scale down operations over healthy ones.

MaxInFlight can be set to a fixed number or a percentage.
Example: when this is set to 20%, the MachineSet controller deletes at most 20% of
the desired replicas.

If not set, remediation is limited to all machines (bounded by replicas)
under the active MachineSet’s management.

triggerIf MachineDeploymentClassHealthCheckRemediationTriggerIf

triggerIf configures if remediations are triggered.
If this field is not set, remediations are always triggered.

MinProperties: 1

templateRef MachineHealthCheckRemediationTemplateReference

templateRef is a reference to a remediation template
provided by an infrastructure provider.

This field is completely optional, when filled, the MachineHealthCheck controller
creates a new object from the template referenced and hands off remediation of the machine to
a controller that lives outside of Cluster API.

MachineDeploymentClassHealthCheckRemediationTriggerIf

MachineDeploymentClassHealthCheckRemediationTriggerIf configures if remediations are triggered.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

unhealthyLessThanOrEqualTo IntOrString

unhealthyLessThanOrEqualTo specifies that remediations are only triggered if the number of
unhealthy Machines is less than or equal to the configured value.
unhealthyInRange takes precedence if set.

unhealthyInRange string

unhealthyInRange specifies that remediations are only triggered if the number of
unhealthy Machines is in the configured range.
Takes precedence over unhealthyLessThanOrEqualTo.
Eg. "[3-5]" - This means that remediation will be allowed only when:
(a) there are at least 3 unhealthy Machines (and)
(b) there are at most 5 unhealthy Machines

MaxLength: 32
MinLength: 1
Pattern: ^\[[0-9]+-[0-9]+\]$

MachineDeploymentClassInfrastructureTemplate

MachineDeploymentClassInfrastructureTemplate defines the InfrastructureTemplate for a MachineDeployment.

Appears In:
Field Description Default Validation

templateRef ClusterClassTemplateReference

templateRef is a required reference to the InfrastructureTemplate for a MachineDeployment.

MachineDeploymentClassMachineDeletionSpec

MachineDeploymentClassMachineDeletionSpec contains configuration options for Machine deletion.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

order MachineSetDeletionOrder

order defines the order in which Machines are deleted when downscaling.
Defaults to "Random". Valid values are "Random, "Newest", "Oldest"

Enum: [Random Newest Oldest]

nodeDrainTimeoutSeconds integer

nodeDrainTimeoutSeconds is the total amount of time that the controller will spend on draining a node.
The default value is 0, meaning that the node can be drained without any time limitations.
NOTE: nodeDrainTimeoutSeconds is different from kubectl drain --timeout
NOTE: This value can be overridden while defining a Cluster.Topology using this MachineDeploymentClass.

Minimum: 0

nodeVolumeDetachTimeoutSeconds integer

nodeVolumeDetachTimeoutSeconds is the total amount of time that the controller will spend on waiting for all volumes
to be detached. The default value is 0, meaning that the volumes can be detached without any time limitations.
NOTE: This value can be overridden while defining a Cluster.Topology using this MachineDeploymentClass.

Minimum: 0

nodeDeletionTimeoutSeconds integer

nodeDeletionTimeoutSeconds defines how long the controller will attempt to delete the Node that the Machine
hosts after the Machine is marked for deletion. A duration of 0 will retry deletion indefinitely.
Defaults to 10 seconds.
NOTE: This value can be overridden while defining a Cluster.Topology using this MachineDeploymentClass.

Minimum: 0

MachineDeploymentClassNamingSpec

MachineDeploymentClassNamingSpec defines the naming strategy for machine deployment objects.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

template string

template defines the template to use for generating the name of the MachineDeployment object.
If not defined, it will fallback to {{ .cluster.name }}-{{ .machineDeployment.topologyName }}-{{ .random }}.
If the templated string exceeds 63 characters, it will be trimmed to 58 characters and will
get concatenated with a random suffix of length 5.
The templating mechanism provides the following arguments:
* .cluster.name: The name of the cluster object.
* .random: A random alphanumeric string, without vowels, of length 5.
* .machineDeployment.topologyName: The name of the MachineDeployment topology (Cluster.spec.topology.workers.machineDeployments[].name).

MaxLength: 1024
MinLength: 1

MachineDeploymentClassRolloutSpec

MachineDeploymentClassRolloutSpec defines the rollout behavior.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

strategy MachineDeploymentClassRolloutStrategy

strategy specifies how to roll out control plane Machines.

MinProperties: 1

MachineDeploymentClassRolloutStrategy

MachineDeploymentClassRolloutStrategy describes how to replace existing machines with new ones.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

type MachineDeploymentRolloutStrategyType

type of rollout. Allowed values are RollingUpdate and OnDelete.
Default is RollingUpdate.

Enum: [RollingUpdate OnDelete]

rollingUpdate MachineDeploymentClassRolloutStrategyRollingUpdate

rollingUpdate is the rolling update config params. Present only if
type = RollingUpdate.

MinProperties: 1

MachineDeploymentClassRolloutStrategyRollingUpdate

MachineDeploymentClassRolloutStrategyRollingUpdate is used to control the desired behavior of rolling update.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

maxUnavailable IntOrString

maxUnavailable is the maximum number of machines that can be unavailable during the update.
Value can be an absolute number (ex: 5) or a percentage of desired
machines (ex: 10%).
Absolute number is calculated from percentage by rounding down.
This can not be 0 if MaxSurge is 0.
Defaults to 0.
Example: when this is set to 30%, the old MachineSet can be scaled
down to 70% of desired machines immediately when the rolling update
starts. Once new machines are ready, old MachineSet can be scaled
down further, followed by scaling up the new MachineSet, ensuring
that the total number of machines available at all times
during the update is at least 70% of desired machines.

maxSurge IntOrString

maxSurge is the maximum number of machines that can be scheduled above the
desired number of machines.
Value can be an absolute number (ex: 5) or a percentage of
desired machines (ex: 10%).
This can not be 0 if MaxUnavailable is 0.
Absolute number is calculated from percentage by rounding up.
Defaults to 1.
Example: when this is set to 30%, the new MachineSet can be scaled
up immediately when the rolling update starts, such that the total
number of old and new machines do not exceed 130% of desired
machines. Once old machines have been killed, new MachineSet can
be scaled up further, ensuring that total number of machines running
at any time during the update is at most 130% of desired machines.

MachineDeploymentDeletionSpec

MachineDeploymentDeletionSpec contains configuration options for MachineDeployment deletion.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

order MachineSetDeletionOrder

order defines the order in which Machines are deleted when downscaling.
Defaults to "Random". Valid values are "Random, "Newest", "Oldest"

Enum: [Random Newest Oldest]

MachineDeploymentDeprecatedStatus

MachineDeploymentDeprecatedStatus groups all the status fields that are deprecated and will be removed in a future version. See https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/proposals/20240916-improve-status-in-CAPI-resources.md for more context.

Appears In:
Field Description Default Validation

v1beta1 MachineDeploymentV1Beta1DeprecatedStatus

v1beta1 groups all the status fields that are deprecated and will be removed when support for v1beta1 will be dropped.

MachineDeploymentRemediationSpec

MachineDeploymentRemediationSpec controls how unhealthy Machines are remediated.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

maxInFlight IntOrString

maxInFlight determines how many in flight remediations should happen at the same time.

Remediation only happens on the MachineSet with the most current revision, while
older MachineSets (usually present during rollout operations) aren’t allowed to remediate.

Note: In general (independent of remediations), unhealthy machines are always
prioritized during scale down operations over healthy ones.

MaxInFlight can be set to a fixed number or a percentage.
Example: when this is set to 20%, the MachineSet controller deletes at most 20% of
the desired replicas.

If not set, remediation is limited to all machines (bounded by replicas)
under the active MachineSet’s management.

MachineDeploymentRolloutSpec

MachineDeploymentRolloutSpec defines the rollout behavior.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

after Time

after is a field to indicate a rollout should be performed
after the specified time even if no changes have been made to the
MachineDeployment.
Example: In the YAML the time can be specified in the RFC3339 format.
To specify the rolloutAfter target as March 9, 2023, at 9 am UTC
use "2023-03-09T09:00:00Z".

strategy MachineDeploymentRolloutStrategy

strategy specifies how to roll out control plane Machines.

MinProperties: 1

MachineDeploymentRolloutStrategy

MachineDeploymentRolloutStrategy describes how to replace existing machines with new ones.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

type MachineDeploymentRolloutStrategyType

type of rollout. Allowed values are RollingUpdate and OnDelete.
Default is RollingUpdate.

Enum: [RollingUpdate OnDelete]

rollingUpdate MachineDeploymentRolloutStrategyRollingUpdate

rollingUpdate is the rolling update config params. Present only if
type = RollingUpdate.

MinProperties: 1

MachineDeploymentRolloutStrategyRollingUpdate

MachineDeploymentRolloutStrategyRollingUpdate is used to control the desired behavior of rolling update.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

maxUnavailable IntOrString

maxUnavailable is the maximum number of machines that can be unavailable during the update.
Value can be an absolute number (ex: 5) or a percentage of desired
machines (ex: 10%).
Absolute number is calculated from percentage by rounding down.
This can not be 0 if MaxSurge is 0.
Defaults to 0.
Example: when this is set to 30%, the old MachineSet can be scaled
down to 70% of desired machines immediately when the rolling update
starts. Once new machines are ready, old MachineSet can be scaled
down further, followed by scaling up the new MachineSet, ensuring
that the total number of machines available at all times
during the update is at least 70% of desired machines.

maxSurge IntOrString

maxSurge is the maximum number of machines that can be scheduled above the
desired number of machines.
Value can be an absolute number (ex: 5) or a percentage of
desired machines (ex: 10%).
This can not be 0 if MaxUnavailable is 0.
Absolute number is calculated from percentage by rounding up.
Defaults to 1.
Example: when this is set to 30%, the new MachineSet can be scaled
up immediately when the rolling update starts, such that the total
number of old and new machines do not exceed 130% of desired
machines. Once old machines have been killed, new MachineSet can
be scaled up further, ensuring that total number of machines running
at any time during the update is at most 130% of desired machines.

MachineDeploymentRolloutStrategyType

Underlying type: string

MachineDeploymentRolloutStrategyType defines the type of MachineDeployment rollout strategies.

Validation:

  • Enum: [RollingUpdate OnDelete]

Appears In:

MachineDeploymentSpec

MachineDeploymentSpec defines the desired state of MachineDeployment.

Appears In:
Field Description Default Validation

clusterName string

clusterName is the name of the Cluster this object belongs to.

MaxLength: 63
MinLength: 1

replicas integer

replicas is the number of desired machines.
This is a pointer to distinguish between explicit zero and not specified.

Defaults to:
* if the Kubernetes autoscaler min size and max size annotations are set:
- if it’s a new MachineDeployment, use min size
- if the replicas field of the old MachineDeployment is < min size, use min size
- if the replicas field of the old MachineDeployment is > max size, use max size
- if the replicas field of the old MachineDeployment is in the (min size, max size) range, keep the value from the oldMD
* otherwise use 1
Note: Defaulting will be run whenever the replicas field is not set:
* A new MachineDeployment is created with replicas not set.
* On an existing MachineDeployment the replicas field was first set and is now unset.
Those cases are especially relevant for the following Kubernetes autoscaler use cases:
* A new MachineDeployment is created and replicas should be managed by the autoscaler
* An existing MachineDeployment which initially wasn’t controlled by the autoscaler
should be later controlled by the autoscaler

rollout MachineDeploymentRolloutSpec

rollout allows you to configure the behaviour of rolling updates to the MachineDeployment Machines.
It allows you to require that all Machines are replaced after a certain time,
and allows you to define the strategy used during rolling replacements.

MinProperties: 1

selector LabelSelector

selector is the label selector for machines. Existing MachineSets whose machines are
selected by this will be the ones affected by this deployment.
It must match the machine template’s labels.

template MachineTemplateSpec

template describes the machines that will be created.

machineNaming MachineNamingSpec

machineNaming allows changing the naming pattern used when creating Machines.
Note: InfraMachines & BootstrapConfigs will use the same name as the corresponding Machines.

MinProperties: 1

remediation MachineDeploymentRemediationSpec

remediation controls how unhealthy Machines are remediated.

MinProperties: 1

deletion MachineDeploymentDeletionSpec

deletion contains configuration options for MachineDeployment deletion.

MinProperties: 1

paused boolean

paused indicates that the deployment is paused.

MachineDeploymentStatus

MachineDeploymentStatus defines the observed state of MachineDeployment.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

conditions Condition array

conditions represents the observations of a MachineDeployment’s current state.
Known condition types are Available, MachinesReady, MachinesUpToDate, ScalingUp, ScalingDown, Remediating, Deleting, Paused.

MaxItems: 32

observedGeneration integer

observedGeneration is the generation observed by the deployment controller.

Minimum: 1

selector string

selector is the same as the label selector but in the string format to avoid introspection
by clients. The string will be in the same format as the query-param syntax.
More info about label selectors: http://kubernetes.io/docs/user-guide/labels#label-selectors

MaxLength: 4096
MinLength: 1

replicas integer

replicas is the total number of non-terminated machines targeted by this deployment
(their labels match the selector).

readyReplicas integer

readyReplicas is the number of ready replicas for this MachineDeployment. A machine is considered ready when Machine’s Ready condition is true.

availableReplicas integer

availableReplicas is the number of available replicas for this MachineDeployment. A machine is considered available when Machine’s Available condition is true.

upToDateReplicas integer

upToDateReplicas is the number of up-to-date replicas targeted by this deployment. A machine is considered up-to-date when Machine’s UpToDate condition is true.

phase string

phase represents the current phase of a MachineDeployment (ScalingUp, ScalingDown, Running, Failed, or Unknown).

Enum: [ScalingUp ScalingDown Running Failed Unknown]

deprecated MachineDeploymentDeprecatedStatus

deprecated groups all the status fields that are deprecated and will be removed when all the nested field are removed.

MachineDeploymentTopology

MachineDeploymentTopology specifies the different parameters for a set of worker nodes in the topology. This set of nodes is managed by a MachineDeployment object whose lifecycle is managed by the Cluster controller.

Appears In:
Field Description Default Validation

metadata ObjectMeta

Refer to Kubernetes API documentation for fields of metadata.

MinProperties: 1

class string

class is the name of the MachineDeploymentClass used to create the set of worker nodes.
This should match one of the deployment classes defined in the ClusterClass object
mentioned in the Cluster.Spec.Class field.

MaxLength: 256
MinLength: 1

name string

name is the unique identifier for this MachineDeploymentTopology.
The value is used with other unique identifiers to create a MachineDeployment’s Name
(e.g. cluster’s name, etc). In case the name is greater than the allowed maximum length,
the values are hashed together.

MaxLength: 63
MinLength: 1
Pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$

failureDomain string

failureDomain is the failure domain the machines will be created in.
Must match a key in the FailureDomains map stored on the cluster object.

MaxLength: 256
MinLength: 1

replicas integer

replicas is the number of worker nodes belonging to this set.
If the value is nil, the MachineDeployment is created without the number of Replicas (defaulting to 1)
and it’s assumed that an external entity (like cluster autoscaler) is responsible for the management
of this value.

healthCheck MachineDeploymentTopologyHealthCheck

healthCheck allows to enable, disable and override MachineDeployment health check
configuration from the ClusterClass for this MachineDeployment.

MinProperties: 1

deletion MachineDeploymentTopologyMachineDeletionSpec

deletion contains configuration options for Machine deletion.

MinProperties: 1

minReadySeconds integer

minReadySeconds is the minimum number of seconds for which a newly created machine should
be ready.
Defaults to 0 (machine will be considered available as soon as it
is ready)

Minimum: 0

readinessGates MachineReadinessGate array

readinessGates specifies additional conditions to include when evaluating Machine Ready condition.

This field can be used e.g. to instruct the machine controller to include in the computation for Machine’s ready
computation a condition, managed by an external controllers, reporting the status of special software/hardware installed on the Machine.

If this field is not defined, readinessGates from the corresponding MachineDeploymentClass will be used, if any.

MaxItems: 32
MinItems: 1

rollout MachineDeploymentTopologyRolloutSpec

rollout allows you to configure the behaviour of rolling updates to the MachineDeployment Machines.
It allows you to define the strategy used during rolling replacements.

MinProperties: 1

variables MachineDeploymentVariables

variables can be used to customize the MachineDeployment through patches.

MinProperties: 1

MachineDeploymentTopologyHealthCheck

MachineDeploymentTopologyHealthCheck defines a MachineHealthCheck for MachineDeployment machines.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

enabled boolean

enabled controls if a MachineHealthCheck should be created for the target machines.

If false: No MachineHealthCheck will be created.

If not set(default): A MachineHealthCheck will be created if it is defined here or
in the associated ClusterClass. If no MachineHealthCheck is defined then none will be created.

If true: A MachineHealthCheck is guaranteed to be created. Cluster validation will
block if enable is true and no MachineHealthCheck definition is available.

checks MachineDeploymentTopologyHealthCheckChecks

checks are the checks that are used to evaluate if a Machine is healthy.

If one of checks and remediation fields are set, the system assumes that an healthCheck override is defined,
and as a consequence the checks and remediation fields from Cluster will be used instead of the
corresponding fields in ClusterClass.

Independent of this configuration the MachineHealthCheck controller will always
flag Machines with cluster.x-k8s.io/remediate-machine annotation and
Machines with deleted Nodes as unhealthy.

Furthermore, if checks.nodeStartupTimeoutSeconds is not set it
is defaulted to 10 minutes and evaluated accordingly.

MinProperties: 1

remediation MachineDeploymentTopologyHealthCheckRemediation

remediation configures if and how remediations are triggered if a Machine is unhealthy.

If one of checks and remediation fields are set, the system assumes that an healthCheck override is defined,
and as a consequence the checks and remediation fields from cluster will be used instead of the
corresponding fields in ClusterClass.

If an health check override is defined and remediation or remediation.triggerIf is not set,
remediation will always be triggered for unhealthy Machines.

If an health check override is defined and remediation or remediation.templateRef is not set,
the OwnerRemediated condition will be set on unhealthy Machines to trigger remediation via
the owner of the Machines, for example a MachineSet or a KubeadmControlPlane.

MinProperties: 1

MachineDeploymentTopologyHealthCheckChecks

MachineDeploymentTopologyHealthCheckChecks are the checks that are used to evaluate if a MachineDeployment Machine is healthy.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

nodeStartupTimeoutSeconds integer

nodeStartupTimeoutSeconds allows to set the maximum time for MachineHealthCheck
to consider a Machine unhealthy if a corresponding Node isn’t associated
through a Spec.ProviderID field.

The duration set in this field is compared to the greatest of:
- Cluster’s infrastructure ready condition timestamp (if and when available)
- Control Plane’s initialized condition timestamp (if and when available)
- Machine’s infrastructure ready condition timestamp (if and when available)
- Machine’s metadata creation timestamp

Defaults to 10 minutes.
If you wish to disable this feature, set the value explicitly to 0.

Minimum: 0

unhealthyNodeConditions UnhealthyNodeCondition array

unhealthyNodeConditions contains a list of conditions that determine
whether a node is considered unhealthy. The conditions are combined in a
logical OR, i.e. if any of the conditions is met, the node is unhealthy.

MaxItems: 100
MinItems: 1

unhealthyMachineConditions UnhealthyMachineCondition array

unhealthyMachineConditions contains a list of the machine conditions that determine
whether a machine is considered unhealthy. The conditions are combined in a
logical OR, i.e. if any of the conditions is met, the machine is unhealthy.

MaxItems: 100
MinItems: 1

MachineDeploymentTopologyHealthCheckRemediation

MachineDeploymentTopologyHealthCheckRemediation configures if and how remediations are triggered if a MachineDeployment Machine is unhealthy.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

maxInFlight IntOrString

maxInFlight determines how many in flight remediations should happen at the same time.

Remediation only happens on the MachineSet with the most current revision, while
older MachineSets (usually present during rollout operations) aren’t allowed to remediate.

Note: In general (independent of remediations), unhealthy machines are always
prioritized during scale down operations over healthy ones.

MaxInFlight can be set to a fixed number or a percentage.
Example: when this is set to 20%, the MachineSet controller deletes at most 20% of
the desired replicas.

If not set, remediation is limited to all machines (bounded by replicas)
under the active MachineSet’s management.

triggerIf MachineDeploymentTopologyHealthCheckRemediationTriggerIf

triggerIf configures if remediations are triggered.
If this field is not set, remediations are always triggered.

MinProperties: 1

templateRef MachineHealthCheckRemediationTemplateReference

templateRef is a reference to a remediation template
provided by an infrastructure provider.

This field is completely optional, when filled, the MachineHealthCheck controller
creates a new object from the template referenced and hands off remediation of the machine to
a controller that lives outside of Cluster API.

MachineDeploymentTopologyHealthCheckRemediationTriggerIf

MachineDeploymentTopologyHealthCheckRemediationTriggerIf configures if remediations are triggered.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

unhealthyLessThanOrEqualTo IntOrString

unhealthyLessThanOrEqualTo specifies that remediations are only triggered if the number of
unhealthy Machines is less than or equal to the configured value.
unhealthyInRange takes precedence if set.

unhealthyInRange string

unhealthyInRange specifies that remediations are only triggered if the number of
unhealthy Machines is in the configured range.
Takes precedence over unhealthyLessThanOrEqualTo.
Eg. "[3-5]" - This means that remediation will be allowed only when:
(a) there are at least 3 unhealthy Machines (and)
(b) there are at most 5 unhealthy Machines

MaxLength: 32
MinLength: 1
Pattern: ^\[[0-9]+-[0-9]+\]$

MachineDeploymentTopologyMachineDeletionSpec

MachineDeploymentTopologyMachineDeletionSpec contains configuration options for Machine deletion.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

order MachineSetDeletionOrder

order defines the order in which Machines are deleted when downscaling.
Defaults to "Random". Valid values are "Random, "Newest", "Oldest"

Enum: [Random Newest Oldest]

nodeDrainTimeoutSeconds integer

nodeDrainTimeoutSeconds is the total amount of time that the controller will spend on draining a node.
The default value is 0, meaning that the node can be drained without any time limitations.
NOTE: nodeDrainTimeoutSeconds is different from kubectl drain --timeout

Minimum: 0

nodeVolumeDetachTimeoutSeconds integer

nodeVolumeDetachTimeoutSeconds is the total amount of time that the controller will spend on waiting for all volumes
to be detached. The default value is 0, meaning that the volumes can be detached without any time limitations.

Minimum: 0

nodeDeletionTimeoutSeconds integer

nodeDeletionTimeoutSeconds defines how long the controller will attempt to delete the Node that the Machine
hosts after the Machine is marked for deletion. A duration of 0 will retry deletion indefinitely.
Defaults to 10 seconds.

Minimum: 0

MachineDeploymentTopologyRolloutSpec

MachineDeploymentTopologyRolloutSpec defines the rollout behavior.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

strategy MachineDeploymentTopologyRolloutStrategy

strategy specifies how to roll out control plane Machines.

MinProperties: 1

MachineDeploymentTopologyRolloutStrategy

MachineDeploymentTopologyRolloutStrategy describes how to replace existing machines with new ones.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

type MachineDeploymentRolloutStrategyType

type of rollout. Allowed values are RollingUpdate and OnDelete.
Default is RollingUpdate.

Enum: [RollingUpdate OnDelete]

rollingUpdate MachineDeploymentTopologyRolloutStrategyRollingUpdate

rollingUpdate is the rolling update config params. Present only if
type = RollingUpdate.

MinProperties: 1

MachineDeploymentTopologyRolloutStrategyRollingUpdate

MachineDeploymentTopologyRolloutStrategyRollingUpdate is used to control the desired behavior of rolling update.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

maxUnavailable IntOrString

maxUnavailable is the maximum number of machines that can be unavailable during the update.
Value can be an absolute number (ex: 5) or a percentage of desired
machines (ex: 10%).
Absolute number is calculated from percentage by rounding down.
This can not be 0 if MaxSurge is 0.
Defaults to 0.
Example: when this is set to 30%, the old MachineSet can be scaled
down to 70% of desired machines immediately when the rolling update
starts. Once new machines are ready, old MachineSet can be scaled
down further, followed by scaling up the new MachineSet, ensuring
that the total number of machines available at all times
during the update is at least 70% of desired machines.

maxSurge IntOrString

maxSurge is the maximum number of machines that can be scheduled above the
desired number of machines.
Value can be an absolute number (ex: 5) or a percentage of
desired machines (ex: 10%).
This can not be 0 if MaxUnavailable is 0.
Absolute number is calculated from percentage by rounding up.
Defaults to 1.
Example: when this is set to 30%, the new MachineSet can be scaled
up immediately when the rolling update starts, such that the total
number of old and new machines do not exceed 130% of desired
machines. Once old machines have been killed, new MachineSet can
be scaled up further, ensuring that total number of machines running
at any time during the update is at most 130% of desired machines.

MachineDeploymentV1Beta1DeprecatedStatus

MachineDeploymentV1Beta1DeprecatedStatus groups all the status fields that are deprecated and will be removed when support for v1beta1 will be dropped. See https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/proposals/20240916-improve-status-in-CAPI-resources.md for more context.

Appears In:
Field Description Default Validation

conditions Conditions

conditions defines current service state of the MachineDeployment.

Deprecated: This field is deprecated and is going to be removed when support for v1beta1 will be dropped. Please see https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/proposals/20240916-improve-status-in-CAPI-resources.md for more details.

updatedReplicas integer

updatedReplicas is the total number of non-terminated machines targeted by this deployment
that have the desired template spec.

Deprecated: This field is deprecated and is going to be removed when support for v1beta1 will be dropped. Please see https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/proposals/20240916-improve-status-in-CAPI-resources.md for more details.

readyReplicas integer

readyReplicas is the total number of ready machines targeted by this deployment.

Deprecated: This field is deprecated and is going to be removed when support for v1beta1 will be dropped. Please see https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/proposals/20240916-improve-status-in-CAPI-resources.md for more details.

availableReplicas integer

availableReplicas is the total number of available machines (ready for at least minReadySeconds)
targeted by this deployment.

Deprecated: This field is deprecated and is going to be removed when support for v1beta1 will be dropped. Please see https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/proposals/20240916-improve-status-in-CAPI-resources.md for more details.

unavailableReplicas integer

unavailableReplicas is the total number of unavailable machines targeted by this deployment.
This is the total number of machines that are still required for
the deployment to have 100% available capacity. They may either
be machines that are running but not yet available or machines
that still have not been created.

Deprecated: This field is deprecated and is going to be removed when support for v1beta1 will be dropped. Please see https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/proposals/20240916-improve-status-in-CAPI-resources.md for more details.

MachineDeploymentVariables

MachineDeploymentVariables can be used to provide variables for a specific MachineDeployment.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

overrides ClusterVariable array

overrides can be used to override Cluster level variables.

MaxItems: 1000
MinItems: 1

MachineDeprecatedStatus

MachineDeprecatedStatus groups all the status fields that are deprecated and will be removed in a future version. See https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/proposals/20240916-improve-status-in-CAPI-resources.md for more context.

Appears In:
Field Description Default Validation

v1beta1 MachineV1Beta1DeprecatedStatus

v1beta1 groups all the status fields that are deprecated and will be removed when support for v1beta1 will be dropped.

Deprecated: This field is deprecated and is going to be removed when support for v1beta1 will be dropped. Please see https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/proposals/20240916-improve-status-in-CAPI-resources.md for more details.

MachineDrainRule

MachineDrainRule is the Schema for the MachineDrainRule API.

Field Description Default Validation

apiVersion string

cluster.x-k8s.io/v1beta2

kind string

MachineDrainRule

metadata ObjectMeta

Refer to Kubernetes API documentation for fields of metadata.

MinProperties: 1

spec MachineDrainRuleSpec

spec defines the spec of a MachineDrainRule.

MachineDrainRuleDrainBehavior

Underlying type: string

MachineDrainRuleDrainBehavior defines the drain behavior. Can be either "Drain", "Skip", or "WaitCompleted".

Validation:

  • Enum: [Drain Skip WaitCompleted]

Appears In:

MachineDrainRuleDrainConfig

MachineDrainRuleDrainConfig configures if and how Pods are drained.

Appears In:
Field Description Default Validation

behavior MachineDrainRuleDrainBehavior

behavior defines the drain behavior.
Can be either "Drain", "Skip", or "WaitCompleted".
"Drain" means that the Pods to which this MachineDrainRule applies will be drained.
If behavior is set to "Drain" the order in which Pods are drained can be configured
with the order field. When draining Pods of a Node the Pods will be grouped by order
and one group after another will be drained (by increasing order). Cluster API will
wait until all Pods of a group are terminated / removed from the Node before starting
with the next group.
"Skip" means that the Pods to which this MachineDrainRule applies will be skipped during drain.
"WaitCompleted" means that the pods to which this MachineDrainRule applies will never be evicted
and we wait for them to be completed, it is enforced that pods marked with this behavior always have Order=0.

Enum: [Drain Skip WaitCompleted]

order integer

order defines the order in which Pods are drained.
Pods with higher order are drained after Pods with lower order.
order can only be set if behavior is set to "Drain".
If order is not set, 0 will be used.
Valid values for order are from -2147483648 to 2147483647 (inclusive).

MachineDrainRuleMachineSelector

MachineDrainRuleMachineSelector defines to which Machines this MachineDrainRule should be applied.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

selector LabelSelector

selector is a label selector which selects Machines by their labels.
This field follows standard label selector semantics; if not present or
empty, it selects all Machines.

If clusterSelector is also set, then the selector as a whole selects
Machines matching selector belonging to Clusters selected by clusterSelector.
If clusterSelector is not set, it selects all Machines matching selector in
all Clusters.

clusterSelector LabelSelector

clusterSelector is a label selector which selects Machines by the labels of
their Clusters.
This field follows standard label selector semantics; if not present or
empty, it selects Machines of all Clusters.

If selector is also set, then the selector as a whole selects
Machines matching selector belonging to Clusters selected by clusterSelector.
If selector is not set, it selects all Machines belonging to Clusters
selected by clusterSelector.

MachineDrainRulePodSelector

MachineDrainRulePodSelector defines to which Pods this MachineDrainRule should be applied.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

selector LabelSelector

selector is a label selector which selects Pods by their labels.
This field follows standard label selector semantics; if not present or
empty, it selects all Pods.

If namespaceSelector is also set, then the selector as a whole selects
Pods matching selector in Namespaces selected by namespaceSelector.
If namespaceSelector is not set, it selects all Pods matching selector in
all Namespaces.

namespaceSelector LabelSelector

namespaceSelector is a label selector which selects Pods by the labels of
their Namespaces.
This field follows standard label selector semantics; if not present or
empty, it selects Pods of all Namespaces.

If selector is also set, then the selector as a whole selects
Pods matching selector in Namespaces selected by namespaceSelector.
If selector is not set, it selects all Pods in Namespaces selected by
namespaceSelector.

MachineDrainRuleSpec

MachineDrainRuleSpec defines the spec of a MachineDrainRule.

Appears In:
Field Description Default Validation

drain MachineDrainRuleDrainConfig

drain configures if and how Pods are drained.

machines MachineDrainRuleMachineSelector array

machines defines to which Machines this MachineDrainRule should be applied.

If machines is not set, the MachineDrainRule applies to all Machines in the Namespace.
If machines contains multiple selectors, the results are ORed.
Within a single Machine selector the results of selector and clusterSelector are ANDed.
Machines will be selected from all Clusters in the Namespace unless otherwise
restricted with the clusterSelector.

Example: Selects control plane Machines in all Clusters or
Machines with label "os" == "linux" in Clusters with label
"stage" == "production".

  • selector:
    matchExpressions:

  • key: cluster.x-k8s.io/control-plane
    operator: Exists

  • selector:
    matchLabels:
    os: linux
    clusterSelector:
    matchExpressions:

  • key: stage
    operator: In
    values:

  • production

MaxItems: 32
MinItems: 1
MinProperties: 1

pods MachineDrainRulePodSelector array

pods defines to which Pods this MachineDrainRule should be applied.

If pods is not set, the MachineDrainRule applies to all Pods in all Namespaces.
If pods contains multiple selectors, the results are ORed.
Within a single Pod selector the results of selector and namespaceSelector are ANDed.
Pods will be selected from all Namespaces unless otherwise
restricted with the namespaceSelector.

Example: Selects Pods with label "app" == "logging" in all Namespaces or
Pods with label "app" == "prometheus" in the "monitoring"
Namespace.

  • selector:
    matchExpressions:

  • key: app
    operator: In
    values:

  • logging

  • selector:
    matchLabels:
    app: prometheus
    namespaceSelector:
    matchLabels:
    kubernetes.io/metadata.name: monitoring

MaxItems: 32
MinItems: 1
MinProperties: 1

MachineHealthCheck

MachineHealthCheck is the Schema for the machinehealthchecks API.

Field Description Default Validation

apiVersion string

cluster.x-k8s.io/v1beta2

kind string

MachineHealthCheck

metadata ObjectMeta

Refer to Kubernetes API documentation for fields of metadata.

MinProperties: 1

spec MachineHealthCheckSpec

spec is the specification of machine health check policy

status MachineHealthCheckStatus

status is the most recently observed status of MachineHealthCheck resource

MinProperties: 1

MachineHealthCheckChecks

MachineHealthCheckChecks are the checks that are used to evaluate if a Machine is healthy.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

nodeStartupTimeoutSeconds integer

nodeStartupTimeoutSeconds allows to set the maximum time for MachineHealthCheck
to consider a Machine unhealthy if a corresponding Node isn’t associated
through a Spec.ProviderID field.

The duration set in this field is compared to the greatest of:
- Cluster’s infrastructure ready condition timestamp (if and when available)
- Control Plane’s initialized condition timestamp (if and when available)
- Machine’s infrastructure ready condition timestamp (if and when available)
- Machine’s metadata creation timestamp

Defaults to 10 minutes.
If you wish to disable this feature, set the value explicitly to 0.

Minimum: 0

unhealthyNodeConditions UnhealthyNodeCondition array

unhealthyNodeConditions contains a list of conditions that determine
whether a node is considered unhealthy. The conditions are combined in a
logical OR, i.e. if any of the conditions is met, the node is unhealthy.

MaxItems: 100
MinItems: 1

unhealthyMachineConditions UnhealthyMachineCondition array

unhealthyMachineConditions contains a list of the machine conditions that determine
whether a machine is considered unhealthy. The conditions are combined in a
logical OR, i.e. if any of the conditions is met, the machine is unhealthy.

MaxItems: 100
MinItems: 1

MachineHealthCheckDeprecatedStatus

MachineHealthCheckDeprecatedStatus groups all the status fields that are deprecated and will be removed in a future version. See https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/proposals/20240916-improve-status-in-CAPI-resources.md for more context.

Appears In:
Field Description Default Validation

v1beta1 MachineHealthCheckV1Beta1DeprecatedStatus

v1beta1 groups all the status fields that are deprecated and will be removed when support for v1beta1 will be dropped.

MachineHealthCheckRemediation

MachineHealthCheckRemediation configures if and how remediations are triggered if a Machine is unhealthy.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

triggerIf MachineHealthCheckRemediationTriggerIf

triggerIf configures if remediations are triggered.
If this field is not set, remediations are always triggered.

MinProperties: 1

templateRef MachineHealthCheckRemediationTemplateReference

templateRef is a reference to a remediation template
provided by an infrastructure provider.

This field is completely optional, when filled, the MachineHealthCheck controller
creates a new object from the template referenced and hands off remediation of the machine to
a controller that lives outside of Cluster API.

MachineHealthCheckRemediationTemplateReference

MachineHealthCheckRemediationTemplateReference is a reference to a remediation template.

Appears In:
Field Description Default Validation

kind string

kind of the remediation template.
kind must consist of alphanumeric characters or '-', start with an alphabetic character, and end with an alphanumeric character.

MaxLength: 63
MinLength: 1
Pattern: ^[a-zA-Z]([-a-zA-Z0-9]*[a-zA-Z0-9])?$

name string

name of the remediation template.
name must consist of lower case alphanumeric characters, '-' or '.', and must start and end with an alphanumeric character.

MaxLength: 253
MinLength: 1
Pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$

apiVersion string

apiVersion of the remediation template.
apiVersion must be fully qualified domain name followed by / and a version.
NOTE: This field must be kept in sync with the APIVersion of the remediation template.

MaxLength: 317
MinLength: 1
Pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*\/[a-z]([-a-z0-9]*[a-z0-9])?$

MachineHealthCheckRemediationTriggerIf

MachineHealthCheckRemediationTriggerIf configures if remediations are triggered.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

unhealthyLessThanOrEqualTo IntOrString

unhealthyLessThanOrEqualTo specifies that remediations are only triggered if the number of
unhealthy Machines is less than or equal to the configured value.
unhealthyInRange takes precedence if set.

unhealthyInRange string

unhealthyInRange specifies that remediations are only triggered if the number of
unhealthy Machines is in the configured range.
Takes precedence over unhealthyLessThanOrEqualTo.
Eg. "[3-5]" - This means that remediation will be allowed only when:
(a) there are at least 3 unhealthy Machines (and)
(b) there are at most 5 unhealthy Machines

MaxLength: 32
MinLength: 1
Pattern: ^\[[0-9]+-[0-9]+\]$

MachineHealthCheckSpec

MachineHealthCheckSpec defines the desired state of MachineHealthCheck.

Appears In:
Field Description Default Validation

clusterName string

clusterName is the name of the Cluster this object belongs to.

MaxLength: 63
MinLength: 1

selector LabelSelector

selector is a label selector to match machines whose health will be exercised

checks MachineHealthCheckChecks

checks are the checks that are used to evaluate if a Machine is healthy.

Independent of this configuration the MachineHealthCheck controller will always
flag Machines with cluster.x-k8s.io/remediate-machine annotation and
Machines with deleted Nodes as unhealthy.

Furthermore, if checks.nodeStartupTimeoutSeconds is not set it
is defaulted to 10 minutes and evaluated accordingly.

MinProperties: 1

remediation MachineHealthCheckRemediation

remediation configures if and how remediations are triggered if a Machine is unhealthy.

If remediation or remediation.triggerIf is not set,
remediation will always be triggered for unhealthy Machines.

If remediation or remediation.templateRef is not set,
the OwnerRemediated condition will be set on unhealthy Machines to trigger remediation via
the owner of the Machines, for example a MachineSet or a KubeadmControlPlane.

MinProperties: 1

MachineHealthCheckStatus

MachineHealthCheckStatus defines the observed state of MachineHealthCheck.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

conditions Condition array

conditions represents the observations of a MachineHealthCheck’s current state.
Known condition types are RemediationAllowed, Paused.

MaxItems: 32

expectedMachines integer

expectedMachines is the total number of machines counted by this machine health check

Minimum: 0

currentHealthy integer

currentHealthy is the total number of healthy machines counted by this machine health check

Minimum: 0

remediationsAllowed integer

remediationsAllowed is the number of further remediations allowed by this machine health check before
maxUnhealthy short circuiting will be applied

Minimum: 0

observedGeneration integer

observedGeneration is the latest generation observed by the controller.

Minimum: 1

targets string array

targets shows the current list of machines the machine health check is watching

MaxItems: 10000
items:MaxLength: 253
items:MinLength: 1

deprecated MachineHealthCheckDeprecatedStatus

deprecated groups all the status fields that are deprecated and will be removed when all the nested field are removed.

MachineHealthCheckV1Beta1DeprecatedStatus

MachineHealthCheckV1Beta1DeprecatedStatus groups all the status fields that are deprecated and will be removed when support for v1beta1 will be dropped. See https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/proposals/20240916-improve-status-in-CAPI-resources.md for more context.

Appears In:
Field Description Default Validation

conditions Conditions

conditions defines current service state of the MachineHealthCheck.

Deprecated: This field is deprecated and is going to be removed when support for v1beta1 will be dropped. Please see https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/proposals/20240916-improve-status-in-CAPI-resources.md for more details.

MachineInitializationStatus

MachineInitializationStatus provides observations of the Machine initialization process. NOTE: Fields in this struct are part of the Cluster API contract and are used to orchestrate initial Machine provisioning.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

infrastructureProvisioned boolean

infrastructureProvisioned is true when the infrastructure provider reports that Machine’s infrastructure is fully provisioned.
NOTE: this field is part of the Cluster API contract, and it is used to orchestrate provisioning.
The value of this field is never updated after provisioning is completed.

bootstrapDataSecretCreated boolean

bootstrapDataSecretCreated is true when the bootstrap provider reports that the Machine’s boostrap secret is created.
NOTE: this field is part of the Cluster API contract, and it is used to orchestrate provisioning.
The value of this field is never updated after provisioning is completed.

MachineNamingSpec

MachineNamingSpec allows changing the naming pattern used when creating Machines. Note: InfraMachines & BootstrapConfigs will use the same name as the corresponding Machines.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

template string

template defines the template to use for generating the names of the
Machine objects.
If not defined, it will fallback to {{ .machineSet.name }}-{{ .random }}.
If the generated name string exceeds 63 characters, it will be trimmed to
58 characters and will
get concatenated with a random suffix of length 5.
Length of the template string must not exceed 256 characters.
The template allows the following variables .cluster.name,
.machineSet.name and .random.
The variable .cluster.name retrieves the name of the cluster object
that owns the Machines being created.
The variable .machineSet.name retrieves the name of the MachineSet
object that owns the Machines being created.
The variable .random is substituted with random alphanumeric string,
without vowels, of length 5. This variable is required part of the
template. If not provided, validation will fail.

MaxLength: 256
MinLength: 1

MachineNodeReference

MachineNodeReference is a reference to the node running on the machine.

Appears In:
Field Description Default Validation

name string

name of the node.
name must consist of lower case alphanumeric characters, '-' or '.', and must start and end with an alphanumeric character.

MaxLength: 253
MinLength: 1
Pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$

MachineReadinessGate

MachineReadinessGate contains the type of a Machine condition to be used as a readiness gate.

Appears In:
Field Description Default Validation

conditionType string

conditionType refers to a condition with matching type in the Machine’s condition list.
If the conditions doesn’t exist, it will be treated as unknown.
Note: Both Cluster API conditions or conditions added by 3rd party controllers can be used as readiness gates.

MaxLength: 316
MinLength: 1
Pattern: ^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$

polarity ConditionPolarity

polarity of the conditionType specified in this readinessGate.
Valid values are Positive, Negative and omitted.
When omitted, the default behaviour will be Positive.
A positive polarity means that the condition should report a true status under normal conditions.
A negative polarity means that the condition should report a false status under normal conditions.

Enum: [Positive Negative]

MachineSet

MachineSet is the Schema for the machinesets API.

Field Description Default Validation

apiVersion string

cluster.x-k8s.io/v1beta2

kind string

MachineSet

metadata ObjectMeta

Refer to Kubernetes API documentation for fields of metadata.

MinProperties: 1

spec MachineSetSpec

spec is the desired state of MachineSet.

status MachineSetStatus

status is the observed state of MachineSet.

MinProperties: 1

MachineSetDeletionOrder

Underlying type: string

MachineSetDeletionOrder defines how priority is assigned to nodes to delete when downscaling a MachineSet. Defaults to "Random".

Validation:

  • Enum: [Random Newest Oldest]

Appears In:

MachineSetDeletionSpec

MachineSetDeletionSpec contains configuration options for MachineSet deletion.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

order MachineSetDeletionOrder

order defines the order in which Machines are deleted when downscaling.
Defaults to "Random". Valid values are "Random, "Newest", "Oldest"

Enum: [Random Newest Oldest]

MachineSetDeprecatedStatus

MachineSetDeprecatedStatus groups all the status fields that are deprecated and will be removed in a future version. See https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/proposals/20240916-improve-status-in-CAPI-resources.md for more context.

Appears In:
Field Description Default Validation

v1beta1 MachineSetV1Beta1DeprecatedStatus

v1beta1 groups all the status fields that are deprecated and will be removed when support for v1beta1 will be dropped.

MachineSetSpec

MachineSetSpec defines the desired state of MachineSet.

Appears In:
Field Description Default Validation

clusterName string

clusterName is the name of the Cluster this object belongs to.

MaxLength: 63
MinLength: 1

replicas integer

replicas is the number of desired replicas.
This is a pointer to distinguish between explicit zero and unspecified.

Defaults to:
* if the Kubernetes autoscaler min size and max size annotations are set:
- if it’s a new MachineSet, use min size
- if the replicas field of the old MachineSet is < min size, use min size
- if the replicas field of the old MachineSet is > max size, use max size
- if the replicas field of the old MachineSet is in the (min size, max size) range, keep the value from the oldMS
* otherwise use 1
Note: Defaulting will be run whenever the replicas field is not set:
* A new MachineSet is created with replicas not set.
* On an existing MachineSet the replicas field was first set and is now unset.
Those cases are especially relevant for the following Kubernetes autoscaler use cases:
* A new MachineSet is created and replicas should be managed by the autoscaler
* An existing MachineSet which initially wasn’t controlled by the autoscaler
should be later controlled by the autoscaler

selector LabelSelector

selector is a label query over machines that should match the replica count.
Label keys and values that must match in order to be controlled by this MachineSet.
It must match the machine template’s labels.
More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#label-selectors

template MachineTemplateSpec

template is the object that describes the machine that will be created if
insufficient replicas are detected.
Object references to custom resources are treated as templates.

machineNaming MachineNamingSpec

machineNaming allows changing the naming pattern used when creating Machines.
Note: InfraMachines & BootstrapConfigs will use the same name as the corresponding Machines.

MinProperties: 1

deletion MachineSetDeletionSpec

deletion contains configuration options for MachineSet deletion.

MinProperties: 1

MachineSetStatus

MachineSetStatus defines the observed state of MachineSet.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

conditions Condition array

conditions represents the observations of a MachineSet’s current state.
Known condition types are MachinesReady, MachinesUpToDate, ScalingUp, ScalingDown, Remediating, Deleting, Paused.

MaxItems: 32

selector string

selector is the same as the label selector but in the string format to avoid introspection
by clients. The string will be in the same format as the query-param syntax.
More info about label selectors: http://kubernetes.io/docs/user-guide/labels#label-selectors

MaxLength: 4096
MinLength: 1

replicas integer

replicas is the most recently observed number of replicas.

readyReplicas integer

readyReplicas is the number of ready replicas for this MachineSet. A machine is considered ready when Machine’s Ready condition is true.

availableReplicas integer

availableReplicas is the number of available replicas for this MachineSet. A machine is considered available when Machine’s Available condition is true.

upToDateReplicas integer

upToDateReplicas is the number of up-to-date replicas for this MachineSet. A machine is considered up-to-date when Machine’s UpToDate condition is true.

observedGeneration integer

observedGeneration reflects the generation of the most recently observed MachineSet.

Minimum: 1

deprecated MachineSetDeprecatedStatus

deprecated groups all the status fields that are deprecated and will be removed when all the nested field are removed.

MachineSetV1Beta1DeprecatedStatus

MachineSetV1Beta1DeprecatedStatus groups all the status fields that are deprecated and will be removed when support for v1beta1 will be dropped. See https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/proposals/20240916-improve-status-in-CAPI-resources.md for more context.

Appears In:
Field Description Default Validation

conditions Conditions

conditions defines current service state of the MachineSet.

Deprecated: This field is deprecated and is going to be removed when support for v1beta1 will be dropped. Please see https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/proposals/20240916-improve-status-in-CAPI-resources.md for more details.

failureReason MachineSetStatusError

failureReason will be set in the event that there is a terminal problem
reconciling the Machine and will contain a succinct value suitable
for machine interpretation.

In the event that there is a terminal problem reconciling the
replicas, both FailureReason and FailureMessage will be set. FailureReason
will be populated with a succinct value suitable for machine
interpretation, while FailureMessage will contain a more verbose
string suitable for logging and human consumption.

These fields should not be set for transitive errors that a
controller faces that are expected to be fixed automatically over
time (like service outages), but instead indicate that something is
fundamentally wrong with the MachineTemplate’s spec or the configuration of
the machine controller, and that manual intervention is required. Examples
of terminal errors would be invalid combinations of settings in the
spec, values that are unsupported by the machine controller, or the
responsible machine controller itself being critically misconfigured.

Any transient errors that occur during the reconciliation of Machines
can be added as events to the MachineSet object and/or logged in the
controller’s output.

Deprecated: This field is deprecated and is going to be removed when support for v1beta1 will be dropped. Please see https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/proposals/20240916-improve-status-in-CAPI-resources.md for more details.

failureMessage string

failureMessage will be set in the event that there is a terminal problem
reconciling the Machine and will contain a more verbose string suitable
for logging and human consumption.

Deprecated: This field is deprecated and is going to be removed when support for v1beta1 will be dropped. Please see https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/proposals/20240916-improve-status-in-CAPI-resources.md for more details.

MaxLength: 10240
MinLength: 1

fullyLabeledReplicas integer

fullyLabeledReplicas is the number of replicas that have labels matching the labels of the machine template of the MachineSet.

Deprecated: This field is deprecated and is going to be removed when support for v1beta1 will be dropped. Please see https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/proposals/20240916-improve-status-in-CAPI-resources.md for more details.

readyReplicas integer

readyReplicas is the number of ready replicas for this MachineSet. A machine is considered ready when the node has been created and is "Ready".

Deprecated: This field is deprecated and is going to be removed when support for v1beta1 will be dropped. Please see https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/proposals/20240916-improve-status-in-CAPI-resources.md for more details.

availableReplicas integer

availableReplicas is the number of available replicas (ready for at least minReadySeconds) for this MachineSet.

Deprecated: This field is deprecated and is going to be removed when support for v1beta1 will be dropped. Please see https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/proposals/20240916-improve-status-in-CAPI-resources.md for more details.

MachineSpec

MachineSpec defines the desired state of Machine.

Appears In:
Field Description Default Validation

clusterName string

clusterName is the name of the Cluster this object belongs to.

MaxLength: 63
MinLength: 1

bootstrap Bootstrap

bootstrap is a reference to a local struct which encapsulates
fields to configure the Machine’s bootstrapping mechanism.

infrastructureRef ContractVersionedObjectReference

infrastructureRef is a required reference to a custom resource
offered by an infrastructure provider.

version string

version defines the desired Kubernetes version.
This field is meant to be optionally used by bootstrap providers.

MaxLength: 256
MinLength: 1

providerID string

providerID is the identification ID of the machine provided by the provider.
This field must match the provider ID as seen on the node object corresponding to this machine.
This field is required by higher level consumers of cluster-api. Example use case is cluster autoscaler
with cluster-api as provider. Clean-up logic in the autoscaler compares machines to nodes to find out
machines at provider which could not get registered as Kubernetes nodes. With cluster-api as a
generic out-of-tree provider for autoscaler, this field is required by autoscaler to be
able to have a provider view of the list of machines. Another list of nodes is queried from the k8s apiserver
and then a comparison is done to find out unregistered machines and are marked for delete.
This field will be set by the actuators and consumed by higher level entities like autoscaler that will
be interfacing with cluster-api as generic provider.

MaxLength: 512
MinLength: 1

failureDomain string

failureDomain is the failure domain the machine will be created in.
Must match the name of a FailureDomain from the Cluster status.

MaxLength: 256
MinLength: 1

minReadySeconds integer

minReadySeconds is the minimum number of seconds for which a Machine should be ready before considering it available.
Defaults to 0 (Machine will be considered available as soon as the Machine is ready)

Minimum: 0

readinessGates MachineReadinessGate array

readinessGates specifies additional conditions to include when evaluating Machine Ready condition.

This field can be used e.g. by Cluster API control plane providers to extend the semantic of the
Ready condition for the Machine they control, like the kubeadm control provider adding ReadinessGates
for the APIServerPodHealthy, SchedulerPodHealthy conditions, etc.

Another example are external controllers, e.g. responsible to install special software/hardware on the Machines;
they can include the status of those components with a new condition and add this condition to ReadinessGates.

Note
 In case readinessGates conditions start with the APIServer, ControllerManager, Scheduler prefix, and all those
readiness gates condition are reporting the same message, when computing the Machine’s Ready condition those
readinessGates will be replaced by a single entry reporting "Control plane components: " + message.
This helps to improve readability of conditions bubbling up to the Machine’s owner resource / to the Cluster).

MaxItems: 32
MinItems: 1

deletion MachineDeletionSpec

deletion contains configuration options for Machine deletion.

MinProperties: 1

taints MachineTaint array

taints are the node taints that Cluster API will manage.
This list is not necessarily complete: other Kubernetes components may add or remove other taints from nodes,
e.g. the node controller might add the node.kubernetes.io/not-ready taint.
Only those taints defined in this list will be added or removed by core Cluster API controllers.

There can be at most 64 taints.
A pod would have to tolerate all existing taints to run on the corresponding node.

Note
 This list is implemented as a "map" type, meaning that individual elements can be managed by different owners.

MaxItems: 64
MinItems: 1

MachineStatus

MachineStatus defines the observed state of Machine.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

conditions Condition array

conditions represents the observations of a Machine’s current state.
Known condition types are Available, Ready, UpToDate, BootstrapConfigReady, InfrastructureReady, NodeReady,
NodeHealthy, Updating, Deleting, Paused.
If a MachineHealthCheck is targeting this machine, also HealthCheckSucceeded, OwnerRemediated conditions are added.
Additionally control plane Machines controlled by KubeadmControlPlane will have following additional conditions:
APIServerPodHealthy, ControllerManagerPodHealthy, SchedulerPodHealthy, EtcdPodHealthy, EtcdMemberHealthy.

MaxItems: 32

initialization MachineInitializationStatus

initialization provides observations of the Machine initialization process.
NOTE: Fields in this struct are part of the Cluster API contract and are used to orchestrate initial Machine provisioning.

MinProperties: 1

nodeRef MachineNodeReference

nodeRef will point to the corresponding Node if it exists.

nodeInfo NodeSystemInfo

nodeInfo is a set of ids/uuids to uniquely identify the node.
More info: https://kubernetes.io/docs/concepts/nodes/node/#info

lastUpdated Time

lastUpdated identifies when the phase of the Machine last transitioned.

addresses MachineAddresses

addresses is a list of addresses assigned to the machine.
This field is copied from the infrastructure provider reference.

MaxItems: 128

phase string

phase represents the current phase of machine actuation.

Enum: [Pending Provisioning Provisioned Running Updating Deleting Deleted Failed Unknown]

certificatesExpiryDate Time

certificatesExpiryDate is the expiry date of the machine certificates.
This value is only set for control plane machines.

observedGeneration integer

observedGeneration is the latest generation observed by the controller.

Minimum: 1

deletion MachineDeletionStatus

deletion contains information relating to removal of the Machine.
Only present when the Machine has a deletionTimestamp and drain or wait for volume detach started.

deprecated MachineDeprecatedStatus

deprecated groups all the status fields that are deprecated and will be removed when all the nested field are removed.

MachineTaint

MachineTaint defines a taint equivalent to corev1.Taint, but additionally having a propagation field.

Appears In:
Field Description Default Validation

key string

key is the taint key to be applied to a node.
Must be a valid qualified name of maximum size 63 characters
with an optional subdomain prefix of maximum size 253 characters,
separated by a /.

MaxLength: 317
MinLength: 1
Pattern: ^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*\/)?([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9]$

value string

value is the taint value corresponding to the taint key.
It must be a valid label value of maximum size 63 characters.

MaxLength: 63
MinLength: 1
Pattern: ^(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])?$

effect TaintEffect

effect is the effect for the taint. Valid values are NoSchedule, PreferNoSchedule and NoExecute.

Enum: [NoSchedule PreferNoSchedule NoExecute]

propagation MachineTaintPropagation

propagation defines how this taint should be propagated to nodes.
Valid values are 'Always' and 'OnInitialization'.
Always: The taint will be continuously reconciled. If it is not set for a node, it will be added during reconciliation.
OnInitialization: The taint will be added during node initialization. If it gets removed from the node later on it will not get added again.

Enum: [Always OnInitialization]

MachineTaintPropagation

Underlying type: string

MachineTaintPropagation defines when a taint should be propagated to nodes.

Validation:

  • Enum: [Always OnInitialization]

Appears In:

MachineTemplateSpec

MachineTemplateSpec describes the data needed to create a Machine from a template.

Appears In:
Field Description Default Validation

metadata ObjectMeta

Refer to Kubernetes API documentation for fields of metadata.

MinProperties: 1

spec MachineSpec

spec is the specification of the desired behavior of the machine.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status

MachineV1Beta1DeprecatedStatus

MachineV1Beta1DeprecatedStatus groups all the status fields that are deprecated and will be removed when support for v1beta1 will be dropped. See https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/proposals/20240916-improve-status-in-CAPI-resources.md for more context.

Appears In:
Field Description Default Validation

conditions Conditions

conditions defines current service state of the Machine.

Deprecated: This field is deprecated and is going to be removed when support for v1beta1 will be dropped. Please see https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/proposals/20240916-improve-status-in-CAPI-resources.md for more details.

failureReason MachineStatusError

failureReason will be set in the event that there is a terminal problem
reconciling the Machine and will contain a succinct value suitable
for machine interpretation.

This field should not be set for transitive errors that a controller
faces that are expected to be fixed automatically over
time (like service outages), but instead indicate that something is
fundamentally wrong with the Machine’s spec or the configuration of
the controller, and that manual intervention is required. Examples
of terminal errors would be invalid combinations of settings in the
spec, values that are unsupported by the controller, or the
responsible controller itself being critically misconfigured.

Any transient errors that occur during the reconciliation of Machines
can be added as events to the Machine object and/or logged in the
controller’s output.

Deprecated: This field is deprecated and is going to be removed when support for v1beta1 will be dropped. Please see https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/proposals/20240916-improve-status-in-CAPI-resources.md for more details.

failureMessage string

failureMessage will be set in the event that there is a terminal problem
reconciling the Machine and will contain a more verbose string suitable
for logging and human consumption.

This field should not be set for transitive errors that a controller
faces that are expected to be fixed automatically over
time (like service outages), but instead indicate that something is
fundamentally wrong with the Machine’s spec or the configuration of
the controller, and that manual intervention is required. Examples
of terminal errors would be invalid combinations of settings in the
spec, values that are unsupported by the controller, or the
responsible controller itself being critically misconfigured.

Any transient errors that occur during the reconciliation of Machines
can be added as events to the Machine object and/or logged in the
controller’s output.

Deprecated: This field is deprecated and is going to be removed when support for v1beta1 will be dropped. Please see https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/proposals/20240916-improve-status-in-CAPI-resources.md for more details.

MaxLength: 10240
MinLength: 1

NetworkRanges

NetworkRanges represents ranges of network addresses.

Appears In:
Field Description Default Validation

cidrBlocks string array

cidrBlocks is a list of CIDR blocks.

MaxItems: 100
MinItems: 1
items:MaxLength: 43
items:MinLength: 1

ObjectMeta

ObjectMeta is metadata that all persisted resources must have, which includes all objects users must create. This is a copy of customizable fields from metav1.ObjectMeta.

ObjectMeta is embedded in Machine.Spec, MachineDeployment.Template and MachineSet.Template, which are not top-level Kubernetes objects. Given that metav1.ObjectMeta has lots of special cases and read-only fields which end up in the generated CRD validation, having it as a subset simplifies the API and some issues that can impact user experience.

During the [upgrade to controller-tools@v2](https://github.com/kubernetes-sigs/cluster-api/pull/1054) for v1alpha2, we noticed a failure would occur running Cluster API test suite against the new CRDs, specifically spec.metadata.creationTimestamp in body must be of type string: "null". The investigation showed that controller-tools@v2 behaves differently than its previous version when handling types from [metav1](k8s.io/apimachinery/pkg/apis/meta/v1) package.

In more details, we found that embedded (non-top level) types that embedded metav1.ObjectMeta had validation properties, including for creationTimestamp (metav1.Time). The metav1.Time type specifies a custom json marshaller that, when IsZero() is true, returns null which breaks validation because the field isn’t marked as nullable.

In future versions, controller-tools@v2 might allow overriding the type and validation for embedded types. When that happens, this hack should be revisited.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

labels object (keys:string, values:string)

labels is a map of string keys and values that can be used to organize and categorize
(scope and select) objects. May match selectors of replication controllers
and services.
More info: http://kubernetes.io/docs/user-guide/labels

annotations object (keys:string, values:string)

annotations is an unstructured key value map stored with a resource that may be
set by external tools to store and retrieve arbitrary metadata. They are not
queryable and should be preserved when modifying objects.
More info: http://kubernetes.io/docs/user-guide/annotations

PatchDefinition

PatchDefinition defines a patch which is applied to customize the referenced templates.

Appears In:
Field Description Default Validation

selector PatchSelector

selector defines on which templates the patch should be applied.

jsonPatches JSONPatch array

jsonPatches defines the patches which should be applied on the templates
matching the selector.
Note: Patches will be applied in the order of the array.

MaxItems: 100
MinItems: 1

PatchSelector

PatchSelector defines on which templates the patch should be applied. Note: Matching on APIVersion and Kind is mandatory, to enforce that the patches are written for the correct version. The version of the references in the ClusterClass may be automatically updated during reconciliation if there is a newer version for the same contract. Note: The results of selection based on the individual fields are ANDed.

Appears In:
Field Description Default Validation

apiVersion string

apiVersion filters templates by apiVersion.
apiVersion must be fully qualified domain name followed by / and a version.

MaxLength: 317
MinLength: 1
Pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*\/[a-z]([-a-z0-9]*[a-z0-9])?$

kind string

kind filters templates by kind.
kind must consist of alphanumeric characters or '-', start with an alphabetic character, and end with an alphanumeric character.

MaxLength: 63
MinLength: 1
Pattern: ^[a-zA-Z]([-a-zA-Z0-9]*[a-zA-Z0-9])?$

matchResources PatchSelectorMatch

matchResources selects templates based on where they are referenced.

MinProperties: 1

PatchSelectorMatch

PatchSelectorMatch selects templates based on where they are referenced. Note: The selector must match at least one template. Note: The results of selection based on the individual fields are ORed.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

controlPlane boolean

controlPlane selects templates referenced in .spec.ControlPlane.
Note: this will match the controlPlane and also the controlPlane
machineInfrastructure (depending on the kind and apiVersion).

infrastructureCluster boolean

infrastructureCluster selects templates referenced in .spec.infrastructure.

machineDeploymentClass PatchSelectorMatchMachineDeploymentClass

machineDeploymentClass selects templates referenced in specific MachineDeploymentClasses in
.spec.workers.machineDeployments.

PatchSelectorMatchMachineDeploymentClass

PatchSelectorMatchMachineDeploymentClass selects templates referenced in specific MachineDeploymentClasses in .spec.workers.machineDeployments.

Appears In:
Field Description Default Validation

names string array

names selects templates by class names.

MaxItems: 100
items:MaxLength: 256
items:MinLength: 1

Topology

Topology encapsulates the information of the managed resources.

Appears In:
Field Description Default Validation

classRef ClusterClassRef

classRef is the ref to the ClusterClass that should be used for the topology.

version string

version is the Kubernetes version of the cluster.

MaxLength: 256
MinLength: 1

controlPlane ControlPlaneTopology

controlPlane describes the cluster control plane.

MinProperties: 1

workers WorkersTopology

workers encapsulates the different constructs that form the worker nodes
for the cluster.

MinProperties: 1

variables ClusterVariable array

variables can be used to customize the Cluster through
patches. They must comply to the corresponding
VariableClasses defined in the ClusterClass.

MaxItems: 1000
MinItems: 1

UnhealthyMachineCondition

UnhealthyMachineCondition represents a Machine condition type and value with a timeout specified as a duration. When the named condition has been in the given status for at least the timeout value, a machine is considered unhealthy.

Appears In:
Field Description Default Validation

type string

type of Machine condition

MaxLength: 316
MinLength: 1
Pattern: ^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$

status ConditionStatus

status of the condition, one of True, False, Unknown.

Enum: [True False Unknown]

timeoutSeconds integer

timeoutSeconds is the duration that a machine must be in a given status for,
after which the machine is considered unhealthy.
For example, with a value of "3600", the machine must match the status
for at least 1 hour before being considered unhealthy.

Minimum: 0

UnhealthyNodeCondition

UnhealthyNodeCondition represents a Node condition type and value with a timeout specified as a duration. When the named condition has been in the given status for at least the timeout value, a node is considered unhealthy.

Appears In:
Field Description Default Validation

type NodeConditionType

type of Node condition

MinLength: 1
Type: string

status ConditionStatus

status of the condition, one of True, False, Unknown.

MinLength: 1
Type: string

timeoutSeconds integer

timeoutSeconds is the duration that a node must be in a given status for,
after which the node is considered unhealthy.
For example, with a value of "3600", the node must match the status
for at least 1 hour before being considered unhealthy.

Minimum: 0

VariableSchema

VariableSchema defines the schema of a variable.

Appears In:
Field Description Default Validation

openAPIV3Schema JSONSchemaProps

openAPIV3Schema defines the schema of a variable via OpenAPI v3
schema. The schema is a subset of the schema used in
Kubernetes CRDs.

MinProperties: 1

VariableSchemaMetadata

Underlying type: struct{Labels map[string]string "json:\"labels,omitempty\""; Annotations map[string]string "json:\"annotations,omitempty\""}

VariableSchemaMetadata is the metadata of a variable or a nested field within a variable. It can be used to add additional data for higher level tools.

Validation:

  • MinProperties: 1

Appears In:

WorkersClass

WorkersClass is a collection of deployment classes.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

machineDeployments MachineDeploymentClass array

machineDeployments is a list of machine deployment classes that can be used to create
a set of worker nodes.

MaxItems: 100
MinItems: 1

WorkersStatus

WorkersStatus groups all the observations about workers current state.

Appears In:
Field Description Default Validation

desiredReplicas integer

desiredReplicas is the total number of desired worker machines in this cluster.

replicas integer

replicas is the total number of worker machines in this cluster.
NOTE: replicas also includes machines still being provisioned or being deleted.

upToDateReplicas integer

upToDateReplicas is the number of up-to-date worker machines in this cluster. A machine is considered up-to-date when Machine’s UpToDate condition is true.

readyReplicas integer

readyReplicas is the total number of ready worker machines in this cluster. A machine is considered ready when Machine’s Ready condition is true.

availableReplicas integer

availableReplicas is the total number of available worker machines in this cluster. A machine is considered available when Machine’s Available condition is true.

WorkersTopology

WorkersTopology represents the different sets of worker nodes in the cluster.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

machineDeployments MachineDeploymentTopology array

machineDeployments is a list of machine deployments in the cluster.

MaxItems: 2000
MinItems: 1

bootstrap.cluster.x-k8s.io/v1beta1

Package v1beta1 contains API Schema definitions for the kubeadm v1beta1 API group.

Deprecated: This package is deprecated and is going to be removed when support for v1beta1 will be dropped.

Resource Types

APIEndpoint

APIEndpoint struct contains elements of API server instance deployed on a node.

Appears In:
Field Description Default Validation

advertiseAddress string

advertiseAddress sets the IP address for the API server to advertise.

MaxLength: 39
MinLength: 1

bindPort integer

bindPort sets the secure port for the API Server to bind to.
Defaults to 6443.

APIServer

APIServer holds settings necessary for API server deployments in the cluster.

Appears In:
Field Description Default Validation

extraArgs object (keys:string, values:string)

extraArgs is an extra set of flags to pass to the control plane component.

extraVolumes HostPathMount array

extraVolumes is an extra set of host volumes, mounted to the control plane component.

MaxItems: 100

extraEnvs EnvVar array

extraEnvs is an extra set of environment variables to pass to the control plane component.
Environment variables passed using ExtraEnvs will override any existing environment variables, or *_proxy environment variables that kubeadm adds by default.
This option takes effect only on Kubernetes >=1.31.0.

MaxItems: 100

certSANs string array

certSANs sets extra Subject Alternative Names for the API Server signing cert.

MaxItems: 100
items:MaxLength: 253
items:MinLength: 1

timeoutForControlPlane Duration

timeoutForControlPlane controls the timeout that we use for API server to appear

BootstrapToken

BootstrapToken describes one bootstrap token, stored as a Secret in the cluster.

Appears In:
Field Description Default Validation

token BootstrapTokenString

token is used for establishing bidirectional trust between nodes and control-planes.
Used for joining nodes in the cluster.

Type: string

description string

description sets a human-friendly message why this token exists and what it’s used
for, so other administrators can know its purpose.

MaxLength: 512
MinLength: 1

ttl Duration

ttl defines the time to live for this token. Defaults to 24h.
Expires and TTL are mutually exclusive.

expires Time

expires specifies the timestamp when this token expires. Defaults to being set
dynamically at runtime based on the TTL. Expires and TTL are mutually exclusive.

usages string array

usages describes the ways in which this token can be used. Can by default be used
for establishing bidirectional trust, but that can be changed here.

MaxItems: 100
items:MaxLength: 256
items:MinLength: 1

groups string array

groups specifies the extra groups that this token will authenticate as when/if
used for authentication

MaxItems: 100
items:MaxLength: 256
items:MinLength: 1

BootstrapTokenDiscovery

BootstrapTokenDiscovery is used to set the options for bootstrap token based discovery.

Appears In:
Field Description Default Validation

token string

token is a token used to validate cluster information
fetched from the control-plane.

MaxLength: 512
MinLength: 1

apiServerEndpoint string

apiServerEndpoint is an IP or domain name to the API server from which info will be fetched.

MaxLength: 512
MinLength: 1

caCertHashes string array

caCertHashes specifies a set of public key pins to verify
when token-based discovery is used. The root CA found during discovery
must match one of these values. Specifying an empty set disables root CA
pinning, which can be unsafe. Each hash is specified as "<type>:<value>",
where the only currently supported type is "sha256". This is a hex-encoded
SHA-256 hash of the Subject Public Key Info (SPKI) object in DER-encoded
ASN.1. These hashes can be calculated using, for example, OpenSSL:
openssl x509 -pubkey -in ca.crt openssl rsa -pubin -outform der 2>&/dev/null | openssl dgst -sha256 -hex

MaxItems: 100
items:MaxLength: 512
items:MinLength: 1

unsafeSkipCAVerification boolean

unsafeSkipCAVerification allows token-based discovery
without CA verification via CACertHashes. This can weaken
the security of kubeadm since other nodes can impersonate the control-plane.

BootstrapTokenString

BootstrapTokenString is a token of the format abcdef.abcdef0123456789 that is used for both validation of the practically of the API server from a joining node’s point of view and as an authentication method for the node in the bootstrap phase of "kubeadm join". This token is and should be short-lived.

Validation:

  • Type: string

Appears In:

ClusterConfiguration

ClusterConfiguration contains cluster-wide configuration for a kubeadm cluster.

Appears In:
Field Description Default Validation

etcd Etcd

etcd holds configuration for etcd.
NB: This value defaults to a Local (stacked) etcd

networking Networking

networking holds configuration for the networking topology of the cluster.
NB: This value defaults to the Cluster object spec.clusterNetwork.

kubernetesVersion string

kubernetesVersion is the target version of the control plane.
NB: This value defaults to the Machine object spec.version

MaxLength: 256
MinLength: 1

controlPlaneEndpoint string

controlPlaneEndpoint sets a stable IP address or DNS name for the control plane; it
can be a valid IP address or a RFC-1123 DNS subdomain, both with optional TCP port.
In case the ControlPlaneEndpoint is not specified, the AdvertiseAddress + BindPort
are used; in case the ControlPlaneEndpoint is specified but without a TCP port,
the BindPort is used.
Possible usages are:
e.g. In a cluster with more than one control plane instances, this field should be
assigned the address of the external load balancer in front of the
control plane instances.
e.g. in environments with enforced node recycling, the ControlPlaneEndpoint
could be used for assigning a stable DNS to the control plane.
NB: This value defaults to the first value in the Cluster object status.apiEndpoints array.

MaxLength: 512
MinLength: 1

apiServer APIServer

apiServer contains extra settings for the API server control plane component

controllerManager ControlPlaneComponent

controllerManager contains extra settings for the controller manager control plane component

scheduler ControlPlaneComponent

scheduler contains extra settings for the scheduler control plane component

dns DNS

dns defines the options for the DNS add-on installed in the cluster.

certificatesDir string

certificatesDir specifies where to store or look for all required certificates.
NB: if not provided, this will default to /etc/kubernetes/pki

MaxLength: 512
MinLength: 1

imageRepository string

imageRepository sets the container registry to pull images from.
* If not set, the default registry of kubeadm will be used, i.e.
* registry.k8s.io (new registry): >= v1.22.17, >= v1.23.15, >= v1.24.9, >= v1.25.0
* k8s.gcr.io (old registry): all older versions
Please note that when imageRepository is not set we don’t allow upgrades to
versions >= v1.22.0 which use the old registry (k8s.gcr.io). Please use
a newer patch version with the new registry instead (i.e. >= v1.22.17,
>= v1.23.15, >= v1.24.9, >= v1.25.0).
* If the version is a CI build (kubernetes version starts with ci/ or ci-cross/)
gcr.io/k8s-staging-ci-images will be used as a default for control plane components
and for kube-proxy, while registry.k8s.io will be used for all the other images.

MaxLength: 512
MinLength: 1

featureGates object (keys:string, values:boolean)

featureGates enabled by the user.

clusterName string

clusterName is the cluster name

MaxLength: 63
MinLength: 1

ContainerLinuxConfig

ContainerLinuxConfig contains CLC-specific configuration.

We use a structured type here to allow adding additional fields, for example 'version'.

Appears In:
Field Description Default Validation

additionalConfig string

additionalConfig contains additional configuration to be merged with the Ignition
configuration generated by the bootstrapper controller. More info: https://coreos.github.io/ignition/operator-notes/#config-merging

The data format is documented here: https://kinvolk.io/docs/flatcar-container-linux/latest/provisioning/cl-config/

MaxLength: 32768
MinLength: 1

strict boolean

strict controls if AdditionalConfig should be strictly parsed. If so, warnings are treated as errors.

ControlPlaneComponent

ControlPlaneComponent holds settings common to control plane component of the cluster.

Appears In:
Field Description Default Validation

extraArgs object (keys:string, values:string)

extraArgs is an extra set of flags to pass to the control plane component.

extraVolumes HostPathMount array

extraVolumes is an extra set of host volumes, mounted to the control plane component.

MaxItems: 100

extraEnvs EnvVar array

extraEnvs is an extra set of environment variables to pass to the control plane component.
Environment variables passed using ExtraEnvs will override any existing environment variables, or *_proxy environment variables that kubeadm adds by default.
This option takes effect only on Kubernetes >=1.31.0.

MaxItems: 100

DNS

DNS defines the DNS addon that should be used in the cluster.

Appears In:
Field Description Default Validation

imageRepository string

imageRepository sets the container registry to pull images from.
if not set, the ImageRepository defined in ClusterConfiguration will be used instead.

MaxLength: 512
MinLength: 1

imageTag string

imageTag allows to specify a tag for the image.
In case this value is set, kubeadm does not change automatically the version of the above components during upgrades.

MaxLength: 256
MinLength: 1

Discovery

Discovery specifies the options for the kubelet to use during the TLS Bootstrap process.

Appears In:
Field Description Default Validation

bootstrapToken BootstrapTokenDiscovery

bootstrapToken is used to set the options for bootstrap token based discovery
BootstrapToken and File are mutually exclusive

file FileDiscovery

file is used to specify a file or URL to a kubeconfig file from which to load cluster information
BootstrapToken and File are mutually exclusive

tlsBootstrapToken string

tlsBootstrapToken is a token used for TLS bootstrapping.
If .BootstrapToken is set, this field is defaulted to .BootstrapToken.Token, but can be overridden.
If .File is set, this field must be set in case the KubeConfigFile does not contain any other authentication information

MaxLength: 512
MinLength: 1

timeout Duration

timeout modifies the discovery timeout

DiskSetup

DiskSetup defines input for generated disk_setup and fs_setup in cloud-init.

Appears In:
Field Description Default Validation

partitions Partition array

partitions specifies the list of the partitions to setup.

MaxItems: 100

filesystems Filesystem array

filesystems specifies the list of file systems to setup.

MaxItems: 100

Encoding

Underlying type: string

Encoding specifies the cloud-init file encoding.

Validation:

  • Enum: [base64 gzip gzip+base64]

Appears In:

EnvVar

EnvVar represents an environment variable present in a Container.

Appears In:
Field Description Default Validation

name string

Name of the environment variable.
May consist of any printable ASCII characters except '='.

value string

Variable references $(VAR_NAME) are expanded
using the previously defined environment variables in the container and
any service environment variables. If a variable cannot be resolved,
the reference in the input string will be unchanged. Double are reduced + to a single $, which allows for escaping the $(VAR_NAME) syntax: i.e. + "(VAR_NAME)" will produce the string literal "$(VAR_NAME)".
Escaped references will never be expanded, regardless of whether the variable
exists or not.
Defaults to "".

valueFrom EnvVarSource

Source for the environment variable’s value. Cannot be used if value is not empty.

Etcd

Etcd contains elements describing Etcd configuration.

Appears In:
Field Description Default Validation

local LocalEtcd

local provides configuration knobs for configuring the local etcd instance
Local and External are mutually exclusive

external ExternalEtcd

external describes how to connect to an external etcd cluster
Local and External are mutually exclusive

ExternalEtcd

ExternalEtcd describes an external etcd cluster. Kubeadm has no knowledge of where certificate files live and they must be supplied.

Appears In:
Field Description Default Validation

endpoints string array

endpoints of etcd members. Required for ExternalEtcd.

MaxItems: 50
items:MaxLength: 512
items:MinLength: 1

caFile string

caFile is an SSL Certificate Authority file used to secure etcd communication.
Required if using a TLS connection.

MaxLength: 512
MinLength: 1

certFile string

certFile is an SSL certification file used to secure etcd communication.
Required if using a TLS connection.

MaxLength: 512
MinLength: 1

keyFile string

keyFile is an SSL key file used to secure etcd communication.
Required if using a TLS connection.

MaxLength: 512
MinLength: 1

File

File defines the input for generating write_files in cloud-init.

Appears In:
Field Description Default Validation

path string

path specifies the full path on disk where to store the file.

MaxLength: 512
MinLength: 1

owner string

owner specifies the ownership of the file, e.g. "root:root".

MaxLength: 256
MinLength: 1

permissions string

permissions specifies the permissions to assign to the file, e.g. "0640".

MaxLength: 16
MinLength: 1

encoding Encoding

encoding specifies the encoding of the file contents.

Enum: [base64 gzip gzip+base64]

append boolean

append specifies whether to append Content to existing file if Path exists.

content string

content is the actual content of the file.

MaxLength: 10240
MinLength: 1

contentFrom FileSource

contentFrom is a referenced source of content to populate the file.

FileDiscovery

FileDiscovery is used to specify a file or URL to a kubeconfig file from which to load cluster information.

Appears In:
Field Description Default Validation

kubeConfigPath string

kubeConfigPath is used to specify the actual file path or URL to the kubeconfig file from which to load cluster information

MaxLength: 512
MinLength: 1

kubeConfig FileDiscoveryKubeConfig

kubeConfig is used (optionally) to generate a KubeConfig based on the KubeadmConfig’s information.
The file is generated at the path specified in KubeConfigPath.

Host address (server field) information is automatically populated based on the Cluster’s ControlPlaneEndpoint.
Certificate Authority (certificate-authority-data field) is gathered from the cluster’s CA secret.

FileDiscoveryKubeConfig

FileDiscoveryKubeConfig contains elements describing how to generate the kubeconfig for bootstrapping.

Appears In:
Field Description Default Validation

cluster KubeConfigCluster

cluster contains information about how to communicate with the kubernetes cluster.

By default the following fields are automatically populated:
- Server with the Cluster’s ControlPlaneEndpoint.
- CertificateAuthorityData with the Cluster’s CA certificate.

user KubeConfigUser

user contains information that describes identity information.
This is used to tell the kubernetes cluster who you are.

FileSource

FileSource is a union of all possible external source types for file data. Only one field may be populated in any given instance. Developers adding new sources of data for target systems should add them here.

Appears In:
Field Description Default Validation

secret SecretFileSource

secret represents a secret that should populate this file.

Filesystem

Filesystem defines the file systems to be created.

Appears In:
Field Description Default Validation

device string

device specifies the device name

MaxLength: 256
MinLength: 1

filesystem string

filesystem specifies the file system type.

MaxLength: 128
MinLength: 1

label string

label specifies the file system label to be used. If set to None, no label is used.

MaxLength: 512
MinLength: 1

partition string

partition specifies the partition to use. The valid options are: "auto|any", "auto", "any", "none", and <NUM>, where NUM is the actual partition number.

MaxLength: 128
MinLength: 1

overwrite boolean

overwrite defines whether or not to overwrite any existing filesystem.
If true, any pre-existing file system will be destroyed. Use with Caution.

replaceFS string

replaceFS is a special directive, used for Microsoft Azure that instructs cloud-init to replace a file system of <FS_TYPE>.
NOTE: unless you define a label, this requires the use of the 'any' partition directive.

MaxLength: 128
MinLength: 1

extraOpts string array

extraOpts defined extra options to add to the command for creating the file system.

MaxItems: 100
items:MaxLength: 256
items:MinLength: 1

Format

Underlying type: string

Format specifies the output format of the bootstrap data

Validation:

  • Enum: [cloud-config ignition]

Appears In:

HostPathMount

HostPathMount contains elements describing volumes that are mounted from the host.

Appears In:
Field Description Default Validation

name string

name of the volume inside the pod template.

MaxLength: 512
MinLength: 1

hostPath string

hostPath is the path in the host that will be mounted inside
the pod.

MaxLength: 512
MinLength: 1

mountPath string

mountPath is the path inside the pod where hostPath will be mounted.

MaxLength: 512
MinLength: 1

readOnly boolean

readOnly controls write access to the volume

pathType HostPathType

pathType is the type of the HostPath.

IgnitionSpec

IgnitionSpec contains Ignition specific configuration.

Appears In:
Field Description Default Validation

containerLinuxConfig ContainerLinuxConfig

containerLinuxConfig contains CLC specific configuration.

ImageMeta

ImageMeta allows to customize the image used for components that are not originated from the Kubernetes/Kubernetes release process.

Appears In:
Field Description Default Validation

imageRepository string

imageRepository sets the container registry to pull images from.
if not set, the ImageRepository defined in ClusterConfiguration will be used instead.

MaxLength: 512
MinLength: 1

imageTag string

imageTag allows to specify a tag for the image.
In case this value is set, kubeadm does not change automatically the version of the above components during upgrades.

MaxLength: 256
MinLength: 1

InitConfiguration

InitConfiguration contains a list of elements that is specific "kubeadm init"-only runtime information.

Appears In:
Field Description Default Validation

bootstrapTokens BootstrapToken array

bootstrapTokens is respected at kubeadm init time and describes a set of Bootstrap Tokens to create.
This information IS NOT uploaded to the kubeadm cluster configmap, partly because of its sensitive nature

MaxItems: 100

nodeRegistration NodeRegistrationOptions

nodeRegistration holds fields that relate to registering the new control-plane node to the cluster.
When used in the context of control plane nodes, NodeRegistration should remain consistent
across both InitConfiguration and JoinConfiguration

localAPIEndpoint APIEndpoint

localAPIEndpoint represents the endpoint of the API server instance that’s deployed on this control plane node
In HA setups, this differs from ClusterConfiguration.ControlPlaneEndpoint in the sense that ControlPlaneEndpoint
is the global endpoint for the cluster, which then loadbalances the requests to each individual API server. This
configuration object lets you customize what IP/DNS name and port the local API server advertises it’s accessible
on. By default, kubeadm tries to auto-detect the IP of the default interface and use that, but in case that process
fails you may set the desired value here.

skipPhases string array

skipPhases is a list of phases to skip during command execution.
The list of phases can be obtained with the "kubeadm init --help" command.
This option takes effect only on Kubernetes >=1.22.0.

MaxItems: 50
items:MaxLength: 256
items:MinLength: 1

patches Patches

patches contains options related to applying patches to components deployed by kubeadm during
"kubeadm init". The minimum kubernetes version needed to support Patches is v1.22

JoinConfiguration

JoinConfiguration contains elements describing a particular node.

Appears In:
Field Description Default Validation

nodeRegistration NodeRegistrationOptions

nodeRegistration holds fields that relate to registering the new control-plane node to the cluster.
When used in the context of control plane nodes, NodeRegistration should remain consistent
across both InitConfiguration and JoinConfiguration

caCertPath string

caCertPath is the path to the SSL certificate authority used to
secure comunications between node and control-plane.
Defaults to "/etc/kubernetes/pki/ca.crt".

MaxLength: 512
MinLength: 1

discovery Discovery

discovery specifies the options for the kubelet to use during the TLS Bootstrap process

controlPlane JoinControlPlane

controlPlane defines the additional control plane instance to be deployed on the joining node.
If nil, no additional control plane instance will be deployed.

skipPhases string array

skipPhases is a list of phases to skip during command execution.
The list of phases can be obtained with the "kubeadm init --help" command.
This option takes effect only on Kubernetes >=1.22.0.

MaxItems: 50
items:MaxLength: 256
items:MinLength: 1

patches Patches

patches contains options related to applying patches to components deployed by kubeadm during
"kubeadm join". The minimum kubernetes version needed to support Patches is v1.22

JoinControlPlane

JoinControlPlane contains elements describing an additional control plane instance to be deployed on the joining node.

Appears In:
Field Description Default Validation

localAPIEndpoint APIEndpoint

localAPIEndpoint represents the endpoint of the API server instance to be deployed on this node.

KubeConfigAuthExec

KubeConfigAuthExec specifies a command to provide client credentials. The command is exec’d and outputs structured stdout holding credentials.

See the client.authentication.k8s.io API group for specifications of the exact input and output format.

Appears In:
Field Description Default Validation

command string

command to execute.

MaxLength: 1024
MinLength: 1

args string array

args is the arguments to pass to the command when executing it.

MaxItems: 100
items:MaxLength: 512
items:MinLength: 1

env KubeConfigAuthExecEnv array

env defines additional environment variables to expose to the process. These
are unioned with the host’s environment, as well as variables client-go uses
to pass argument to the plugin.

MaxItems: 100

apiVersion string

apiVersion is preferred input version of the ExecInfo. The returned ExecCredentials MUST use
the same encoding version as the input.
Defaults to client.authentication.k8s.io/v1 if not set.

MaxLength: 512
MinLength: 1

provideClusterInfo boolean

provideClusterInfo determines whether or not to provide cluster information,
which could potentially contain very large CA data, to this exec plugin as a
part of the KUBERNETES_EXEC_INFO environment variable. By default, it is set
to false. Package k8s.io/client-go/tools/auth/exec provides helper methods for
reading this environment variable.

KubeConfigAuthExecEnv

Underlying type: struct{Name string "json:\"name\""; Value string "json:\"value\""}

KubeConfigAuthExecEnv is used for setting environment variables when executing an exec-based credential plugin.

Appears In:

KubeConfigAuthProvider

KubeConfigAuthProvider holds the configuration for a specified auth provider.

Appears In:
Field Description Default Validation

name string

name is the name of the authentication plugin.

MaxLength: 256
MinLength: 1

config object (keys:string, values:string)

config holds the parameters for the authentication plugin.

KubeConfigCluster

KubeConfigCluster contains information about how to communicate with a kubernetes cluster.

Adapted from clientcmdv1.Cluster.

Appears In:
Field Description Default Validation

server string

server is the address of the kubernetes cluster (https://hostname:port).

Defaults to https:// + Cluster.Spec.ControlPlaneEndpoint.

MaxLength: 512
MinLength: 1

tlsServerName string

tlsServerName is used to check server certificate. If TLSServerName is empty, the hostname used to contact the server is used.

MaxLength: 512
MinLength: 1

insecureSkipTLSVerify boolean

insecureSkipTLSVerify skips the validity check for the server’s certificate. This will make your HTTPS connections insecure.

certificateAuthorityData integer array

certificateAuthorityData contains PEM-encoded certificate authority certificates.

Defaults to the Cluster’s CA certificate if empty.

MaxLength: 51200
MinLength: 1

proxyURL string

proxyURL is the URL to the proxy to be used for all requests made by this
client. URLs with "http", "https", and "socks5" schemes are supported. If
this configuration is not provided or the empty string, the client
attempts to construct a proxy configuration from http_proxy and
https_proxy environment variables. If these environment variables are not
set, the client does not attempt to proxy requests.

socks5 proxying does not currently support spdy streaming endpoints (exec,
attach, port forward).

MaxLength: 512
MinLength: 1

KubeConfigUser

KubeConfigUser contains information that describes identity information. This is used to tell the kubernetes cluster who you are.

Either authProvider or exec must be filled.

Adapted from clientcmdv1.AuthInfo.

Appears In:
Field Description Default Validation

authProvider KubeConfigAuthProvider

authProvider specifies a custom authentication plugin for the kubernetes cluster.

exec KubeConfigAuthExec

exec specifies a custom exec-based authentication plugin for the kubernetes cluster.

KubeadmConfig

KubeadmConfig is the Schema for the kubeadmconfigs API.

Field Description Default Validation

apiVersion string

bootstrap.cluster.x-k8s.io/v1beta1

kind string

KubeadmConfig

metadata ObjectMeta

Refer to Kubernetes API documentation for fields of metadata.

MinProperties: 1

spec KubeadmConfigSpec

spec is the desired state of KubeadmConfig.

status KubeadmConfigStatus

status is the observed state of KubeadmConfig.

KubeadmConfigSpec

KubeadmConfigSpec defines the desired state of KubeadmConfig. Either ClusterConfiguration and InitConfiguration should be defined or the JoinConfiguration should be defined.

Appears In:
Field Description Default Validation

clusterConfiguration ClusterConfiguration

clusterConfiguration along with InitConfiguration are the configurations necessary for the init command

initConfiguration InitConfiguration

initConfiguration along with ClusterConfiguration are the configurations necessary for the init command

joinConfiguration JoinConfiguration

joinConfiguration is the kubeadm configuration for the join command

files File array

files specifies extra files to be passed to user_data upon creation.

MaxItems: 200

diskSetup DiskSetup

diskSetup specifies options for the creation of partition tables and file systems on devices.

mounts MountPoints array

mounts specifies a list of mount points to be setup.

MaxItems: 100
items:MaxLength: 512
items:MinLength: 1

bootCommands string array

bootCommands specifies extra commands to run very early in the boot process via the cloud-init bootcmd
module. bootcmd will run on every boot, 'cloud-init-per' command can be used to make bootcmd run exactly
once. This is typically run in the cloud-init.service systemd unit. This has no effect in Ignition.

MaxItems: 1000
items:MaxLength: 10240
items:MinLength: 1

preKubeadmCommands string array

preKubeadmCommands specifies extra commands to run before kubeadm runs.
With cloud-init, this is prepended to the runcmd module configuration, and is typically executed in
the cloud-final.service systemd unit. In Ignition, this is prepended to /etc/kubeadm.sh.

MaxItems: 1000
items:MaxLength: 10240
items:MinLength: 1

postKubeadmCommands string array

postKubeadmCommands specifies extra commands to run after kubeadm runs.
With cloud-init, this is appended to the runcmd module configuration, and is typically executed in
the cloud-final.service systemd unit. In Ignition, this is appended to /etc/kubeadm.sh.

MaxItems: 1000
items:MaxLength: 10240
items:MinLength: 1

users User array

users specifies extra users to add

MaxItems: 100

ntp NTP

ntp specifies NTP configuration

format Format

format specifies the output format of the bootstrap data

Enum: [cloud-config ignition]

verbosity integer

verbosity is the number for the kubeadm log level verbosity.
It overrides the --v flag in kubeadm commands.

useExperimentalRetryJoin boolean

useExperimentalRetryJoin replaces a basic kubeadm command with a shell
script with retries for joins.

This is meant to be an experimental temporary workaround on some environments
where joins fail due to timing (and other issues). The long term goal is to add retries to
kubeadm proper and use that functionality.

This will add about 40KB to userdata

For more information, refer to https://github.com/kubernetes-sigs/cluster-api/pull/2763#discussion_r397306055.

Deprecated: This experimental fix is no longer needed and this field will be removed in a future release.
When removing also remove from staticcheck exclude-rules for SA1019 in golangci.yml

ignition IgnitionSpec

ignition contains Ignition specific configuration.

KubeadmConfigStatus

KubeadmConfigStatus defines the observed state of KubeadmConfig.

Appears In:
Field Description Default Validation

ready boolean

ready indicates the BootstrapData field is ready to be consumed

dataSecretName string

dataSecretName is the name of the secret that stores the bootstrap data script.

MaxLength: 253
MinLength: 1

failureReason string

failureReason will be set on non-retryable errors

Deprecated: This field is deprecated and is going to be removed when support for v1beta1 will be dropped. Please see https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/proposals/20240916-improve-status-in-CAPI-resources.md for more details.

MaxLength: 256
MinLength: 1

failureMessage string

failureMessage will be set on non-retryable errors

Deprecated: This field is deprecated and is going to be removed when support for v1beta1 will be dropped. Please see https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/proposals/20240916-improve-status-in-CAPI-resources.md for more details.

MaxLength: 10240
MinLength: 1

observedGeneration integer

observedGeneration is the latest generation observed by the controller.

conditions Conditions

conditions defines current service state of the KubeadmConfig.

v1beta2 KubeadmConfigV1Beta2Status

v1beta2 groups all the fields that will be added or modified in KubeadmConfig’s status with the V1Beta2 version.

KubeadmConfigTemplate

KubeadmConfigTemplate is the Schema for the kubeadmconfigtemplates API.

Field Description Default Validation

apiVersion string

bootstrap.cluster.x-k8s.io/v1beta1

kind string

KubeadmConfigTemplate

metadata ObjectMeta

Refer to Kubernetes API documentation for fields of metadata.

MinProperties: 1

spec KubeadmConfigTemplateSpec

spec is the desired state of KubeadmConfigTemplate.

KubeadmConfigTemplateResource

KubeadmConfigTemplateResource defines the Template structure.

Appears In:
Field Description Default Validation

metadata ObjectMeta

Refer to Kubernetes API documentation for fields of metadata.

spec KubeadmConfigSpec

spec is the desired state of KubeadmConfig.

KubeadmConfigTemplateSpec

KubeadmConfigTemplateSpec defines the desired state of KubeadmConfigTemplate.

Appears In:
Field Description Default Validation

template KubeadmConfigTemplateResource

template defines the desired state of KubeadmConfigTemplate.

KubeadmConfigV1Beta2Status

KubeadmConfigV1Beta2Status groups all the fields that will be added or modified in KubeadmConfig with the V1Beta2 version. See https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/proposals/20240916-improve-status-in-CAPI-resources.md for more context.

Appears In:
Field Description Default Validation

conditions Condition array

conditions represents the observations of a KubeadmConfig’s current state.
Known condition types are Ready, DataSecretAvailable, CertificatesAvailable.

MaxItems: 32

LocalEtcd

LocalEtcd describes that kubeadm should run an etcd cluster locally.

Appears In:
Field Description Default Validation

imageRepository string

imageRepository sets the container registry to pull images from.
if not set, the ImageRepository defined in ClusterConfiguration will be used instead.

MaxLength: 512
MinLength: 1

imageTag string

imageTag allows to specify a tag for the image.
In case this value is set, kubeadm does not change automatically the version of the above components during upgrades.

MaxLength: 256
MinLength: 1

dataDir string

dataDir is the directory etcd will place its data.
Defaults to "/var/lib/etcd".

MaxLength: 512
MinLength: 1

extraArgs object (keys:string, values:string)

extraArgs are extra arguments provided to the etcd binary
when run inside a static pod.

extraEnvs EnvVar array

extraEnvs is an extra set of environment variables to pass to the control plane component.
Environment variables passed using ExtraEnvs will override any existing environment variables, or *_proxy environment variables that kubeadm adds by default.
This option takes effect only on Kubernetes >=1.31.0.

MaxItems: 100

serverCertSANs string array

serverCertSANs sets extra Subject Alternative Names for the etcd server signing cert.

MaxItems: 100
items:MaxLength: 253
items:MinLength: 1

peerCertSANs string array

peerCertSANs sets extra Subject Alternative Names for the etcd peer signing cert.

MaxItems: 100
items:MaxLength: 253
items:MinLength: 1

MountPoints

Underlying type: string array

MountPoints defines input for generated mounts in cloud-init.

Validation:

  • items:MaxLength: 512

  • items:MinLength: 1

Appears In:

NTP

NTP defines input for generated ntp in cloud-init.

Appears In:
Field Description Default Validation

servers string array

servers specifies which NTP servers to use

MaxItems: 100
items:MaxLength: 512
items:MinLength: 1

enabled boolean

enabled specifies whether NTP should be enabled

Networking

Networking contains elements describing cluster’s networking configuration.

Appears In:
Field Description Default Validation

serviceSubnet string

serviceSubnet is the subnet used by k8s services.
Defaults to a comma-delimited string of the Cluster object’s spec.clusterNetwork.pods.cidrBlocks, or
to "10.96.0.0/12" if that’s unset.

MaxLength: 1024
MinLength: 1

podSubnet string

podSubnet is the subnet used by pods.
If unset, the API server will not allocate CIDR ranges for every node.
Defaults to a comma-delimited string of the Cluster object’s spec.clusterNetwork.services.cidrBlocks if that is set

MaxLength: 1024
MinLength: 1

dnsDomain string

dnsDomain is the dns domain used by k8s services. Defaults to "cluster.local".

MaxLength: 253
MinLength: 1

NodeRegistrationOptions

NodeRegistrationOptions holds fields that relate to registering a new control-plane or node to the cluster, either via "kubeadm init" or "kubeadm join". Note: The NodeRegistrationOptions struct has to be kept in sync with the structs in MarshalJSON.

Appears In:
Field Description Default Validation

name string

name is the .Metadata.Name field of the Node API object that will be created in this kubeadm init or kubeadm join operation.
This field is also used in the CommonName field of the kubelet’s client certificate to the API server.
Defaults to the hostname of the node if not provided.

MaxLength: 253
MinLength: 1

criSocket string

criSocket is used to retrieve container runtime info. This information will be annotated to the Node API object, for later re-use

MaxLength: 512
MinLength: 1

taints Taint array

taints specifies the taints the Node API object should be registered with. If this field is unset, i.e. nil, in the kubeadm init process
it will be defaulted to []v1.Taint{'node-role.kubernetes.io/master=""'}. If you don’t want to taint your control-plane node, set this field to an
empty slice, i.e. taints: [] in the YAML file. This field is solely used for Node registration.

MaxItems: 100

kubeletExtraArgs object (keys:string, values:string)

kubeletExtraArgs passes through extra arguments to the kubelet. The arguments here are passed to the kubelet command line via the environment file
kubeadm writes at runtime for the kubelet to source. This overrides the generic base-level configuration in the kubelet-config-1.X ConfigMap
Flags have higher priority when parsing. These values are local and specific to the node kubeadm is executing on.

ignorePreflightErrors string array

ignorePreflightErrors provides a slice of pre-flight errors to be ignored when the current node is registered.

MaxItems: 50
items:MaxLength: 512
items:MinLength: 1

imagePullPolicy string

imagePullPolicy specifies the policy for image pulling
during kubeadm "init" and "join" operations. The value of
this field must be one of "Always", "IfNotPresent" or
"Never". Defaults to "IfNotPresent". This can be used only
with Kubernetes version equal to 1.22 and later.

Enum: [Always IfNotPresent Never]

imagePullSerial boolean

imagePullSerial specifies if image pulling performed by kubeadm must be done serially or in parallel.
This option takes effect only on Kubernetes >=1.31.0.
Default: true (defaulted in kubeadm)

Partition

Partition defines how to create and layout a partition.

Appears In:
Field Description Default Validation

device string

device is the name of the device.

MaxLength: 256
MinLength: 1

layout boolean

layout specifies the device layout.
If it is true, a single partition will be created for the entire device.
When layout is false, it means don’t partition or ignore existing partitioning.

overwrite boolean

overwrite describes whether to skip checks and create the partition if a partition or filesystem is found on the device.
Use with caution. Default is 'false'.

tableType string

tableType specifies the tupe of partition table. The following are supported:
'mbr': default and setups a MS-DOS partition table
'gpt': setups a GPT partition table

Enum: [mbr gpt]

PasswdSource

PasswdSource is a union of all possible external source types for passwd data. Only one field may be populated in any given instance. Developers adding new sources of data for target systems should add them here.

Appears In:
Field Description Default Validation

secret SecretPasswdSource

secret represents a secret that should populate this password.

Patches

Patches contains options related to applying patches to components deployed by kubeadm.

Appears In:
Field Description Default Validation

directory string

directory is a path to a directory that contains files named "target[suffix][+patchtype].extension".
For example, "kube-apiserver0+merge.yaml" or just "etcd.json". "target" can be one of
"kube-apiserver", "kube-controller-manager", "kube-scheduler", "etcd". "patchtype" can be one
of "strategic" "merge" or "json" and they match the patch formats supported by kubectl.
The default "patchtype" is "strategic". "extension" must be either "json" or "yaml".
"suffix" is an optional string that can be used to determine which patches are applied
first alpha-numerically.
These files can be written into the target directory via KubeadmConfig.Files which
specifies additional files to be created on the machine, either with content inline or
by referencing a secret.

MaxLength: 512
MinLength: 1

SecretFileSource

SecretFileSource adapts a Secret into a FileSource.

The contents of the target Secret’s Data field will be presented as files using the keys in the Data field as the file names.

Appears In:
Field Description Default Validation

name string

name of the secret in the KubeadmBootstrapConfig’s namespace to use.

MaxLength: 253
MinLength: 1

key string

key is the key in the secret’s data map for this value.

MaxLength: 256
MinLength: 1

SecretPasswdSource

SecretPasswdSource adapts a Secret into a PasswdSource.

The contents of the target Secret’s Data field will be presented as passwd using the keys in the Data field as the file names.

Appears In:
Field Description Default Validation

name string

name of the secret in the KubeadmBootstrapConfig’s namespace to use.

MaxLength: 253
MinLength: 1

key string

key is the key in the secret’s data map for this value.

MaxLength: 256
MinLength: 1

User

User defines the input for a generated user in cloud-init.

Appears In:
Field Description Default Validation

name string

name specifies the user name

MaxLength: 256
MinLength: 1

gecos string

gecos specifies the gecos to use for the user

MaxLength: 256
MinLength: 1

groups string

groups specifies the additional groups for the user

MaxLength: 256
MinLength: 1

homeDir string

homeDir specifies the home directory to use for the user

MaxLength: 256
MinLength: 1

inactive boolean

inactive specifies whether to mark the user as inactive

shell string

shell specifies the user’s shell

MaxLength: 256
MinLength: 1

passwd string

passwd specifies a hashed password for the user

MaxLength: 256
MinLength: 1

passwdFrom PasswdSource

passwdFrom is a referenced source of passwd to populate the passwd.

primaryGroup string

primaryGroup specifies the primary group for the user

MaxLength: 256
MinLength: 1

lockPassword boolean

lockPassword specifies if password login should be disabled

sudo string

sudo specifies a sudo role for the user

MaxLength: 256
MinLength: 1

sshAuthorizedKeys string array

sshAuthorizedKeys specifies a list of ssh authorized keys for the user

MaxItems: 100
items:MaxLength: 2048
items:MinLength: 1

bootstrap.cluster.x-k8s.io/v1beta2

Package v1beta2 contains API Schema definitions for the kubeadm v1beta2 API group.

Resource Types

APIEndpoint

APIEndpoint struct contains elements of API server instance deployed on a node.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

advertiseAddress string

advertiseAddress sets the IP address for the API server to advertise.

MaxLength: 39
MinLength: 1

bindPort integer

bindPort sets the secure port for the API Server to bind to.
Defaults to 6443.

Minimum: 1

APIServer

APIServer holds settings necessary for API server deployments in the cluster.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

extraArgs Arg array

extraArgs is a list of args to pass to the control plane component.
The arg name must match the command line flag name except without leading dash(es).
Extra arguments will override existing default arguments set by kubeadm.

MaxItems: 100
MinItems: 1

extraVolumes HostPathMount array

extraVolumes is an extra set of host volumes, mounted to the control plane component.

MaxItems: 100
MinItems: 1

extraEnvs EnvVar

extraEnvs is an extra set of environment variables to pass to the control plane component.
Environment variables passed using ExtraEnvs will override any existing environment variables, or *_proxy environment variables that kubeadm adds by default.
This option takes effect only on Kubernetes >=1.31.0.

MaxItems: 100
MinItems: 1

certSANs string array

certSANs sets extra Subject Alternative Names for the API Server signing cert.

MaxItems: 100
MinItems: 1
items:MaxLength: 253
items:MinLength: 1

Arg

Arg represents an argument with a name and a value.

Appears In:
Field Description Default Validation

name string

name is the Name of the extraArg.

MaxLength: 256
MinLength: 1

value string

value is the Value of the extraArg.

MaxLength: 1024
MinLength: 0

BootstrapToken

BootstrapToken describes one bootstrap token, stored as a Secret in the cluster.

Appears In:
Field Description Default Validation

token BootstrapTokenString

token is used for establishing bidirectional trust between nodes and control-planes.
Used for joining nodes in the cluster.

MaxLength: 23
MinLength: 1
Type: string

description string

description sets a human-friendly message why this token exists and what it’s used
for, so other administrators can know its purpose.

MaxLength: 512
MinLength: 1

ttlSeconds integer

ttlSeconds defines the time to live for this token. Defaults to 24h.
Expires and ttlSeconds are mutually exclusive.

Minimum: 0

expires Time

expires specifies the timestamp when this token expires. Defaults to being set
dynamically at runtime based on the ttlSeconds. Expires and ttlSeconds are mutually exclusive.

usages string array

usages describes the ways in which this token can be used. Can by default be used
for establishing bidirectional trust, but that can be changed here.

MaxItems: 100
MinItems: 1
items:MaxLength: 256
items:MinLength: 1

groups string array

groups specifies the extra groups that this token will authenticate as when/if
used for authentication

MaxItems: 100
MinItems: 1
items:MaxLength: 256
items:MinLength: 1

BootstrapTokenDiscovery

BootstrapTokenDiscovery is used to set the options for bootstrap token based discovery.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

token string

token is a token used to validate cluster information
fetched from the control-plane.

MaxLength: 512
MinLength: 1

apiServerEndpoint string

apiServerEndpoint is an IP or domain name to the API server from which info will be fetched.

MaxLength: 512
MinLength: 1

caCertHashes string array

caCertHashes specifies a set of public key pins to verify
when token-based discovery is used. The root CA found during discovery
must match one of these values. Specifying an empty set disables root CA
pinning, which can be unsafe. Each hash is specified as "<type>:<value>",
where the only currently supported type is "sha256". This is a hex-encoded
SHA-256 hash of the Subject Public Key Info (SPKI) object in DER-encoded
ASN.1. These hashes can be calculated using, for example, OpenSSL:
openssl x509 -pubkey -in ca.crt openssl rsa -pubin -outform der 2>&/dev/null | openssl dgst -sha256 -hex

MaxItems: 100
MinItems: 1
items:MaxLength: 512
items:MinLength: 1

unsafeSkipCAVerification boolean

unsafeSkipCAVerification allows token-based discovery
without CA verification via CACertHashes. This can weaken
the security of kubeadm since other nodes can impersonate the control-plane.

BootstrapTokenString

BootstrapTokenString is a token of the format abcdef.abcdef0123456789 that is used for both validation of the practically of the API server from a joining node’s point of view and as an authentication method for the node in the bootstrap phase of "kubeadm join". This token is and should be short-lived.

Validation:

  • MaxLength: 23

  • MinLength: 1

  • Type: string

Appears In:

ClusterConfiguration

ClusterConfiguration contains cluster-wide configuration for a kubeadm cluster.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

etcd Etcd

etcd holds configuration for etcd.
NB: This value defaults to a Local (stacked) etcd

MinProperties: 1

controlPlaneEndpoint string

controlPlaneEndpoint sets a stable IP address or DNS name for the control plane; it
can be a valid IP address or a RFC-1123 DNS subdomain, both with optional TCP port.
In case the ControlPlaneEndpoint is not specified, the AdvertiseAddress + BindPort
are used; in case the ControlPlaneEndpoint is specified but without a TCP port,
the BindPort is used.
Possible usages are:
e.g. In a cluster with more than one control plane instances, this field should be
assigned the address of the external load balancer in front of the
control plane instances.
e.g. in environments with enforced node recycling, the ControlPlaneEndpoint
could be used for assigning a stable DNS to the control plane.
NB: This value defaults to the first value in the Cluster object status.apiEndpoints array.

MaxLength: 512
MinLength: 1

apiServer APIServer

apiServer contains extra settings for the API server control plane component

MinProperties: 1

controllerManager ControllerManager

controllerManager contains extra settings for the controller manager control plane component

MinProperties: 1

scheduler Scheduler

scheduler contains extra settings for the scheduler control plane component

MinProperties: 1

dns DNS

dns defines the options for the DNS add-on installed in the cluster.

MinProperties: 1

certificatesDir string

certificatesDir specifies where to store or look for all required certificates.
NB: if not provided, this will default to /etc/kubernetes/pki

MaxLength: 512
MinLength: 1

imageRepository string

imageRepository sets the container registry to pull images from.
If not set, the default registry of kubeadm will be used (registry.k8s.io).

MaxLength: 512
MinLength: 1

featureGates object (keys:string, values:boolean)

featureGates enabled by the user.

certificateValidityPeriodDays integer

certificateValidityPeriodDays specifies the validity period for non-CA certificates generated by kubeadm.
If not specified, kubeadm will use a default of 365 days (1 year).
This field is only supported with Kubernetes v1.31 or above.

Maximum: 1095
Minimum: 1

caCertificateValidityPeriodDays integer

caCertificateValidityPeriodDays specifies the validity period for CA certificates generated by Cluster API.
If not specified, Cluster API will use a default of 3650 days (10 years).
This field cannot be modified.

Maximum: 36500
Minimum: 1

encryptionAlgorithm EncryptionAlgorithmType

encryptionAlgorithm holds the type of asymmetric encryption algorithm used for keys and certificates.
Can be one of "RSA-2048", "RSA-3072", "RSA-4096", "ECDSA-P256" or "ECDSA-P384".
For Kubernetes 1.34 or above, "ECDSA-P384" is supported.
If not specified, Cluster API will use RSA-2048 as default.
When this field is modified every certificate generated afterward will use the new
encryptionAlgorithm. Existing CA certificates and service account keys are not rotated.
This field is only supported with Kubernetes v1.31 or above.

Enum: [ECDSA-P256 ECDSA-P384 RSA-2048 RSA-3072 RSA-4096]

ContainerLinuxConfig

ContainerLinuxConfig contains CLC-specific configuration.

We use a structured type here to allow adding additional fields, for example 'version'.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

additionalConfig string

additionalConfig contains additional configuration to be merged with the Ignition
configuration generated by the bootstrapper controller. More info: https://coreos.github.io/ignition/operator-notes/#config-merging

The data format is documented here: https://kinvolk.io/docs/flatcar-container-linux/latest/provisioning/cl-config/

MaxLength: 32768
MinLength: 1

strict boolean

strict controls if AdditionalConfig should be strictly parsed. If so, warnings are treated as errors.

ControllerManager

ControllerManager holds settings necessary for controller-manager deployments in the cluster.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

extraArgs Arg array

extraArgs is a list of args to pass to the control plane component.
The arg name must match the command line flag name except without leading dash(es).
Extra arguments will override existing default arguments set by kubeadm.

MaxItems: 100
MinItems: 1

extraVolumes HostPathMount array

extraVolumes is an extra set of host volumes, mounted to the control plane component.

MaxItems: 100
MinItems: 1

extraEnvs EnvVar

extraEnvs is an extra set of environment variables to pass to the control plane component.
Environment variables passed using ExtraEnvs will override any existing environment variables, or *_proxy environment variables that kubeadm adds by default.
This option takes effect only on Kubernetes >=1.31.0.

MaxItems: 100
MinItems: 1

DNS

DNS defines the DNS addon that should be used in the cluster.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

imageRepository string

imageRepository sets the container registry to pull images from.
if not set, the ImageRepository defined in ClusterConfiguration will be used instead.

MaxLength: 512
MinLength: 1

imageTag string

imageTag allows to specify a tag for the image.
In case this value is set, kubeadm does not change automatically the version of the above components during upgrades.

MaxLength: 256
MinLength: 1

Discovery

Discovery specifies the options for the kubelet to use during the TLS Bootstrap process.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

bootstrapToken BootstrapTokenDiscovery

bootstrapToken is used to set the options for bootstrap token based discovery
BootstrapToken and File are mutually exclusive

MinProperties: 1

file FileDiscovery

file is used to specify a file or URL to a kubeconfig file from which to load cluster information
BootstrapToken and File are mutually exclusive

tlsBootstrapToken string

tlsBootstrapToken is a token used for TLS bootstrapping.
If .BootstrapToken is set, this field is defaulted to .BootstrapToken.Token, but can be overridden.
If .File is set, this field must be set in case the KubeConfigFile does not contain any other authentication information

MaxLength: 512
MinLength: 1

DiskSetup

DiskSetup defines input for generated disk_setup and fs_setup in cloud-init.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

partitions Partition array

partitions specifies the list of the partitions to setup.

MaxItems: 100

filesystems Filesystem array

filesystems specifies the list of file systems to setup.

MaxItems: 100

Encoding

Underlying type: string

Encoding specifies the cloud-init file encoding.

Validation:

  • Enum: [base64 gzip gzip+base64]

Appears In:

EncryptionAlgorithmType

Underlying type: string

EncryptionAlgorithmType can define an asymmetric encryption algorithm type.

Validation:

  • Enum: [ECDSA-P256 ECDSA-P384 RSA-2048 RSA-3072 RSA-4096]

Appears In:

EnvVar

EnvVar represents an environment variable present in a Container.

Appears In:
Field Description Default Validation

name string

Name of the environment variable.
May consist of any printable ASCII characters except '='.

value string

Variable references $(VAR_NAME) are expanded
using the previously defined environment variables in the container and
any service environment variables. If a variable cannot be resolved,
the reference in the input string will be unchanged. Double are reduced + to a single $, which allows for escaping the $(VAR_NAME) syntax: i.e. + "(VAR_NAME)" will produce the string literal "$(VAR_NAME)".
Escaped references will never be expanded, regardless of whether the variable
exists or not.
Defaults to "".

valueFrom EnvVarSource

Source for the environment variable’s value. Cannot be used if value is not empty.

Etcd

Etcd contains elements describing Etcd configuration.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

local LocalEtcd

local provides configuration knobs for configuring the local etcd instance
Local and External are mutually exclusive

MinProperties: 1

external ExternalEtcd

external describes how to connect to an external etcd cluster
Local and External are mutually exclusive

ExternalEtcd

ExternalEtcd describes an external etcd cluster. Kubeadm has no knowledge of where certificate files live and they must be supplied.

Appears In:
Field Description Default Validation

endpoints string array

endpoints of etcd members. Required for ExternalEtcd.

MaxItems: 50
MinItems: 1
items:MaxLength: 512
items:MinLength: 1

caFile string

caFile is an SSL Certificate Authority file used to secure etcd communication.
Required if using a TLS connection.

MaxLength: 512
MinLength: 1

certFile string

certFile is an SSL certification file used to secure etcd communication.
Required if using a TLS connection.

MaxLength: 512
MinLength: 1

keyFile string

keyFile is an SSL key file used to secure etcd communication.
Required if using a TLS connection.

MaxLength: 512
MinLength: 1

File

File defines the input for generating write_files in cloud-init.

Appears In:
Field Description Default Validation

path string

path specifies the full path on disk where to store the file.

MaxLength: 512
MinLength: 1

owner string

owner specifies the ownership of the file, e.g. "root:root".

MaxLength: 256
MinLength: 1

permissions string

permissions specifies the permissions to assign to the file, e.g. "0640".

MaxLength: 16
MinLength: 1

encoding Encoding

encoding specifies the encoding of the file contents.

Enum: [base64 gzip gzip+base64]

append boolean

append specifies whether to append Content to existing file if Path exists.

content string

content is the actual content of the file.

MaxLength: 10240
MinLength: 1

contentFrom FileSource

contentFrom is a referenced source of content to populate the file.

FileDiscovery

FileDiscovery is used to specify a file or URL to a kubeconfig file from which to load cluster information.

Appears In:
Field Description Default Validation

kubeConfigPath string

kubeConfigPath is used to specify the actual file path or URL to the kubeconfig file from which to load cluster information

MaxLength: 512
MinLength: 1

kubeConfig FileDiscoveryKubeConfig

kubeConfig is used (optionally) to generate a KubeConfig based on the KubeadmConfig’s information.
The file is generated at the path specified in KubeConfigPath.

Host address (server field) information is automatically populated based on the Cluster’s ControlPlaneEndpoint.
Certificate Authority (certificate-authority-data field) is gathered from the cluster’s CA secret.

FileDiscoveryKubeConfig

FileDiscoveryKubeConfig contains elements describing how to generate the kubeconfig for bootstrapping.

Appears In:
Field Description Default Validation

cluster KubeConfigCluster

cluster contains information about how to communicate with the kubernetes cluster.

By default the following fields are automatically populated:
- Server with the Cluster’s ControlPlaneEndpoint.
- CertificateAuthorityData with the Cluster’s CA certificate.

MinProperties: 1

user KubeConfigUser

user contains information that describes identity information.
This is used to tell the kubernetes cluster who you are.

MinProperties: 1

FileSource

FileSource is a union of all possible external source types for file data. Only one field may be populated in any given instance. Developers adding new sources of data for target systems should add them here.

Appears In:
Field Description Default Validation

secret SecretFileSource

secret represents a secret that should populate this file.

Filesystem

Filesystem defines the file systems to be created.

Appears In:
Field Description Default Validation

device string

device specifies the device name

MaxLength: 256
MinLength: 1

filesystem string

filesystem specifies the file system type.

MaxLength: 128
MinLength: 1

label string

label specifies the file system label to be used. If set to None, no label is used.

MaxLength: 512
MinLength: 1

partition string

partition specifies the partition to use. The valid options are: "auto|any", "auto", "any", "none", and <NUM>, where NUM is the actual partition number.

MaxLength: 128
MinLength: 1

overwrite boolean

overwrite defines whether or not to overwrite any existing filesystem.
If true, any pre-existing file system will be destroyed. Use with Caution.

replaceFS string

replaceFS is a special directive, used for Microsoft Azure that instructs cloud-init to replace a file system of <FS_TYPE>.
NOTE: unless you define a label, this requires the use of the 'any' partition directive.

MaxLength: 128
MinLength: 1

extraOpts string array

extraOpts defined extra options to add to the command for creating the file system.

MaxItems: 100
items:MaxLength: 256
items:MinLength: 1

Format

Underlying type: string

Format specifies the output format of the bootstrap data

Validation:

  • Enum: [cloud-config ignition]

Appears In:

HostPathMount

HostPathMount contains elements describing volumes that are mounted from the host.

Appears In:
Field Description Default Validation

name string

name of the volume inside the pod template.

MaxLength: 512
MinLength: 1

hostPath string

hostPath is the path in the host that will be mounted inside
the pod.

MaxLength: 512
MinLength: 1

mountPath string

mountPath is the path inside the pod where hostPath will be mounted.

MaxLength: 512
MinLength: 1

readOnly boolean

readOnly controls write access to the volume

pathType HostPathType

pathType is the type of the HostPath.

IgnitionSpec

IgnitionSpec contains Ignition specific configuration.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

containerLinuxConfig ContainerLinuxConfig

containerLinuxConfig contains CLC specific configuration.

MinProperties: 1

InitConfiguration

InitConfiguration contains a list of elements that is specific "kubeadm init"-only runtime information.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

bootstrapTokens BootstrapToken array

bootstrapTokens is respected at kubeadm init time and describes a set of Bootstrap Tokens to create.
This information IS NOT uploaded to the kubeadm cluster configmap, partly because of its sensitive nature

MaxItems: 100
MinItems: 1

nodeRegistration NodeRegistrationOptions

nodeRegistration holds fields that relate to registering the new control-plane node to the cluster.
When used in the context of control plane nodes, NodeRegistration should remain consistent
across both InitConfiguration and JoinConfiguration

MinProperties: 1

localAPIEndpoint APIEndpoint

localAPIEndpoint represents the endpoint of the API server instance that’s deployed on this control plane node
In HA setups, this differs from ClusterConfiguration.ControlPlaneEndpoint in the sense that ControlPlaneEndpoint
is the global endpoint for the cluster, which then loadbalances the requests to each individual API server. This
configuration object lets you customize what IP/DNS name and port the local API server advertises it’s accessible
on. By default, kubeadm tries to auto-detect the IP of the default interface and use that, but in case that process
fails you may set the desired value here.

MinProperties: 1

skipPhases string array

skipPhases is a list of phases to skip during command execution.
The list of phases can be obtained with the "kubeadm init --help" command.
This option takes effect only on Kubernetes >=1.22.0.

MaxItems: 50
MinItems: 1
items:MaxLength: 256
items:MinLength: 1

patches Patches

patches contains options related to applying patches to components deployed by kubeadm during
"kubeadm init". The minimum kubernetes version needed to support Patches is v1.22

MinProperties: 1

timeouts Timeouts

timeouts holds various timeouts that apply to kubeadm commands.

MinProperties: 1

JoinConfiguration

JoinConfiguration contains elements describing a particular node.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

nodeRegistration NodeRegistrationOptions

nodeRegistration holds fields that relate to registering the new control-plane node to the cluster.
When used in the context of control plane nodes, NodeRegistration should remain consistent
across both InitConfiguration and JoinConfiguration

MinProperties: 1

caCertPath string

caCertPath is the path to the SSL certificate authority used to
secure communications between node and control-plane.
Defaults to "/etc/kubernetes/pki/ca.crt".

MaxLength: 512
MinLength: 1

discovery Discovery

discovery specifies the options for the kubelet to use during the TLS Bootstrap process

MinProperties: 1

controlPlane JoinControlPlane

controlPlane defines the additional control plane instance to be deployed on the joining node.
If nil, no additional control plane instance will be deployed.

skipPhases string array

skipPhases is a list of phases to skip during command execution.
The list of phases can be obtained with the "kubeadm init --help" command.
This option takes effect only on Kubernetes >=1.22.0.

MaxItems: 50
MinItems: 1
items:MaxLength: 256
items:MinLength: 1

patches Patches

patches contains options related to applying patches to components deployed by kubeadm during
"kubeadm join". The minimum kubernetes version needed to support Patches is v1.22

MinProperties: 1

timeouts Timeouts

timeouts holds various timeouts that apply to kubeadm commands.

MinProperties: 1

JoinControlPlane

JoinControlPlane contains elements describing an additional control plane instance to be deployed on the joining node.

Appears In:
Field Description Default Validation

localAPIEndpoint APIEndpoint

localAPIEndpoint represents the endpoint of the API server instance to be deployed on this node.

MinProperties: 1

KubeConfigAuthExec

KubeConfigAuthExec specifies a command to provide client credentials. The command is exec’d and outputs structured stdout holding credentials.

See the client.authentication.k8s.io API group for specifications of the exact input and output format.

Appears In:
Field Description Default Validation

command string

command to execute.

MaxLength: 1024
MinLength: 1

args string array

args is the arguments to pass to the command when executing it.

MaxItems: 100
MinItems: 1
items:MaxLength: 512
items:MinLength: 1

env KubeConfigAuthExecEnv array

env defines additional environment variables to expose to the process. These
are unioned with the host’s environment, as well as variables client-go uses
to pass argument to the plugin.

MaxItems: 100
MinItems: 1

apiVersion string

apiVersion is preferred input version of the ExecInfo. The returned ExecCredentials MUST use
the same encoding version as the input.
Defaults to client.authentication.k8s.io/v1 if not set.

MaxLength: 512
MinLength: 1

provideClusterInfo boolean

provideClusterInfo determines whether or not to provide cluster information,
which could potentially contain very large CA data, to this exec plugin as a
part of the KUBERNETES_EXEC_INFO environment variable. By default, it is set
to false. Package k8s.io/client-go/tools/auth/exec provides helper methods for
reading this environment variable.

KubeConfigAuthExecEnv

KubeConfigAuthExecEnv is used for setting environment variables when executing an exec-based credential plugin.

Appears In:
Field Description Default Validation

name string

name of the environment variable

MaxLength: 512
MinLength: 1

value string

value of the environment variable

MaxLength: 512
MinLength: 1

KubeConfigAuthProvider

KubeConfigAuthProvider holds the configuration for a specified auth provider.

Appears In:
Field Description Default Validation

name string

name is the name of the authentication plugin.

MaxLength: 256
MinLength: 1

config object (keys:string, values:string)

config holds the parameters for the authentication plugin.

KubeConfigCluster

KubeConfigCluster contains information about how to communicate with a kubernetes cluster.

Adapted from clientcmdv1.Cluster.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

server string

server is the address of the kubernetes cluster (https://hostname:port).

Defaults to https:// + Cluster.Spec.ControlPlaneEndpoint.

MaxLength: 512
MinLength: 1

tlsServerName string

tlsServerName is used to check server certificate. If TLSServerName is empty, the hostname used to contact the server is used.

MaxLength: 512
MinLength: 1

insecureSkipTLSVerify boolean

insecureSkipTLSVerify skips the validity check for the server’s certificate. This will make your HTTPS connections insecure.

certificateAuthorityData integer array

certificateAuthorityData contains PEM-encoded certificate authority certificates.

Defaults to the Cluster’s CA certificate if empty.

MaxLength: 51200
MinLength: 1

proxyURL string

proxyURL is the URL to the proxy to be used for all requests made by this
client. URLs with "http", "https", and "socks5" schemes are supported. If
this configuration is not provided or the empty string, the client
attempts to construct a proxy configuration from http_proxy and
https_proxy environment variables. If these environment variables are not
set, the client does not attempt to proxy requests.

socks5 proxying does not currently support spdy streaming endpoints (exec,
attach, port forward).

MaxLength: 512
MinLength: 1

KubeConfigUser

KubeConfigUser contains information that describes identity information. This is used to tell the kubernetes cluster who you are.

Either authProvider or exec must be filled.

Adapted from clientcmdv1.AuthInfo.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

authProvider KubeConfigAuthProvider

authProvider specifies a custom authentication plugin for the kubernetes cluster.

exec KubeConfigAuthExec

exec specifies a custom exec-based authentication plugin for the kubernetes cluster.

KubeadmConfig

KubeadmConfig is the Schema for the kubeadmconfigs API.

Field Description Default Validation

apiVersion string

bootstrap.cluster.x-k8s.io/v1beta2

kind string

KubeadmConfig

metadata ObjectMeta

Refer to Kubernetes API documentation for fields of metadata.

MinProperties: 1

spec KubeadmConfigSpec

spec is the desired state of KubeadmConfig.

MinProperties: 1

status KubeadmConfigStatus

status is the observed state of KubeadmConfig.

MinProperties: 1

KubeadmConfigDeprecatedStatus

KubeadmConfigDeprecatedStatus groups all the status fields that are deprecated and will be removed in a future version. See https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/proposals/20240916-improve-status-in-CAPI-resources.md for more context.

Appears In:
Field Description Default Validation

v1beta1 KubeadmConfigV1Beta1DeprecatedStatus

v1beta1 groups all the status fields that are deprecated and will be removed when support for v1beta1 will be dropped.

KubeadmConfigInitializationStatus

KubeadmConfigInitializationStatus provides observations of the KubeadmConfig initialization process.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

dataSecretCreated boolean

dataSecretCreated is true when the Machine’s boostrap secret is created.
NOTE: this field is part of the Cluster API contract, and it is used to orchestrate initial Machine provisioning.

KubeadmConfigSpec

KubeadmConfigSpec defines the desired state of KubeadmConfig. Either ClusterConfiguration and InitConfiguration should be defined or the JoinConfiguration should be defined.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

clusterConfiguration ClusterConfiguration

clusterConfiguration along with InitConfiguration are the configurations necessary for the init command

MinProperties: 1

initConfiguration InitConfiguration

initConfiguration along with ClusterConfiguration are the configurations necessary for the init command

MinProperties: 1

joinConfiguration JoinConfiguration

joinConfiguration is the kubeadm configuration for the join command

MinProperties: 1

files File array

files specifies extra files to be passed to user_data upon creation.

MaxItems: 200
MinItems: 1

diskSetup DiskSetup

diskSetup specifies options for the creation of partition tables and file systems on devices.

MinProperties: 1

mounts MountPoints array

mounts specifies a list of mount points to be setup.

MaxItems: 100
MinItems: 1
items:MaxLength: 512
items:MinLength: 1

bootCommands string array

bootCommands specifies extra commands to run very early in the boot process via the cloud-init bootcmd
module. bootcmd will run on every boot, 'cloud-init-per' command can be used to make bootcmd run exactly
once. This is typically run in the cloud-init.service systemd unit. This has no effect in Ignition.

MaxItems: 1000
MinItems: 1
items:MaxLength: 10240
items:MinLength: 1

preKubeadmCommands string array

preKubeadmCommands specifies extra commands to run before kubeadm runs.
With cloud-init, this is prepended to the runcmd module configuration, and is typically executed in
the cloud-final.service systemd unit. In Ignition, this is prepended to /etc/kubeadm.sh.

MaxItems: 1000
MinItems: 1
items:MaxLength: 10240
items:MinLength: 1

postKubeadmCommands string array

postKubeadmCommands specifies extra commands to run after kubeadm runs.
With cloud-init, this is appended to the runcmd module configuration, and is typically executed in
the cloud-final.service systemd unit. In Ignition, this is appended to /etc/kubeadm.sh.

MaxItems: 1000
MinItems: 1
items:MaxLength: 10240
items:MinLength: 1

users User array

users specifies extra users to add

MaxItems: 100
MinItems: 1

ntp NTP

ntp specifies NTP configuration

MinProperties: 1

format Format

format specifies the output format of the bootstrap data.
Defaults to cloud-config if not set.

Enum: [cloud-config ignition]

verbosity integer

verbosity is the number for the kubeadm log level verbosity.
It overrides the --v flag in kubeadm commands.

ignition IgnitionSpec

ignition contains Ignition specific configuration.

MinProperties: 1

KubeadmConfigStatus

KubeadmConfigStatus defines the observed state of KubeadmConfig.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

conditions Condition array

conditions represents the observations of a KubeadmConfig’s current state.
Known condition types are Ready, DataSecretAvailable, CertificatesAvailable.

MaxItems: 32

initialization KubeadmConfigInitializationStatus

initialization provides observations of the KubeadmConfig initialization process.
NOTE: Fields in this struct are part of the Cluster API contract and are used to orchestrate initial Machine provisioning.

MinProperties: 1

dataSecretName string

dataSecretName is the name of the secret that stores the bootstrap data script.

MaxLength: 253
MinLength: 1

observedGeneration integer

observedGeneration is the latest generation observed by the controller.

Minimum: 1

deprecated KubeadmConfigDeprecatedStatus

deprecated groups all the status fields that are deprecated and will be removed when all the nested field are removed.

KubeadmConfigTemplate

KubeadmConfigTemplate is the Schema for the kubeadmconfigtemplates API.

Field Description Default Validation

apiVersion string

bootstrap.cluster.x-k8s.io/v1beta2

kind string

KubeadmConfigTemplate

metadata ObjectMeta

Refer to Kubernetes API documentation for fields of metadata.

MinProperties: 1

spec KubeadmConfigTemplateSpec

spec is the desired state of KubeadmConfigTemplate.

KubeadmConfigTemplateResource

KubeadmConfigTemplateResource defines the Template structure.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

metadata ObjectMeta

Refer to Kubernetes API documentation for fields of metadata.

MinProperties: 1

spec KubeadmConfigSpec

spec is the desired state of KubeadmConfig.

MinProperties: 1

KubeadmConfigTemplateSpec

KubeadmConfigTemplateSpec defines the desired state of KubeadmConfigTemplate.

Appears In:
Field Description Default Validation

template KubeadmConfigTemplateResource

template defines the desired state of KubeadmConfigTemplate.

MinProperties: 1

KubeadmConfigV1Beta1DeprecatedStatus

KubeadmConfigV1Beta1DeprecatedStatus groups all the status fields that are deprecated and will be removed when support for v1beta1 will be dropped. See https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/proposals/20240916-improve-status-in-CAPI-resources.md for more context.

Appears In:
Field Description Default Validation

conditions Conditions

conditions defines current service state of the KubeadmConfig.

Deprecated: This field is deprecated and is going to be removed when support for v1beta1 will be dropped. Please see https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/proposals/20240916-improve-status-in-CAPI-resources.md for more details.

failureReason string

failureReason will be set on non-retryable errors

Deprecated: This field is deprecated and is going to be removed when support for v1beta1 will be dropped. Please see https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/proposals/20240916-improve-status-in-CAPI-resources.md for more details.

MaxLength: 256
MinLength: 1

failureMessage string

failureMessage will be set on non-retryable errors

Deprecated: This field is deprecated and is going to be removed when support for v1beta1 will be dropped. Please see https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/proposals/20240916-improve-status-in-CAPI-resources.md for more details.

MaxLength: 10240
MinLength: 1

LocalEtcd

LocalEtcd describes that kubeadm should run an etcd cluster locally.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

imageRepository string

imageRepository sets the container registry to pull images from.
if not set, the ImageRepository defined in ClusterConfiguration will be used instead.

MaxLength: 512
MinLength: 1

imageTag string

imageTag allows to specify a tag for the image.
In case this value is set, kubeadm does not change automatically the version of the above components during upgrades.

MaxLength: 256
MinLength: 1

dataDir string

dataDir is the directory etcd will place its data.
Defaults to "/var/lib/etcd".

MaxLength: 512
MinLength: 1

extraArgs Arg array

extraArgs is a list of args to pass to etcd.
The arg name must match the command line flag name except without leading dash(es).
Extra arguments will override existing default arguments set by kubeadm.

MaxItems: 100
MinItems: 1

extraEnvs EnvVar

extraEnvs is an extra set of environment variables to pass to etcd.
Environment variables passed using ExtraEnvs will override any existing environment variables, or *_proxy environment variables that kubeadm adds by default.
This option takes effect only on Kubernetes >=1.31.0.

MaxItems: 100
MinItems: 1

serverCertSANs string array

serverCertSANs sets extra Subject Alternative Names for the etcd server signing cert.

MaxItems: 100
MinItems: 1
items:MaxLength: 253
items:MinLength: 1

peerCertSANs string array

peerCertSANs sets extra Subject Alternative Names for the etcd peer signing cert.

MaxItems: 100
MinItems: 1
items:MaxLength: 253
items:MinLength: 1

MountPoints

Underlying type: string array

MountPoints defines input for generated mounts in cloud-init.

Validation:

  • MaxItems: 100

  • MinItems: 1

  • items:MaxLength: 512

  • items:MinLength: 1

Appears In:

NTP

NTP defines input for generated ntp in cloud-init.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

servers string array

servers specifies which NTP servers to use

MaxItems: 100
items:MaxLength: 512
items:MinLength: 1

enabled boolean

enabled specifies whether NTP should be enabled

NodeRegistrationOptions

NodeRegistrationOptions holds fields that relate to registering a new control-plane or node to the cluster, either via "kubeadm init" or "kubeadm join". Note: The NodeRegistrationOptions struct has to be kept in sync with the structs in MarshalJSON.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

name string

name is the .Metadata.Name field of the Node API object that will be created in this kubeadm init or kubeadm join operation.
This field is also used in the CommonName field of the kubelet’s client certificate to the API server.
Defaults to the hostname of the node if not provided.

MaxLength: 253
MinLength: 1

criSocket string

criSocket is used to retrieve container runtime info. This information will be annotated to the Node API object, for later re-use

MaxLength: 512
MinLength: 1

taints Taint

taints specifies the taints the Node API object should be registered with. If this field is unset, i.e. nil, in the kubeadm init process
it will be defaulted to []v1.Taint{'node-role.kubernetes.io/master=""'}. If you don’t want to taint your control-plane node, set this field to an
empty slice, i.e. taints: [] in the YAML file. This field is solely used for Node registration.

MaxItems: 100
MinItems: 0

kubeletExtraArgs Arg array

kubeletExtraArgs is a list of args to pass to kubelet.
The arg name must match the command line flag name except without leading dash(es).
Extra arguments will override existing default arguments set by kubeadm.

MaxItems: 100
MinItems: 1

ignorePreflightErrors string array

ignorePreflightErrors provides a slice of pre-flight errors to be ignored when the current node is registered, e.g. 'IsPrivilegedUser,Swap'.
Value 'all' ignores errors from all checks.

MaxItems: 50
MinItems: 1
items:MaxLength: 512
items:MinLength: 1

imagePullPolicy PullPolicy

imagePullPolicy specifies the policy for image pulling
during kubeadm "init" and "join" operations. The value of
this field must be one of "Always", "IfNotPresent" or
"Never". Defaults to "IfNotPresent" if not set.

Enum: [Always IfNotPresent Never]

imagePullSerial boolean

imagePullSerial specifies if image pulling performed by kubeadm must be done serially or in parallel.
This option takes effect only on Kubernetes >=1.31.0.
Default: true (defaulted in kubeadm)

Partition

Partition defines how to create and layout a partition.

Appears In:
Field Description Default Validation

device string

device is the name of the device.

MaxLength: 256
MinLength: 1

layout boolean

layout specifies the device layout.
If it is true, a single partition will be created for the entire device.
When layout is false, it means don’t partition or ignore existing partitioning.

overwrite boolean

overwrite describes whether to skip checks and create the partition if a partition or filesystem is found on the device.
Use with caution. Default is 'false'.

tableType string

tableType specifies the tupe of partition table. The following are supported:
'mbr': default and setups a MS-DOS partition table
'gpt': setups a GPT partition table

Enum: [mbr gpt]

PasswdSource

PasswdSource is a union of all possible external source types for passwd data. Only one field may be populated in any given instance. Developers adding new sources of data for target systems should add them here.

Appears In:
Field Description Default Validation

secret SecretPasswdSource

secret represents a secret that should populate this password.

Patches

Patches contains options related to applying patches to components deployed by kubeadm.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

directory string

directory is a path to a directory that contains files named "target[suffix][+patchtype].extension".
For example, "kube-apiserver0+merge.yaml" or just "etcd.json". "target" can be one of
"kube-apiserver", "kube-controller-manager", "kube-scheduler", "etcd". "patchtype" can be one
of "strategic" "merge" or "json" and they match the patch formats supported by kubectl.
The default "patchtype" is "strategic". "extension" must be either "json" or "yaml".
"suffix" is an optional string that can be used to determine which patches are applied
first alpha-numerically.
These files can be written into the target directory via KubeadmConfig.Files which
specifies additional files to be created on the machine, either with content inline or
by referencing a secret.

MaxLength: 512
MinLength: 1

Scheduler

Scheduler holds settings necessary for scheduler deployments in the cluster.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

extraArgs Arg array

extraArgs is a list of args to pass to the control plane component.
The arg name must match the command line flag name except without leading dash(es).
Extra arguments will override existing default arguments set by kubeadm.

MaxItems: 100
MinItems: 1

extraVolumes HostPathMount array

extraVolumes is an extra set of host volumes, mounted to the control plane component.

MaxItems: 100
MinItems: 1

extraEnvs EnvVar

extraEnvs is an extra set of environment variables to pass to the control plane component.
Environment variables passed using ExtraEnvs will override any existing environment variables, or *_proxy environment variables that kubeadm adds by default.
This option takes effect only on Kubernetes >=1.31.0.

MaxItems: 100
MinItems: 1

SecretFileSource

SecretFileSource adapts a Secret into a FileSource.

The contents of the target Secret’s Data field will be presented as files using the keys in the Data field as the file names.

Appears In:
Field Description Default Validation

name string

name of the secret in the KubeadmBootstrapConfig’s namespace to use.

MaxLength: 253
MinLength: 1

key string

key is the key in the secret’s data map for this value.

MaxLength: 256
MinLength: 1

SecretPasswdSource

SecretPasswdSource adapts a Secret into a PasswdSource.

The contents of the target Secret’s Data field will be presented as passwd using the keys in the Data field as the file names.

Appears In:
Field Description Default Validation

name string

name of the secret in the KubeadmBootstrapConfig’s namespace to use.

MaxLength: 253
MinLength: 1

key string

key is the key in the secret’s data map for this value.

MaxLength: 256
MinLength: 1

Timeouts

Timeouts holds various timeouts that apply to kubeadm commands.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

controlPlaneComponentHealthCheckSeconds integer

controlPlaneComponentHealthCheckSeconds is the amount of time to wait for a control plane
component, such as the API server, to be healthy during "kubeadm init" and "kubeadm join".
If not set, it defaults to 4m (240s).

Minimum: 0

kubeletHealthCheckSeconds integer

kubeletHealthCheckSeconds is the amount of time to wait for the kubelet to be healthy
during "kubeadm init" and "kubeadm join".
If not set, it defaults to 4m (240s).

Minimum: 0

kubernetesAPICallSeconds integer

kubernetesAPICallSeconds is the amount of time to wait for the kubeadm client to complete a request to
the API server. This applies to all types of methods (GET, POST, etc).
If not set, it defaults to 1m (60s).

Minimum: 0

etcdAPICallSeconds integer

etcdAPICallSeconds is the amount of time to wait for the kubeadm etcd client to complete a request to
the etcd cluster.
If not set, it defaults to 2m (120s).

Minimum: 0

tlsBootstrapSeconds integer

tlsBootstrapSeconds is the amount of time to wait for the kubelet to complete TLS bootstrap
for a joining node.
If not set, it defaults to 5m (300s).

Minimum: 0

discoverySeconds integer

discoverySeconds is the amount of time to wait for kubeadm to validate the API server identity
for a joining node.
If not set, it defaults to 5m (300s).

Minimum: 0

User

User defines the input for a generated user in cloud-init.

Appears In:
Field Description Default Validation

name string

name specifies the user name

MaxLength: 256
MinLength: 1

gecos string

gecos specifies the gecos to use for the user

MaxLength: 256
MinLength: 1

groups string

groups specifies the additional groups for the user

MaxLength: 256
MinLength: 1

homeDir string

homeDir specifies the home directory to use for the user

MaxLength: 256
MinLength: 1

inactive boolean

inactive specifies whether to mark the user as inactive

shell string

shell specifies the user’s shell

MaxLength: 256
MinLength: 1

passwd string

passwd specifies a hashed password for the user

MaxLength: 256
MinLength: 1

passwdFrom PasswdSource

passwdFrom is a referenced source of passwd to populate the passwd.

primaryGroup string

primaryGroup specifies the primary group for the user

MaxLength: 256
MinLength: 1

lockPassword boolean

lockPassword specifies if password login should be disabled

sudo string

sudo specifies a sudo role for the user

MaxLength: 256
MinLength: 1

sshAuthorizedKeys string array

sshAuthorizedKeys specifies a list of ssh authorized keys for the user

MaxItems: 100
items:MaxLength: 2048
items:MinLength: 1

controlplane.cluster.x-k8s.io/v1beta1

Package v1beta1 contains API Schema definitions for the kubeadm v1beta1 API group,

Deprecated: This package is deprecated and is going to be removed when support for v1beta1 will be dropped.

Resource Types

KubeadmControlPlane

KubeadmControlPlane is the Schema for the KubeadmControlPlane API.

Field Description Default Validation

apiVersion string

controlplane.cluster.x-k8s.io/v1beta1

kind string

KubeadmControlPlane

metadata ObjectMeta

Refer to Kubernetes API documentation for fields of metadata.

MinProperties: 1

spec KubeadmControlPlaneSpec

spec is the desired state of KubeadmControlPlane.

status KubeadmControlPlaneStatus

status is the observed state of KubeadmControlPlane.

KubeadmControlPlaneMachineTemplate

KubeadmControlPlaneMachineTemplate defines the template for Machines in a KubeadmControlPlane object.

Appears In:
Field Description Default Validation

metadata ObjectMeta

Refer to Kubernetes API documentation for fields of metadata.

infrastructureRef ObjectReference

infrastructureRef is a required reference to a custom resource
offered by an infrastructure provider.

readinessGates MachineReadinessGate array

readinessGates specifies additional conditions to include when evaluating Machine Ready condition;
KubeadmControlPlane will always add readinessGates for the condition it is setting on the Machine:
APIServerPodHealthy, SchedulerPodHealthy, ControllerManagerPodHealthy, and if etcd is managed by CKP also
EtcdPodHealthy, EtcdMemberHealthy.

This field can be used e.g. to instruct the machine controller to include in the computation for Machine’s ready
computation a condition, managed by an external controllers, reporting the status of special software/hardware installed on the Machine.

Note
 This field is considered only for computing v1beta2 conditions.

MaxItems: 32

nodeDrainTimeout Duration

nodeDrainTimeout is the total amount of time that the controller will spend on draining a controlplane node
The default value is 0, meaning that the node can be drained without any time limitations.
NOTE: NodeDrainTimeout is different from kubectl drain --timeout

nodeVolumeDetachTimeout Duration

nodeVolumeDetachTimeout is the total amount of time that the controller will spend on waiting for all volumes
to be detached. The default value is 0, meaning that the volumes can be detached without any time limitations.

nodeDeletionTimeout Duration

nodeDeletionTimeout defines how long the machine controller will attempt to delete the Node that the Machine
hosts after the Machine is marked for deletion. A duration of 0 will retry deletion indefinitely.
If no value is provided, the default value for this property of the Machine resource will be used.

KubeadmControlPlaneSpec

KubeadmControlPlaneSpec defines the desired state of KubeadmControlPlane.

Appears In:
Field Description Default Validation

replicas integer

replicas is the number of desired machines. Defaults to 1. When stacked etcd is used only
odd numbers are permitted, as per [etcd best practice](https://etcd.io/docs/v3.3.12/faq/#why-an-odd-number-of-cluster-members).
This is a pointer to distinguish between explicit zero and not specified.

version string

version defines the desired Kubernetes version.
Please note that if kubeadmConfigSpec.ClusterConfiguration.imageRepository is not set
we don’t allow upgrades to versions >= v1.22.0 for which kubeadm uses the old registry (k8s.gcr.io).
Please use a newer patch version with the new registry instead. The default registries of kubeadm are:
* registry.k8s.io (new registry): >= v1.22.17, >= v1.23.15, >= v1.24.9, >= v1.25.0
* k8s.gcr.io (old registry): all older versions

MaxLength: 256
MinLength: 1

machineTemplate KubeadmControlPlaneMachineTemplate

machineTemplate contains information about how machines
should be shaped when creating or updating a control plane.

kubeadmConfigSpec KubeadmConfigSpec

kubeadmConfigSpec is a KubeadmConfigSpec
to use for initializing and joining machines to the control plane.

rolloutBefore RolloutBefore

rolloutBefore is a field to indicate a rollout should be performed
if the specified criteria is met.

rolloutAfter Time

rolloutAfter is a field to indicate a rollout should be performed
after the specified time even if no changes have been made to the
KubeadmControlPlane.
Example: In the YAML the time can be specified in the RFC3339 format.
To specify the rolloutAfter target as March 9, 2023, at 9 am UTC
use "2023-03-09T09:00:00Z".

rolloutStrategy RolloutStrategy

rolloutStrategy is the RolloutStrategy to use to replace control plane machines with
new ones.

{ rollingUpdate:map[maxSurge:1] type:RollingUpdate }

remediationStrategy RemediationStrategy

remediationStrategy is the RemediationStrategy that controls how control plane machine remediation happens.

machineNamingStrategy MachineNamingStrategy

machineNamingStrategy allows changing the naming pattern used when creating Machines.
InfraMachines & KubeadmConfigs will use the same name as the corresponding Machines.

KubeadmControlPlaneStatus

KubeadmControlPlaneStatus defines the observed state of KubeadmControlPlane.

Appears In:
Field Description Default Validation

selector string

selector is the label selector in string format to avoid introspection
by clients, and is used to provide the CRD-based integration for the
scale subresource and additional integrations for things like kubectl
describe.. The string will be in the same format as the query-param syntax.
More info about label selectors: http://kubernetes.io/docs/user-guide/labels#label-selectors

MaxLength: 4096
MinLength: 1

replicas integer

replicas is the total number of non-terminated machines targeted by this control plane
(their labels match the selector).

version string

version represents the minimum Kubernetes version for the control plane machines
in the cluster.

MaxLength: 256
MinLength: 1

updatedReplicas integer

updatedReplicas is the total number of non-terminated machines targeted by this control plane
that have the desired template spec.

readyReplicas integer

readyReplicas is the total number of fully running and ready control plane machines.

unavailableReplicas integer

unavailableReplicas is the total number of unavailable machines targeted by this control plane.
This is the total number of machines that are still required for
the deployment to have 100% available capacity. They may either
be machines that are running but not yet ready or machines
that still have not been created.

Deprecated: This field is deprecated and is going to be removed when support for v1beta1 will be dropped. Please see https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/proposals/20240916-improve-status-in-CAPI-resources.md for more details.

initialized boolean

initialized denotes that the KubeadmControlPlane API Server is initialized and thus
it can accept requests.
NOTE: this field is part of the Cluster API contract and it is used to orchestrate provisioning.
The value of this field is never updated after provisioning is completed. Please use conditions
to check the operational state of the control plane.

ready boolean

ready denotes that the KubeadmControlPlane API Server became ready during initial provisioning
to receive requests.
NOTE: this field is part of the Cluster API contract and it is used to orchestrate provisioning.
The value of this field is never updated after provisioning is completed. Please use conditions
to check the operational state of the control plane.

failureReason KubeadmControlPlaneStatusError

failureReason indicates that there is a terminal problem reconciling the
state, and will be set to a token value suitable for
programmatic interpretation.

Deprecated: This field is deprecated and is going to be removed when support for v1beta1 will be dropped. Please see https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/proposals/20240916-improve-status-in-CAPI-resources.md for more details.

failureMessage string

failureMessage indicates that there is a terminal problem reconciling the
state, and will be set to a descriptive error message.

Deprecated: This field is deprecated and is going to be removed when support for v1beta1 will be dropped. Please see https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/proposals/20240916-improve-status-in-CAPI-resources.md for more details.

MaxLength: 10240
MinLength: 1

observedGeneration integer

observedGeneration is the latest generation observed by the controller.

conditions Conditions

conditions defines current service state of the KubeadmControlPlane.

lastRemediation LastRemediationStatus

lastRemediation stores info about last remediation performed.

v1beta2 KubeadmControlPlaneV1Beta2Status

v1beta2 groups all the fields that will be added or modified in KubeadmControlPlane’s status with the V1Beta2 version.

KubeadmControlPlaneTemplate

KubeadmControlPlaneTemplate is the Schema for the kubeadmcontrolplanetemplates API.

Field Description Default Validation

apiVersion string

controlplane.cluster.x-k8s.io/v1beta1

kind string

KubeadmControlPlaneTemplate

metadata ObjectMeta

Refer to Kubernetes API documentation for fields of metadata.

MinProperties: 1

spec KubeadmControlPlaneTemplateSpec

spec is the desired state of KubeadmControlPlaneTemplate.

KubeadmControlPlaneTemplateMachineTemplate

KubeadmControlPlaneTemplateMachineTemplate defines the template for Machines in a KubeadmControlPlaneTemplate object. NOTE: KubeadmControlPlaneTemplateMachineTemplate is similar to KubeadmControlPlaneMachineTemplate but omits ObjectMeta and InfrastructureRef fields. These fields do not make sense on the KubeadmControlPlaneTemplate, because they are calculated by the Cluster topology reconciler during reconciliation and thus cannot be configured on the KubeadmControlPlaneTemplate.

Appears In:
Field Description Default Validation

metadata ObjectMeta

Refer to Kubernetes API documentation for fields of metadata.

nodeDrainTimeout Duration

nodeDrainTimeout is the total amount of time that the controller will spend on draining a controlplane node
The default value is 0, meaning that the node can be drained without any time limitations.
NOTE: NodeDrainTimeout is different from kubectl drain --timeout

nodeVolumeDetachTimeout Duration

nodeVolumeDetachTimeout is the total amount of time that the controller will spend on waiting for all volumes
to be detached. The default value is 0, meaning that the volumes can be detached without any time limitations.

nodeDeletionTimeout Duration

nodeDeletionTimeout defines how long the machine controller will attempt to delete the Node that the Machine
hosts after the Machine is marked for deletion. A duration of 0 will retry deletion indefinitely.
If no value is provided, the default value for this property of the Machine resource will be used.

KubeadmControlPlaneTemplateResource

KubeadmControlPlaneTemplateResource describes the data needed to create a KubeadmControlPlane from a template.

Appears In:
Field Description Default Validation

metadata ObjectMeta

Refer to Kubernetes API documentation for fields of metadata.

spec KubeadmControlPlaneTemplateResourceSpec

spec is the desired state of KubeadmControlPlaneTemplateResource.

KubeadmControlPlaneTemplateResourceSpec

KubeadmControlPlaneTemplateResourceSpec defines the desired state of KubeadmControlPlane. NOTE: KubeadmControlPlaneTemplateResourceSpec is similar to KubeadmControlPlaneSpec but omits Replicas and Version fields. These fields do not make sense on the KubeadmControlPlaneTemplate, because they are calculated by the Cluster topology reconciler during reconciliation and thus cannot be configured on the KubeadmControlPlaneTemplate.

Appears In:
Field Description Default Validation

machineTemplate KubeadmControlPlaneTemplateMachineTemplate

machineTemplate contains information about how machines
should be shaped when creating or updating a control plane.

kubeadmConfigSpec KubeadmConfigSpec

kubeadmConfigSpec is a KubeadmConfigSpec
to use for initializing and joining machines to the control plane.

rolloutBefore RolloutBefore

rolloutBefore is a field to indicate a rollout should be performed
if the specified criteria is met.

rolloutAfter Time

rolloutAfter is a field to indicate a rollout should be performed
after the specified time even if no changes have been made to the
KubeadmControlPlane.

rolloutStrategy RolloutStrategy

rolloutStrategy is the RolloutStrategy to use to replace control plane machines with
new ones.

{ rollingUpdate:map[maxSurge:1] type:RollingUpdate }

remediationStrategy RemediationStrategy

remediationStrategy is the RemediationStrategy that controls how control plane machine remediation happens.

machineNamingStrategy MachineNamingStrategy

machineNamingStrategy allows changing the naming pattern used when creating Machines.
InfraMachines & KubeadmConfigs will use the same name as the corresponding Machines.

KubeadmControlPlaneTemplateSpec

KubeadmControlPlaneTemplateSpec defines the desired state of KubeadmControlPlaneTemplate.

Appears In:
Field Description Default Validation

template KubeadmControlPlaneTemplateResource

template defines the desired state of KubeadmControlPlaneTemplate.

KubeadmControlPlaneV1Beta2Status

KubeadmControlPlaneV1Beta2Status Groups all the fields that will be added or modified in KubeadmControlPlane with the V1Beta2 version. See https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/proposals/20240916-improve-status-in-CAPI-resources.md for more context.

Appears In:
Field Description Default Validation

conditions Condition array

conditions represents the observations of a KubeadmControlPlane’s current state.
Known condition types are Available, CertificatesAvailable, EtcdClusterAvailable, MachinesReady, MachinesUpToDate,
ScalingUp, ScalingDown, Remediating, Deleting, Paused.

MaxItems: 32

readyReplicas integer

readyReplicas is the number of ready replicas for this KubeadmControlPlane. A machine is considered ready when Machine’s Ready condition is true.

availableReplicas integer

availableReplicas is the number of available replicas targeted by this KubeadmControlPlane. A machine is considered available when Machine’s Available condition is true.

upToDateReplicas integer

upToDateReplicas is the number of up-to-date replicas targeted by this KubeadmControlPlane. A machine is considered up-to-date when Machine’s UpToDate condition is true.

LastRemediationStatus

LastRemediationStatus stores info about last remediation performed. NOTE: if for any reason information about last remediation are lost, RetryCount is going to restart from 0 and thus more remediations than expected might happen.

Appears In:
Field Description Default Validation

machine string

machine is the machine name of the latest machine being remediated.

MaxLength: 253
MinLength: 1

timestamp Time

timestamp is when last remediation happened. It is represented in RFC3339 form and is in UTC.

retryCount integer

retryCount used to keep track of remediation retry for the last remediated machine.
A retry happens when a machine that was created as a replacement for an unhealthy machine also fails.

MachineNamingStrategy

MachineNamingStrategy allows changing the naming pattern used when creating Machines. InfraMachines & KubeadmConfigs will use the same name as the corresponding Machines.

Appears In:
Field Description Default Validation

template string

template defines the template to use for generating the names of the Machine objects.
If not defined, it will fallback to {{ .kubeadmControlPlane.name }}-{{ .random }}.
If the generated name string exceeds 63 characters, it will be trimmed to 58 characters and will
get concatenated with a random suffix of length 5.
Length of the template string must not exceed 256 characters.
The template allows the following variables .cluster.name, .kubeadmControlPlane.name and .random.
The variable .cluster.name retrieves the name of the cluster object that owns the Machines being created.
The variable .kubeadmControlPlane.name retrieves the name of the KubeadmControlPlane object that owns the Machines being created.
The variable .random is substituted with random alphanumeric string, without vowels, of length 5. This variable is required
part of the template. If not provided, validation will fail.

MaxLength: 256
MinLength: 1

RemediationStrategy

RemediationStrategy allows to define how control plane machine remediation happens.

Appears In:
Field Description Default Validation

maxRetry integer

maxRetry is the Max number of retries while attempting to remediate an unhealthy machine.
A retry happens when a machine that was created as a replacement for an unhealthy machine also fails.
For example, given a control plane with three machines M1, M2, M3:

M1 become unhealthy; remediation happens, and M1-1 is created as a replacement.
If M1-1 (replacement of M1) has problems while bootstrapping it will become unhealthy, and then be
remediated; such operation is considered a retry, remediation-retry #1.
If M1-2 (replacement of M1-1) becomes unhealthy, remediation-retry #2 will happen, etc.

A retry could happen only after RetryPeriod from the previous retry.
If a machine is marked as unhealthy after MinHealthyPeriod from the previous remediation expired,
this is not considered a retry anymore because the new issue is assumed unrelated from the previous one.

If not set, the remedation will be retried infinitely.

retryPeriod Duration

retryPeriod is the duration that KCP should wait before remediating a machine being created as a replacement
for an unhealthy machine (a retry).

If not set, a retry will happen immediately.

minHealthyPeriod Duration

minHealthyPeriod defines the duration after which KCP will consider any failure to a machine unrelated
from the previous one. In this case the remediation is not considered a retry anymore, and thus the retry
counter restarts from 0. For example, assuming MinHealthyPeriod is set to 1h (default)

M1 become unhealthy; remediation happens, and M1-1 is created as a replacement.
If M1-1 (replacement of M1) has problems within the 1hr after the creation, also
this machine will be remediated and this operation is considered a retry - a problem related
to the original issue happened to M1 -.

If instead the problem on M1-1 is happening after MinHealthyPeriod expired, e.g. four days after
m1-1 has been created as a remediation of M1, the problem on M1-1 is considered unrelated to
the original issue happened to M1.

If not set, this value is defaulted to 1h.

RollingUpdate

RollingUpdate is used to control the desired behavior of rolling update.

Appears In:
Field Description Default Validation

maxSurge IntOrString

maxSurge is the maximum number of control planes that can be scheduled above or under the
desired number of control planes.
Value can be an absolute number 1 or 0.
Defaults to 1.
Example: when this is set to 1, the control plane can be scaled
up immediately when the rolling update starts.

RolloutBefore

RolloutBefore describes when a rollout should be performed on the KCP machines.

Appears In:
Field Description Default Validation

certificatesExpiryDays integer

certificatesExpiryDays indicates a rollout needs to be performed if the
certificates of the machine will expire within the specified days.

RolloutStrategy

RolloutStrategy describes how to replace existing machines with new ones.

Appears In:
Field Description Default Validation

type RolloutStrategyType

type of rollout. Currently the only supported strategy is
"RollingUpdate".
Default is RollingUpdate.

Enum: [RollingUpdate]

rollingUpdate RollingUpdate

rollingUpdate is the rolling update config params. Present only if
RolloutStrategyType = RollingUpdate.

RolloutStrategyType

Underlying type: string

RolloutStrategyType defines the rollout strategies for a KubeadmControlPlane.

Validation:

  • Enum: [RollingUpdate]

Appears In:

controlplane.cluster.x-k8s.io/v1beta2

Package v1beta2 contains API Schema definitions for the kubeadm v1beta2 API group.

Resource Types

KubeadmControlPlane

KubeadmControlPlane is the Schema for the KubeadmControlPlane API.

Field Description Default Validation

apiVersion string

controlplane.cluster.x-k8s.io/v1beta2

kind string

KubeadmControlPlane

metadata ObjectMeta

Refer to Kubernetes API documentation for fields of metadata.

MinProperties: 1

spec KubeadmControlPlaneSpec

spec is the desired state of KubeadmControlPlane.

status KubeadmControlPlaneStatus

status is the observed state of KubeadmControlPlane.

MinProperties: 1

KubeadmControlPlaneDeprecatedStatus

KubeadmControlPlaneDeprecatedStatus groups all the status fields that are deprecated and will be removed in a future version. See https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/proposals/20240916-improve-status-in-CAPI-resources.md for more context.

Appears In:
Field Description Default Validation

v1beta1 KubeadmControlPlaneV1Beta1DeprecatedStatus

v1beta1 groups all the status fields that are deprecated and will be removed when support for v1beta1 will be dropped.

KubeadmControlPlaneInitializationStatus

KubeadmControlPlaneInitializationStatus provides observations of the KubeadmControlPlane initialization process.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

controlPlaneInitialized boolean

controlPlaneInitialized is true when the KubeadmControlPlane provider reports that the Kubernetes control plane is initialized;
A control plane is considered initialized when it can accept requests, no matter if this happens before
the control plane is fully provisioned or not.
NOTE: this field is part of the Cluster API contract, and it is used to orchestrate initial Machine provisioning.

KubeadmControlPlaneMachineTemplate

KubeadmControlPlaneMachineTemplate defines the template for Machines in a KubeadmControlPlane object.

Appears In:
Field Description Default Validation

metadata ObjectMeta

Refer to Kubernetes API documentation for fields of metadata.

MinProperties: 1

spec KubeadmControlPlaneMachineTemplateSpec

spec defines the spec for Machines
in a KubeadmControlPlane object.

KubeadmControlPlaneMachineTemplateDeletionSpec

KubeadmControlPlaneMachineTemplateDeletionSpec contains configuration options for Machine deletion.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

nodeDrainTimeoutSeconds integer

nodeDrainTimeoutSeconds is the total amount of time that the controller will spend on draining a controlplane node
The default value is 0, meaning that the node can be drained without any time limitations.
NOTE: nodeDrainTimeoutSeconds is different from kubectl drain --timeout

Minimum: 0

nodeVolumeDetachTimeoutSeconds integer

nodeVolumeDetachTimeoutSeconds is the total amount of time that the controller will spend on waiting for all volumes
to be detached. The default value is 0, meaning that the volumes can be detached without any time limitations.

Minimum: 0

nodeDeletionTimeoutSeconds integer

nodeDeletionTimeoutSeconds defines how long the machine controller will attempt to delete the Node that the Machine
hosts after the Machine is marked for deletion. A duration of 0 will retry deletion indefinitely.
If no value is provided, the default value for this property of the Machine resource will be used.

Minimum: 0

KubeadmControlPlaneMachineTemplateSpec

KubeadmControlPlaneMachineTemplateSpec defines the spec for Machines in a KubeadmControlPlane object.

Appears In:
Field Description Default Validation

infrastructureRef ContractVersionedObjectReference

infrastructureRef is a required reference to a custom resource
offered by an infrastructure provider.

readinessGates MachineReadinessGate array

readinessGates specifies additional conditions to include when evaluating Machine Ready condition;
KubeadmControlPlane will always add readinessGates for the condition it is setting on the Machine:
APIServerPodHealthy, SchedulerPodHealthy, ControllerManagerPodHealthy, and if etcd is managed by CKP also
EtcdPodHealthy, EtcdMemberHealthy.

This field can be used e.g. to instruct the machine controller to include in the computation for Machine’s ready
computation a condition, managed by an external controllers, reporting the status of special software/hardware installed on the Machine.

MaxItems: 32
MinItems: 1

deletion KubeadmControlPlaneMachineTemplateDeletionSpec

deletion contains configuration options for Machine deletion.

MinProperties: 1

KubeadmControlPlaneRemediationSpec

KubeadmControlPlaneRemediationSpec controls how unhealthy control plane Machines are remediated.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

maxRetry integer

maxRetry is the Max number of retries while attempting to remediate an unhealthy machine.
A retry happens when a machine that was created as a replacement for an unhealthy machine also fails.
For example, given a control plane with three machines M1, M2, M3:

M1 become unhealthy; remediation happens, and M1-1 is created as a replacement.
If M1-1 (replacement of M1) has problems while bootstrapping it will become unhealthy, and then be
remediated; such operation is considered a retry, remediation-retry #1.
If M1-2 (replacement of M1-1) becomes unhealthy, remediation-retry #2 will happen, etc.

A retry could happen only after retryPeriodSeconds from the previous retry.
If a machine is marked as unhealthy after minHealthyPeriodSeconds from the previous remediation expired,
this is not considered a retry anymore because the new issue is assumed unrelated from the previous one.

If not set, the remedation will be retried infinitely.

retryPeriodSeconds integer

retryPeriodSeconds is the duration that KCP should wait before remediating a machine being created as a replacement
for an unhealthy machine (a retry).

If not set, a retry will happen immediately.

Minimum: 0

minHealthyPeriodSeconds integer

minHealthyPeriodSeconds defines the duration after which KCP will consider any failure to a machine unrelated
from the previous one. In this case the remediation is not considered a retry anymore, and thus the retry
counter restarts from 0. For example, assuming minHealthyPeriodSeconds is set to 1h (default)

M1 become unhealthy; remediation happens, and M1-1 is created as a replacement.
If M1-1 (replacement of M1) has problems within the 1hr after the creation, also
this machine will be remediated and this operation is considered a retry - a problem related
to the original issue happened to M1 -.

If instead the problem on M1-1 is happening after minHealthyPeriodSeconds expired, e.g. four days after
m1-1 has been created as a remediation of M1, the problem on M1-1 is considered unrelated to
the original issue happened to M1.

If not set, this value is defaulted to 1h.

Minimum: 0

KubeadmControlPlaneRolloutBeforeSpec

KubeadmControlPlaneRolloutBeforeSpec describes when a rollout should be performed on the KCP machines.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

certificatesExpiryDays integer

certificatesExpiryDays indicates a rollout needs to be performed if the
certificates of the machine will expire within the specified days.
The minimum for this field is 7.

Minimum: 7

KubeadmControlPlaneRolloutSpec

KubeadmControlPlaneRolloutSpec allows you to configure the behaviour of rolling updates to the control plane Machines. It allows you to require that all Machines are replaced before or after a certain time, and allows you to define the strategy used during rolling replacements.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

before KubeadmControlPlaneRolloutBeforeSpec

before is a field to indicate a rollout should be performed
if the specified criteria is met.

MinProperties: 1

after Time

after is a field to indicate a rollout should be performed
after the specified time even if no changes have been made to the
KubeadmControlPlane.
Example: In the YAML the time can be specified in the RFC3339 format.
To specify the rolloutAfter target as March 9, 2023, at 9 am UTC
use "2023-03-09T09:00:00Z".

strategy KubeadmControlPlaneRolloutStrategy

strategy specifies how to roll out control plane Machines.

MinProperties: 1

KubeadmControlPlaneRolloutStrategy

KubeadmControlPlaneRolloutStrategy describes how to replace existing machines with new ones.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

type KubeadmControlPlaneRolloutStrategyType

type of rollout. Currently the only supported strategy is
"RollingUpdate".
Default is RollingUpdate.

Enum: [RollingUpdate]

rollingUpdate KubeadmControlPlaneRolloutStrategyRollingUpdate

rollingUpdate is the rolling update config params. Present only if
type = RollingUpdate.

MinProperties: 1

KubeadmControlPlaneRolloutStrategyRollingUpdate

KubeadmControlPlaneRolloutStrategyRollingUpdate is used to control the desired behavior of rolling update.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

maxSurge IntOrString

maxSurge is the maximum number of control planes that can be scheduled above or under the
desired number of control planes.
Value can be an absolute number 1 or 0.
Defaults to 1.
Example: when this is set to 1, the control plane can be scaled
up immediately when the rolling update starts.

KubeadmControlPlaneRolloutStrategyType

Underlying type: string

KubeadmControlPlaneRolloutStrategyType defines the rollout strategies for a KubeadmControlPlane.

Validation:

  • Enum: [RollingUpdate]

Appears In:

KubeadmControlPlaneSpec

KubeadmControlPlaneSpec defines the desired state of KubeadmControlPlane.

Appears In:
Field Description Default Validation

replicas integer

replicas is the number of desired machines. Defaults to 1. When stacked etcd is used only
odd numbers are permitted, as per [etcd best practice](https://etcd.io/docs/v3.3.12/faq/#why-an-odd-number-of-cluster-members).
This is a pointer to distinguish between explicit zero and not specified.

version string

version defines the desired Kubernetes version.

MaxLength: 256
MinLength: 1

machineTemplate KubeadmControlPlaneMachineTemplate

machineTemplate contains information about how machines
should be shaped when creating or updating a control plane.

kubeadmConfigSpec KubeadmConfigSpec

kubeadmConfigSpec is a KubeadmConfigSpec
to use for initializing and joining machines to the control plane.

MinProperties: 1

rollout KubeadmControlPlaneRolloutSpec

rollout allows you to configure the behaviour of rolling updates to the control plane Machines.
It allows you to require that all Machines are replaced before or after a certain time,
and allows you to define the strategy used during rolling replacements.

MinProperties: 1

remediation KubeadmControlPlaneRemediationSpec

remediation controls how unhealthy Machines are remediated.

MinProperties: 1

machineNaming MachineNamingSpec

machineNaming allows changing the naming pattern used when creating Machines.
InfraMachines & KubeadmConfigs will use the same name as the corresponding Machines.

MinProperties: 1

KubeadmControlPlaneStatus

KubeadmControlPlaneStatus defines the observed state of KubeadmControlPlane.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

conditions Condition array

conditions represents the observations of a KubeadmControlPlane’s current state.
Known condition types are Available, CertificatesAvailable, EtcdClusterAvailable, MachinesReady, MachinesUpToDate,
ScalingUp, ScalingDown, Remediating, Deleting, Paused.

MaxItems: 32

initialization KubeadmControlPlaneInitializationStatus

initialization provides observations of the KubeadmControlPlane initialization process.
NOTE: Fields in this struct are part of the Cluster API contract and are used to orchestrate initial Machine provisioning.

MinProperties: 1

selector string

selector is the label selector in string format to avoid introspection
by clients, and is used to provide the CRD-based integration for the
scale subresource and additional integrations for things like kubectl
describe.. The string will be in the same format as the query-param syntax.
More info about label selectors: http://kubernetes.io/docs/user-guide/labels#label-selectors

MaxLength: 4096
MinLength: 1

replicas integer

replicas is the total number of non-terminated machines targeted by this control plane
(their labels match the selector).

readyReplicas integer

readyReplicas is the number of ready replicas for this KubeadmControlPlane. A machine is considered ready when Machine’s Ready condition is true.

availableReplicas integer

availableReplicas is the number of available replicas targeted by this KubeadmControlPlane. A machine is considered available when Machine’s Available condition is true.

upToDateReplicas integer

upToDateReplicas is the number of up-to-date replicas targeted by this KubeadmControlPlane. A machine is considered up-to-date when Machine’s UpToDate condition is true.

version string

version represents the minimum Kubernetes version for the control plane machines
in the cluster.

MaxLength: 256
MinLength: 1

observedGeneration integer

observedGeneration is the latest generation observed by the controller.

Minimum: 1

lastRemediation LastRemediationStatus

lastRemediation stores info about last remediation performed.

deprecated KubeadmControlPlaneDeprecatedStatus

deprecated groups all the status fields that are deprecated and will be removed when all the nested field are removed.

KubeadmControlPlaneTemplate

KubeadmControlPlaneTemplate is the Schema for the kubeadmcontrolplanetemplates API. NOTE: This CRD can only be used if the ClusterTopology feature gate is enabled.

Field Description Default Validation

apiVersion string

controlplane.cluster.x-k8s.io/v1beta2

kind string

KubeadmControlPlaneTemplate

metadata ObjectMeta

Refer to Kubernetes API documentation for fields of metadata.

MinProperties: 1

spec KubeadmControlPlaneTemplateSpec

spec is the desired state of KubeadmControlPlaneTemplate.

KubeadmControlPlaneTemplateMachineTemplate

KubeadmControlPlaneTemplateMachineTemplate defines the template for Machines in a KubeadmControlPlaneTemplate object. NOTE: KubeadmControlPlaneTemplateMachineTemplate is similar to KubeadmControlPlaneMachineTemplate but omits ObjectMeta and InfrastructureRef fields. These fields do not make sense on the KubeadmControlPlaneTemplate, because they are calculated by the Cluster topology reconciler during reconciliation and thus cannot be configured on the KubeadmControlPlaneTemplate.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

metadata ObjectMeta

Refer to Kubernetes API documentation for fields of metadata.

MinProperties: 1

spec KubeadmControlPlaneTemplateMachineTemplateSpec

spec defines the spec for Machines
in a KubeadmControlPlane object.

MinProperties: 1

KubeadmControlPlaneTemplateMachineTemplateDeletionSpec

KubeadmControlPlaneTemplateMachineTemplateDeletionSpec contains configuration options for Machine deletion.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

nodeDrainTimeoutSeconds integer

nodeDrainTimeoutSeconds is the total amount of time that the controller will spend on draining a controlplane node
The default value is 0, meaning that the node can be drained without any time limitations.
NOTE: nodeDrainTimeoutSeconds is different from kubectl drain --timeout

Minimum: 0

nodeVolumeDetachTimeoutSeconds integer

nodeVolumeDetachTimeoutSeconds is the total amount of time that the controller will spend on waiting for all volumes
to be detached. The default value is 0, meaning that the volumes can be detached without any time limitations.

Minimum: 0

nodeDeletionTimeoutSeconds integer

nodeDeletionTimeoutSeconds defines how long the machine controller will attempt to delete the Node that the Machine
hosts after the Machine is marked for deletion. A duration of 0 will retry deletion indefinitely.
If no value is provided, the default value for this property of the Machine resource will be used.

Minimum: 0

KubeadmControlPlaneTemplateMachineTemplateSpec

KubeadmControlPlaneTemplateMachineTemplateSpec defines the spec for Machines in a KubeadmControlPlane object.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

deletion KubeadmControlPlaneTemplateMachineTemplateDeletionSpec

deletion contains configuration options for Machine deletion.

MinProperties: 1

KubeadmControlPlaneTemplateResource

KubeadmControlPlaneTemplateResource describes the data needed to create a KubeadmControlPlane from a template.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

metadata ObjectMeta

Refer to Kubernetes API documentation for fields of metadata.

MinProperties: 1

spec KubeadmControlPlaneTemplateResourceSpec

spec is the desired state of KubeadmControlPlaneTemplateResource.

MinProperties: 1

KubeadmControlPlaneTemplateResourceSpec

KubeadmControlPlaneTemplateResourceSpec defines the desired state of KubeadmControlPlane. NOTE: KubeadmControlPlaneTemplateResourceSpec is similar to KubeadmControlPlaneSpec but omits Replicas and Version fields. These fields do not make sense on the KubeadmControlPlaneTemplate, because they are calculated by the Cluster topology reconciler during reconciliation and thus cannot be configured on the KubeadmControlPlaneTemplate.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

machineTemplate KubeadmControlPlaneTemplateMachineTemplate

machineTemplate contains information about how machines
should be shaped when creating or updating a control plane.

MinProperties: 1

kubeadmConfigSpec KubeadmConfigSpec

kubeadmConfigSpec is a KubeadmConfigSpec
to use for initializing and joining machines to the control plane.

MinProperties: 1

rollout KubeadmControlPlaneRolloutSpec

rollout allows you to configure the behaviour of rolling updates to the control plane Machines.
It allows you to require that all Machines are replaced before or after a certain time,
and allows you to define the strategy used during rolling replacements.

MinProperties: 1

remediation KubeadmControlPlaneRemediationSpec

remediation controls how unhealthy Machines are remediated.

MinProperties: 1

machineNaming MachineNamingSpec

machineNaming allows changing the naming pattern used when creating Machines.
InfraMachines & KubeadmConfigs will use the same name as the corresponding Machines.

MinProperties: 1

KubeadmControlPlaneTemplateSpec

KubeadmControlPlaneTemplateSpec defines the desired state of KubeadmControlPlaneTemplate.

Appears In:
Field Description Default Validation

template KubeadmControlPlaneTemplateResource

template defines the desired state of KubeadmControlPlaneTemplate.

MinProperties: 1

KubeadmControlPlaneV1Beta1DeprecatedStatus

KubeadmControlPlaneV1Beta1DeprecatedStatus groups all the status fields that are deprecated and will be removed when support for v1beta1 will be dropped. See https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/proposals/20240916-improve-status-in-CAPI-resources.md for more context.

Appears In:
Field Description Default Validation

conditions Conditions

conditions defines current service state of the KubeadmControlPlane.

Deprecated: This field is deprecated and is going to be removed when support for v1beta1 will be dropped. Please see https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/proposals/20240916-improve-status-in-CAPI-resources.md for more details.

failureReason KubeadmControlPlaneStatusError

failureReason indicates that there is a terminal problem reconciling the
state, and will be set to a token value suitable for
programmatic interpretation.

Deprecated: This field is deprecated and is going to be removed when support for v1beta1 will be dropped. Please see https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/proposals/20240916-improve-status-in-CAPI-resources.md for more details.

failureMessage string

failureMessage indicates that there is a terminal problem reconciling the
state, and will be set to a descriptive error message.

Deprecated: This field is deprecated and is going to be removed when support for v1beta1 will be dropped. Please see https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/proposals/20240916-improve-status-in-CAPI-resources.md for more details.

MaxLength: 10240
MinLength: 1

updatedReplicas integer

updatedReplicas is the total number of non-terminated machines targeted by this control plane
that have the desired template spec.

Deprecated: This field is deprecated and is going to be removed when support for v1beta1 will be dropped. Please see https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/proposals/20240916-improve-status-in-CAPI-resources.md for more details.

readyReplicas integer

readyReplicas is the total number of fully running and ready control plane machines.

Deprecated: This field is deprecated and is going to be removed when support for v1beta1 will be dropped. Please see https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/proposals/20240916-improve-status-in-CAPI-resources.md for more details.

unavailableReplicas integer

unavailableReplicas is the total number of unavailable machines targeted by this control plane.
This is the total number of machines that are still required for
the deployment to have 100% available capacity. They may either
be machines that are running but not yet ready or machines
that still have not been created.

Deprecated: This field is deprecated and is going to be removed when support for v1beta1 will be dropped. Please see https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/proposals/20240916-improve-status-in-CAPI-resources.md for more details.

LastRemediationStatus

LastRemediationStatus stores info about last remediation performed. NOTE: if for any reason information about last remediation are lost, RetryCount is going to restart from 0 and thus more remediations than expected might happen.

Appears In:
Field Description Default Validation

machine string

machine is the machine name of the latest machine being remediated.

MaxLength: 253
MinLength: 1

time Time

time is when last remediation happened. It is represented in RFC3339 form and is in UTC.

retryCount integer

retryCount used to keep track of remediation retry for the last remediated machine.
A retry happens when a machine that was created as a replacement for an unhealthy machine also fails.

Minimum: 0

MachineNamingSpec

MachineNamingSpec allows changing the naming pattern used when creating Machines. InfraMachines & KubeadmConfigs will use the same name as the corresponding Machines.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

template string

template defines the template to use for generating the names of the Machine objects.
If not defined, it will fallback to {{ .kubeadmControlPlane.name }}-{{ .random }}.
If the generated name string exceeds 63 characters, it will be trimmed to 58 characters and will
get concatenated with a random suffix of length 5.
Length of the template string must not exceed 256 characters.
The template allows the following variables .cluster.name, .kubeadmControlPlane.name and .random.
The variable .cluster.name retrieves the name of the cluster object that owns the Machines being created.
The variable .kubeadmControlPlane.name retrieves the name of the KubeadmControlPlane object that owns the Machines being created.
The variable .random is substituted with random alphanumeric string, without vowels, of length 5. This variable is required
part of the template. If not provided, validation will fail.

MaxLength: 256
MinLength: 1

vmware.infrastructure.cluster.x-k8s.io/v1beta1

Package v1beta1 contains API Schema definitions for the vmware.infrastructure v1beta1 API group

Package v1beta1 contains API types.

Resource Types

InterfaceNetworkReference

InterfaceNetworkReference describes a reference to another object in the same namespace as the referrer.

Appears In:
Field Description Default Validation

kind string

kind of the remediation template.
kind must consist of alphanumeric characters or '-', start with an alphabetic character, and end with an alphanumeric character.

MaxLength: 63
MinLength: 1
Pattern: ^[a-zA-Z]([-a-zA-Z0-9]*[a-zA-Z0-9])?$

name string

name of the remediation template.
name must consist of lower case alphanumeric characters, '-' or '.', and must start and end with an alphanumeric character.

MaxLength: 253
MinLength: 1
Pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$

apiVersion string

apiVersion of the remediation template.
apiVersion must be fully qualified domain name followed by / and a version.
NOTE: This field must be kept in sync with the APIVersion of the remediation template.

MaxLength: 317
MinLength: 1
Pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*\/[a-z]([-a-z0-9]*[a-z0-9])?$

InterfaceSpec

InterfaceSpec defines properties of a network interface.

Appears In:
Field Description Default Validation

network InterfaceNetworkReference

network is the name of the network resource to which this interface is
connected.

mtu integer

mtu is the Maximum Transmission Unit size in bytes.

Maximum: 9000
Minimum: 576

routes RouteSpec array

routes is a list of optional, static routes.

Please note this feature is available only with the following bootstrap
providers: CloudInit.

MaxItems: 100
MinItems: 1

InterfacesSpec

InterfacesSpec defines all the network interfaces of a VSphereMachine from Kubernetes perspective.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

primary InterfaceSpec

primary is the primary network interface.

It is used to connect the Kubernetes primary network for Load balancer,
Service discovery, Pod traffic and management traffic etc.
Leave it unset if you don’t want to customize the primary network and interface.
Customization is only supported with network provider NSX-VPC.
It should be set only when VSphereCluster spec.network.nsxVPC.createSubnetSet is set to false.

secondary SecondaryInterfaceSpec array

secondary are the secondary network interfaces.

It is used for any purpose like deploying Antrea secondary network,
Multus, mounting NFS etc.
Secondary network is supported with network provider NSX-VPC and vsphere-network.

MaxItems: 9
MinItems: 1

KeyValuePair

KeyValuePair is useful when wanting to realize a map as a list of key/value pairs.

Appears In:
Field Description Default Validation

key string

key is the key part of the key/value pair.

MaxLength: 100
MinLength: 1

value string

value is the optional value part of the key/value pair.

MaxLength: 10000
MinLength: 1

NSXVPC

NSXVPC defines the configuration when the network provider is NSX-VPC.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

createSubnetSet boolean

createSubnetSet is a flag to indicate whether to create a SubnetSet or not as the primary network. If not set, the default is true.

Network

Network defines the network configuration for the cluster with different network providers.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

nsxVPC NSXVPC

nsxVPC defines the configuration when the network provider is NSX-VPC.

MinProperties: 1

RouteSpec

RouteSpec defines a static route for a guest.

Appears In:
Field Description Default Validation

to string

to is an IP4 CIDR. IP6 is not supported yet.
Examples: 192.168.1.0/24, 192.168.100.100/32, 0.0.0.0/0

MaxLength: 18
MinLength: 9
Pattern: ^([0-9]\{1,3}\.){3}[0-9]\{1,3}\/[0-9]\{1,2}$

via string

via is an IP4 address. IP6 is not supported yet.

MaxLength: 15
MinLength: 7
Pattern: ^([0-9]\{1,3}\.){3}[0-9]\{1,3}$

SecondaryInterfaceSpec

SecondaryInterfaceSpec defines a secondary network interface for a VSphereMachine.

Appears In:
Field Description Default Validation

name string

name describes the unique name of this network interface, used to
distinguish it from other network interfaces attached to this VSphereMachine.

MaxLength: 15
MinLength: 2
Pattern: ^[a-z0-9]\{2,}$

network InterfaceNetworkReference

network is the name of the network resource to which this interface is
connected.

mtu integer

mtu is the Maximum Transmission Unit size in bytes.

Maximum: 9000
Minimum: 576

routes RouteSpec array

routes is a list of optional, static routes.

Please note this feature is available only with the following bootstrap
providers: CloudInit.

MaxItems: 100
MinItems: 1

VSphereCluster

VSphereCluster is the Schema for the VSphereClusters API.

Field Description Default Validation

apiVersion string

vmware.infrastructure.cluster.x-k8s.io/v1beta1

kind string

VSphereCluster

metadata ObjectMeta

Refer to Kubernetes API documentation for fields of metadata.

MinProperties: 1

spec VSphereClusterSpec

status VSphereClusterStatus

VSphereClusterSpec

VSphereClusterSpec defines the desired state of VSphereCluster.

Appears In:
Field Description Default Validation

controlPlaneEndpoint APIEndpoint

network Network

network defines the network configuration for the cluster with different network providers.

MinProperties: 1

VSphereClusterStatus

VSphereClusterStatus defines the observed state of VSphereClusterSpec.

Appears In:
Field Description Default Validation

ready boolean

Ready indicates the infrastructure required to deploy this cluster is
ready.

resourcePolicyName string

ResourcePolicyName is the name of the VirtualMachineSetResourcePolicy for
the cluster, if one exists

conditions Conditions

Conditions defines current service state of the VSphereCluster.

failureDomains FailureDomains

FailureDomains is a list of failure domain objects synced from the
infrastructure provider.

v1beta2 VSphereClusterV1Beta2Status

v1beta2 groups all the fields that will be added or modified in VSphereCluster’s status with the V1Beta2 version.

VSphereClusterTemplate

VSphereClusterTemplate is the Schema for the vsphereclustertemplates API.

Field Description Default Validation

apiVersion string

vmware.infrastructure.cluster.x-k8s.io/v1beta1

kind string

VSphereClusterTemplate

metadata ObjectMeta

Refer to Kubernetes API documentation for fields of metadata.

MinProperties: 1

spec VSphereClusterTemplateSpec

VSphereClusterTemplateResource

VSphereClusterTemplateResource defines the template structure.

Appears In:
Field Description Default Validation

spec VSphereClusterSpec

VSphereClusterTemplateSpec

VSphereClusterTemplateSpec defines the desired state of VSphereClusterTemplate.

Appears In:
Field Description Default Validation

template VSphereClusterTemplateResource

VSphereClusterV1Beta2Status

VSphereClusterV1Beta2Status groups all the fields that will be added or modified in VSphereClusterStatus with the V1Beta2 version. See https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/proposals/20240916-improve-status-in-CAPI-resources.md for more context.

Appears In:
Field Description Default Validation

conditions Condition array

conditions represents the observations of a VSphereCluster’s current state.
Known condition types are Ready, ResourcePolicyReady, NetworkReady, LoadBalancerReady,
ProviderServiceAccountsReady, ServiceDiscoveryReady and Paused.

MaxItems: 32

VSphereMachine

VSphereMachine is the Schema for the vspheremachines API

Field Description Default Validation

apiVersion string

vmware.infrastructure.cluster.x-k8s.io/v1beta1

kind string

VSphereMachine

metadata ObjectMeta

Refer to Kubernetes API documentation for fields of metadata.

MinProperties: 1

spec VSphereMachineSpec

status VSphereMachineStatus

VSphereMachineNetworkDHCPOptionsStatus

VSphereMachineNetworkDHCPOptionsStatus describes the observed state of DHCP options.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

config KeyValuePair array

config describes platform-dependent settings for the DHCP client.

The key part is a unique number while the value part is the platform
specific configuration command. For example on Linux and BSD systems
using the file dhclient.conf output would be reported at system scope:
key='1', value='timeout 60;' key='2', value='reboot 10;'. The output
reported per interface would be:
key='1', value='prepend domain-name-servers 192.0.2.1;'
key='2', value='require subnet-mask, domain-name-servers;'.

MaxItems: 100
MinItems: 1

enabled boolean

enabled reports the status of the DHCP client services.

VSphereMachineNetworkDHCPStatus

VSphereMachineNetworkDHCPStatus describes the observed state of the client-side, system-wide DHCP settings for IP4 and IP6.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

ip4 VSphereMachineNetworkDHCPOptionsStatus

ip4 describes the observed state of the IP4 DHCP client settings.

MinProperties: 1

ip6 VSphereMachineNetworkDHCPOptionsStatus

ip6 describes the observed state of the IP6 DHCP client settings.

MinProperties: 1

VSphereMachineNetworkDNSStatus

VSphereMachineNetworkDNSStatus describes the observed state of the guest’s RFC 1034 client-side DNS settings.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

dhcp boolean

dhcp indicates whether or not dynamic host control protocol (DHCP) was
used to configure DNS configuration.

domainName string

domainName is the domain name portion of the DNS name. For example,
the "domain.local" part of "my-vm.domain.local".

MaxLength: 512
MinLength: 1

hostName string

hostName is the host name portion of the DNS name. For example,
the "my-vm" part of "my-vm.domain.local".

MaxLength: 512
MinLength: 1

nameservers string array

nameservers is a list of the IP addresses for the DNS servers to use.

IP4 addresses are specified using dotted decimal notation. For example,
"192.0.2.1".

IP6 addresses are 128-bit addresses represented as eight fields of up to
four hexadecimal digits. A colon separates each field (:). For example,
2001:DB8:101::230:6eff:fe04:d9ff. The address can also consist of the
symbol '::' to represent multiple 16-bit groups of contiguous 0’s only
once in an address as described in RFC 2373.

MaxItems: 100
MinItems: 1
items:MaxLength: 512
items:MinLength: 1

searchDomains string array

searchDomains is a list of domains in which to search for hosts, in the
order of preference.

MaxItems: 100
MinItems: 1
items:MaxLength: 512
items:MinLength: 1

VSphereMachineNetworkInterfaceIPAddrStatus

VSphereMachineNetworkInterfaceIPAddrStatus describes information about a specific IP address.

Appears In:
Field Description Default Validation

address string

address is an IP4 or IP6 address and their network prefix length.

An IP4 address is specified using dotted decimal notation. For example,
"192.0.2.1".

IP6 addresses are 128-bit addresses represented as eight fields of up to
four hexadecimal digits. A colon separates each field (:). For example,
2001:DB8:101::230:6eff:fe04:d9ff. The address can also consist of the
symbol '::' to represent multiple 16-bit groups of contiguous 0’s only
once in an address as described in RFC 2373.

MaxLength: 512
MinLength: 7

lifetime Time

lifetime describes when this address will expire.

origin string

origin describes how this address was configured.

Enum: [dhcp linklayer manual other random]

state string

state describes the state of this IP address.

Enum: [deprecated duplicate inaccessible invalid preferred tentative unknown]

VSphereMachineNetworkInterfaceIPStatus

VSphereMachineNetworkInterfaceIPStatus describes the observed state of a VM’s network interface’s IP configuration.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

autoConfigurationEnabled boolean

autoConfigurationEnabled describes whether or not ICMPv6 router
solicitation requests are enabled or disabled from a given interface.

These requests acquire an IP6 address and default gateway route from
zero-to-many routers on the connected network.

If not set then ICMPv6 is not available on this VM.

dhcp VSphereMachineNetworkDHCPStatus

dhcp describes the VM’s observed, client-side, interface-specific DHCP
options.

MinProperties: 1

addresses VSphereMachineNetworkInterfaceIPAddrStatus array

addresses describes observed IP addresses for this interface.

MaxItems: 10
MinItems: 1

macAddr string

macAddr describes the observed MAC address for this interface.

MaxLength: 512
MinLength: 1

VSphereMachineNetworkInterfaceStatus

VSphereMachineNetworkInterfaceStatus describes the observed state of a VM’s network interface.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

name string

name describes the corresponding network interface with the same name
in the VM’s desired network interface list. If unset, then there is no
corresponding entry for this interface.

Please note this name is not necessarily related to the name of the
device as it is surfaced inside of the guest.

MaxLength: 512
MinLength: 2

deviceKey integer

deviceKey describes the unique hardware device key of this network
interface.

Maximum: 1e+06
Minimum: 1

ip VSphereMachineNetworkInterfaceIPStatus

ip describes the observed state of the interface’s IP configuration.

MinProperties: 1

dns VSphereMachineNetworkDNSStatus

dns describes the observed state of the interface’s DNS configuration.

MinProperties: 1

VSphereMachineNetworkSpec

VSphereMachineNetworkSpec defines the network configuration of a VSphereMachine.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

interfaces InterfacesSpec

interfaces is the list of network interfaces attached to this VSphereMachine.

MinProperties: 1

VSphereMachineNetworkStatus

VSphereMachineNetworkStatus defines the observed state of a VM’s network configuration.

This a mirror of the v1alpha2 VirtualMachineNetworkStatus. See https://github.com/vmware-tanzu/vm-operator/blob/main/api/v1alpha2/virtualmachine_network_types.go for more information.

Validation:

  • MinProperties: 1

Appears In:
Field Description Default Validation

interfaces VSphereMachineNetworkInterfaceStatus array

interfaces describes the status of the VM’s network interfaces.

MaxItems: 100
MinItems: 1
MinProperties: 1

VSphereMachineSpec

VSphereMachineSpec defines the desired state of VSphereMachine.

Appears In:
Field Description Default Validation

providerID string

ProviderID is the virtual machine’s BIOS UUID formatted as
vsphere://12345678-1234-1234-1234-123456789abc.
This is required at runtime by CAPI. Do not remove this field.

failureDomain string

FailureDomain is the failure domain the machine will be created in.
Must match a key in the FailureDomains map stored on the cluster object.

imageName string

ImageName is the name of the base image used when specifying the
underlying virtual machine

className string

ClassName is the name of the class used when specifying the underlying
virtual machine

storageClass string

StorageClass is the name of the storage class used when specifying the
underlying virtual machine.

volumes VSphereMachineVolume array

Volumes is the set of PVCs to be created and attached to the VSphereMachine

network VSphereMachineNetworkSpec

network is the network configuration for the VSphereMachine

MinProperties: 1

powerOffMode VirtualMachinePowerOpMode

PowerOffMode describes the desired behavior when powering off a VM.

There are three, supported power off modes: hard, soft, and
trySoft. The first mode, hard, is the equivalent of a physical
system’s power cord being ripped from the wall. The soft mode
requires the VM’s guest to have VM Tools installed and attempts to
gracefully shut down the VM. Its variant, trySoft, first attempts
a graceful shutdown, and if that fails or the VM is not in a powered off
state after reaching 5 minutes timeout, the VM is halted.

If omitted, the mode defaults to hard.

hard

Enum: [hard soft trySoft]

minHardwareVersion string

MinHardwareVersion specifies the desired minimum hardware version
for this VM. Setting this field will ensure that the hardware version
of the VM is at least set to the specified value.
The expected format of the field is vmx-15.

namingStrategy VirtualMachineNamingStrategy

NamingStrategy allows configuring the naming strategy used when calculating the name of the VirtualMachine.

VSphereMachineStatus

VSphereMachineStatus defines the observed state of VSphereMachine.

Appears In:
Field Description Default Validation

ready boolean

Ready is true when the provider resource is ready.
This is required at runtime by CAPI. Do not remove this field.

addresses NodeAddress array

Addresses contains the instance associated addresses.

MaxItems: 10
MinItems: 1

vmID string

ID is used to identify the virtual machine.

vmIp string

IPAddr is the IP address used to access the virtual machine.

failureReason MachineStatusError

FailureReason will be set in the event that there is a terminal problem
reconciling the Machine and will contain a succinct value suitable
for machine interpretation.

This field should not be set for transitive errors that a controller
faces that are expected to be fixed automatically over
time (like service outages), but instead indicate that something is
fundamentally wrong with the Machine’s spec or the configuration of
the controller, and that manual intervention is required. Examples
of terminal errors would be invalid combinations of settings in the
spec, values that are unsupported by the controller, or the
responsible controller itself being critically misconfigured.

Any transient errors that occur during the reconciliation of Machines
can be added as events to the Machine object and/or logged in the
controller’s output.

failureMessage string

FailureMessage will be set in the event that there is a terminal problem
reconciling the Machine and will contain a more verbose string suitable
for logging and human consumption.

This field should not be set for transitive errors that a controller
faces that are expected to be fixed automatically over
time (like service outages), but instead indicate that something is
fundamentally wrong with the Machine’s spec or the configuration of
the controller, and that manual intervention is required. Examples
of terminal errors would be invalid combinations of settings in the
spec, values that are unsupported by the controller, or the
responsible controller itself being critically misconfigured.

Any transient errors that occur during the reconciliation of Machines
can be added as events to the Machine object and/or logged in the
controller’s output.

vmstatus VirtualMachineState

VMStatus is used to identify the virtual machine status.

conditions Conditions

Conditions defines current service state of the VSphereMachine.

v1beta2 VSphereMachineV1Beta2Status

v1beta2 groups all the fields that will be added or modified in VSphereMachine’s status with the V1Beta2 version.

network VSphereMachineNetworkStatus

network describes the observed state of the VM’s network configuration.
Please note much of the network status information is only available if
the guest has VM Tools installed.

MinProperties: 1

VSphereMachineTemplate

VSphereMachineTemplate is the Schema for the vspheremachinetemplates API.

Field Description Default Validation

apiVersion string

vmware.infrastructure.cluster.x-k8s.io/v1beta1

kind string

VSphereMachineTemplate

metadata ObjectMeta

Refer to Kubernetes API documentation for fields of metadata.

MinProperties: 1

spec VSphereMachineTemplateSpec

status VSphereMachineTemplateStatus

VSphereMachineTemplateResource

VSphereMachineTemplateResource describes the data needed to create a VSphereMachine from a template.

Appears In:
Field Description Default Validation

spec VSphereMachineSpec

Spec is the specification of the desired behavior of the machine.

VSphereMachineTemplateSpec

VSphereMachineTemplateSpec defines the desired state of VSphereMachineTemplate.

Appears In:
Field Description Default Validation

template VSphereMachineTemplateResource

VSphereMachineTemplateStatus

VSphereMachineTemplateStatus defines the observed state of VSphereMachineTemplate.

Appears In:

VSphereMachineV1Beta2Status

VSphereMachineV1Beta2Status groups all the fields that will be added or modified in VSphereMachineStatus with the V1Beta2 version. See https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/proposals/20240916-improve-status-in-CAPI-resources.md for more context.

Appears In:
Field Description Default Validation

conditions Condition array

conditions represents the observations of a VSphereMachine’s current state.
Known condition types are Ready, VirtualMachineProvisioned and Paused.

MaxItems: 32

VSphereMachineVolume

VSphereMachineVolume defines a PVC attachment.

Appears In:
Field Description Default Validation

name string

Name is suffix used to name this PVC as: VSphereMachine.Name + "-" + Name

storageClass string

StorageClass defaults to VSphereMachineSpec.StorageClass

VirtualMachineNamingStrategy

VirtualMachineNamingStrategy defines the naming strategy for the VirtualMachines.

Appears In:
Field Description Default Validation

template string

Template defines the template to use for generating the name of the VirtualMachine object.
If not defined, it will fall back to {{ .machine.name }}.
The templating has the following data available:
* .machine.name: The name of the Machine object.
The templating also has the following funcs available:
* trimSuffix: same as strings.TrimSuffix
* trunc: truncates a string, e.g. trunc 2 "hello" or trunc -2 "hello"
Notes:
* While the template offers some flexibility, we would like the name to link to the Machine name
to ensure better user experience when troubleshooting
* Generated names must be valid Kubernetes names as they are used to create a VirtualMachine object
and usually also as the name of the Node object.
* Names are automatically truncated at 63 characters. Please note that this can lead to name conflicts,
so we highly recommend to use a template which leads to a name shorter than 63 characters.

VirtualMachinePowerOpMode

Underlying type: string

VirtualMachinePowerOpMode represents the various power operation modes when powering off or suspending a VM.

Validation:

  • Enum: [hard soft trySoft]

Appears In:

VirtualMachineState

Underlying type: string

VirtualMachineState describes the state of a VM.

Appears In:

kubernetes.vmware.com/v1alpha1

Package v1alpha1 contains API Schema definitions for the kubernetes.vmware.com v1alpha1 API group

Resource Types

ContainerImageInfo

ContainerImageInfo allows to customize the image used for components that are not originated from the Kubernetes/Kubernetes release process (such as etcd and coredns).

Appears In:
Field Description Default Validation

imageRepository string

ImageRepository sets the container registry to pull images from.
if not set, defaults to the ImageRepository defined in KubernetesSpec.

imageTag string

ImageTag specifies a tag for the image.

KubernetesRelease

KubernetesRelease is the schema for the kubernetesreleases API. KubernetesRelease objects represent Kubernetes releases available via Kubernetes Service, which can be used to create KubernetesCluster instances. KRs are immutable to end-users. They are created and managed by Kubernetes Service to provide discovery of Kubernetes releases to Kubernetes Service users.

Field Description Default Validation

apiVersion string

kubernetes.vmware.com/v1alpha1

kind string

KubernetesRelease

metadata ObjectMeta

Refer to Kubernetes API documentation for fields of metadata.

MinProperties: 1

spec KubernetesReleaseSpec

status KubernetesReleaseStatus

KubernetesReleaseSpec

KubernetesReleaseSpec defines the desired state of KubernetesRelease

Appears In:
Field Description Default Validation

version string

Version is the fully qualified Semantic Versioning conformant version of the KubernetesRelease.
Version MUST be unique across all KubernetesRelease objects.

kubernetes KubernetesSpec

Kubernetes is Kubernetes

osImages LocalObjectReference array

OSImages lists references to all OSImage objects shipped with this KubernetesRelease.

bootstrapPackages LocalObjectReference array

BootstrapPackages lists references to all bootstrap packages shipped with this KubernetesRelease.

KubernetesReleaseStatus

KubernetesReleaseStatus defines the observed state of KubernetesRelease

Appears In:
Field Description Default Validation

conditions Condition array

KubernetesSpec

KubernetesSpec specifies the details about the Kubernetes distribution shipped by this KubernetesRelease.

Appears In:
Field Description Default Validation

version string

Version is Semantic Versioning conformant version of the Kubernetes build shipped by this KubernetesRelease.
The same Kubernetes build MAY be shipped by multiple KubernetesReleases.

imageRepository string

ImageRepository specifies container image registry to pull images from.

etcd ContainerImageInfo

Etcd specifies the container image repository and tag for etcd.

pause ContainerImageInfo

Pause specifies the container image repository and tag for pause.

coredns ContainerImageInfo

CoreDNS specifies the container image repository and tag for coredns.

kube-vip ContainerImageInfo

KubeVIP specifies the container image repository and tag for kube-vip.

cni.tanzu.vmware.com/v1alpha1

Package v1alpha1 contains API Schema definitions for the cni v1alpha1 API group

Resource Types

Antrea

Appears In:
Field Description Default Validation

config AntreaConfigDataValue

{ }

windows AntreaWindowsConfigDataValue

{ }

AntreaCloudProvider

Appears In:
Field Description Default Validation

name string

Name is the cloud provider name. Disable the cloud controller if it is empty.
At the moment, the only supported value is "aws".

Optional: \{}

AntreaConfig

AntreaConfig is the Schema for the antreaconfigs API

Field Description Default Validation

apiVersion string

cni.tanzu.vmware.com/v1alpha1

kind string

AntreaConfig

metadata ObjectMeta

Refer to Kubernetes API documentation for fields of metadata.

MinProperties: 1

spec AntreaConfigSpec

status AntreaConfigStatus

AntreaConfigDataValue

Appears In:
Field Description Default Validation

egress AntreaEgress

Specifies Egress related configuration.

Optional: \{}

nodePortLocal AntreaNodePortLocal

Specifies NodePortLocal related configuration.

Optional: \{}

antreaProxy AntreaProxy

Specifies AntreaProxy related configuration.

Optional: \{}

flowExporter AntreaFlowExporter

Specifies FlowExporter related configuration.

Optional: \{}

kubeAPIServerOverride string

Provide the address of Kubernetes apiserver, to override any value provided in kubeconfig or InClusterConfig.

Optional: \{}

multicast AntreaMulticast

Multicast related configuration.

Optional: \{}

multicluster AntreaMultiCluster

MultiCluster realted configuration.

Optional: \{}

cloudProvider AntreaCloudProvider

CloudProvider realted configuration.

Optional: \{}

transportInterface string

The name of the interface on Node which is used for tunneling or routing.

Optional: \{}

transportInterfaceCIDRs string array

The network CIDRs of the interface on Node which is used for tunneling or routing.

Optional: \{}

multicastInterfaces string array

The names of the interfaces on Nodes that are used to forward multicast traffic.

Optional: \{}

tunnelType string

Tunnel protocols used for encapsulating traffic across Nodes. One of the following options =:> geneve, vxlan, gre, stt

Optional: \{}

tunnelPort integer

TunnelPort is the destination port for UDP and TCP based tunnel protocols (Geneve, VXLAN, and STT).If zero, it will use the assigned IANA port for the protocol.

0

Optional: \{}

tunnelCsum boolean

TunnelCsum determines whether to compute UDP encapsulation header (Geneve or VXLAN) checksums on outgoing packets

false

Optional: \{}

trafficEncryptionMode string

Determines how tunnel traffic is encrypted. One of the following options =:> none, ipsec, wireguard

Optional: \{}

enableUsageReporting boolean

Enable usage reporting (telemetry) to VMware.

false

Optional: \{}

wireGuard AntreaWireGuard

Specifies WireGuard related configuration.

Optional: \{}

serviceCIDR string

ClusterIP CIDR range for Services.

Optional: \{}

trafficEncapMode string

The traffic encapsulation mode. One of the following options ⇒ encap, noEncap, hybrid, networkPolicyOnly

encap

Enum: [encap noEncap hybrid networkPolicyOnly]
Optional: \{}

noSNAT boolean

Flag to enable/disable SNAT for the egress traffic from a Pod to the external network

false

Optional: \{}

disableUdpTunnelOffload boolean

Disable UDP tunnel offload feature on default NIC

false

Optional: \{}

defaultMTU string

Default MTU to use for the host gateway interface and the network interface of each Pod. If omitted, antrea-agent will discover the MTU of the Node’s primary interface

Optional: \{}

tlsCipherSuites string

List of allowed cipher suites. If omitted, the default Go Cipher Suites will be used

TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_256_GCM_SHA384

Optional: \{}

enableBridgingMode boolean

Enable bridging mode of Pod network on Nodes

false

Optional: \{}

disableTXChecksumOffload boolean

Disable TX checksum offloading for container network interfaces

false

Optional: \{}

dnsServerOverride string

Provide the address of DNS server, to override the kube-dns service

Optional: \{}

fqdnCacheMinTTL integer

fqdnCacheMinTTL helps address the issue of applications caching DNS response IPs beyond the TTL value
for the DNS record. It is used to enforce FQDN policy rules, ensuring that resolved IPs are included
in datapath rules for as long as the application caches them. Ideally, this value should be set to
the maximum caching duration across all applications.

Optional: \{}

snatFullyRandomPorts boolean

Fully randomize source port mapping in SNAT rules used for egress traffic from Pods to the external network.

Optional: \{}

featureGates AntreaFeatureGates

FeatureGates is a map of feature names to flags that enable or disable experimental features

{ }

Optional: \{}

packetInRate integer

PacketInRate defines the OVS controller packet rate limits for different features. The number stands for the
rate as packets per second(pps) and the burst size will be automatically set to twice the rate.

Optional: \{}

auditLogging AuditLogging

Log rotation configuration for audit logs.

Optional: \{}

secondaryNetwork AntreaSecondaryNetwork

Configuration of OVS bridges for secondary network. At the moment, at
most one OVS bridge can be specified. If the specified bridge does not exist
on the Node, antrea-agent will create it based on the configuration.

Optional: \{}

AntreaConfigSpec

AntreaConfigSpec defines the desired state of AntreaConfig

Appears In:
Field Description Default Validation

antrea Antrea

{ }

antreaNSX AntreaNSX

AntreaNSX defines nsxt adapter related configurations

{ }

antreaIPFIX AntreaIPFIX

{ }

AntreaConfigStatus

AntreaConfigStatus defines the observed state of AntreaConfig

Appears In:
Field Description Default Validation

message string

Message to indicate failure reason

Optional: \{}

secretRef string

Reference to the data value secret created by controller

Optional: \{}

AntreaEgress

Appears In:
Field Description Default Validation

exceptCIDRs string array

EgressExceptCIDRs is a list of CIDR ranges to which outbound Pod traffic will not be SNAT’d by Egresses,
e.g. ["192.168.0.0/16", "172.16.0.0/12"].

maxEgressIPsPerNode integer

MaxEgressIPsPerNode is the maximum number of Egress IPs that can be assigned to a Node. It’s useful when
the Node network restricts the number of secondary IPs a Node can have. It must not be greater than 255.

snatFullyRandomPorts boolean

SnatFullyRandomPorts fully randomizes source port mapping in Egress SNAT rules. This has no impact on
the default SNAT rules enforced by each Node for local Pod traffic. By default, we use the same value as for
the top-level snatFullyRandomPorts configuration, but this field can be used as an override.

Optional: \{}

AntreaFeatureGates

Appears In:
Field Description Default Validation

AntreaProxy boolean

Enable AntreaProxy which provides ServiceLB for in-cluster Services in antrea-agent.
Note that this feature gate is deprecated since this feature was promoted to GA in v1.14.

true

Optional: \{}

EndpointSlice boolean

Flag to enable/disable EndpointSlice support in AntreaProxy. If AntreaProxy is not enabled, this flag will not take effect

false

Optional: \{}

AntreaPolicy boolean

Flag to enable/disable antrea policy

true

Optional: \{}

FlowExporter boolean

Flag to enable/disable flow exporter

false

Optional: \{}

Egress boolean

Flag to enable/disable SNAT IPs of Pod egress traffic

true

Optional: \{}

NodePortLocal boolean

Flag to enable/disable NodePortLocal feature to make the pods reachable externally through NodePort

true

Optional: \{}

AntreaTraceflow boolean

Flag to enable/disable antrea traceflow

true

Optional: \{}

NetworkPolicyStats boolean

Flag to enable/disable network policy stats

false

Optional: \{}

AntreaIPAM boolean

Flag to enable/disable antrea IPAM

false

Optional: \{}

ServiceExternalIP boolean

Flag to enable/disable service external IP

false

Optional: \{}

Multicast boolean

Flag to enable/disable multicast

false

Optional: \{}

Multicluster boolean

Enable Antrea Multi-cluster Gateway to support cross-cluster traffic.

false

Optional: \{}

SecondaryNetwork boolean

Enable support for provisioning secondary network interfaces for Pods (using Pod annotations).

false

Optional: \{}

TrafficControl boolean

Enable mirroring or redirecting the traffic Pods send or receive.

false

Optional: \{}

TopologyAwareHints boolean

Enable TopologyAwareHints in AntreaProxy. This requires AntreaProxy and EndpointSlice to be enabled, otherwise this flag will not take effect.

false

Optional: \{}

SupportBundleCollection boolean

Enable collecting support bundle files with SupportBundleCollection CRD.

Optional: \{}

L7NetworkPolicy boolean

Enable users to protect their applications by specifying how they are allowed to communicate with others.

Optional: \{}

AdminNetworkPolicy boolean

Enable the use of Network Policy APIs which helps administrators set security postures for their clusters.

Optional: \{}

CleanupStaleUDPSvcConntrack boolean

Enable support for cleaning up stale UDP Service conntrack connections in AntreaProxy

Optional: \{}

NodeLatencyMonitor boolean

Enable NodeLatencyMonitor to monitor the latency between Nodes.

Optional: \{}

EgressTrafficShaping boolean

Enable Egress traffic shaping.

Optional: \{}

EgressSeparateSubnet boolean

Allow users to allocate Egress IPs from a different subnet from the default Node subnet.

Optional: \{}

NodeNetworkPolicy boolean

Allow users to apply ClusterNetworkPolicy to Kubernetes Nodes.

Optional: \{}

L7FlowExporter boolean

Enable L7FlowExporter on Pods and Namespaces to export the application layer flows such as HTTP flows.

Optional: \{}

PacketCapture boolean

Enable PacketCapture feature which supports capturing packets to diagnose network issues.

Optional: \{}

ServiceTrafficDistribution boolean

Enable ServiceTrafficDistribution in AntreaProxy. This requires AntreaProxy and EndpointSlice to be
enabled, otherwise this flag will not take effect.

Optional: \{}

AntreaFlowExporter

Appears In:
Field Description Default Validation

enable boolean

Enable FlowExporter, a feature used to export polled conntrack connections as
IPFIX flow records from each agent to a configured collector. To enable this
feature, you need to set "enable" to true, and ensure that the FlowExporter
feature gate is also enabled.

collectorAddress string

CollectorAddress provides the IPFIX collector address as a string with format <HOST>:[<PORT>][:<PROTO>].
HOST can either be the DNS name, IP, or Service name of the Flow Collector. If
using an IP, it can be either IPv4 or IPv6. However, IPv6 address should be
wrapped with []. When the collector is running in-cluster as a Service, set
<HOST> to <Service namespace>/<Service name>. For example,
"flow-aggregator/flow-aggregator" can be provided to connect to the Antrea
Flow Aggregator Service.
If PORT is empty, we default to 14739. If no PROTO is given, we consider "grpc" as default.
We support "grpc", "tls", "tcp" and "udp" protocols. "grpc", "tls" are used for securing
communication between flow exporter and flow aggregator.

pollInterval string

PollInterval provides flow poll interval as a duration string. This determines how often the
flow exporter dumps connections from the conntrack module. Flow poll interval
should be greater than or equal to 1s (one second).
Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h".

activeFlowTimeout string

ActiveFlowTimeout provides the active flow export timeout, which is the timeout after which a flow
record is sent to the collector for active flows. Thus, for flows with a continuous
stream of packets, a flow record will be exported to the collector once the elapsed
time since the last export event is equal to the value of this timeout.
Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h".

idleFlowTimeout string

IdleFlowTimeout provides the idle flow export timeout, which is the timeout after which a flow
record is sent to the collector for idle flows. A flow is considered idle if no
packet matching this flow has been observed since the last export event.
Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h".

AntreaIPFIX

Appears In:
Field Description Default Validation

enable boolean

Enable indicates AntreaIPFIX shall be enabled in the cluster

Optional: \{}

AntreaMultiCluster

Appears In:
Field Description Default Validation

enable boolean

Enable indicates whether to enable Antrea Multi-cluster Gateway to support cross-cluster traffic.
This feature is supported only with encap mode.

namespace string

Namespace is the Namespace where Antrea Multi-cluster Controller is running.
The default is antrea-agent’s Namespace.

enableStretchedNetworkPolicy boolean

EnableStretchedNetworkPolicy enables Multi-cluster NetworkPolicy (ingress rules).
Multi-cluster Gateway must be enabled to enable StretchedNetworkPolicy.

enablePodToPodConnectivity boolean

EnablePodToPodConnectivity enables Pod to Pod connectivity.

AntreaMulticast

Appears In:
Field Description Default Validation

enable boolean

Enable is used to enable Multicast. You need to set "enable" to true, and ensure that the
Multicast feature gate is also enabled (which is the default).

igmpQueryInterval string

IGMPQueryInterval is the interval at which the antrea-agent sends IGMP queries to Pods.
Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h".

igmpQueryVersions integer array

IGMPQueryVersions specifies the versions of IGMP queries antrea-agent sends to Pods.
Valid versions are 1, 2 and 3.

AntreaNSX

Appears In:
Field Description Default Validation

enable boolean

Enable indicates whether nsxt adapter shall be enabled in the cluster.

Optional: \{}

config AntreaNSXConfig

Config is configuration for nsxt adapter.

{ }

Optional: \{}

AntreaNSXConfig

Appears In:
Field Description Default Validation

bootstrapFrom string

BootstrapFrom is used to specify the bootstrap method: either Inline or SupervisorCluster.

Optional: \{}

nsxCert string

One line base64 encoded data. Can be generated by command: cat tls.crt | base64 -w 0

Optional: \{}

nsxKey string

NSXKey is base64 encoded NSX client key data.One line base64 encoded data. Can be generated by command: cat tls.key | base64 -w 0

Optional: \{}

clusterName string

ClusterName is the name of the cluster.

Optional: \{}

nsxManagers string array

NSXManagers is a string slice that contains the IP address or domain name of the NSX Managers.

Optional: \{}

vpcPath string array

VPCPath is the VPC configuration path.

Optional: \{}

proxyEndpoints ProxyEndpoints

ProxyEndpoints is a struct for proxy endpoints containing the information needed to access the API server.

Optional: \{}

mpAdapterConf MPAdapterConf

{ }

Optional: \{}

ccpAdapterConf CCPAdapterConf

{ }

Optional: \{}

AntreaNodePortLocal

Appears In:
Field Description Default Validation

enabled boolean

Enabled enables NodePortLocal, a feature used to make Pods reachable using port forwarding on the host.

portRange string

PortRange provides the port range used by NodePortLocal. When the NodePortLocal feature is enabled, a port
from that range will be assigned whenever a Pod’s container defines a specific port to be exposed
(each container can define a list of ports as pod.spec.containers[].ports), and all Node traffic
directed to that port will be forwarded to the Pod. Format: "61000-62000".

AntreaProxy

Appears In:
Field Description Default Validation

proxyAll boolean

ProxyAll tells antrea-agent to proxy all Service traffic, including NodePort, LoadBalancer, and ClusterIP traffic,
regardless of where they come from. Therefore, running kube-proxy is no longer required.
Note that this option is experimental. If kube-proxy is removed, option kubeAPIServerOverride must be used to access apiserver directly.

nodePortAddresses string array

NodePortAddresses is a string array of values which specifies the host IPv4/IPv6 addresses for NodePort. Values can be valid IP blocks.
(e.g. 1.2.3.0/24, 1.2.3.4/32). An empty string slice is meant to select all host IPv4/IPv6 addresses.
Note that the option is only valid when proxyAll is true.

skipServices string array

SkipServices is an array of string values to specify a list of Services which should be ignored by AntreaProxy (traffic to these
Services will not be load-balanced). Values can be a valid ClusterIP (e.g. 10.11.1.2) or a Service name
with Namespace (e.g. kube-system/kube-dns)

proxyLoadBalancerIPs boolean

ProxyLoadBalancerIPs when set to false, AntreaProxy no longer load-balances traffic destined to the
External IPs of LoadBalancer Services. This is useful when the external LoadBalancer provides additional
capabilities (e.g. TLS termination) and it is desirable for Pod-to-ExternalIP traffic to be sent to the
external LoadBalancer instead of being load-balanced to an Endpoint directly by AntreaProxy.
Note that setting ProxyLoadBalancerIPs to false usually only makes sense when proxyAll is set to true and
kube-proxy is removed from the cluster, otherwise kube-proxy will still load-balance this traffic.

serviceProxyName string

ServiceProxyName is the value of the "service.kubernetes.io/service-proxy-name" label for AntreaProxy to match. If it is set,
then AntreaProxy will only handle Services with the label that equals the provided value. If it is not set,
then AntreaProxy will only handle Services without the "service.kubernetes.io/service-proxy-name" label,
ignoring Services with the label regardless of the value.

enable boolean

Enable controls whether to disable AntreaProxy. Set this to false to disable AntreaProxy.

disableServiceHealthCheckServer boolean

DisableServiceHealthCheckServer disables the health check server run by Antrea Proxy, which provides health information about
Services of type LoadBalancer with externalTrafficPolicy set to Local, when proxyAll is enabled. This avoids race conditions
between kube-proxy and Antrea proxy, with both trying to bind to the same addresses, when proxyAll is enabled while
kube-proxy has not been removed.

AntreaSecondaryNetwork

Appears In:
Field Description Default Validation

ovsBridges OVSBridge array

OVSBridges is the configuration of OVS bridges for secondary network. At the moment, at
most one OVS bridge can be specified. If the specified bridge does not exist
on the Node, antrea-agent will create it based on the configuration.

AntreaWindowsConfig

Appears In:
Field Description Default Validation

antreaProxy AntreaWindowsProxy

Specifies AntreaProxy related configuration.

Optional: \{}

nodePortLocal AntreaNodePortLocal

Specifies NodePortLocal related configuration.

Optional: \{}

flowExporter AntreaFlowExporter

Specifies FlowExporter related configuration.

Optional: \{}

kubeAPIServerOverride string

Provide the address of Kubernetes apiserver, to override any value provided in kubeconfig or InClusterConfig.

Optional: \{}

transportInterface string

The name of the interface on Node which is used for tunneling or routing.

Optional: \{}

transportInterfaceCIDRs string array

The network CIDRs of the interface on Node which is used for tunneling or routing.

Optional: \{}

tlsCipherSuites string

List of allowed cipher suites. If omitted, the default Go Cipher Suites will be used

TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_256_GCM_SHA384

Optional: \{}

featureGates AntreaWindowsFeatureGates

FeatureGates is a map of feature names to flags that enable or disable experimental features

Optional: \{}

AntreaWindowsConfigDataValue

Appears In:
Field Description Default Validation

config AntreaWindowsConfig

{ }

Optional: \{}

enable boolean

Enable windows config

Optional: \{}

AntreaWindowsFeatureGates

Appears In:
Field Description Default Validation

AntreaProxy boolean

Enable antrea proxy which provides ServiceLB for in-cluster services in antrea agent.
It should be enabled on Windows, otherwise NetworkPolicy will not take effect on
Service traffic. Note that this feature gate is deprecated since this feature was
promoted to GA in v1.14.

Optional: \{}

NodePortLocal boolean

Enable NodePortLocal feature to make the Pods reachable externally through NodePort

Optional: \{}

FlowExporter boolean

Enable flowexporter which exports polled conntrack connections as IPFIX flow records from each agent to a configured collector.

Optional: \{}

AntreaWindowsProxy

Appears In:
Field Description Default Validation

enable boolean

Enable controls whether to enable AntreaProxy on Windows nodes. Set this to true to enable AntreaProxy.
To disable AntreaProxy, set this to false. It should be enabled on Windows, otherwise NetworkPolicy will
not take effect on Service traffic.

proxyAll boolean

ProxyAll tells antrea-agent to proxy ClusterIP Service traffic, regardless of where they come from.
Therefore, running kube-proxy is no longer required. This requires the AntreaProxy feature to be enabled.
Note that this option is experimental. If kube-proxy is removed, option kubeAPIServerOverride must be used to access apiserver directly.

serviceProxyName string

The value of the "service.kubernetes.io/service-proxy-name" label for AntreaProxy to match. If it is set,
then AntreaProxy will only handle Services with the label that equals the provided value. If it is not set,
then AntreaProxy will only handle Services without the "service.kubernetes.io/service-proxy-name" label,
but ignore Services with the label no matter what is the value.

AntreaWireGuard

Appears In:
Field Description Default Validation

port integer

Port is the port for WireGuard to receive traffic.

AuditLogging

Appears In:
Field Description Default Validation

maxSize integer

MaxSize is the maximum size in MB of a log file before it gets rotated.

maxBackups integer

MaxBackups is the maximum number of old log files to retain. If set to 0,
all log files will be retained (unless MaxAge causes them to be deleted).

maxAge integer

MaxAge is the maximum number of days to retain old log files based on the
timestamp encoded in their filename. If set to 0, old log files are not
removed based on age.

compress boolean

Compress enables gzip compression on rotated files.

CCPAdapterConf

Appears In:
Field Description Default Validation

enableDebugServer boolean

EnableDebugServer indicates whether to enable the debug server.

Optional: \{}

apiServerPort integer

Port on which the API server listens.

Optional: \{}

debugServerPort integer

DebugServerPort is the port for the APIServer to serve on. Defaults to 16667.

Optional: \{}

nsxRPCDebug boolean

NSXRPCDebug indicates whether to enable NSX RPC debug mode.

Optional: \{}

realizeTimeoutSeconds integer

Time to wait for realization.

Optional: \{}

realizeErrorSyncIntervalSeconds integer

An interval for regularly report latest realization error in background.

Optional: \{}

reconcilerWorkerCount integer

Number of workers for reconciler.

Optional: \{}

reconcilerQPS integer

Average QPS = ReconcilerWorkerCount * ReconcilerQPS

Optional: \{}

reconcilerBurst integer

Peak QPS = ReconcilerWorkerCount * ReconcilerBurst

Optional: \{}

reconcilerResyncSeconds integer

Period for Reconciler to rsync downstream events.

Optional: \{}

Calico

Calico stores the configurations for Calico.

Appears In:
Field Description Default Validation

config CalicoConfigDataValue

CalicoConfig

CalicoConfig is the Schema for the calicoconfigs API.

Field Description Default Validation

apiVersion string

cni.tanzu.vmware.com/v1alpha1

kind string

CalicoConfig

metadata ObjectMeta

Refer to Kubernetes API documentation for fields of metadata.

MinProperties: 1

spec CalicoConfigSpec

status CalicoConfigStatus

CalicoConfigDataValue

CalicoConfigDataValue contains the specific configurations for the Calico package.

Appears In:
Field Description Default Validation

vethMTU integer

VethMTU defines maximum transmission unit. "0" as default means MTU will be auto detected.

0

Minimum: 0
Optional: \{}

skipCNIBinaries boolean

SkipCNIBinaries allows to skip the cni plugin binaries installation.
Default to false. Set to true for providers who already installed
cni plugin binaries in their OVAs and do not want Calico to overwrite them.

false

Optional: \{}

ipv4AutodetectionMethod string

The method to use to autodetect the IPv4 address for this host.
If it is empty then the first-found method is used.

Optional: \{}

ipv6AutodetectionMethod string

The method to use to autodetect the IPv6 address for this host.
If it is empty then the first-found method is used.

Optional: \{}

CalicoConfigSpec

CalicoConfigSpec defines the desired state of CalicoConfig.

Appears In:
Field Description Default Validation

calico Calico

CalicoConfigStatus

CalicoConfigStatus defines the observed state of CalicoConfig.

Appears In:
Field Description Default Validation

secretRef string

SecretRef is the name of the data value secret created by calico controller.

MPAdapterConf

Appears In:
Field Description Default Validation

nsxClientAuthCertFile string

Path to the client authentication certificate file.

Optional: \{}

nsxClientAuthKeyFile string

Path to the client authentication key file.

Optional: \{}

nsxRemoteAuth boolean

NSXRemoteAuth indicates whether to use remote authentication.

Optional: \{}

nsxCAFile string

Path to the CA file.

Optional: \{}

nsxInsecure boolean

NSXInsecure indicates whether to enable insecure connections.

Optional: \{}

nsxRPCConnType string

NsxRpcConnType is the NSX connection type: either mock or tnproxy.

Optional: \{}

clusterType string

ClusterType represents the type of the cluster.

Optional: \{}

nsxClientTimeout integer

Timeout for NSX client.

Optional: \{}

inventoryBatchSize integer

InventoryBatchSize is the max objects in one inventory update request.

Optional: \{}

inventoryBatchPeriod integer

InventoryBatchPeriod is the time in seconds to send out request even if the max batch size is not reached.

Optional: \{}

enableDebugServer boolean

EnableDebugServer indicates whether to enable the debug server.

Optional: \{}

apiServerPort integer

Port on which the API server listens.

Optional: \{}

debugServerPort integer

DebugServerPort is the port for the APIServer to serve on. Defaults to 16666.

Optional: \{}

nsxRPCDebug boolean

NSXRPCDebug indicates whether to enable NSX RPC debug mode.

Optional: \{}

conditionTimeout integer

Monitor for determine the timeout.

Optional: \{}

nsxVerifyServerName boolean

NSXVerifyServerName indicates whether to validate NSX server name when NSXInsecure is false.

Optional: \{}

OVSBridge

Appears In:
Field Description Default Validation

bridgeName string

BridgeName is the name of the OVS bridge for secondary network. At the moment, at
most one OVS bridge can be specified. If the specified bridge does not exist
on the Node, antrea-agent will create it based on the configuration.

physicalInterfaces string array

PhysicalInterfaces is a list of physical interfaces to be connected to the OVS bridge.
These interfaces will serve as uplinks for the bridge. For now, at most one interface
should be specified on VKS cluster

enableMulticastSnooping boolean

EnableMulticastSnooping enables multicast snooping on the OVS bridge, allowing the bridge to learn about
multicast group memberships and forward multicast traffic only to ports that have interested receivers.
When disabled, multicast traffic is flooded to all ports in the bridge. The default value is false

ProxyEndpoints

ProxyEndpoints is a struct for proxy endpoints containing the information needed to access the API server.

Appears In:
Field Description Default Validation

restApi string array

RestAPI is a string slice that contains the IP address or domain name of the REST API endpoint.

Optional: \{}

nsxRpcFwdProxy string array

NSXRPCFwdProxy is a string slice that contains the IP address or domain name of the NSX RPC forward proxy.

Optional: \{}

cpi.tanzu.vmware.com/v1alpha1

Package v1alpha1 contains API Schema definitions for the cpi v1alpha1 API group

Resource Types

KubevipCPIConfig

KubevipCPIConfig is the Schema for the kubevipcpiconfigs API

Field Description Default Validation

apiVersion string

cpi.tanzu.vmware.com/v1alpha1

kind string

KubevipCPIConfig

metadata ObjectMeta

Refer to Kubernetes API documentation for fields of metadata.

MinProperties: 1

spec KubevipCPIConfigSpec

status KubevipCPIConfigStatus

KubevipCPIConfigSpec

KubevipCPIConfigSpec defines the desired state of KubevipCPIConfig

Appears In:
Field Description Default Validation

loadbalancerCIDRs string

loadbalancerCIDRs is a list of comma separated cidrs will
be used to allocate IP for external load balancer.
For example 192.168.0.200/29,192.168.1.200/29

loadbalancerIPRanges string

loadbalancerIPRanges is a list of comma separated IP ranges will
be used to allocate IP for external load balancer.
For example 192.168.0.10-192.168.0.11,192.168.0.10-192.168.0.13

KubevipCPIConfigStatus

KubevipCPIConfigStatus defines the observed state of KubevipCPIConfig

Appears In:
Field Description Default Validation

secretRef string

Name of the secret created by kubevip cloudprovider config controller

NSXTRouteConfig

Appears In:
Field Description Default Validation

routerPath string

NSX-T T0/T1 logical router path

Optional: \{}

NSXVPC

NSXVPC represents the configuration in the VPC network

Appears In:
Field Description Default Validation

podIPPoolType string

The type of IP pool for routable Pods: Public, Private

Enum: [Public Private]
Optional: \{}

ParavirtualConfig

ParavirtualConfig represents the configuration in the paravirtual mode

Appears In:
Field Description Default Validation

antreaNSXPodRoutingEnabled boolean

A flag that enables pod routing by Antrea NSX for paravirtual mode

false

Optional: \{}

nsxVPC NSXVPC

Optional: \{}

VSphereCPI

Appears In:
Field Description Default Validation

mode string

The vSphere mode. Either vsphereCPI or vsphereParavirtualCPI.

Enum: [vsphereCPI vsphereParavirtualCPI]
Optional: \{}

ParavirtualConfig ParavirtualConfig

VSphereCPIConfig

VSphereCPIConfig is the Schema for the VSphereCPIConfig API

Field Description Default Validation

apiVersion string

cpi.tanzu.vmware.com/v1alpha1

kind string

VSphereCPIConfig

metadata ObjectMeta

Refer to Kubernetes API documentation for fields of metadata.

MinProperties: 1

spec VSphereCPIConfigSpec

status VSphereCPIConfigStatus

VSphereCPIConfigSpec

VSphereCPIConfigSpec defines the desired state of VSphereCPIConfig

Appears In:
Field Description Default Validation

vsphereCPI VSphereCPI

VSphereCPIConfigStatus

VSphereCPIConfigStatus defines the observed state of VSphereCPIConfig

Appears In:
Field Description Default Validation

message string

Message to indicate failure reason

Optional: \{}

secretRef string

Name of the data value secret created by vSphere CPI controller

csi.tanzu.vmware.com/v1alpha1

Package v1alpha1 contains API Schema definitions for the csi v1alpha1 API group

Resource Types

VSphereCSI

Appears In:
Field Description Default Validation

mode string

The vSphere mode. Either vsphereCSI or vsphereParavirtualCSI.

Enum: [vsphereCSI vsphereParavirtualCSI]
Required: \{}

VSphereCSIConfig

VSphereCSIConfig is the Schema for the vspherecsiconfigs API

Field Description Default Validation

apiVersion string

csi.tanzu.vmware.com/v1alpha1

kind string

VSphereCSIConfig

metadata ObjectMeta

Refer to Kubernetes API documentation for fields of metadata.

MinProperties: 1

spec VSphereCSIConfigSpec

status VSphereCSIConfigStatus

VSphereCSIConfigSpec

VSphereCSIConfigSpec defines the desired state of VSphereCSIConfig

Appears In:
Field Description Default Validation

vsphereCSI VSphereCSI

VSphereCSIConfigStatus

VSphereCSIConfigStatus defines the observed state of VSphereCSIConfig

Appears In:
Field Description Default Validation

secretRef string

Name of the secret created by csi controller

run.tanzu.vmware.com/v1alpha3

Package v1alpha3 contains API Schema definitions for the run.tanzu v1alpha3 API group

Resource Types

APIEndpoint

APIEndpoint represents a reachable Kubernetes API endpoint.

Appears In:
Field Description Default Validation

host string

The hostname on which the API server is serving.

port integer

The port on which the API server is serving.

AddonStatus

AddonStatus represents the status of an addon.

Appears In:
Field Description Default Validation

name string

Name of the add-on used.

type AddonType

Type of the add-on used

version string

Version of the distribution applied

conditions Conditions

Conditions defines the current conditions of the add-on.

AddonType

Underlying type: string

Appears In:

CNIConfiguration

CNIConfiguration indicates which CNI should be used.

Appears In:
Field Description Default Validation

name string

Name is the name of the CNI plugin to use.

Supported values: "calico", "antrea".

ClusterBootstrap

ClusterBootstrap is the Schema for the ClusterBootstraps API

Field Description Default Validation

apiVersion string

run.tanzu.vmware.com/v1alpha3

kind string

ClusterBootstrap

metadata ObjectMeta

Refer to Kubernetes API documentation for fields of metadata.

MinProperties: 1

spec ClusterBootstrapTemplateSpec

status ClusterBootstrapStatus

ClusterBootstrapPackage

Appears In:
Field Description Default Validation

refName string

valuesFrom ValuesFrom

ClusterBootstrapStatus

ClusterBootstrapStatus defines the observed state of ClusterBootstrap

Appears In:
Field Description Default Validation

resolvedTKR string

conditions Conditions

ClusterBootstrapTemplate

ClusterBootstrapTemplate is the Schema for the ClusterBootstraptemplates API

Field Description Default Validation

apiVersion string

run.tanzu.vmware.com/v1alpha3

kind string

ClusterBootstrapTemplate

metadata ObjectMeta

Refer to Kubernetes API documentation for fields of metadata.

MinProperties: 1

spec ClusterBootstrapTemplateSpec

ClusterBootstrapTemplateSpec

ClusterBootstrapTemplateSpec defines the desired state of ClusterBootstrapTemplate

Appears In:
Field Description Default Validation

paused boolean

Paused can be used to prevent controllers from processing the ClusterBootstrap and all its associated objects.

false

cni ClusterBootstrapPackage

csi ClusterBootstrapPackage

cpi ClusterBootstrapPackage

kapp ClusterBootstrapPackage

additionalPackages ClusterBootstrapPackage array

ContainerImage

ContainerImage is a struct representing a single fully qualified container image name, constructed as {Repository}/{Name}:{Tag}.

Appears In:
Field Description Default Validation

repository string

Repository is the container image repository used by this image. It MUST be a DNS-compatible name.

name string

Name is the container image name without the repository prefix.
It MUST be a valid URI path, MAY contain zero or more '/', and SHOULD NOT start or end with '/'.

tag string

Tag is the container image version tag. It is the suffix coming after ':' in a fully qualified image name.

ContainerImageInfo

ContainerImageInfo allows to customize the image used for components that are not originated from the Kubernetes/Kubernetes release process (such as etcd and coredns).

Appears In:
Field Description Default Validation

imageRepository string

ImageRepository sets the container registry to pull images from.
if not set, defaults to the ImageRepository defined in KubernetesSpec.

imageTag string

ImageTag specifies a tag for the image.

Deployment

Appears In:
Field Description Default Validation

updateStrategy string

Deployment update strategy

RollingUpdate

Enum: [RollingUpdate Recreate]
Optional: \{}

rollingUpdate RollingUpdateInfo

Deployment rolling update info

Optional: \{}

Distribution

Distribution specifies the version of software which should be installed on the control plane and worker nodes. This version information encompasses Kubernetes and its dependencies, the base OS of the node, and add-ons.

Appears In:
Field Description Default Validation

fullVersion string

Version specifies the fully-qualified desired Kubernetes distribution version of the Tanzu Kubernetes cluster. If the
cluster exists and is not of the specified version, it will be upgraded.

Version is a semantic version string. The version may not be decreased. The major version may not be changed. If
the minor version is changed, it may only be incremented; skipping minor versions is not supported.

The current observed version of the cluster is held by status.version.
Deprecated: use topology.controlPlane.tkr and topology.nodePools[*].tkr instead.

version string

VersionHint provides the version webhook with guidance about the desired Kubernetes distribution version of the
Tanzu Kubernetes cluster. If a hint is provided without a full version, the most recent distribution matching the hint
will be selected.

The version selected based on the hint will be stored in the spec as the full version. This ensures that the same
version is used if the cluster is scaled out in the future.

VersionHint is a semantic prefix of a full version number. (E.g., v1.15.1 matches any distribution of v1.15.1,
including v1.15.1+vmware.1-tkg.1 or v1.15.1+vmware.2-tkg.1, but not v1.15.10+vmware.1-tkg.1.)

A hint that does not match the full version is invalid and will be rejected.

To upgrade a cluster to the most recent version that still matches the hint, leave the hint alone and remove the
fullVersion from the spec. This will cause the hint to be re-resolved.
Deprecated: use topology.controlPlane.tkr and topology.nodePools[*].tkr instead.

KappConfig

Appears In:
Field Description Default Validation

caCerts string

A cert chain of trusted CA certs. These will be added to the system-wide cert pool of trusted CA’s. Cluster-wide CA Certificate setting will be used if this is not provided.

Optional: \{}

httpProxy string

The url/ip of a proxy for kapp controller to use when making network requests. Cluster-wide HTTP proxy setting will be used if this is not provided.

Optional: \{}

httpsProxy string

The url/ip of a TLS capable proxy for kapp-controller to use when making network requests. Cluster-wide HTTPS proxy setting will be used if this is not provided.

Optional: \{}

noProxy string

A comma delimited list of domain names which kapp-controller should bypass the proxy for when making requests. Cluster-wide no-proxy setting will be used if this is not provided.

Optional: \{}

dangerousSkipTLSVerify string

A comma delimited list of hostnames for which kapp-controller should skip TLS verification

Optional: \{}

KappController

Appears In:
Field Description Default Validation

createNamespace boolean

Whether to create namespace specified for kapp-controller

false

Optional: \{}

globalNamespace string

The namespace value used for global packaging resources. Any Package and PackageMetadata CRs within that namespace will be included in all other namespaces on the cluster, without duplicating them

tkg-system

Optional: \{}

deployment KappDeployment

{ hostNetwork:true }

Optional: \{}

config KappConfig

KappControllerConfig

KappControllerConfig is the Schema for the kappcontrollerconfigs API

Field Description Default Validation

apiVersion string

run.tanzu.vmware.com/v1alpha3

kind string

KappControllerConfig

metadata ObjectMeta

Refer to Kubernetes API documentation for fields of metadata.

MinProperties: 1

spec KappControllerConfigSpec

status KappControllerConfigStatus

KappControllerConfigSpec

KappControllerConfigSpec defines the desired state of KappControllerConfig

Appears In:
Field Description Default Validation

namespace string

The namespace in which kapp-controller is deployed

tkg-system

Optional: \{}

deployment Deployment

Optional: \{}

kappController KappController

{ deployment:map[hostNetwork:true] }

Optional: \{}

KappControllerConfigStatus

KappControllerConfigStatus defines the observed state of KappControllerConfig

Appears In:
Field Description Default Validation

secretRef string

Name of the data value secret created by controller

Optional: \{}

KappDeployment

Appears In:
Field Description Default Validation

hostNetwork boolean

Whether to enable host networking for kapp-controller deployment

true

Optional: \{}

priorityClassName string

The priority value that various system components use to find the priority of the kapp-controller pod

system-cluster-critical

Optional: \{}

concurrency integer

Concurrency of kapp-controller deployment

4

Optional: \{}

tolerations object array

kapp-controller deployment tolerations

Optional: \{}

apiPort integer

Bind port for kapp-controller API

10100

Optional: \{}

metricsBindAddress string

Address for metrics server

0

Optional: \{}

KubernetesSpec

KubernetesSpec specifies the details about the Kubernetes distribution shipped by this TKR.

Appears In:
Field Description Default Validation

version string

Version is Semantic Versioning conformant version of the Kubernetes build shipped by this TKR.
The same Kubernetes build MAY be shipped by multiple TKRs.

imageRepository string

ImageRepository specifies container image registry to pull images from.

etcd ContainerImageInfo

Etcd specifies the container image repository and tag for etcd.

pause ContainerImageInfo

Pause specifies the container image repository and tag for pause.

coredns ContainerImageInfo

CoreDNS specifies the container image repository and tag for coredns.

kube-vip ContainerImageInfo

KubeVIP specifies the container image repository and tag for kube-vip.

MachineImageInfo

MachineImageInfo describes the "Image" part of the OSImage, defined by the image type.

Appears In:
Field Description Default Validation

type string

Type of the OSImage, roughly corresponding to the infrastructure provider (vSphere can serve both ova and vmop).
Some of currently known types are: "docker", "ova", "vmop".

ref object (keys:string, values:interface{})

Ref is a key-value map identifying the image within the infrastructure provider. This is the data
to be injected into the infra-Machine objects (like vSphereMachine) on creation.

Schemaless: \{}
Type: object

ManifestResource

ManifestResource represents a YAML manifest for installing an addon.

Appears In:
Field Description Default Validation

version string

Version is the addon version.

type string

Type is the type of the manifest resource. In VirtualMachineImage based addons its value is 'inline'.

value string

Value is the text of the YAML manifest.

Network

Network specifies network-related settings for a cluster.

Appears In:
Field Description Default Validation

services NetworkRanges

Services specify network settings for services.

Defaults to 10.96.0.0/12.

pods NetworkRanges

Pods specify network settings for pods.

When CNI is antrea, set Defaults to 192.168.0.0/16.
When CNI is antrea-nsx-routed, set Defaults to empty

serviceDomain string

ServiceDomain specifies service domain for Tanzu Kubernetes cluster.

Defaults to a cluster.local.

cni CNIConfiguration

CNI is the Container Networking Interface plugin for the Tanzu Kubernetes cluster.

Defaults to Calico.

proxy ProxyConfiguration

Proxy specifies HTTP(s) proxy configuration for Tanzu Kubernetes cluster.

If omitted, no proxy will be configured in the system.

trust TrustConfiguration

Trust specifies certificate configuration for the Tanzu Kubernetes Cluster.

If omitted, no certificate will be configured in the system.

NetworkRanges

NetworkRanges describes a collection of IP addresses as a list of ranges.

Appears In:
Field Description Default Validation

cidrBlocks string array

CIDRBlocks specifies one or more ranges of IP addresses.

Note: supplying multiple ranges many not be supported by all CNI plugins.

NodePool

NodePool describes a group of nodes within a cluster that have the same configuration

Appears In:
Field Description Default Validation

name string

Name is the name of the NodePool.

labels object (keys:string, values:string)

Labels are map of string keys and values that can be used to organize and categorize objects.
User-defined labels will be propagated to the created nodes.

taints Taint array

Taints specifies the taints the Node API object should be registered with.
User-defined taints will be propagated to the created nodes.

failureDomain string

FailureDomain is the failure domain the machines will be created in.
Must match a key in the FailureDomains map stored on the cluster object.

replicas integer

Replicas is the number of nodes.
This is a pointer to distinguish between explicit zero and not specified, nil.
For control plane, defaults to 1 if nil.
For node pools, a value of nil indicates that the field will not be reconciled, allowing external services like
autoscalers to choose the number of nodes. By default, CAPI’s MachineDeployment will pick 1.

vmClass string

VMClass is the name of the VirtualMachineClass, which describes the virtual hardware settings, to be used each node
in the pool. This controls the hardware available to the node (CPU and memory) as well as the requests and limits
on those resources. Run kubectl describe virtualmachineclasses to see which VM classes are available to use.

storageClass string

StorageClass is the storage class to be used for storage of the disks which store the root filesystems of the
nodes. Run kubectl describe ns on your namespace to see which storage classes are available to use.

volumes Volume array

Volumes is the set of PVCs to be created and attached to each node.

tkr TKRReference

TKR points to KubernetesRelease intended to be used by the node pool
(the control plane being special kind of a node pool).

nodeDrainTimeout Duration

NodeDrainTimeout is the total amount of time that the controller will
spend on draining a node. The default value is 0, meaning that the node
will be drained without any time limitations.
NOTE: NodeDrainTimeout is different from kubectl drain --timeout

OSImage

OSImage is the schema for the OSImages API. OSImage objects represent OSImages shipped as parts of TKRs. OSImages are immutable to end-users. They are created and managed by TKG to provide discovery of Kubernetes releases to TKG users and OS image details for infrastructure Machines.

Field Description Default Validation

apiVersion string

run.tanzu.vmware.com/v1alpha3

kind string

OSImage

metadata ObjectMeta

Refer to Kubernetes API documentation for fields of metadata.

MinProperties: 1

spec OSImageSpec

status OSImageStatus

OSImageSpec

OSImageSpec defines the desired state of OSImage

Appears In:
Field Description Default Validation

kubernetesVersion string

KubernetesVersion specifies the build version of the Kubernetes shipped with this OSImage.

os OSInfo

OS specifies the "OS" part of the OSImage.

image MachineImageInfo

Image specifies the "Image" part of the OSImage.

OSImageStatus

OSImageStatus defines the observed state of OSImage

Appears In:
Field Description Default Validation

conditions Condition array

OSInfo

OSInfo describes the "OS" part of the OSImage, defined by the Operating System’s name, version and CPU architecture.

Appears In:
Field Description Default Validation

type string

name string

version string

arch string

ProxyConfiguration

ProxyConfiguration configures the HTTP(s) proxy to be used inside the Tanzu Kubernetes cluster.

Appears In:
Field Description Default Validation

httpProxy string

HttpProxy specifies a proxy URL to use for creating HTTP connections outside the cluster.
Example: http://<user>:<pwd>@<ip>:<port>;

httpsProxy string

HttpsProxy specifies a proxy URL to use for creating HTTPS connections outside the cluster.
Example: http://<user>:<pwd>@<ip>:<port>;

noProxy string array

NoProxy specifies a list of destination domain names, domains, IP addresses or other network CIDRs to exclude proxying.
Example: [localhost, 127.0.0.1, 10.10.10.0/24]

RollingUpdateInfo

RollingUpdateInfo contains the rolling update settings

Appears In:
Field Description Default Validation

maxUnavailable integer

0

Optional: \{}

maxSurge integer

1

Optional: \{}

Settings

Settings specifies configuration information for a cluster.

Appears In:
Field Description Default Validation

network Network

Network specifies network-related settings for the cluster.

storage Storage

Storage specifies storage-related settings for the cluster.

The storage used for node’s disks is controlled by TopologySettings.

Storage

Storage configures persistent storage for a cluster.

Appears In:
Field Description Default Validation

classes string array

Classes is a list of storage classes from the supervisor namespace to expose within a cluster.

If omitted, all storage classes from the supervisor namespace will be exposed within the cluster.

defaultClass string

DefaultClass is the valid storage class name which is treated as the default storage class within a cluster.
If omitted, no default storage class is set

TKRReference

TKRReference is an extensible way to link a KubernetesRelease.

Appears In:
Field Description Default Validation

reference ObjectReference

Reference is a way to set the fixed link to the target object.

TLSCertificate

TLSCertificate specifies a single additional certificate name and contents

Appears In:
Field Description Default Validation

name string

Name specifies the name of the additional certificate, used in the filename
Example: CompanyInternalCA

data string

Data specifies the contents of the additional certificate, encoded as a
base64 string. Specifically, this is the PEM Public Certificate data as
a base64 string..
Example: LS0tLS1C…​LS0tCg== (where "…​" is the middle section of the long base64 string)

TanzuKubernetesAddon

TanzuKubernetesAddon is the schema for the tanzukubernetesaddons API. TanzuKubernetesAddon objects represent Kubernetes addons available via TKG Service, which can be used to create TanzuKubernetesCluster instances. TKAs are immutable to end-users. They are created and managed by TKG Service to provide discovery of Kubernetes addons to TKG Service users.

Field Description Default Validation

apiVersion string

run.tanzu.vmware.com/v1alpha3

kind string

TanzuKubernetesAddon

metadata ObjectMeta

Refer to Kubernetes API documentation for fields of metadata.

MinProperties: 1

spec TanzuKubernetesAddonSpec

status TanzuKubernetesAddonStatus

TanzuKubernetesAddonSpec

TanzuKubernetesAddonSpec defines the desired state of TanzuKubernetesAddon

Appears In:
Field Description Default Validation

addonName string

AddonName is the generic name of this addon, e.g. "antrea", "calico", "pvcsi", etc.

version string

Version is the fully qualified Semantic Versioning conformant version of the TanzuKubernetesAddon.
If set, Version MUST be unique across all TanzuKubernetesAddon objects with the same addonName.

repository string

Repository is the default container image repository used by Images. It MUST be a DNS-compatible name.

images ContainerImage array

Images is the list of container images shipped by this addon (e.g. coredns, etcd).

resource ManifestResource

Resource contains the YAML manifest for installing the addon.

TanzuKubernetesAddonStatus

TanzuKubernetesAddonStatus defines the observed state of TanzuKubernetesAddon

Appears In:

TanzuKubernetesCluster

TanzuKubernetesCluster is the schema for the Tanzu Kubernetes Grid service for vSphere API.

Field Description Default Validation

apiVersion string

run.tanzu.vmware.com/v1alpha3

kind string

TanzuKubernetesCluster

metadata ObjectMeta

Refer to Kubernetes API documentation for fields of metadata.

MinProperties: 1

spec TanzuKubernetesClusterSpec

status TanzuKubernetesClusterStatus

TanzuKubernetesClusterPhase

Underlying type: string

TanzuKubernetesClusterPhase is a type for the Tanzu Kubernetes cluster’s phase constants.

Appears In:

TanzuKubernetesClusterSpec

TanzuKubernetesClusterSpec defines the desired state of TanzuKubernetesCluster: its nodes, the software installed on those nodes and the way that software should be configured.

Appears In:
Field Description Default Validation

topology Topology

Topology specifies the topology for the Tanzu Kubernetes cluster: the number, purpose, and organization of the nodes which
form the cluster and the resources allocated for each.

distribution Distribution

Distribution specifies the distribution for the Tanzu Kubernetes cluster: the software installed on the control plane and
worker nodes, including Kubernetes itself.
Deprecated: use topology.controlPlane.tkr and topology.nodePools[*].tkr instead.

settings Settings

Settings specifies settings for the Tanzu Kubernetes cluster: the way an instance of a distribution is configured,
including information about pod networking and storage.

TanzuKubernetesClusterStatus

TanzuKubernetesClusterStatus defines the observed state of TanzuKubernetesCluster.

Appears In:
Field Description Default Validation

apiEndpoints APIEndpoint array

APIEndpoints represents the endpoints to communicate with the control plane.

version string

Version holds the observed version of the Tanzu Kubernetes cluster. While an upgrade is in progress this value will be the
version of the cluster when the upgrade began.

addons AddonStatus array

Addons groups the statuses of a Tanzu Kubernetes cluster’s add-ons.

phase TanzuKubernetesClusterPhase

Phase of this TanzuKubernetesCluster.
Deprecated: will be removed in v1alpha3

conditions Conditions

Conditions defines current service state of the TanzuKubernetestCluster.

totalWorkerReplicas integer

Total number of replicas in worker node pools.

TanzuKubernetesRelease

TanzuKubernetesRelease is the schema for the tanzukubernetesreleases API. TanzuKubernetesRelease objects represent Kubernetes releases available via TKG, which can be used to create TanzuKubernetesCluster instances. TKRs are immutable to end-users. They are created and managed by TKG to provide discovery of Kubernetes releases to TKG users.

Field Description Default Validation

apiVersion string

run.tanzu.vmware.com/v1alpha3

kind string

TanzuKubernetesRelease

metadata ObjectMeta

Refer to Kubernetes API documentation for fields of metadata.

MinProperties: 1

spec TanzuKubernetesReleaseSpec

status TanzuKubernetesReleaseStatus

TanzuKubernetesReleaseSpec

TanzuKubernetesReleaseSpec defines the desired state of TanzuKubernetesRelease

Appears In:
Field Description Default Validation

version string

Version is the fully qualified Semantic Versioning conformant version of the TanzuKubernetesRelease.
Version MUST be unique across all TanzuKubernetesRelease objects.

kubernetes KubernetesSpec

Kubernetes is Kubernetes

osImages LocalObjectReference array

OSImages lists references to all OSImage objects shipped with this TKR.

bootstrapPackages LocalObjectReference array

BootstrapPackages lists references to all bootstrap packages shipped with this TKR.

TanzuKubernetesReleaseStatus

TanzuKubernetesReleaseStatus defines the observed state of TanzuKubernetesRelease

Appears In:
Field Description Default Validation

conditions Condition array

TkgServiceConfiguration

TkgServiceConfiguration is the Schema for the tkgserviceconfigurations API

Field Description Default Validation

apiVersion string

run.tanzu.vmware.com/v1alpha3

kind string

TkgServiceConfiguration

metadata ObjectMeta

Refer to Kubernetes API documentation for fields of metadata.

MinProperties: 1

spec TkgServiceConfigurationSpec

status TkgServiceConfigurationStatus

TkgServiceConfigurationSpec

TkgServiceConfigurationSpec defines the desired state of TkgServiceConfiguration

Appears In:
Field Description Default Validation

defaultCNI string

Default CNI for TanzuKubernetesCluster

proxy ProxyConfiguration

Proxy specifies default global HTTP(s) Proxy Configuration for all new TanzuKubernetesClusters in this Supervisor cluster

If omitted, no proxy will be configured for new TanzuKubernetesClusters

trust TrustConfiguration

Trust specifies default global Trust settings for all new TanzuKubernetesClusters
in the Supervisor Cluster.

If omitted, no additional Trust settings will be configured for the new TanzuKubernetesCluster.

defaultNodeDrainTimeout Duration

DefaultNodeDrainTimeout specifies the total amount of time that the
controller will spend on draining a node by default. Undefined, the value
is 0, meaning that the node can be drained without any time limitations.
NOTE: NodeDrainTimeout is different from kubectl drain --timeout

TkgServiceConfigurationStatus

TkgServiceConfigurationStatus defines the observed state of TkgServiceConfiguration

Appears In:

Topology

Topology describes the number, purpose, and organization of nodes and the resources allocated for each. Nodes are grouped into pools based on their intended purpose. Each pool is homogeneous, having the same resource allocation and using the same storage.

Appears In:
Field Description Default Validation

controlPlane TopologySettings

ControlPlane specifies the topology of the cluster’s control plane, including the number of control plane nodes
and resources allocated for each. The control plane must have an odd number of nodes.

nodePools NodePool array

NodePools specifies the topology of cluster’s worker node pools, including the number of nodes and resources
allocated for each node.

TopologySettings

TopologySettings describes a homogeneous pool of nodes: the number of nodes in the pool and the properties of each of those nodes, including resource allocation and storage.

Appears In:
Field Description Default Validation

replicas integer

Replicas is the number of nodes.
This is a pointer to distinguish between explicit zero and not specified, nil.
For control plane, defaults to 1 if nil.
For node pools, a value of nil indicates that the field will not be reconciled, allowing external services like
autoscalers to choose the number of nodes. By default, CAPI’s MachineDeployment will pick 1.

vmClass string

VMClass is the name of the VirtualMachineClass, which describes the virtual hardware settings, to be used each node
in the pool. This controls the hardware available to the node (CPU and memory) as well as the requests and limits
on those resources. Run kubectl describe virtualmachineclasses to see which VM classes are available to use.

storageClass string

StorageClass is the storage class to be used for storage of the disks which store the root filesystems of the
nodes. Run kubectl describe ns on your namespace to see which storage classes are available to use.

volumes Volume array

Volumes is the set of PVCs to be created and attached to each node.

tkr TKRReference

TKR points to KubernetesRelease intended to be used by the node pool
(the control plane being special kind of a node pool).

nodeDrainTimeout Duration

NodeDrainTimeout is the total amount of time that the controller will
spend on draining a node. The default value is 0, meaning that the node
will be drained without any time limitations.
NOTE: NodeDrainTimeout is different from kubectl drain --timeout

TrustConfiguration

TrustConfiguration configures additional trust parameters to the cluster configuration

Appears In:
Field Description Default Validation

additionalTrustedCAs TLSCertificate array

AdditionalTrustedCAs specifies the additional trusted certificates (which
can be additional CAs or end certificates) to add to the cluster

ValuesFrom

ValuesFrom specifies how values for package install are retrieved from

Appears In:
Field Description Default Validation

inline object (keys:string, values:interface{})

Schemaless: \{}
Type: object

secretRef string

providerRef TypedLocalObjectReference

Volume

Volume defines a PVC attachment. These volumes are tied to the node lifecycle, created and deleted when the node is. The volumes are mounted in the node during the bootstrap process, prior to services being started (e.g. etcd, containerd).

Appears In:
Field Description Default Validation

name string

Name is suffix used to name this PVC as: node.Name + "-" + Name

mountPath string

MountPath is the directory where the volume device is to be mounted

storageClass string

StorageClass is the storage class to be used for the disks.
Defaults to TopologySettings.StorageClass