4 Salt Formulas and SUSE Manager

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:

Note: Formula with Forms Improvements

Forms are a graphical representation of the formulas parameter data. You can customize these configuration data in the SUSE Manager Web UI, with entry fields, drop-down, check boxes, etc.

For more information, see https://www.suse.com/c/forms-formula-success/.

SUSE releases formulas as RPM packages.

Note: Formula Channel Location

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:

/srv/formula_metadata/<custom-formula-name>/form.yml

SUSE Manager requires a file called form.yml, to describe how formula data should look within the Web UI. form.yml is used by SUSE Manager 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:

/usr/share/susemanager/formulas/metadata/locale/form.yml

See part of the following locale-formula example:

# This file is part of locale-formula.
#
# Foobar is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# Foobar is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with Foobar.  If not, see <http://www.gnu.org/licenses/>.

timezone:
  $type: group

  name:
    $type: select
    $values: ["CET",
              "CST6CDT",
              "EET",
              "EST",
              "EST5EDT",
              "GMT",
              "GMT+0",
              "GMT-0",
              "GMT0",
              "Greenwich",
              "HST",
              "MET",
              "MST",
              "MST7MDT",
              "NZ",
              "NZ-CHAT",
              "Navajo",
              "PST8PDT",
              "UCT",
              "UTC",
              "Universal",
              "W-SU",
              "WET",
              "Zulu",
              "Etc/GMT+1",
              "Etc/GMT+2",
              "Etc/GMT+3",
              "Etc/GMT+4",
              "Etc/GMT+5",
              "Etc/GMT+6",
              "Etc/GMT+7",
              "Etc/GMT+8",
              "Etc/GMT+9",
              "Etc/GMT+10",
              "Etc/GMT+11",
              "Etc/GMT+12",
              "Etc/GMT-1",
              "Etc/GMT-2",
              "Etc/GMT-3",
              "Etc/GMT-4",
              "Etc/GMT-5",
              "Etc/GMT-6",
              "Etc/GMT-7",
              "Etc/GMT-8",
              "Etc/GMT-9",
              "Etc/GMT-10",
              "Etc/GMT-11",
              "Etc/GMT-12",
              "Etc/GMT-13",
              "Etc/GMT-14",
              "Etc/GMT",
              "Etc/GMT+0",
              "Etc/GMT-0",
              "Etc/GMT0",
              "Etc/Greenwich",
              "Etc/UCT",
              "Etc/UTC",
              "Etc/Universal",
              "Etc/Zulu"
              ]
    $default: CET

  hardware_clock_set_to_utc:
    $type: boolean
    $default: True
...

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

Important: Ignored Values

All values that start with a $ sign are annotations used to display the UI that users interact with. These annotations are not part of pillar data itself and are handled as metadata.

The following are valid attributes.

Note: Text Attribute

The text attribute is the default and does not need to be specified explicitly.

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. 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 Section 4.4.1, “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.

4.4.1 Simple edit-group Example #

See the following edit-group example:

partitions:
  $name: "Hard Disk Partitions"
  $type: "edit-group"
  $minItems: 1
  $maxItems: 4
  $itemName: "Partition ${name}"
  $prototype:
    name:
      $default: "New partition"
    mountpoint:
      $default: "/var"
    size:
      $type: "number"
      $name: "Size in GB"
  $default:
    - name: "Boot"
      mountpoint: "/boot"
    - name: "Root"
      mountpoint: "/"
      size: 5000

After clicking Add for one time you will see Figure 4.1, “edit-group Example in the Web UI” filled with the default values. The formula itself is called hd-partitions and will appear as Hd Partitions in the Web UI.

Figure 4.1: edit-group Example in the Web UI #

To remove the definition of a partition click the minus symbol in the title line of an inner group. When form fields are properly filled confirm with clicking Save Formula in the upper right corner of the formula.

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:

pillar.some.value

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

salt['pillar.get']('some:value', 'default value')

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:

install_a_package:
  pkg.installed:
    - name: {{ pillar.package_name }}

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

{% if pillar.installSomething %}
something:
  pkg.installed
{% else %}
anotherPackage:
  pkg.installed
{% endif %}

Another example:

{% for service in pillar.services %}
start_{{ service }}:
  service.running:
    - name: {{ service }}
{% endfor %}

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

{% for key, value in some_dictionary.items() %}
do_something_with_{{ key }}: {{ value }}
{% endfor %}

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:

/etc/my_program/my_program.conf:
  file.managed:
    - source: salt://my_state/files/my_program.conf
    - template: jinja

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 minion and template it with Jinja. This allows you to use Jinja in the file, exactly like shown above for states:

some_config_option = {{ pillar.config_option_a }}

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

{% set data = salt['grains.filter_by']({
    'Suse': {
        'package': 'packageA',
        'service': 'serviceA'
    },
    'RedHat': {
        'package': 'package_a',
        'service': 'service_a'
    }
}, merge=salt['pillar.get']('some:pillar:data')) %}

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:

{% from "some_folder/map.jinja" import data with context %}

install_package_a:
  pkg.installed:
    - name: {{ data.package }}

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

{% set server = salt['grains.filter_by']({
    'Suse': {
        'package': 'my-server-pkg'
    }
}, merge=salt['pillar.get']('myFormula:server')) %}
{% set client = salt['grains.filter_by']({
    'Suse': {
        'package': 'my-client-pkg'
    }
}, merge=salt['pillar.get']('myFormula:client')) %}

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

