You are viewing docs from the master branch, some of these features are not yet released.

Thorium Complex Reactor¶

The original Salt Reactor is based on the idea of listening for a specific event and then reacting to it. This model comes with many logical limitations, for instance it is very difficult (and hacky) to fire a reaction based on aggregate data or based on multiple events.

The Thorium reactor is intended to alleviate this problem in a very elegant way. Instead of using extensive jinja routines or complex python sls files the aggregation of data and the determination of what should run becomes isolated to the sls data logic, makes the definitions much cleaner.

Starting the Thorium Engine¶

To enable the thorium engine add the following configuration to the engines section of your Salt Master or Minion configuration file and restart the daemon:

engines:
  - thorium: {}

Thorium Modules¶

Because of its specialized nature, Thorium uses its own set of modules. However, many of these modules are designed to wrap the more commonly-used Salt subsystems. These modules are:

local: Execution modules
runner: Runner modules
wheel: Wheel modules

There are other modules that ship with Thorium as well. Some of these will be highlighted later in this document.

Writing Thorium Formulas¶

Like some other Salt subsystems, Thorium uses its own directory structure. The default location for this structure is /srv/thorium/, but it can be changed using the thorium_roots setting in the master configuration file.

This would explicitly set the roots to the default:

thorium_roots:
  base:
    - /srv/thorium

Example thorium_roots configuration:

thorium_roots:
  base:
    - /etc/salt/thorium

It is also possible to use gitfs with Thorium, using the thoriumenv or thorium_top settings.

Example using thorium_top:

thorium_top: salt://thorium/top.sls
gitfs_provider: pygit2

gitfs_remotes:
  - git@github.com:user/repo.git:
    - name: salt-backend
    - root: salt
    - base: master
  - git@github.com:user/repo.git:
    - name: thorium-backend
    - root: thorium
    - base: master
    - mountpoint: salt://thorium

Note

When using this method don't forget to prepend the mountpoint to files served by this repo, for example top.sls:

base:
  '*':
    - thorium.key_clean

Example using thoriumenv:

thoriumenv: thorium
gitfs_provider: pygit2

gitfs_remotes:
  - git@github.com:user/repo.git:
    - name: salt-backend
    - root: salt
    - base: master
  - git@github.com:user/repo.git:
    - name: thorium-backend
    - root: thorium
    - saltenv:
      - thorium:
        - ref: master

Note

When using this method all state will run under the defined environment, for example top.sls:

thorium:
  '*':
    - key_clean

The Thorium top.sls File¶

Thorium uses its own top.sls file, which follows the same convention as is found in /srv/salt/:

<srv>:
  <target>:
    - <formula 1>
    - <formula 2>
    - <etc...>

For instance, a top.sls using a standard base environment and a single Thorium formula called key_clean, would look like:

base:
  '*':
    - key_clean

Take note that the target in a Thorium top.sls is not used; it only exists to follow the same convention as other top.sls files. Leave this set to '*' in your own Thorium top.sls.

Thorium Formula Files¶

Thorium SLS files are processed by the same state compiler that processes Salt state files. This means that features like requisites, templates, and so on are available.

Let's take a look at an example, and then discuss each component of it. This formula uses Thorium to detect when a minion has disappeared and then deletes the key from the master when the minion has been gone for 60 seconds:

statreg:
  status.reg

keydel:
  key.timeout:
    - delete: 60
    - require:
      - status: statreg

There are two stanzas in this formula, whose IDs are statreg and keydel. The first stanza, statreg, tells Thorium to keep track of minion status beacons in its register. We'll talk more about the register in a moment.

The second stanza, keydel, is the one that does the real work. It uses the key module to apply an expiration (using the timeout function) to a minion. Because delete is set to 60, this is a 60 second expiration. If a minion does not check in at least once every 60 seconds, its key will be deleted from the master. This particular function also allows you to use reject instead of delete, allowing for a minion to be rejected instead of deleted if it does not check in within the specified time period.

