HostOSConfiguration

TechPreview since MCC 2.26.0 (17.1.0 and 16.1.0)

Warning

For security reasons and to ensure safe and reliable cluster operability, test this configuration on a staging environment before applying it to production. For any questions, contact Mirantis support.

Caution

As long as the feature is still on the development stage, Mirantis highly recommends deleting all HostOSConfiguration objects, if any, before automatic upgrade of the management cluster to Container Cloud 2.27.0 (Cluster release 16.2.0). After the upgrade, you can recreate the required objects using the updated parameters.

This precautionary step prevents re-processing and re-applying of existing configuration, which is defined in HostOSConfiguration objects, during management cluster upgrade to 2.27.0. Such behavior is caused by changes in the HostOSConfiguration API introduced in 2.27.0.

This section describes the HostOSConfiguration custom resource (CR) used in the management API. It contains all necessary information to introduce and load modules for further configuration of the host operating system of the related Machine object.

Note

This object must be created and managed on the management cluster.

For demonstration purposes, we split the HostOSConfiguration CR into the following sections:

HostOSConfiguration metadata

The HostOSConfiguration custom resource (CR) metadata contains the following fields:

  • apiVersion

    API version of the object that is ipam.mirantis.com/v1alpha1.

  • kind

    Object type that is HostOSConfiguration.

  • metadata

    Object metadata that contains the following subfields:

    • name

      Object name.

    • namespace

      Project in which the HostOSConfiguration object is created.

Configuration example:

apiVersion: kaas.mirantis.com/v1alpha1
kind: HostOSConfiguration
metadata:
  name: host-os-configuration-sample
  namespace: default

HostOSConfiguration configuration

The spec object field contains configuration for a HostOSConfiguration object and has the following fields:

  • machineSelector

    Required for production deployments. A set of Machine objects to apply the HostOSConfiguration object to. Has the format of the Kubernetes label selector.

  • configs

    Required. List of configurations to apply to Machine objects defined in machineSelector. Each entry has the following fields:

    • module

      Required. Name of the module that refers to an existing module in one of the HostOSConfigurationModules objects.

    • moduleVersion

      Required. Version of the module in use in the SemVer format.

    • description

      Optional. Description and purpose of the configuration.

    • order

      Optional. Positive integer between 1 and 1024 that indicates the order of applying the module configuration. A configuration with the lowest order value is applied first. If the order field is not set:

      • Since MCC 2.27.0 (Cluster releases 17.2.0 and 16.2.0), the configuration is applied in the order of appearance in the list after all configurations with the value are applied.

      • In MCC 2.26.0 (Cluster releases 17.1.0 and 16.1.0), the following rules apply to the ordering when comparing each pair of entries:

        1. Ordering by alphabet based on the module values unless they are equal.

        2. Ordering by version based on the moduleVersion values, with preference given to the lesser value.

    • values

      Optional if secretValues is set. Module configuration in the format of key-value pairs.

    • secretValues

      Optional if values is set. Reference to a Secret object that contains the configuration values for the module:

      • namespace

        Project name of the Secret object.

      • name

        Name of the Secret object.

      Note

      You can use both values and secretValues together. But if the values are duplicated, the secretValues data rewrites duplicated keys of the values data.

      Warning

      The referenced Secret object must contain only primitive non-nested values. Otherwise, the values will not be applied correctly.

    • phase

      Optional. LCM phase, in which a module configuration must be executed. The only supported and default value is reconfigure. Hence, you may omit this field.

  • order

    Removed in Container Cloud 2.27.0 (Cluster releases 17.2.0 and 16.2.0). Optional. Positive integer between 1 and 1024 that indicates the order of applying HostOSConfiguration objects on newly added or newly assigned machines. An object with the lowest order value is applied first. If the value is not set, the object is applied last in the order.

    If no order field is set for all HostOSConfiguration objects, the objects are sorted by name.

    Note

    If a user changes the HostOSConfiguration object that was already applied on some machines, then only the changed items from the spec.configs section of the HostOSConfiguration object are applied to those machines, and the execution order applies only to the changed items.

    The configuration changes are applied on corresponding LCMMachine objects almost immediately after host-os-modules-controller verifies the changes.

Configuration example:

spec:
   machineSelector:
      matchLabels:
        label-name: "label-value"
   configs:
   - description: Brief description of the configuration
     module: container-cloud-provided-module-name
     moduleVersion: 1.0.0
     order: 1
     # the 'phase' field is provided for illustration purposes. it is redundant
     # because the only supported value is "reconfigure".
     phase: "reconfigure"
     values:
       foo: 1
       bar: "baz"
     secretValues:
       name: values-from-secret
       namespace: default

HostOSConfiguration status

