Machine

This section describes the Machine resource used in Mirantis Container Cloud API. The Machine resource describes the machine-level parameters.

For demonstration purposes, the Container Cloud the Machine custom resource (CR) can be split into the following major sections:

Warning

The fields in this resource are available for viewing only. They are automatically generated by the vSphere cloud provider and must not be modified using the Container Cloud API.

metadata

The Container Cloud Machine custom resource (CR) contains the following fields:

  • apiVersion

    Object API version 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

    Container Cloud project in which the machine has been created

  • labels

    • kaas.mirantis.com/provider

      Provider type that is vsphere for vSphere machines and matches the provider type in the Cluster object

    • 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 is assigned 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 or does not contain any value

Configuration example:

apiVersion: cluster.k8s.io/v1alpha1
kind: Machine
metadata:
  name: example-control-plane
  namespace: example-ns
  labels:
    kaas.mirantis.com/provider: vsphere
    cluster.sigs.k8s.io/cluster-name: example-cluster
    cluster.sigs.k8s.io/control-plane: "true" # remove for worker

spec:providerSpec for instance configuration

The spec object field of the Machine object represents the VsphereMachineProviderSpec subresource with all required details to create a vSphere virtual machine. It contains the following fields:

  • apiVersion

    vsphere.cluster.k8s.io/v1alpha1.

  • kind

    VsphereMachineProviderSpec.

  • machineRef

    Field used to look up a vSphere VM. The field value is set automatically at runtime by the vSphere provider and must not be set or modified manually.

  • network

    Network configuration of a vSphere VM:

  • diskGiB

    Disk size of a VM.

  • memoryMiB

    RAM size of a VM.

  • numCPUs

    CPU number of a VM.

  • rhelLicense

    For RHEL-based deployments, a RHEL license name to be applied to a vSphere VM.

  • template

    Full path to a VM template used to create a VM. Mutually exclusive with vsphereVMTemplate.

  • vsphereVMTemplate GA since 2.25.0 and TechPreview since 2.24.0

    Name of the existing VsphereVMTemplate object to use for VM creation. For details, see VsphereVMTemplate. Mutually exclusive with template.

    Caution

    Before using the vsphereVMTemplate field, make sure that the templateStatus field in the VsphereVMTemplate object is set to Present.

    After the Machine configuration applies, the vsphereVMTemplate field is automatically removed and the template field is automatically set to the corresponding template path from the referenced object.

  • 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 status providerStatus.releaseRef.current.allowedNodeLabels field.

    If the value field is not defined in allowedNodeLabels, 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 in machine.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.

  • maintenance

    Maintenance mode of a machine. If enabled, the node of the selected machine is drained, cordoned, and prepared for maintenance operations.

  • 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:

providerSpec:
  value:
    apiVersion: vsphere.cluster.k8s.io/v1alpha1
    diskGiB: 120
    kind: VsphereMachineProviderSpec
    memoryMiB: 32768
    metadata:
      creationTimestamp: null
    network:
      devices:
      - dhcp4: true
    numCPUs: 8
    rhelLicense: rhel-license
    template: /DATACENTER/vm/vm-folder/templates/rhel-8.7-template
    delete: false
    deletionPolicy: graceful

status:providerStatus

The status object field of the vSphere Machine object represents the VsphereMachineProviderStatus subresource that describes the current state of a vSphere virtual machine. It contains the following fields:

  • apiVersion

    vsphere.cluster.k8s.io/v1alpha1

  • kind

    VsphereMachineProviderStatus

  • conditions

    List of a machine status conditions:

    • type

      Object type, for example, Kubelet

    • ready

      Readiness flag

    • message

      Status details

  • providerInstanceState

    Current state of a vSphere VM:

    • id

      ID of a VM

    • ready

      Readiness flag

    • state

      State of a VM

  • networkStatus

    Network status of a vSphere VM:

    • networkName

      vSphere network name that a VM is assigned to

    • connected

      Flag indicating whether the network is currently connected to the VM

    • ipAddrs

      One or more IP addresses reported by vm-tools

    • macAddr

      MAC addresses of the VM network interface

  • privateIp

    Private IPv4 address assigned to a VM

  • maintenance

    Maintenance mode of a machine. If enabled, the node of the selected machine is drained, cordoned, and prepared for maintenance operations.

  • status

    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

    • 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: vsphere.cluster.k8s.io/v1alpha1
    conditions:
    - message: Kubelet's NodeReady condition is True
      ready: true
      type: Kubelet
    - message: Swarm state of the machine is ready
      ready: true
      type: Swarm
    - message: Maintenance state of the machine is false
      ready: true
      type: Maintenance
    - message: LCM Status of the machine is Ready
      ready: true
      type: LCM
    - message: Provider instance 4215081f-7460-be62-0274-e437f6a1fe9b has status green
      ready: true
      type: ProviderInstance
    hardware: {}
    kind: VsphereMachineProviderStatus
    metadata:
      creationTimestamp: null
    networkStatus:
    - connected: true
      ipAddrs:
      - 172.16.39.203
      macAddr: 00:50:56:95:54:a0
      networkName: VMWare_Network
    privateIp: 10.0.0.3
    providerInstanceState:
      id: 4215081f-7460-be62-0274-e437f6a1fe9b
      ready: true
      state: green
    ready: true
    status: Ready
    upgradeIndex: 3
    delete: true
    prepareDeletionPhase: started