Saltstack debugging in vscode

Intro

The Saltstack remote execution and configuration management system is written in python, and setting up a development environment to extend it for your own needs is a pretty simple task. You might wish to extend salt with a custom execution module, state, engine, or to fix a bug. In all those cases, you could log debug output to verify your code, but it’s also not difficult to configure salt to be run through vscode’s debugger granting better introspection.

Virtualenv Setup

Follow the existing documentation on https://docs.saltstack.com/en/latest/topics/development/hacking.html. This will guide you through creating a python virtualenv, installing salt’s dependencies, as well as checking out salt’s git repository. By the end of the walkthrough, you should have a clone of the salt git repo and a virtualenv configured with salt’s dependencies. 

Quick command summary:

git clone https://github.com/saltstack/salt
virtualenv /path/to/your/virtualenv
source /path/to/your/virtualenv/bin/activate
pip install pyzmq PyYAML pycrypto msgpack-python jinja2 psutil futures tornado

pip install -e ./salt # the path to the salt git clone from above

Continue following the document to configure your salt master and minion to be run from your git checkout. This will allow you to test your edits on an actual salt environment. 

Test Suite

Once you have your shiny custom functionality, you may wish to test that it doesn’t break over time or that your edits didn’t break features others rely on. To do this you should write tests in salt’s test suite as documented on https://docs.saltstack.com/en/latest/topics/development/tests/index.html. 

Quick (Debian/Ubuntu) command summary:

pip install -r requirements/dev_python34.txt
apt install build-essential python-dev

pip install -r requirements/zeromq.txt

Read over the documentation for specifics, but once everything is setup you can run individual test files with

python tests/runtests.py -n unit.modules.test_pip

Or run a specific test with

python tests/runtests.py -n unit.modules.test_pip.PipTestCase.test_install_multiple_editable

VSCode

Now that you have your salt environment ready to go, you can make your changes in vscode and debug with a launch.json configuration for the feature you’re testing. This example is debugging a session of

sudo salt-call saltcheck.run_highstate_tests

launch.json

{
 "name": "salt-call saltcheck.run_highstate_tests",
 "type": "python",
 "request": "launch",
 "program": "/path/to/git/clone/of/salt/scripts/salt-call",
 "console": "integratedTerminal",
 "args": [
   "saltcheck.run_highstate_tests"
 ],
 "sudo": true

}

When needing a salt-master for the minion to connect to, you can launch a salt-master process in a new vscode terminal tab with 

source /path/to/virtualenv/salt/bin/activate

sudo PATH="$PATH" scripts/salt-master

Now you can run your debugging session by selecting it from the debug runner, as that's all there is to it! Since this is in vscode, you have all the power of it’s debugger available as well as the ability to run all of this through WSL or a remote ssh session.