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