Text editor plugins for Salt states and YAML/Jinja

12 minute read Updated:

YAML Ruler

Image by Justin Palmer

If you have ever written a couple of Salt states, these problems may sound familiar:

And even if your states are valid YAML, they still can have no sense for Salt because your wathc_in requisite has a typo. Sprinkle a few Jinja tags here and there, and the errors can get even fancier…

Is there anything that could be done?

These issues definitely have come up before (#802). Smart developers probably have this figured out, right?

Indeed, it is possible to validate your states, in a semi- or completely automated way, even before they touch your infrastructure. For Salt, you have the following options:

  1. Use the salt-call --local --retcode-passthrough state.show_sls YOUR_STATE either manually or using a commit hook. This triggers the state rendering process and can catch tons of possible errors.

  2. Test your states using Test Kitchen together with kitchen-salt and some verifier. A helpful guide on this topic is available here.

However, all of this feels a bit heavy. You need to commit and push to run your tests, spin up VMs or containers, dive into Ruby code, and write tests for all possible pillar/grain permutations. Such a long feedback cycle could easily lead to git commit -m "Fuck YAML" in your commit history and a subsequent amend/rebase/squash dance (and you can’t squash the obscene commit notifications sent to the rest of your team!).

Is there something more lightweight?

Well, your development environment can help you. The first layer of defense can work right in your text editor as you type, providing immediate feedback. It will catch your typos before they get committed and deployed (and let the CI system deal with more complicated stuff). An ideal editor plugin can:

Below I’ll cover plugins for 9 different editors, so you do not have to switch away from your favorite one. Also, I will give a few installation/configuration tips to save you some googling. These plugins aren’t ideal, but they are open source, and you can contribute to any of them if you want (I did).

If your favorite editor is not covered here, or you want to share a nifty hack that helps you reduce the number of YAML mistakes, ping me on Twitter.

Atom

SaltStack package for Atom

Out of the box, Atom understands *.sls files as YAML. Plus, you could install atom-jinja2 and manually switch a file grammar to YAML (Jinja Templates) by pressing Ctrl+Shift+L.

For better results, you can install both atom-salt and atom-jinja2. Just click Edit -> Preferences -> Install, search for atom-salt or atom-jinja and install them.

Features

You can assign specific language scope to any extension with something like this in your ~/.atom/config.cson:

"*":
  core:
    customFileTypes:
      "source.python.salt": [
        "py.sls"
        "pysls"
      ]

Other things to try

Eclipse

SaltStack plugin for Eclipse

I was unable to find a good enough solution for Eclipse, but below are two directions you can try to explore:

  1. Go to Help -> Eclipse Marketplace, search for “yedit” and install it. Then go to Window -> Preferences -> General -> Editors -> File Associations and associate the *.sls extension with YEdit. This enables syntax highlighting for plain YAML files (no luck with Jinja though).

  2. Another plugin is called LiClipseText. It has support for both YAML and Jinja syntaxes, but can’t enable them simultaneously for a single file. It should be possible though, and there are some hints if you want to contribute.

Indentation guides are available via a separate indent-guide plugin.

To browse offline docs using Dash you can try DashLookup.

Emacs

SaltStack mode for Emacs

Salt-mode is your best bet. It is based on yaml-mode and mmm-mode and is automatically enabled for *.sls files. The simplest way to install is through MELPA.

Features

Things to be aware of

Other things to try

(mmm-add-mode-ext-class nil "\\.jinja\\'" 'jinja2)

Kate

SaltStack syntax highlighter for Kate

Kate-jinja2-highlighting has a bunch of syntax highlighters for different file types with Jinja on top.

Features

To install it, copy the *.xml files into the ~/.local/share/org.kde.syntax-highlighting/syntax/ folder. Then go to Settings -> Configure Kate -> Editor Component -> Open/Save -> Modes & Filetypes, select Markup/Jinja2/YAML, open the Variables drop-down, and then set both indent-width tab-width to 2 and Indent using to Spaces.

You also need to associate *.sls files with the syntax highlighter:

sed -i'' -e 's/\(\*\.yml\)"/\1;*.sls"/' yaml-jinja2.xml

The sed command above is equivalent to the patch below:

--- yaml-jinja2.xml.orig	2018-10-25 02:39:31.000000000 +0700
+++ yaml-jinja2.xml	2018-10-25 02:39:40.000000000 +0700
@@ -3,7 +3,7 @@
 <!-- Author: Dr Orlovsky MA <maxim@orlovsky.info> //-->
 <!-- Autogenerated from yaml.xml -->
 <language name="Jinja2/YAML" version="1.2" kateversion="2.3" section="Markup"
-          extensions="*.yaml;*.yml" mimetype="text/yaml"
+          extensions="*.yaml;*.yml;*.sls" mimetype="text/yaml"
           author="Dr Orlovsky MA (dr.orlovsky@gmail.com)" license="LGPL">
   <highlighting>
     <contexts>

To browse offline docs using Zeal you can try ZealSearch.

Midnight Commander

SaltStack syntax highlighter for Midnight Commander

Midnight Commander is an oldie but goodie for those of us who used orthodox file managers back in the 90’s and can’t live without one. Personally, I use it to quickly navigate the filesystem tree and view the files without opening them in my primary editor. According to this ticket, out of the box, mcedit highlights *.yml and *.yaml files and understands simple Jinja variables (no support for tags though). Also, it does not understand *.jinja files.

To enable *.sls highlighting you need to make a copy of the default Syntax file and tweak it a bit:

mkdir -p ~/.config/mc/mcedit
sed -e 's/\(|YML)\)/|sls\1/' /usr/share/mc/syntax/Syntax > ~/.config/mc/mcedit/Syntax

The sed command above is equivalent to the patch below:

--- /home/user/.config/mc/mcedit/Syntax.orig 2017-08-05 04:03:29.000000000 +0700
+++ /home/user/.config/mc/mcedit/Syntax	2018-10-10 19:50:11.390542735 +0700
@@ -271,7 +271,7 @@
 file ..\*\\.cl$ OpenCL\sProgram
 include opencl.syntax
 
-file ..\*\\.(ya?ml|YML)$ YAML\sFile
+file ..\*\\.(ya?ml|sls|YML)$ YAML\sFile
 include yaml.syntax
 
 file .\*\\.osl$ OSL\sProgram

PyCharm

SaltStack support in PyCharm

Well, it looks there are no Salt-specific plugins for PyCharm. Ansible users are luckier here - PyCharm has support for JSON Schemas, and someone from RedHat has created one. This means code auto-completion for Ansible-specific YAML data structures right out of the box! Plus, there is a separate YAML/Ansible plugin (GitHub).

However (aside from using Ansible plugins), you can tweak PyCharm to make it work with Salt states. Click File -> Settings -> Languages & Frameworks -> Python Template Languages, select Jinja2 in the Template language drop-down, click the “+” button and select YAML. This should enable syntax highlighting for YAML+Jinja combo. To associate it with the *.sls files, go to File -> Settings -> Editor -> File Types, find YAML and add the *.sls extension.

Other features

To browse offline docs using Dash, Zeal, or Velocity you can try Dash.

Sublime Text

SaltStack plugin for Sublime Text

The extension is available on GitHub. To install it click Preferences -> Package Control -> Install Package, search for saltstack and click to install. It is also recommended to install the separate extension for Jinja (go to Package Control and search for jinja2).

Features

Indentation guides are enabled by default, but you may also want to set "indent_guide_options": ["draw_normal", "draw_active"] in the settings to highlight currently active guide.

To browse offline docs using Dash, Zeal, or Velocity you can try DashDoc or Zeal for Sublime Text.

Vim

SaltStack plugin for Vim

You need both salt-vim and vim-jinja2-syntax.

Features

NOTE: the plugin is not maintained and the repo was archived by VMware.

If you are using Vim 8 or higher, you may skip the Pathogen/Vundle route and install the plugins directly:

mkdir -p ~/.vim/pack/plugins/start
cd !$
git clone https://github.com/vmware-archive/salt-vim.git salt.vim
git clone https://github.com/Glench/Vim-Jinja2-Syntax.git jinja2.vim

Then add the following lines to your .vimrc:

syntax on
set nocompatible
set modeline
filetype plugin indent on
let g:sls_use_jinja_syntax = 1

In addition to that, there are multiple ways to highlight the vertical or horizontal line at the cursor’s position. The simplest option is to use set: cursorcolumn. You might also consider vim-indentguides, vim-indent-guides or indentLine . Some folks use crosshair highlighting.

To browse offline docs using Dash or Zeal you can try dash.vim, Zeavim or nvim-telescope-zeal.

Visual Studio Code

SaltStack extension for Visual Studio Code

The VSCode extension for SaltStack is available on the Marketplace. To install it click File -> Preferences -> Extensions, then search for saltstack and click install. The source code is available on GitHub

Features

So far it looks like the plugin has the most comprehensive Salt autocompletion feature amongst other editors:

VSCode SaltStack autocompletion

Screenshot by Christian McHugh

If you get annoyed by an extra closing bracket added by autocompletion {%%}}, add the following snippet to your settings.json file (File -> Preferences -> Settings, then press the {} icon to open User Settings):

"[sls]": { "editor.autoClosingBrackets": "never" }

There is also a companion saltstack-extension-pack that bundles this extension with salt-lint.

Another plugin is named jinjahtml-vscode and can recognize *.yml.j2, *.yaml.j2 and *.sls files.

To browse offline docs using Dash, Zeal, or Velocity you can try Visual Studio Code Dash.

Final tips

For teams

If you have a team of engineers who regularly contribute to a common Salt state tree, it is essential to establish some YAML/Jinja style conventions.

You could add the following boilerplate to each state file, but it is easy to forget and requires some discipline:

# -*- coding: utf-8; mode: salt; -*-
# vim: ft=sls

Alternatively, you could ask engineers to set up their editors properly. Or you can adopt http://editorconfig.org/ - just create a .editorconfig in your project root, and any compatible editor will automatically pick up your coding convention.

Also, it makes sense to add .jinja or .j2 suffix to all config templates managed by Salt, to help most editors recognize the syntax.

YAML docs

Jinja docs

Online parsers/linters

These could be helpful if you don’t want to or can’t use any editor plugins:

Also, YAML is a superset of JSON, so you could just use square brackets for lists and curly ones for dictionaries:

/etc/http/conf/http.conf:
  file.managed:
    - source: salt://apache/http.conf
    - mode: 644
    - template: jinja
    - context: { custom_var: "override" }
    - defaults: { custom_var: "default value", other_var: 123 }

Language Server Protocol implementation

In April 2021 an LSP for Salt state files was implemented during SUSE hackweek. A short list of supported features:

Parsing Jinja blocks (as well as Mako, Py, and other renderers) is not supported. You can find the server source code at https://github.com/dcermak/salt-lsp.

Also, you can follow me on Twitter where I periodically post things like this:

SaltTips tweet