The status field of the HostOSConfiguration object contains the current state of the object:

  • controllerUpdate

    Reserved. Available since Container Cloud 2.27.0 (Cluster releases 17.2.0 and 16.2.0). Indicates whether the status updates are initiated by host-os-modules-controller.

  • isValid

    Available since Container Cloud 2.27.0 (Cluster releases 17.2.0 and 16.2.0). Indicates whether all given configurations have been validated successfully and are ready to be applied on machines. An invalid object is discarded from processing.

  • specUpdatedAt

    Available since Container Cloud 2.27.0 (Cluster releases 17.2.0 and 16.2.0). Defines the time of the last change in the object spec observed by host-os-modules-controller.

  • containsDeprecatedModules

    Available since Container Cloud 2.28.0 (Cluster releases 17.3.0 and 16.3.0). Indicates whether the object uses one or several deprecated modules. Boolean.

  • machinesStates

    Available since Container Cloud 2.27.0 (Cluster releases 17.2.0 and 16.2.0). Specifies the per-machine state observed by baremetal-provider. The keys are machines names, and each entry has the following fields:

    • observedGeneration

      Read-only. Specifies the sequence number representing the quantity of changes in the object since its creation. For example, during object creation, the value is 1.

    • selected

      Indicates whether the machine satisfied the selector of the object. Non-selected machines are not defined in machinesStates. Boolean.

    • secretValuesChanged

      Indicates whether the secret values have been changed and the corresponding stateItems have to be updated. Boolean.

      The value is set to true by host-os-modules-controller if changes in the secret data are detected. The value is set to false by baremetal-provider after processing.

    • configStateItemsStatuses

      Specifies key-value pairs with statuses of StateItems that are applied to the machine. Each key contains the name and version of the configuration module. Each key value has the following format:

      • Key: name of a configuration StateItem

      • Value: simplified status of the configuration StateItem that has the following fields:

        • hash

          Value of the hash sum from the status of the corresponding StateItem in the LCMMachine object. Appears when the status switches to Success.

        • state

          Actual state of the corresponding StateItem from the LCMMachine object. Possible values: Not Started, Running, Success, Failed.

  • configs

    List of configurations statuses, indicating results of application of each configuration. Every entry has the following fields:

    • moduleName

      Existing module name from the list defined in the spec:modules section of the related HostOSConfigurationModules object.

    • moduleVersion

      Existing module version defined in the spec:modules section of the related HostOSConfigurationModules object.

    • modulesReference

      Name of the HostOSConfigurationModules object that contains the related module configuration.

    • modulePlaybook

      Name of the Ansible playbook of the module. The value is taken from the related HostOSConfigurationModules object where this module is defined.

    • moduleURL

      URL to the module package in the FQDN format. The value is taken from the related HostOSConfigurationModules object where this module is defined.

    • moduleHashsum

      Hash sum of the module. The value is taken from the related HostOSConfigurationModules object where this module is defined.

    • lastDesignatedConfiguration

      Removed in Container Cloud 2.27.0 (Cluster releases 17.2.0 and 16.2.0). Key-value pairs representing the latest designated configuration data for modules. Each key corresponds to a machine name, while the associated value contains the configuration data encoded in the gzip+base64 format.

    • lastValidatedSpec

      Removed in Container Cloud 2.27.0 (Cluster releases 17.2.0 and 16.2.0). Last validated module configuration encoded in the gzip+base64 format.

    • valuesValid

      Removed in Container Cloud 2.27.0 (Cluster releases 17.2.0 and 16.2.0). Validation state of the configuration and secret values defined in the object spec against the module valuesValidationSchema. Always true when valuesValidationSchema is empty.

    • error

      Details of an error, if any, that occurs during the object processing by host-os-modules-controller.

    • secretObjectVersion

      Available since Container Cloud 2.27.0 (Cluster releases 17.2.0 and 16.2.0). Resource version of the corresponding Secret object observed by host-os-modules-controller. Is present only if secretValues is set.

    • moduleDeprecatedBy

      Available since Container Cloud 2.28.0 (Cluster releases 17.3.0 and 16.3.0). List of modules that deprecate the currently configured module. Contains the name and version fields specifying one or more modules that deprecate the current module.

    • supportedDistributions

      Available since Container Cloud 2.28.0 (Cluster releases 17.3.0 and 16.3.0). List of operating system distributions that are supported by the current module. An empty list means support of any distribution by the current module.

HostOSConfiguration status example:

status:
  configs:
  - moduleHashsum: bc5fafd15666cb73379d2e63571a0de96fff96ac28e5bce603498cc1f34de299
    moduleName: module-name
    modulePlaybook: main.yaml
    moduleURL: <url-to-module-archive.tgz>
    moduleVersion: 1.1.0
    modulesReference: mcc-modules
    moduleDeprecatedBy:
    - name: another-module-name
      version: 1.0.0
  - moduleHashsum: 53ec71760dd6c00c6ca668f961b94d4c162eef520a1f6cb7346a3289ac5d24cd
    moduleName: another-module-name
    modulePlaybook: main.yaml
    moduleURL: <url-to-another-module-archive.tgz>
    moduleVersion: 1.1.0
    modulesReference: mcc-modules
    secretObjectVersion: "14234794"
  containsDeprecatedModules: true
  isValid: true
  machinesStates:
    default/master-0:
      configStateItemsStatuses:
        # moduleName-moduleVersion
        module-name-1.1.0:
          # corresponding state item
          host-os-download-<object-name>-module-name-1.1.0-reconfigure:
            hash: 0e5c4a849153d3278846a8ed681f4822fb721f6d005021c4509e7126164f428d
            state: Success
          host-os-<object-name>-module-name-1.1.0-reconfigure:
            state: Not Started
        another-module-name-1.1.0:
          host-os-download-<object-name>-another-module-name-1.1.0-reconfigure:
            state: Not Started
          host-os-<object-name>-another-module-name-1.1.0-reconfigure:
            state: Not Started
      observedGeneration: 1
      selected: true
  updatedAt: "2024-04-23T14:10:28Z"