23.9. classify - Classify¶
The following documentation is for Classify (classify) content package at version v4.9.0-alpha00.67+g2af61053ec23a91be2e566ecf386ec23b2ae1119.
The Classifier System allows an operator to flexibly define groups of test/action sequences to perform on a Machine. These can be used to do any number of tasks. Typically the classifier allows an operator to add additional information to a Machine object that will alter the behavior of subsequent Workflow stages/tasks.
By default the classifier provides a limited set of tests and actions
that can be performed. However, the operator can specify additional
groups of test/actions pairs by use of the classify/custom-functions
Param. See the Param classify/custom-functions documentation on how to
use it.
By default, the classifier is designed to exit on the first test match
that succeeds with a “pass” status. The operator can override this
behavior by setting the optional continue value set to true
in the classify/classification-data structure.
If you are extending the Classifier to add custom groups of test/action
sequences, please review the function ... {} BASH functions in the
classify.sh.tmpl template for examples.
23.9.1. Getting Started with the Classifier¶
The Classifier rulesets of test/action sequences are configured by setting the Param
classify/classification-data on a Machine. The usual rules and orders of precedence
are followed on this Param (Param on Machine; Profile on Machine; Global Profile; etc…).
The classification data structure is a list of YAML or JSON objects, with two required and one optional set of values. The structure is as follows (example in YAML):
- test: "<TEST_TYPE>" actions: - "<ACTION>" - "<ACTION>" continue: true
The test and actions are required elements. continue is optional based on the
operators need.
Here are some example usage scenarious to help you get started.
23.9.1.1. Simple MAC Address Match and Classify¶
In this scenario, you will use the MAC Address as a simple test matcher to apply actions. Demonstrated in this example are adding two Params, and two profiles to the machine.
The Params in this example sets hostname, and universal/application value to specify the
role that this machine will perform. Subsequent content/plugins can react accordingly to
this. The profiles might be responsible for carrying configuration data for subsequent
content/plugins to operate on. For example, setting BIOS bios-target-configuraion,
determining what Firmware/Flash versions to use, Operating System configuration profile
data (eg VMware ESXi configuration, etc.).
Last, this classify test/action sequence will continue on in the list to any subsequent
test/action sequences after a match is found (continue: true).
classify/classification-data: - test: "has_mac 24:6e:96:6a:40:34" actions: - "set_parameter hostname r3r6-u03" - "set_parameter universal/application vcf381" - "add_profile demo-r3r6-machine-r3r6-u03" - "add_profile demo-r3r6-application-vcf381" continue: true
23.9.1.2. Change Workflow¶
In this scenario, the Classify system will be used to change the Machines Workflow. We
will match on the Inventory field inventory/Manufacturer with a match of QEMU
(which is typically how a KVM hypervisor will present a KVM backed Virtual Machine). The
Machine will be changed to the centos-install workflow to install CentOS operating
system.
Note
When the Machine’s workflow is changed, any remaining Stages/Tasks from the current workflow will be immediately replaced by the new Workflow.
This example assumes that the operator has already set the classify/custom-functions to include
the has_inventory_value.sh.tmpl template included already.
classify/classification-data: - test: "has_inventory_value Manufacturer QEMU" actions: - "change_workflow centos-install"
Since there is no continue: true setting, the classifier will exit after this rule, and
will not process any further rules listed after this one.
Note
The Flexiflow content pack is designed to provide controlled ways to inject new
tasks and switch workflows. You may wish to utilize the constructs in that
content pack over the change_workflow action in the Classifier.
23.9.2. Object Specific Documentation¶
23.9.2.1. params¶
The content package provides the following params.
23.9.2.1.1. classify/classification-data¶
This object defines a series of tests to determine the classification of a Machine followed by a list of actions to apply to that Machine if the test is successful.
The order of precedence is important! A Machine will be evaluated in the order you specify in the tests below. Generally speaking, you should order the MOST SPECIFIC tests first, followed by general tests next. The very last test in the example below would be a default in the event no previous tests matched.
Setting continue: true in this Param data structure will allow the
classifier to continue classifying after the first match. This
effectively allows the operations to continue multiple tests/actions
sequences, instead of exiting on first match.
If none of the tests match, then the Machine will not be modified.
The object should look like this.
- test: "has_mac 00:11:22:33:44:55"
continue: true
actions:
- "add_profile profile_name_1"
- "change_workflow workflow_name_1"
- test: "in_subnet 192.168.0.0/24"
actions:
- "set_parameter param_name value"
- "add_profile profile_name_2"
- "change_workflow workflow_name_2"
- test: "always"
actions:
- "change_workflow wait-for-input"
In the above example, the has_mac test will be applied, if the test
passes, it would normally exit the Classifier. However, the continue
operator has been set to true, so the tests will continue to the next
(in_subnet), and subsequently if passing that test, will apply the
actions specified.
EXTENDING CLASSIFIER tests AND actions
The classifier can be extended to add custom test and actions groups.
See the classify/custom-functions Param for details.
23.9.2.1.2. classify/custom-functions¶
Use this Param to specify additional custom templates to include in to the Classifier.
This is intended to inject BASH “function NAME { … }” stanzas in the classifer to provide custom function blocks to extend the tests and/or actions you can apply to the classifier.
YAML Example
- "my-classify-function-1.tmpl"
- "my-classify-function-2.tmpl"
JSON Example
[
"my-classify-function-1.tmpl",
"my-classify-function-2.tmpl"
]
Note
The executing environment is Sledgehammer with BASH scripts. You
must ensure that the Function you inject operates correctly in
this environment. For reference, see the Functions in the existing
classifier Template classify.sh.tmpl.
Any test functions should echo "pass" or echo "fail" to signal the test
condition status and should subsequently apply the given actions specified.
An example template named has_inventory_value.tmpl has been provided that
the operator can use as an example test condition.
23.9.2.1.3. classify/data-parameter¶
This defines the name of a parameter that contains the classification data.
The parameter should have the same type as classify/classification-data.
23.9.2.1.4. classify/disable-classifier¶
In some use cases, you may need to disable the classifier system from running when machines are being provisioned. This parameter enables a fast disable, without having to remove the classifier itself.
Apply this Param with the value true to disable the classifier,
on any machines or profiles applied to machines, to effect disabling.
For example, you could apply this Param to global profile to disable
it globally.
Note
Normal precedence with Paramaters applies, so if a Machine has the Param applied also, the Machines Param value overrides the global value.
23.9.2.1.5. classify/disable-parameter¶
This defines the name of a parameter that defines if this classifer should be skipped.
The parameter should have the same type as classify/disable-classifier, boolean.
23.9.2.1.6. classify/function-parameter¶
This defines the name of a parameter that contains the list of classification functions to add.
The parameter should have the same type as classify/custom-functions, a list of template names.
23.9.2.1.7. classify/stage-list¶
Use this Param to specify additional classify stages. In general, this is an example and is used as a different parameter through indirection.
23.9.2.1.8. classify/stage-list-parameter¶
This defines the name of a parameter that defines the list of classifaction stages to add to the machine.
The parameter should have the same type as classify/stage-list, array of strings.
23.9.2.1.9. classify/version¶
This parameter defines the version of classifier to use. Version 1 uses the normal parameters. Version 2 uses the parameter name parameters to determine what to do.
23.9.2.2. stages¶
The content package provides the following stages.
23.9.2.2.1. classify¶
Applies classification test and action sequences to a Machine. Operations allow adding Params, Profiles, etc. to the Machine object. Based on these added values, subsequent stages in a workflow can utilize the information that the classifier has added to a Machine.
Some examples including adding Profiles with BIOS configurations, lists
of Firmware versions to apply by the flash content pack, etc. In
addition, you can use the flexiflow content pack to check if a specific
values in a Param has been set, and based on that, switch to a completely
new Workflow.
23.9.2.2.2. classify-stage-list¶
This stages uses the classify/stage-list parameter to add classification stages
to the machine.
To build custom sets of lists, you can extend this by changing the classify/stage-list-parameter.
23.9.2.3. tasks¶
The content package provides the following tasks.
23.9.2.3.1. classify¶
This will run specified test and action sequences to make
changes to a Machines object.
23.9.2.3.2. classify-stage-list-start¶
Using the parameter specified by the classify/stage-list-parameter, the
stages specified in that list will be added to the system. This assumes that
they are classify stages and have a single task of classify.
No other tasks should preceed it on the stage, and the only other task that
should follow is the classify-stage-list-stop task.
Tasks will be dynamically injected in to the workflow after this task, if they have been specified by the appropriate control Params.
23.9.2.3.3. classify-stage-list-stop¶
This task ends a given set of classifcation stages. No other tasks should follow it on the stage.
Tasks will be dynamically injected in to the workflow if they have been specified by the appropriate control Params prior to this task.
