GitLocker: The Coding Marketplace

Description:

isalt 2021.2.2

ISalt is an IPython style console to facilitate the debugging or even
development of Salt code.

Salt code typically makes use of a number of dunder (i.e., _d_ouble
_under_score) variables such as __salt__, __opts__, __grains__,
__proxy__, or __pillar__, etc., which give you quick access to various
resources and features. They also have a different meaning depending on the
context - for example, __opts__ on the Minion side is a different object
than __opts__ on the Master side; __salt__ on the Minion side gives you
access to the list of Execution Modules, while __salt__ on the Master side
provides the Runners, and so on.
The main difficulty when working with these variables is that they only make
sense when actually running Salt and having a Master and eventually one or more
Minions running. It often happens that you don’t necessarily want to have these
services running when writing a new function (that use these dunders), or just
want to quickly debug something without pushing code to production.
With ISalt, you can easily get access to these variables, by simply executing
isalt, e.g.,
$ isalt
>>> __salt__['test.ping']()
True
>>>
>>> __grains__['osfinger']
'Ubuntu-18.04'
In other words, ISalt is an enhanced IPython console which gives you access to
the Salt global variables typically used in Salt code.

Install
ISalt is distributed via PyPI, and you can install it by executing:
$ pip install isalt
Dependencies:

salt
IPython

No specific version for either of these packages, so it doesn’t mess up with
your environment. It should normally work well with any version.

Usage
You can configure various bits of data or conditionals using one or more of the
following options, with precedence in this order: ISalt configuration file,
environment variables, and CLI arguments.
One of the most important details to keep in mind is the difference between
running the code on the Minion side, versus Master side (where we can further
distinguish between code to be executed as a Runner, vs. Execution Module for
an arbitrary Minion – for the former you may need to provide the Minion ID
using the --minion-id CLI argument).
Typically, when you install ISalt where you have a Salt Minion running, it
should be sufficient to execute just $ isalt.
When you want to use ISalt on the Master side, but to test Execution Modules,
you can run $ isalt --on-master.
When you’re looking into evaluating Runner code, you can only do this one the
Master side, therefore, you’d need to start the console as $ isalt --master.
You can check the complete list of CLI optional arguments by
$ isalt -h
usage: isalt [-h] [--saltenv SALTENV] [--pillarenv PILLARENV] [-c CFG_FILE]
[-e CFG_FILE_ENV_VAR] [--minion-cfg MINION_CFG_FILE]
[--proxy-cfg PROXY_CFG_FILE] [--master-cfg MASTER_CFG_FILE]
[--minion] [--proxytype PROXYTYPE] [--proxy] [--sproxy]
[--master] [--local] [--minion-id MINION_ID] [--on-master]

ISalt console

optional arguments:
-h, --help show this help message and exit
--saltenv SALTENV Salt environment name.
--pillarenv PILLARENV
The Salt environment name to compile the Pillar from.
-c CFG_FILE, --cfg-file CFG_FILE
The absolute path to the ISalt config file.
-e CFG_FILE_ENV_VAR, --env-var CFG_FILE_ENV_VAR
The name of the environment variable pointing to the
ISalt config file.
--minion-cfg MINION_CFG_FILE
The absolute path to the Minion config file.
--proxy-cfg PROXY_CFG_FILE
The absolute path to the Proxy Minion config file.
--master-cfg MASTER_CFG_FILE
The absolute path to the Master config file.
--minion Prepare the Salt dunders for the Minion.
--proxy Prepare the Salt dunders for the Proxy Minion.
--sproxy Prepare the Salt dunders for the salt-sproxy (Master
side).
--master Prepare the Salt dunders for the Master.
--local Override the Minion config and use the local client.
This option loads the file roots config from the
Master file.
--minion-id MINION_ID
The Minion ID to compile the Salt dunders for. This
argument is optional, however it may fail when ISalt
is not able to determine the Minion ID, or take it
from the environment variable, etc.
--on-minion Whether should compile the dunders for the Minion
side, starting the ISalt console on the Minion
machine. The main difference is that the Pillar and
Grains are compiled locally, while when using --on-
master, it's using the local cached data.
--on-master Whether should compile the dunders for the Minion
side, starting the ISalt console on the Master
machine. This option is ignored when used in
conjunction with --master.

Usage Examples

Using ISalt on the Master
Start with isalt --master. Remember that the __salt__ dunder currently
maps to the Runner functions, and not to the execution modules.
$ isalt --master

In [1]: # execute the ``test.sleep`` Runner:

In [2]: # https://docs.saltstack.com/en/latest/ref/runners/all/salt.runners.test.html#module-salt.runners.test

In [3]: __salt__['test.sleep'](1)
1
Out[3]: True

Using ISalt on the Master, loading the (Proxy) Minion dunders
In this mode, you need to specify the Minion ID to use and collect and compile
data for (otherwise it’ll use local machine’s hostname):
$ isalt --on-master --minion-id jerry

