Salt States

SaltStack is a configuration management software like Ansible or Puppet which allows you to configure your machines via so-called salt states. Salt states are YAML documents with support for Jinja2 templates: 

mysql:
  pkg.installed:
    - name: mysql
  service.running:
    - name: mysql


web_server:
  pkg.installed:
{% if grains['os_family'] == 'RedHat' %}
    - name: httpd
{% elif grains['os_family'] == 'Debian' %}
    - name: apache2
{% endif %}

Note that in contrast to Ansible, salt states support Jinja2 templates in arbitrary places. In fact, the Jinja2 templates are first rendered and the resulting document is then fed into the YAML parser.

What is it all about?

A language server is a piece of software that speaks a JSON protocol (called the Language Server Protocol, abreviated LSP) to provide text editors with code completion, diagnostics, documentation, etc. There are several editors and numerous language servers already implementing this protocol.

While already two extensions providing Salt support for VSCode like the one from korekontrol for syntax hightlighting and one for linting exist, none leverages LSP for Salt's SLS files.

Since SUSE provides one week to its employees every now and then to work on any project they like, both Dan Čermák and I decided to give it a try during hackweek #20.

The hackweek outcome

The code of the started server can be found in Dan's github repo. After a week of coding the server provides:

  • Completion of salt state names with their doc extracted using the baredoc module.

completion of state name

  • Completion of include paths

completion of include path

  • Go to definition for identifiers in requisites.

Go to definition

In order to provide an accurate completion, the SLS file content is parsed using a home-brewed parser based on the PyYAML scanner. This parser creates an abstract syntax tree (AST) that makes it easy to know the context of the SLS files currently being edited.

What originally motivated us to write a parser was that the existing YAML parsers were not fault tolerant enough... and when writing an SLS file there are often states where the file is not yet a valid YAML file!

The AST will also help to provide other features like syntax highlighting or symbol details.

Note that so far only SLS file with a more or less valid YAML content are supported. This means that SLS files containing Jinja blocks or maybe even jinja {{ }} content will not be parsed properly.

What next?

Since neither Dan no I have dedicated time to contribute to this new language server, it will only progress slowly...

That being said we would welcome any pull request!

Among the main big challenges and features:

  • Parse files with Jinja2 templates
  • Enhance completion, for instance on state names or parameters
  • Implement syntax highlighting
  • Dan is currently adding support for document symbols. These allow an editor to render breadcrumbs