{% from "map.jinja" import server, client with context %}

Formulas utilized with SUSE Manager 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:

/usr/share/susemanager/modules/pillar/suma_minion.py

The process is executed as follows:

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

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

This conclude your introduction to Salt Formulas. For additional information, see:

This section provides an introduction to Salt Formulas shipped with SUSE Manager for Retail. These formulas such as the PXE boot, branch server network, or saltboot formulas are used to fine-tune the SUSE Manager for Retail infrastructure.

4.10.1 Pxe Formula #

The Pxe formula (pxe-formula) for installing, setting up, and uninstalling syslinux PXE boot on the POS branchserver.

Figure 4.2: pxe formula #

4.10.2 Branch Network Formula #

The Branch Network formula (branch-network-formula) for configuring the branch server network.

Figure 4.3: branch network formula #

4.10.3 Saltboot Formula #

The Saltboot formula (saltboot-formula) is a formula for configuring a boot image of a POS terminal.

Figure 4.4: saltboot formula #

Then you configure one or more partitions:

Figure 4.5: saltboot formula partitions #

salt <branchserver> state.apply image-sync

For general information, see the Salt Formulas installation and usage instructions at https://docs.saltstack.com/en/latest/topics/development/conventions/formulas.html.

4.11.2 Domain Name System (Bind) #

With the bind formula you set up and configure a Domain Name System (DNS) server. For technical information about the bind formula and low-level pillar data, see the README.rst file on the SUSE Manager server: /usr/share/susemanager/formulas/metadata/bind/README.rst.

DNS is needed to resolve the domain names and host names into IP addresses. For more information about DNS, see the SLES Administration Guide, Services, The Domain Name System.

Figure 4.6: Bind Formula #

In the Config group you can set arbitrary options such as directory where are the zone data files (usually /var/lib/named/) or forwarders. Click Add Item to provide more Key/Value fields for configuration.

Check Include Forwarders if you want to rely on an external DNS server if your DNS is down (or is otherwise not able to resolve an address).

At least, you will configure one zone. In Configured Zones define your zone; for example, example.com. Then in Available Zones configure this zone: as Name enter your zone (in this case example.com) and the File to which this configuration should be written (example.com.txt). Enter the mandatory SOA record (start of authority), and the A, NS, and CNAME Records you need.

On the other hand, if no records entry exists, the zone file is not generated by this state rather than taken from salt://zones. For how to overwrite this URL, see pillar.example.

Figure 4.7: bind-02-zones #

Figure 4.8: bind-03-records #

Figure 4.9: bind-03-records2 #

In Generate Reverse, and define reverse mapping and for which zones:

Figure 4.10: bind-04-reverse #

When saved, data is written to /srv/susemanager/formula_data/pillar/<salt-minion.example.com>_bind.json.

If you apply the highstate (System Details › States › Highstate), it first ensures that bind and all required packages will get installed. Then it will start the DNS service (named).

4.11.3 Dhcpd #

With the dhcpd formula you set up and configure a DHCP server (Dynamic Host Configuration Protocol). For technical information about the dhcpd formula and low-level pillar data, see the Pillar example file /usr/share/susemanager/formulas/metadata/dhcpd/pillar.example.

DHCP is needed to define network settings centrally (on a server) and let clients retrieve and use this information for local host configuration. For more information about DHCP, see the SLES Administration Guide, Services, DHCP.

Figure 4.11: dhcpd formula #

Domain Name.

Domain Name Servers. One or more Domain Name Service (DNS) servers.

On which interface(s) the DHCP server should listen (Listen interfaces). Set option for this interface: Authoritative: Max Lease Time: Default Lease Time:

Next is at least one network in the Network configuration (subnet) group (with IP address, netmask, etc.). You define every network with Dynamic IP range, Routers, and Hosts with static IP addresses (with defaults from subnet) (optionally).

And finally Hosts with static IP addresses (with global defaults).

If you apply the highstate (System Details › States › Highstate), it first ensures that dhcp-server and all required packages will get installed. Then it will start the DHCP service (dhcpd).

4.11.4 Tftpd #

With the tftpd formula you set up and configure a TFTP server (Trivial File Transfer Protocol). A TFTP server is a component that provides infrastructure for booting with PXE.

For more information about setting up TFTP, see the SLES Deployment Guide, Preparing Network Boot Environment, Setting Up a TFTP Server.

Figure 4.12: tftpd formula #

For setting up a TFTP server, specify the Internal Network Address, TFTP base directory (default: /srv/tftpboot), and run TFTP under user (default: sftp).

If you apply the highstate (System Details › States › Highstate), it first ensures that atftp and all required packages will get installed. Then it will start TFTP (atftpd).

4.11.5 Vsftpd #

With the vsftpd formula you set up and configure Vsftpd. Vsftpd is an FTP server or daemon, written with security in mind. "vs" in its name stands for "Very Secure".

Figure 4.13: vsftpd formula #

For configuring a VSFTP server, specify the settings and options in the Vsftpd formula. There are settings such as FTP server directory, Internal Network Address Enable ssl, etc.

If you apply the highstate (System Details › States › Highstate), it first ensures that vsftpd and all required packages will get installed. Then it will start the VSFTP service (vsftpd).

For more information about setting up and tuning Vsftpd, see the documentation coming with the vsftpd package (/usr/share/doc/packages/vsftpd/ when the package is installed).