Note
You can equally specify the Minion ID in the proxy/minion configuration
file, from --minion-cfg or --proxy-cfg options.

For Proxy Minions, you have to pass the --proxy CLI argument, e.g.,
$ isalt --on-master --minion-id edge-router --proxy
For Proxy Minions, in order to load the __salt__ modules correctly, you may
have to provide the proxytype as well into the Proxy configuration file (by
default at /etc/salt/proxy, or a different path set using the
--proxy-cfg arg) - or using the --proxytype CLI argument, e.g.,
/etc/salt/proxy
proxy:
proxytype: napalm
And execute as isalt --on-master --proxy --minion-id jerry.
Or directly as isalt --on-master --proxytype napalm --minion-id jerry.

Using ISalt on the (Proxy) Minion
This is the default ISalt mode, and you no longer have to provide the Minion
ID, as it’s collected from local machine, unless you want to use a specific
one. As always, you can have the Minion ID in the Proxy / Minion configuration
file, the ISALT_MINION_ID environment variable, or the ISalt configuration
file (as the minion_id option).
Example:
$ echo $ISALT_MINION_ID
jerry
$ isalt

In [1]: __opts__['id']
Out[1]: 'jerry'

Note
The local Proxy / Minion key must be accepted by the Master. To avoid
connecting to the Master, you can use the --local argument to start the
Minion in Masterless
mode - you will however need to make sure that you point to the file (and
pillar) roots you need as those won’t be pulled from the Master.
One good way to deal with this is pointing the file_roots option to the
cache directory of the production Minion. For example, you have a Minion
that is pulling the production files from the Master, and caching them
under /var/cache/salt/minion/files/base (whatever would be your
filesystem backend). Now, to use these files when starting ISalt in local
mode, you can reference that dir as:
/etc/salt/minion (excerpt)
file_roots:
base:
- /var/cache/salt/minion/files/base
Now, starting with isalt --local, you still load your modules, states,
and other files without connecting to the Master.

Using ISalt in conjunction with Salt Super Proxy (Master side)

Note
This option requires salt-sproxy to be installed in the same environment as
ISalt: pip install salt-sproxy. For simplicity, you can, for example,
install as: pip install isalt[sproxy].

Usage example:
$ isalt --sproxy
In this interactive console, you have access to the usual Salt Master dunders,
as well as the salt-sproxy features. As a shortcut, you have access to the
salt-sproxy core function, through the sproxy global variable:
>>> sproxy
<function execute at 0x7fd394075510>
>>> sproxy('*', preview_target=True)
['router1',
'router2']
In a similar way, this facilitates the execution of any Salt function through
salt-sproxy, e.g.,
>>> sproxy('router1', function='test.ping', static=True)
{'router1': True}
>>>

Tip
For best results using salt-sproxy, it is recommended to pass the
static=True argument.

You can also get into the sproxy mode by default, by setting the value
role: sproxy into the ISalt configuration file (see also the next
paragraph).

Important
Check also the salt-sproxy documentation for more usage
instructions and examples.

ISalt configuration file
Every of the options presented above are available through the ISalt
configuration file, by default /etc/salt/isalt. To read the file from
a specific path, use the -c / --cfg-file args, e.g.,
$ isalt -c /path/to/isalt/config/file
Or, alternative, using the ISALT_CFG_FILE environment variable, e.g.,
$ echo $ISALT_CFG_FILE
/path/to/isalt/config/file
$ isalt
Even more, if you want to read the path to the config file from a different
environment variable, use the -e / --env-var arg:
$ echo $ALTERNATIVE_ISALT_CFG_FILE
/path/to/another/isalt/config/file
$ isalt -e ALTERNATIVE_ISALT_CFG_FILE

ISalt configuration file example
on_master: true
proxytype: dummy
proxy_cfg: /path/to/proxy/config
minion_cfg: /path/to/minion/config
master_cfg: /path/to/master/config
With the configuration file above, you can simplify the CLI usage, e.g., from
isalt --on-master --proxy-cfg /path/to/proxy/config --proxytype dummy --minion-id jerry to just isalt --minion-id jerry, etc.

Environment Variables

ISALT_CFG_FILE
Absolute path to the ISalt configuration file.

ISALT_ROLE
The Salt system role. Choose between: master, minion, or proxy.

ISALT_ON_MASTER
If you’re running ISalt on the Master.

ISALT_MINION_ID
The Minion ID to use.

ISALT_PROXYTYPE
The Proxy Minion module name to use.

ISALT_MASTER_CONFIG
Absolute path to the Master configuration file.

ISALT_MINION_CONFIG
Absolute path to the Minion configuration file.

ISALT_PROXY_MINION_CONFIG
Absolute path to the Proxy Minion configuration file.

ISALT_USE_CACHED_PILLAR
When starting in Proxy / Minion mode, on the Master: whether to use the
cached Pillars that may be already available for the specified Minion,
or compile fresh data.