22.9. classify - Classify

The following documentation is for Classify (classify) content package at version v4.10.0-alpha00.46+g1471cf9bbea9d50f3360a078e87e85f65fff4c7c.

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.

22.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.

22.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

22.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.

22.9.2. Object Specific Documentation

22.9.2.1. params

The content package provides the following params.

22.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.

22.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.

22.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.

22.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.

22.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.

22.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.

22.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.

22.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.

22.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.

22.9.2.2. stages

The content package provides the following stages.

22.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.

22.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.

22.9.2.3. tasks

The content package provides the following tasks.

22.9.2.3.1. classify

This will run specified test and action sequences to make changes to a Machines object.

22.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.

22.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.

22.9.2.4. workflows

The content package provides the following workflows.

22.9.2.4.1. classify

Workflow that runs the classify Stage, which allows an operator to match test and action sequences on the given machine that the workflow is run on.