Machine¶
This section describes the Machine
resource used in Mirantis
Container Cloud API for bare metal provider.
The Machine
resource describes the machine-level parameters.
For demonstration purposes, the Container Cloud Machine
custom resource (CR) is split into the following major sections:
metadata¶
The Container Cloud Machine
CR contains the following fields:
apiVersion
API version of the object that is
cluster.k8s.io/v1alpha1
.
kind
Object type that is
Machine
.
The metadata
object field of the Machine
resource contains
the following fields:
name
Name of the
Machine
object.
namespace
Project in which the
Machine
object is created.
annotations
Key-value pair to attach arbitrary metadata to the object:
metal3.io/BareMetalHost
Annotation attached to the
Machine
object to reference the correspondingBareMetalHost
object in the<BareMetalHostProjectName/BareMetalHostName>
format.
labels
Key-value pairs that are attached to the object:
kaas.mirantis.com/provider
Provider type that matches the provider type in the
Cluster
object and must bebaremetal
.
kaas.mirantis.com/region
Region name that matches the region name in the
Cluster
object.Note
The
kaas.mirantis.com/region
label is removed from all Container Cloud objects in 2.26.0 (Cluster releases 17.1.0 and 16.1.0). Therefore, do not add the label starting these releases. On existing clusters updated to these releases, or if manually added, this label will be ignored by Container Cloud.
cluster.sigs.k8s.io/cluster-name
Cluster name that the
Machine
object is linked to.
cluster.sigs.k8s.io/control-plane
For the control plane role of a machine, this label contains any value, for example,
"true"
. For the worker role, this label is absent.
kaas.mirantis.com/machinepool-name
(optional)Name of the
MachinePool
object to which this machine is assigned to. If the machine is not assigned to any machine pool, this label is absent.
Warning
Labels and annotations that are not documented in this API Reference are generated automatically by Container Cloud. Do not modify them using the Container Cloud API.
Configuration example:
apiVersion: cluster.k8s.io/v1alpha1
kind: Machine
metadata:
name: example-control-plane
namespace: example-ns
annotations:
metal3.io/BareMetalHost: default/master-0
labels:
kaas.mirantis.com/provider: baremetal
cluster.sigs.k8s.io/cluster-name: example-cluster
cluster.sigs.k8s.io/control-plane: "true" # remove for worker
spec:providerSpec for instance configuration¶
Caution
If a machine is assigned to a machine pool, the providerSpec
section of the specific Machine
object automatically updates during pool
configuration. The only providerSpec
field that is not overwritten
automatically is maintenance
. Do not edit other fields of this section
manually.
The spec
object field of the Machine
object represents
the BareMetalMachineProviderSpec
subresource with all required
details to create a bare metal instance. It contains the following fields:
apiVersion
API version of the object that is
baremetal.k8s.io/v1alpha1
.
kind
Object type that is
BareMetalMachineProviderSpec
.
bareMetalHostProfile
Configuration profile of a bare metal host:
name
Name of a bare metal host profile
namespace
Project in which the bare metal host profile is created.
l2TemplateIfMappingOverride
If specified, overrides the interface mapping value for the corresponding
L2Template
object.
l2TemplateSelector
If specified, contains the
name
(first priority) orlabel
of the L2 template that will be applied during a machine creation. Thel2TemplateSelector
field is copied from theMachine
providerSpec
object to theIpamHost
object only once, during a machine creation. To modifyl2TemplateSelector
after creation of aMachine
CR, edit theIpamHost
object.
hostSelector
Specifies the matching criteria for labels on the bare metal hosts. Limits the set of the
BareMetalHost
objects considered for claiming for theMachine
object. The following selector labels can be added when creating a machine using the Container Cloud web UI:hostlabel.bm.kaas.mirantis.com/controlplane
hostlabel.bm.kaas.mirantis.com/worker
hostlabel.bm.kaas.mirantis.com/storage
Any custom label that is assigned to one or more bare metal hosts using API can be used as a host selector. If the
BareMetalHost
objects with the specified label are missing, theMachine
object will not be deployed until at least one bare metal host with the specified label is available.
nodeLabels
List of node labels to be attached to a node for the user to run certain components on separate cluster nodes. The list of allowed node labels is located in the
Cluster
object statusproviderStatus.releaseRef.current.allowedNodeLabels
field.If the
value
field is not defined inallowedNodeLabels
, a label can have any value.Before or after a machine deployment, add the required label from the allowed node labels list with the corresponding value to
spec.providerSpec.value.nodeLabels
inmachine.yaml
. For example:nodeLabels: - key: stacklight value: enabled
The addition of a node label that is not available in the list of allowed node labels is restricted.
distribution
MandatorySpecifies an operating system (OS) distribution ID that is present in the current
ClusterRelease
object under theAllowedDistributions
list. When specified, theBareMetalHost
object linked to thisMachine
object will be provisioned using the selected OS distribution instead of the default one.By default, the following distributions are installed on greenfield managed clusters:
ubuntu/jammy
:Since Container Cloud 2.28.0 (Cluster releases 17.3.0 and 16.3.0), for MOSK clusters
Since Container Cloud 2.27.0 (Cluster releases 17.2.0 and 16.2.0), for non-MOSK clusters
ubuntu/focal
, which is deprecated since 2.28.0 and only supported for existing clusters, was installed by default since Container Cloud 2.17.0 (Cluster releases 11.1.0 and 7.7.0)
The default distribution is marked with the boolean flag
default
inside one of the elements under theAllowedDistributions
list.Caution
The outdated
ubuntu/bionic
distribution, which is removed in Cluster releases 17.0.0 and 16.0.0, is only supported for existing clusters based on Ubuntu 18.04. For greenfield deployments of managed clusters, onlyubuntu/jammy
is supported.Warning
During the course of the Container Cloud 2.28.x series, Mirantis highly recommends upgrading an operating system on your cluster machines to Ubuntu 22.04 before the next major Cluster release becomes available. It is not mandatory to upgrade all machines at once. You can upgrade them one by one or in small batches, for example, if the maintenance window is limited in time.
Otherwise, the Cluster release update of the Ubuntu 20.04-based clusters will become impossible as of the Cluster releases introduced in Container Cloud 2.29.0 (Cluster releases 17.4.0 and 16.4.0) with Ubuntu 22.04 as the only supported version.
maintenance
Maintenance mode of a machine. If enabled, the node of the selected machine is drained, cordoned, and prepared for maintenance operations.
upgradeIndex
(optional)Positive numeral value that determines the order of machines upgrade. The first machine to upgrade is always one of the control plane machines with the lowest
upgradeIndex
. Other control plane machines are upgraded one by one according to their upgrade indexes.If the
Cluster
specdedicatedControlPlane
field isfalse
, worker machines are upgraded only after the upgrade of all control plane machines finishes. Otherwise, they are upgraded after the first control plane machine, concurrently with other control plane machines.If two or more machines have the same value of
upgradeIndex
, these machines are equally prioritized during upgrade.
deletionPolicy
Technology Preview since 2.21.0 for non-MOSK clusters. Policy used to identify steps required during a
Machine
object deletion. Supported policies are as follows:graceful
Prepares a machine for deletion by cordoning, draining, and removing from Docker Swarm of the related node. Then deletes Kubernetes objects and associated resources. Can be aborted only before a node is removed from Docker Swarm.
unsafe
Default. Deletes Kubernetes objects and associated resources without any preparations.
forced
Deletes Kubernetes objects and associated resources without any preparations. Removes the
Machine
object even if the cloud provider or LCM Controller gets stuck at some step. May require a manual cleanup of machine resources in case of the controller failure.
For more details on the workflow of machine deletion policies, see Overview of machine deletion policies.
delete
Technology Preview since 2.21.0 for non-MOSK clusters. Boolean trigger for a machine deletion. Set to
false
to abort a machine deletion.
Configuration example:
spec:
...
providerSpec:
value:
apiVersion: baremetal.k8s.io/v1alpha1
kind: BareMetalMachineProviderSpec
bareMetalHostProfile:
name: default
namespace: default
l2TemplateIfMappingOverride:
- eno1
- enp0s0
l2TemplateSelector:
label: l2-template1-label-1
hostSelector:
matchLabels:
kaas.mirantis.com/baremetalhost-id: hw-master-0
kind: BareMetalMachineProviderSpec
nodeLabels:
- key: stacklight
value: enabled
distribution: ubuntu/jammy
delete: false
deletionPolicy: graceful
Machine status¶
The status
object field of the Machine
object represents the
BareMetalMachineProviderStatus
subresource that describes the current
bare metal instance state and contains the following fields:
apiVersion
API version of the object that is
cluster.k8s.io/v1alpha1
.
kind
Object type that is
BareMetalMachineProviderStatus
.
hardware
Provides a machine hardware information:
cpu
Number of CPUs.
ram
RAM capacity in GB.
storage
List of hard drives mounted on the machine. Contains the disk name and size in GB.
status
Represents the current status of a machine:
Provision
A machine is yet to obtain a status
Uninitialized
A machine is yet to obtain the node IP address and host name
Pending
A machine is yet to receive the deployment instructions and it is either not booted yet or waits for the LCM controller to be deployed
Prepare
A machine is running the
Prepare
phase during which Docker images and packages are being predownloaded
Deploy
A machine is processing the LCM Controller instructions
Reconfigure
A machine is being updated with a configuration without affecting workloads running on the machine
Ready
A machine is deployed and the supported Mirantis Kubernetes Engine (MKE) version is set
Maintenance
A machine host is cordoned, drained, and prepared for maintenance operations
currentDistribution
Since 2.24.0 as TechPreview and 2.24.2 as GADistribution ID of the current operating system installed on the machine. For example,
ubuntu/jammy
.
maintenance
Maintenance mode of a machine. If enabled, the node of the selected machine is drained, cordoned, and prepared for maintenance operations.
reboot
Available since 2.22.0Indicator of a host reboot to complete the Ubuntu operating system updates, if any.
required
Specifies whether a host reboot is required. Boolean. If
true
, a manual host reboot is required.
reason
Specifies the package name(s) to apply during a host reboot.
upgradeIndex
Positive numeral value that determines the order of machines upgrade. The first machine to upgrade is always one of the control plane machines with the lowest
upgradeIndex
. Other control plane machines are upgraded one by one according to their upgrade indexes.If the
Cluster
specdedicatedControlPlane
field isfalse
, worker machines are upgraded only after the upgrade of all control plane machines finishes. Otherwise, they are upgraded after the first control plane machine, concurrently with other control plane machines.If two or more machines have the same value of
upgradeIndex
, these machines are equally prioritized during upgrade.If
upgradeIndex
in theMachine
object spec is set, this status value equals the one in the spec. Otherwise, this value displays the automatically generated order of upgrade.
delete
Technology Preview since 2.21.0 for non-MOSK clusters. Start of a machine deletion or a successful abortion. Boolean.
prepareDeletionPhase
Technology Preview since 2.21.0 for non-MOSK clusters. Preparation phase for a graceful machine deletion. Possible values are as follows:
started
Cloud provider controller prepares a machine for deletion by cordoning, draining the machine, and so on.
completed
LCM Controller starts removing the machine resources since the preparation for deletion is complete.
aborting
Cloud provider controller attempts to uncordon the node. If the attempt fails, the status changes to
failed
.
failed
Error in the deletion workflow.
For the workflow description of a graceful deletion, see Overview of machine deletion policies.
Configuration example:
status:
providerStatus:
apiVersion: baremetal.k8s.io/v1alpha1
kind: BareMetalMachineProviderStatus
hardware:
cpu: 11
ram: 16
storage:
- name: /dev/vda
size: 61
- name: /dev/vdb
size: 32
- name: /dev/vdc
size: 32
reboot:
required: true
reason: |
linux-image-5.13.0-51-generic
linux-base
status: Ready
upgradeIndex: 1