HostOSConfiguration and HostOSConfigurationModules concepts¶

TechPreview since 2.26.0 (17.1.0 and 16.1.0)

This section outlines fundamental concepts of the HostOSConfiguration, aka hoc, and HostOSConfigurationModules, aka hocm, custom resources as well as provides usage guidelines for these resources. For detailed descriptions of these resources, see API Reference: Bare metal resources.

Container Cloud and custom-made modules¶

Container Cloud provides modules, which are described in Modules provided by Container Cloud, using the designated hocm object named mcc-modules. All other hocm objects contain custom modules.

Warning

Do not modify the mcc-modules object that contains only Mirantis-provided modules. Any changes to this object will be overwritten with data from an external source.

Machine selector¶

Selector value¶

When the value of the machineSelector field in a hoc object is empty (by default), no machines are selected. Therefore, no actions are triggered until you provide a non-empty machineSelector.

This approach differs from the default behavior of Kubernetes selectors to ensure that none of configurations are applied to all machines in a cluster accidentally.

Namespace of a Machine object¶

It is crucial to ensure that the namespace of a hoc object is the same as the namespace of the associated Machine objects defined in the machineSelector field.

For example, the following machines are located in two separate namespaces, default and other-ns, and the hoc object is located in other-ns:

NAMESPACE    NAME                              LABELS
default      machine.cluster.k8s.io/master-0   example-label="1"
default      machine.cluster.k8s.io/master-1   example-label="1"
default      machine.cluster.k8s.io/master-2   example-label="1"
other-ns     machine.cluster.k8s.io/worker-0   example-label="1"
other-ns     machine.cluster.k8s.io/worker-1   example-label="1"
other-ns     machine.cluster.k8s.io/worker-2   example-label="1"

NAMESPACE    NAME                                             LABELS
other-ns     hostosconfigurations.kaas.mirantis.com/example   <none>

And although machineSelector in the hoc object contains example-label="1", which is set for machines in both namespaces, but only worker-0, worker-1, worker-2 will be selected because the hoc object is located in the other-ns namespace.

machineSelector:
  matchLabels:
    example-label: "1"

Configuration values of a module¶

You may use arbitrary types for primitive (non-nested) values. But for optimal compatibility and clarity, Mirantis recommends using string values for primitives in the values section of a hoc object. This practice helps maintain consistency and simplifies the interpretation of configurations.

Under the hood, all primitive values are converted to strings.

For example:

values:
  # instead of
  # primitive-float-value: 1.05
  primitive-float-value: "1.05"
  # instead of
  # primitive-boolean-value: true
  primitive-boolean-value: "true"
  object-value:
    object-key: "string-data"

You can pass the values of any day-2 module to the HostOSConfiguration object using both the values and secretValues fields simultaneously. But if a key is present in both fields, the value from secretValues is applied.

The values field supports the YAML format for values with any nesting level. The HostOSConfiguration controller and provider use the YAML parser underneath to manage the values. The following examples illustrate simple and nested configuration formats:

Simple key-value map:

apiVersion: kaas.mirantis.com/v1alpha1
kind: HostOSConfiguration
...
spec:
  configs:
    - module: somemodule
      moduleVersion: 1.0.0
      values:
        key1: value1
        key2: value2

Nested YAML:

apiVersion: kaas.mirantis.com/v1alpha1
kind: HostOSConfiguration
...
spec:
  configs:
    - module: somemodule
      moduleVersion: 1.0.0
      values:
        nestedkey1:
          nestedkey2:
            - value1
            - value2
        key2: value3

The secretValues field is a reference (namespace and name) to the Secret object.

Warning

The referenced Secret object must contain only primitive non-nested values. Otherwise, the values will not be applied correctly. Therefore, implement your custom modules in a way that secret parameters are on the top level and not used within nested module parameters.

You can create a Secret object in the YAML format. For example:

apiVersion: v1
data:
  key1: <base64-encoded-string-value1>
  key2: <base64-encoded-string-value2>
kind: Secret
metadata:
  name: top-secret
  namespace: default
type: Opaque

Caution

Manually encode secret values using the base64 format and ensure that the value does not contain trailing whitespaces or line translation such as the \n symbol. For example:

echo -n "secret" | base64

You can also create the Secret object using the kubectl command. This way, the secret values are automatically base64-encoded:

kubectl create secret generic top-secret --from-literal=key1=value1 --from-literal=key2=value2

The following example illustrates the use of a secret in HostOSConfiguration:

apiVersion: kaas.mirantis.com/v1alpha1
kind: HostOSConfiguration
...
spec:
  configs:
    - module: somemodule
      moduleVersion: 1.0.0
      secretValues:
        name: top-secret
        namespace: default
      values:
        key3: value3
        key4: value4

Execution order of configurations¶

For details about execution order of configurations, see API Reference: HostOSConfiguration - spec.configs.order.

Identify deprecated modules in use¶

Available since 2.28.0 (17.3.0 and 16.3.0)

To identify whether a cluster has hoc objects with deprecated modules:

kubectl get hoc -A -o go-template="{{range .items}}HOC {{.metadata.namespace}}/{{.metadata.name}} has deprecated modules: {{if .status.containsDeprecatedModules}}yes{{else}}no{{end}}{{\"\n\"}}{{end}}"

Example output:

HOC default/hoc-example1 has deprecated modules: yes
HOC default/hoc-example2 has deprecated modules: yes
HOC default/hoc-example3 has deprecated modules: no
HOC default/hoc-example4 has deprecated modules: yes

To identify specific deprecated modules:

kubectl get hoc -A -o go-template="{{range .items}}HOC {{.metadata.namespace}}/{{.metadata.name}} deprecated modules:{{\"\n\"}}{{range .status.configs}}{{if .moduleDeprecatedBy}}{{.moduleName}}-{{.moduleVersion}}{{\"\n\"}}{{end}}{{end}}{{end}}"

Example output:

HOC default/hoc-example1 deprecated modules:
foo-1.1.0
HOC default/hoc-example2 deprecated modules:
bar-1.1.0
HOC default/hoc-example3 deprecated modules:
HOC default/hoc-example4 deprecated modules:
baz-1.1.0
qux-1.1.0