Salt Formulas

Formulas are collections of Salt States that have been pre-written by other Salt users and contain generic parameter fields. Formulas allow for reliable reproduction of a specific configuration again and again. Formulas can be installed from RPM packages or an external git repository.

This list will help you decide whether to use a state or a formula:

SUSE releases formulas as RPM packages. Available formulas can be located within the SUSE-Manager-Server-3.2-Pool channel.

RPM-based formulas must be placed in a specific directory structure to ensure proper functionality. A formula always consists of two separate directories: The states directory and the metadata directory. Folders in these directories need to have an exactly matching name, for example locale.

All custom folders located in the following directories need to contain a form.yml file. These files are detected as form recipes and may be applied to groups and systems from the Web UI:

Uyuni requires a file called form.yml, to describe how formula data should look within the Web UI. form.yml is used by Uyuni to generate the desired form, with values editable by a user.

For example, the form.yml that is included with the locale-formula is placed in:

See part of the following locale-formula example:

form.yml contains additional information that describes how the form for a pillar should look for Uyuni. This information is contained in attributes that always start with a $ sign.

The following are valid attributes.

Many of these values are self-explanatory:

The group, edit-group, and namespace (formerly hidden-group) types do not generate an editable field and are used to structure form and pillar data. All these types support nesting. For providing default values with nesting, see edit-group Example with Nesting. The difference between group and namespace is group generates a visible border with a heading, and namespace shows nothing visually (and is only used to structure pillar data). The difference between group and edit-group is: edit-group allows to structure and restrict editable fields in a more flexible way. edit-group is a collection of items of the same kind; collections can have the following four "shapes":

The size of each collection is variable; users can add or remove elements.

For example, edit-group supports the $minItems and $maxItems attributes, and thus it simplifies complex and repeatable input structures. These, and also itemName, are optional. For an edit-group example, see Simple edit-group Example.

$placeholder may only be used with text fields like text, password, email or date. It does not make sense to add a placeholder if you also use $default as this will hide the placeholder.

Salt formulas are pre-written Salt states, which may be configured with pillar data. You can parametrize state files using Jinja. Jinja allows you to access pillar data by using the following syntax. This syntax works best when you are uncertain whether a pillar value exists as it will throw an error:

When you are sure a pillar exists you may also use the following syntax:

You may also replace the pillar value with grains (for example, grains.some.value) allowing access to grains.

Using data this way allows you to make a formula configurable. The following code snippet will install a package specified in the pillar package_name:

You may also use more complex constructs such as if/else and for-loops to provide greater functionality:

Another example:

Jinja also provides other helpful functions. For example, you can iterate over a dictionary:

You may want to have Salt manage your files (for example, configuration files for a program), and you can change these with pillar data. For example, the following snippet shows how you can manage a file using Salt:

Salt will copy the file salt-file_roots/my_state/files/my_program.conf on the salt master to /etc/my_program/my_program.conf on the client and template it with Jinja. This allows you to use Jinja in the file, exactly like shown above for states:

It is often a good idea to separate data from a state to increase its flexibility and add re-usability value. This is often done by writing values into a separate file named map.jinja. This file should be placed within the same directory as your state files.

The following example will set data to a dictionary with different values, depending on which system the state runs on. It will also merge data with the pillar using the some.pillar.data value so you can access some.pillar.data.value by just using data.value.

You can also choose to override defined values from pillars (for example, by overriding some.pillar.data.package in the example).

After creating a map file like the above example, you can maintain compatibility with multiple system types while accessing "deep" pillar data in a simpler way. Now you can import and use data in any file. For example:

You can also define multiple variables by copying the {% set …​%} statement with different values and then merge it with other pillars. For example:

To import multiple variables, separate them with a comma. For Example:

Formulas utilized with Uyuni should follow formula conventions listed in the official documentation:

When pillar data is generated (for example, after applying the highstate) the following external pillar script generates pillar data for packages, group ids, etc. and includes all pillar data for a system:

The process is executed as follows:

Formulas should be designed/created directly after a Uyuni installation, but if you encounter any issues check the following:

The following procedure provides an overview on using Salt Formulas with Uyuni.

For more information about Salt formulas, see https://docs.saltstack.com/en/latest/topics/development/conventions/formulas.html

For more information about using Salt formulas in a SUSE Manager for Retail environment, see retail:retail-formulas-intro.adoc.