Package: isalt
ISalt is an IPython style console to facilitate the debugging or even
development of Salt code.Salt code typically makes use of a number ofdunder(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 executingisalt, 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.InstallISalt is distributed via PyPI, and you can install it by executing:$pipinstallisaltDependencies:saltIPythonNo specific version for either of these packages, so it doesn’t mess up with
your environment. It should normally work well with any version.UsageYou 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-idCLI 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-husage:isalt[-h][--saltenvSALTENV][--pillarenvPILLARENV][-cCFG_FILE][-eCFG_FILE_ENV_VAR][--minion-cfgMINION_CFG_FILE][--proxy-cfgPROXY_CFG_FILE][--master-cfgMASTER_CFG_FILE][--minion][--proxytypePROXYTYPE][--proxy][--sproxy][--master][--local][--minion-idMINION_ID][--on-master]ISaltconsoleoptionalarguments:-h,--helpshowthishelpmessageandexit--saltenvSALTENVSaltenvironmentname.--pillarenvPILLARENVTheSaltenvironmentnametocompilethePillarfrom.-cCFG_FILE,--cfg-fileCFG_FILETheabsolutepathtotheISaltconfigfile.-eCFG_FILE_ENV_VAR,--env-varCFG_FILE_ENV_VARThenameoftheenvironmentvariablepointingtotheISaltconfigfile.--minion-cfgMINION_CFG_FILETheabsolutepathtotheMinionconfigfile.--proxy-cfgPROXY_CFG_FILETheabsolutepathtotheProxyMinionconfigfile.--master-cfgMASTER_CFG_FILETheabsolutepathtotheMasterconfigfile.--minionPreparetheSaltdundersfortheMinion.--proxyPreparetheSaltdundersfortheProxyMinion.--sproxyPreparetheSaltdundersforthesalt-sproxy(Masterside).--masterPreparetheSaltdundersfortheMaster.--localOverridetheMinionconfigandusethelocalclient.ThisoptionloadsthefilerootsconfigfromtheMasterfile.--minion-idMINION_IDTheMinionIDtocompiletheSaltdundersfor.Thisargumentisoptional,howeveritmayfailwhenISaltisnotabletodeterminetheMinionID,ortakeitfromtheenvironmentvariable,etc.--on-minionWhethershouldcompilethedundersfortheMinionside,startingtheISaltconsoleontheMinionmachine.ThemaindifferenceisthatthePillarandGrainsarecompiledlocally,whilewhenusing--on-master,it'susingthelocalcacheddata.--on-masterWhethershouldcompilethedundersfortheMinionside,startingtheISaltconsoleontheMastermachine.Thisoptionisignoredwhenusedinconjunctionwith--master.Usage ExamplesUsing ISalt on the MasterStart withisalt--master. Remember that the__salt__dunder currently
maps to the Runner functions, and not to the execution modules.$isalt--masterIn[1]:# execute the ``test.sleep`` Runner:In[2]:# https://docs.saltstack.com/en/latest/ref/runners/all/salt.runners.test.html#module-salt.runners.testIn[3]:__salt__['test.sleep'](1)1Out[3]:TrueUsing ISalt on the Master, loading the (Proxy) Minion dundersIn 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-idjerryNoteYou can equally specify the Minion ID in the proxy/minion configuration
file, from--minion-cfgor--proxy-cfgoptions.For Proxy Minions, you have to pass the--proxyCLI argument, e.g.,$isalt--on-master--minion-idedge-router--proxyFor Proxy Minions, in order to load the__salt__modules correctly, you may
have to provide theproxytypeas well into the Proxy configuration file (by
default at/etc/salt/proxy, or a different path set using the--proxy-cfgarg) - or using the--proxytypeCLI argument, e.g.,/etc/salt/proxyproxy:proxytype:napalmAnd execute asisalt--on-master--proxy--minion-idjerry.Or directly asisalt--on-master--proxytypenapalm--minion-idjerry.Using ISalt on the (Proxy) MinionThis 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, theISALT_MINION_IDenvironment variable, or the ISalt configuration
file (as theminion_idoption).Example:$echo$ISALT_MINION_IDjerry$isaltIn[1]:__opts__['id']Out[1]:'jerry'NoteThe local Proxy / Minion key must be accepted by the Master. To avoid
connecting to the Master, you can use the--localargument to start the
Minion inMasterlessmode - 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 thefile_rootsoption 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/baseNow, starting withisalt--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)NoteThis option requires salt-sproxy to be installed in the same environment as
ISalt:pip installsalt-sproxy. For simplicity, you can, for example,
install as:pip install isalt[sproxy].Usage example:$isalt--sproxyIn 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 thesproxyglobal variable:>>>sproxy<functionexecuteat0x7fd394075510>>>>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}>>>TipFor best results using salt-sproxy, it is recommended to pass thestatic=Trueargument.You can also get into thesproxymode by default, by setting the valuerole: sproxyinto the ISalt configuration file (see also the next
paragraph).ImportantCheck also thesalt-sproxy documentationfor more usage
instructions and examples.ISalt configuration fileEvery 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-fileargs, e.g.,$isalt-c/path/to/isalt/config/fileOr, alternative, using theISALT_CFG_FILEenvironment variable, e.g.,$echo$ISALT_CFG_FILE/path/to/isalt/config/file$isaltEven more, if you want to read the path to the config file from a different
environment variable, use the-e/--env-vararg:$echo$ALTERNATIVE_ISALT_CFG_FILE/path/to/another/isalt/config/file$isalt-eALTERNATIVE_ISALT_CFG_FILEISalt configuration file exampleon_master:trueproxytype:dummyproxy_cfg:/path/to/proxy/configminion_cfg:/path/to/minion/configmaster_cfg:/path/to/master/configWith the configuration file above, you can simplify the CLI usage, e.g., fromisalt--on-master--proxy-cfg/path/to/proxy/config--proxytypedummy--minion-idjerryto justisalt--minion-idjerry, etc.Environment VariablesISALT_CFG_FILEAbsolute path to the ISalt configuration file.ISALT_ROLEThe Salt system role. Choose between:master,minion, orproxy.ISALT_ON_MASTERIf you’re running ISalt on the Master.ISALT_MINION_IDThe Minion ID to use.ISALT_PROXYTYPEThe Proxy Minion module name to use.ISALT_MASTER_CONFIGAbsolute path to the Master configuration file.ISALT_MINION_CONFIGAbsolute path to the Minion configuration file.ISALT_PROXY_MINION_CONFIGAbsolute path to the Proxy Minion configuration file.ISALT_USE_CACHED_PILLARWhen 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.