Internal API for day-2 operations

TechPreview since 2.26.0 (17.1.0 and 16.1.0)

This section describes integrations between the HostOSConfiguration custom resouce, aka hoc, HostOSConfigurationModules custom resouce, aka hocm, LCMCluster, and LCMMachine.

Basic integration in LCM

The implementation of the internal API used by day-2 operations utilizes the current approach of StateItems, including the way how they are processed and passed to lcm-agent.

The workflow of the internal API implementation is as follows:

  1. Create a set of StateItem entries in LCMCluster taking into account all hoc objects in the namespace of LCMCluster.

  2. Fill out StateItems for each LCMMachine that was selected by the machineSelector field value of a hoc object.

  3. Pass StateItems to lcm-agent that is responsible for their execution on nodes.

The machineSelector field selects Machine objects, but they map to LCMMachine objects in 1-1 relation. This way, each selected Machine exactly maps to a relevant LCMMachine object.

LCMCluster and LCM StateItem

LCMCluster utilizes empty StateItem to establish a baseline connection between the hoc, LCMMachine objects and lcm-agent on nodes. These empty items have no parameters and serve as placeholders, providing a template for further processing.

To identify items added from hoc objects, these StateItems along with other state items of an LCMCluster object are located in the .spec.machinesTypes.control and .spec.machinesTypes.worker blocks with the following fields in an LCMCluster object:

  • params is absent

  • phase is reconfigure as the only supported value

  • version is v1 as the only supported value

  • runner can be either downloader or ansible:

    • downloader downloads the package of a module of the provided version into machine.

    • ansible executes the module on the machine with provided values.

  • name has the following patterns:

    • host-os-<hocObjectName>-<moduleName>-<moduleVersion>-<modulePhase> if the runner field has the ansible value set

    • host-os-download-<hocObjectName>-<moduleName>-<moduleVersion> -<modulePhase> if the runner field has the downloader value set.

The following example of an LCMCluster object illustrates empty StateItems for the following configuration:

  • Machine type - worker

  • hoc object name - test with a single entry in the configs field

  • Module name - sample-module

  • Module version - 1.0.0

spec:
  machineTypes:
    worker:
    - name: host-os-download-test-sample-module-1.0.0-reconfigure
      runner: downloader
      version: "v1"
      phase: reconfigure
    - name: host-os-test-sample-module-1.0.0-reconfigure
      runner: ansible
      version: "v1"
      phase: reconfigure

LCMMachine overwrites

To properly execute the StateItem list according to given configurations from a hoc object, the implementation utilizes the .spec.stateItemsOverwrites field in an LCMMachine object.

For each state item that corresponds to a hoc object selected for current machine, each entry of the stateItemsOverwrites field dictionary is filled in with key-value pairs:

  • Key is a StateItem name

  • Value is a set of parameters from the module configuration values that will be passed as parameters to StateItem.

After the stateItemsOverwrites field is updated, the corresponding StateItem entries are filled out with values from the stateItemsOverwrites.

Once the StateItem list is updated, it is passed to lcm-agent to be finally applied on nodes.

The following example of an LCMMachine object illustrates the stateItemsOverwrites field having a hoc object with a single entry in the configs field, configuring a module named sample-module with version 1.0.0:

spec:
  stateItemsOverwrites:
    host-os-download-test-sample-module-1.0.0-reconfigure:
      playbook: directory/playbook-name.yaml
      ansible: /usr/bin/ansible-playbook
    host-os-test-sample-module-1.0.0-reconfigure:
      path: "/root/host-os-modules/sample-module-1.0.0"
      sha256: <sha256sum>
      url: https://example.mirantis.com/path/to/sample-module.tgz

HostOSConfiguration processing by baremetal-provider

While processing the hoc object, baremetal-provider verifies the hoc resource for both controlled LCMCluster and LCMMachine resources.

Each change to a hoc object immediately triggers its resources if host-os-modules-controller has successfully validated changes. This behavior enables updates to existing LCMCluster and LCMMachine objects described in the sections above. Thus, all empty StateItems, overwrites, and filled out StateItems appear almost instantly.

This behavior also applies when removing a hoc object, thereby cleaning everything related to the object. The object deletion is suspended until the corresponding StateItems of a particular LCMMachine object is cleaned up from the object status field.

Warning

A configuration that is already applied using the deleted hoc object will not be reverted from nodes, because the feature does not provide rollback mechanism. For module implementation details, refer to Global recommendations for implementation of custom modules.