HostOSConfiguration¶

TechPreview since 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 Container Cloud 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 Container Cloud HostOSConfiguration CR into the following sections:

HostOSConfiguration metadata
HostOSConfiguration configuration
HostOSConfiguration status

HostOSConfiguration metadata¶

metadata¶

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

apiVersion
Object API version that is kaas.mirantis.com/v1alpha1.
kind
Object type that is HostOSConfiguration.

The metadata object field of the HostOSConfiguration resource contains the following fields:

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 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 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:
  
  Ordering by alphabet based on the module values unless they are equal.
  
  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 2.27.0 (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 ^{Since 2.27.0 (17.2.0 and 16.2.0)}
Reserved. Indicates whether the status updates are initiated by host-os-modules-controller.
isValid ^{Since 2.27.0 (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 ^{Since 2.27.0 (17.2.0 and 16.2.0)}
Defines the time of the last change in the object spec observed by host-os-modules-controller.
machinesStates ^{Since 2.27.0 (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.

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
  - 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"
  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"