There is also a require requisite in this stanza. It states that the key.timeout function will not be called unless the status.reg function in the statreg codeblock has been successfully called first.

Thorium Links to Beacons¶

The above example was added in the 2016.11.0 release of Salt and makes use of the status beacon also added in the 2016.11.0 release. For the above Thorium state to function properly you will also need to enable the status beacon in the minion configuration file:

beacons:
  status:
    - interval: 10

This will cause the minion to use the status beacon to check in with the master every 10 seconds.

The Thorium Register¶

In order to keep track of information, Thorium uses an in-memory register (or rather, collection of registers) on the master. These registers are only populated when told to by a formula, and they normally will be erased when the master is restarted. It is possible to persist the registers to disk, but we'll get to that in a moment.

The example above uses status.reg to populate a register for you, which is automatically used by the key.timeout function. However, you can set your own register values as well, using the reg module.

Because Thorium watches the event bus, the reg module is designed to look for user-specified tags, and then extract data from the payload of events that match those tags. For instance, the following stanza will look for an event with a tag of my/custom/event:

foo:
  reg.list:
    - add: bar
    - match: my/custom/event

When such an event is found, the data found in the payload dictionary key of bar will be stored in a register called foo. This register will store that data in a list. You may also use reg.set to add data to a set() instead.

If you would like to see a copy of the register as it is stored in memory, you can use the file.save function:

myreg:
  file.save

In this case, each time the register is updated, a copy will be saved in JSON format at /var/cache/salt/master/thorium/saves/myreg. If you would like to see when particular events are added to a list-type register, you may add a stamp option to reg.list (but not reg.set). With the above two stanzas put together, this would look like:

foo:
  reg.list:
    - add: bar
    - match: my/custom/event
    - stamp: True

myreg:
  file.save

If you would like to only keep a certain number of the most recent register entries, you may also add a prune option to reg.list (but not reg.set):

foo:
  reg.list:
    - add: bar
    - match: my/custom/event
    - stamp: True
    - prune: 50

This example will only keep the 50 most recent entries in the foo register.

Using Register Data¶

Putting data in a register is useless if you don't do anything with it. The check module is designed to examine register data and determine whether it matches the given parameters. For instance, the check.contains function will return True if the given value is contained in the specified register:

foo:
  reg.list:
    - add: bar
    - match: my/custom/event
    - stamp: True
    - prune: 50
  check.contains:
    - value: somedata

Used with a require requisite, we can call one of the wrapper modules and perform an operation. For example:

shell_test:
  local.cmd:
    - tgt: dufresne
    - func: cmd.run
    - arg:
      - echo 'thorium success' > /tmp/thorium.txt
    - require:
      - check: foo

This stanza will only run if the check.contains function under the foo ID returns true (meaning the match was found).

There are a number of other functions in the check module which use different means of comparing values:

gt: Check whether the register entry is greater than the given value
gte: Check whether the register entry is greater than or equal to the given value
lt: Check whether the register entry is less than the given value
lte: Check whether the register entry is less than or equal to the given value
eq: Check whether the register entry is equal to the given value
ne: Check whether the register entry is not equal to the given value

There is also a function called check.event which does not examine the register. Instead, it looks directly at an event as it is coming in on the event bus, and returns True if that event's tag matches. For example:

salt/foo/*/bar:
  check.event

run_remote_ex:
  local.cmd:
    - tgt: '*'
    - func: test.version
    - require:
      - check: salt/foo/*/bar

This formula will look for an event whose tag is salt/foo/<anything>/bar and if it comes in, issue a test.version to all minions.

Register Persistence¶

It is possible to persist the register data to disk when a master is stopped gracefully, and reload it from disk when the master starts up again. This functionality is provided by the returner subsystem, and is enabled whenever any returner containing a load_reg and a save_reg function is used.