Machine

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

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

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 object has been created.

  • annotations
    • openstack-floating-ip-address

      Automatically generated floating IP which will be associated with an OpenStack instance.

  • labels

    • kaas.mirantis.com/provider

      Provider type that matches the provider type in the Cluster object and should be openstack for OpenStack machines.

    • 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 this machine 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:
    openstack-floating-ip-address: 172.16.246.182
  labels:
    kaas.mirantis.com/provider: openstack
    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 OpenstackMachineProviderSpec subresource with all required details to create an OpenStack instance. It contains the following fields:

  • apiVersion

    openstackproviderconfig.k8s.io/v1alpha.

  • kind

    OpenstackMachineProviderSpec.

  • availabilityZone

    Availability zone to launch the OpenStack instance from.

  • flavor

    Flavor reference to the OpenStack instance flavor.

  • image

    Name of the image to use for the OpenStack instance.

  • securityGroups

    List of the security groups IDs assigned to the OpenStack instance.

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

  • 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 spec dedicatedControlPlane field is false, 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.

  • bootFromVolume TechPreview

    Configuration to boot a server from a block storage volume based on a given image. Required parameters:

  • 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: openstackproviderconfig.k8s.io/v1alpha1
    kind: OpenstackMachineProviderSpec
    availabilityZone: nova
    flavor: kaas.small
    image: bionic-server-cloudimg-amd64-20200724
    securityGroups:
      - kaas-sg-ctrl-abcdefgh-0123-4567-890a-0a1b2c3d4e5f
      - kaas-sg-glob-abcdefgh-0123-4567-890a-0a1b2c3d4e5f
    nodeLabels:
    - key: openstack-control-plane
      value: enabled
    bootFromVolume:
       enabled: true
       volumeSize: 120
    delete: false
    deletionPolicy: graceful

status:providerStatus

The status object field of the Machine object represents the OpenstackMachineProviderStatus subresource that describes current state of an OpenStack instance and contains the following fields:

  • apiVersion

    openstackproviderconfig.k8s.io/v1alpha1

  • kind

    OpenstackMachineProviderStatus

  • conditions

    List of the Machine status condition:

    • type

      Object type

    • ready

      Readiness flag

    • message

      Status details

  • providerInstanceState

    Current state of an OpenStack instance:

    • id

      ID of an OpenStack instance

    • ready

      Readiness flag

    • state

      State of an OpenStack instance

  • hardware

    Machine hardware information:

    • cpu

      CPUs number

    • ram

      RAM capacity (in GB)

  • privateIp

    Private IPv4 address assigned to the instance

  • maintenance

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

  • 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 spec dedicatedControlPlane field is false, 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 the Machine object spec is set, this status value equals the one in the spec. Otherwise, this value displays the automatically generated order of upgrade.

  • status

    Current state 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: openstackproviderconfig.k8s.io/v1alpha1
    kind: OpenstackMachineProviderStatus
    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: LCM Status of the machine is Ready
       ready: true
       type: LCM
       ...
    providerInstanceState:
      id: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
      ready: true
      state: ACTIVE
    hardware:
      cpu: 8
      ram: 24
    privateIp: 10.10.10.169
    status: Ready
    delete: true
    prepareDeletionPhase: started