The great Salt module migration

5 minute read Updated:

In Salt 3008 Argon, many states and modules that you might be currently using will be gone:

(I will update the underlying data once in a while, but not forever)

In Salt 3008 Argon, many states and modules that you might be currently using will be gone. What could you do if you want to continue using them?

Salt extensions history

Have no idea what Salt extensions are? Roughly speaking, an extension is a Python package containing various kinds of Salt modules that can be installed via salt-pip or pip.installed. Below is a little bit of historical context:

What can you do about it?

Disable Salt auto updates

It is a good idea to disable automatic Salt master and minion package updates. You do not want them to update to 3008 on their own without your approval.

Inspect your Salt state tree

You can get a rough list of used state modules (assuming they are included in the top.sls file) using the following one-liner:

salt minion1 state.show_lowstate --out json | jq -r '.[][].state' | sort -u

If that is too cryptic and cumbersome to remember, install the TSL module by running sudo salt-pip install saltext.tsl on a minion and then try the following command on your state tree:

sudo salt-call tsl.states

To see which SLS files use a particular state function, run another command:

sudo salt-call tsl.state file.managed

Identify other kinds of modules you use

That could be: execution modules (often called via Jinja or CLI), external pillar, grains, cloud, beacons, engines, runners, sdb, returners, executors, fileservers, proxy, serializers, renderers, outputters, roster, etc. This could be done by inspecting master and minion config files, your runbooks, shell scripts, etc.

Identify which modules were moved to extensions

You can do that using the search box, and it will show the corresponding Salt extensions if they exist. Alternatively, skim through the great module purge PR and look for the corresponding extensions in the salt-extensions community org.

Start testing Salt 3008

You can try the nightly builds or wait till 3008 Release Candidate. To install an extension into a Salt Master or Minion onedir environment, use salt-pip or pip.installed.

If an extension does not exist

The quick and dirty way is to grab a removed module from the holding repository, drop it into your Salt state tree (into _modules, _states, etc.) and sync via saltutil.sync_all. But this method is not a long-term solution.

A better way is to convert a module (or a set of related modules) into a Salt extension:

  1. Watch the Salt Extension Overview video
  2. Check out the Create and Maintain Salt Extensions Guide created by Salt Community members.
  3. Create and publish your extension using the salt-extension-copier template (the original salt-extension template mentioned in the overview video is deprecated)
  4. It is highly advised to publish your extension repository under the salt-extensions umbrella for better discoverability
  5. Join the #salt-extensions Discord channel if you want to discuss something first or have any questions. There are also regular Salt Extensions WG meetings (*.ics link) you can attend.

An extra tip (follow @SaltTips for more):

See also: