FORMULA File¶

name¶

The name of the package, as it will appear in the package filename, in the repository metadata, and the package database. Even if the source formula has -formula in its name, this name should probably not include that. For instance, when packaging the apache-formula, the name should be set to apache.

os¶

The value of the os grain that this formula supports. This is used to help users know which operating systems can support this package.

os_family¶

The value of the os_family grain that this formula supports. This is used to help users know which operating system families can support this package.

version¶

The version of the package. While it is up to the organization that manages this package, it is suggested that this version is specified in a YYYYMM format. For instance, if this version was released in June 2015, the package version should be 201506. If multiple releases are made in a month, the release field should be used.

minimum_version¶

Minimum recommended version of Salt to use this formula. Not currently enforced.

release¶

This field refers primarily to a release of a version, but also to multiple versions within a month. In general, if a version has been made public, and immediate updates need to be made to it, this field should also be updated.

summary¶

A one-line description of the package.

description¶

A more detailed description of the package which can contain more than one line.

top_level_dir¶

This field is optional, but highly recommended. If it is not specified, the package name will be used.

Formula repositories typically do not store .sls files in the root of the repository; instead they are stored in a subdirectory. For instance, an apache-formula repository would contain a directory called apache, which would contain an init.sls, plus a number of other related files. In this instance, the top_level_dir should be set to apache.

Files outside the top_level_dir, such as README.rst, FORMULA, and LICENSE will not be installed. The exceptions to this rule are files that are already treated specially, such as pillar.example and _modules/.

dependencies¶

A comma-separated list of packages that must be installed along with this package. When this package is installed, SPM will attempt to discover and install these packages as well. If it is unable to, then it will refuse to install this package.

This is useful for creating packages which tie together other packages. For instance, a package called wordpress-mariadb-apache would depend upon wordpress, mariadb, and apache.

optional¶

A comma-separated list of packages which are related to this package, but are neither required nor necessarily recommended. This list is displayed in an informational message when the package is installed to SPM.

recommended¶

A comma-separated list of optional packages that are recommended to be installed with the package. This list is displayed in an informational message when the package is installed to SPM.

files¶

A files section can be added, to specify a list of files to add to the SPM. Such a section might look like:

files:
  - _pillar
  - FORMULA
  - _runners
  - d|mymodule/index.rst
  - r|README.rst

When files are specified, then only those files will be added to the SPM, regardless of what other files exist in the directory. They will also be added in the order specified, which is useful if you have a need to lay down files in a specific order.

As can be seen in the example above, you may also tag files as being a specific type. This is done by pre-pending a filename with its type, followed by a pipe (|) character. The above example contains a document file and a readme. The available file types are:

• c: config file

• d: documentation file

• g: ghost file (i.e. the file contents are not included in the package payload)

• l: license file

• r: readme file

• s: SLS file

• m: Salt module

The first 5 of these types (c, d, g, l, r) will be placed in /usr/share/salt/spm/ by default. This can be changed by setting an spm_share_dir value in your /etc/salt/spm configuration file.

The last two types (s and m) are currently ignored, but they are reserved for future use.

pre_local_state: >
  echo test > /tmp/spmtest:
    cmd:
      - run

local States¶

local states are evaluated locally; this is analogous to issuing a state run using a salt-call --local command. These commands will be issued on the local machine running the spm command, whether that machine is a master or a minion.

local states do not require any special arguments, but they must still use the > marker to denote that the state is evaluated as text, not a data structure.

pre_local_state: >
  echo test > /tmp/spmtest:
    cmd:
      - run

tgt States¶

tgt states are issued against a remote target. This is analogous to issuing a state using the salt command. As such it requires that the machine that the spm command is running on is a master.

Because tgt states require that a target be specified, their code blocks are a little different. Consider the following state:

pre_tgt_state:
  tgt: '*'
  data: >
    echo test > /tmp/spmtest:
      cmd:
        - run

With tgt states, the state data is placed under a data section, inside the *_tgt_state code block. The target is of course specified as a tgt and you may also optionally specify a tgt_type (the default is glob).

You still need to use the > marker, but this time it follows the data line, rather than the *_tgt_state line.

Templating States¶

The reason that state data must be evaluated as text rather than a data structure is because that state data is first processed through the rendering engine, as it would be with a standard state run.

This means that you can use Jinja or any other supported renderer inside of Salt. All formula variables are available to the renderer, so you can reference FORMULA data inside your state if you need to:

pre_tgt_state:
  tgt: '*'
  data: >
     echo {{ name }} > /tmp/spmtest:
      cmd:
        - run

You may also declare your own variables inside the FORMULA. If SPM doesn't recognize them then it will ignore them, so there are no restrictions on variable names, outside of avoiding reserved words.

By default the renderer is set to jinja|yaml. You may change this by changing the renderer setting in the FORMULA itself.

spm build /path/to/saltstack-formulas/apache-formula

spm remove apache