salt-lint 0.1.0

A command-line utility that checks for best practices in SaltStack.

Salt-lint

salt-lint checks Salt State files (SLS) for practices and behavior that could potentially be improved.

The project is heavily based on ansible-lint, which was created by Will Thames and is now maintained as part of the Ansible by Red Hat project.

Installing

Using Pip

pip install salt-lint

From Source

pip install git+https://github.com/warpnet/salt-lint.git

Usage

Command Line Options

The following is the output from salt-lint --help, providing an overview of the basic command line options:

Usage: salt-lint [options] init.sls [state ...]

Options:
  --version             show program's version number and exit
  -h, --help            show this help message and exit
  -L                    list all the rules
  -r RULESDIR           specify one or more rules directories using one or
                        more -r arguments. Any -r flags override the default
                        rules in /path/to/salt-lint/saltlint/rules, unless 
                        -R is also used.
  -R                    Use default rules in
                        /path/to/salt-lint/saltlint/rules in addition to any
                        extra rules directories specified with -r. There is
                        no need to specify this if no -r flags are used.
  -t TAGS               only check rules whose id/tags match these values
  -T                    list all the tags
  -v                    Increase verbosity level
  -x SKIP_LIST          only check rules whose id/tags do not match these
                        values
  --nocolor             disable colored output
  --force-color         Try force colored output (relying on salt's code)
  --exclude=EXCLUDE_PATHS
                        path to directories or files to skip. This option is
                        repeatable.
  --json                parse the output as JSON
  -c C                  Specify configuration file to use.  Defaults to
                        ".salt-lint"

Linting Salt State files

It's important to note that salt-lint accepts a list of Salt State files or a list of directories.

GitHub Action

Salt-lint is available on the GitHub marketplace as a GitHub Action. The salt-lint-action allows you to run salt-lint with no additional options.

To use the action simply add the following lines to your .github/workflows/main.yml.

on: [push]

jobs:
  test:
    runs-on: ubuntu-latest
    name: Salt Lint Action
    steps:
    - uses: actions/checkout@v1
    - name: Run salt-lint
      uses: roaldnefs/salt-lint-action@master
      env:
        ACTION_STATE_NAME: init.sls

Configuring

Configuration File

Salt-lint supports local configuration via a .salt-lint configuration file. Salt-lint checks the working directory for the presence of this file and applies any configuration found there. The configuration file location can also be overridden via the -c path/to/file CLI flag.

If a value is provided on both the command line and via a configuration file, the values will be merged (if a list like exclude_paths), or the True value will be preferred, in the case of something like quiet.

The following values are supported, and function identically to their CLI counterparts:

---
exclude_paths:
  - exclude_this_file
  - exclude_this_directory/
  - exclude/this/sub-directory/
skip_list:
  - 207
  - 208
tags:
  - formatting
verbosity: 1
rules:
  formatting:
    ignore: |
      ignore/this/directory/*.sls
      *.jinja
  210:
    ignore: 'exclude_this_file.sls'

Pre-commit Setup

To use salt-lint with pre-commit, just add the following to your local repo's .pre-commit-config.yaml file. Prior to version 0.12.0 of pre-commit the file was hooks.yaml (now .pre-commit-config.yaml).

---

# For use with pre-commit.
# See usage instructions at http://pre-commit.com

-   id: salt-lint
    name: Salt-lint
    description: This hook runs salt-lint.
    entry: salt-lint
    language: python
    files: \.(sls)$

Rules

List of rules

Rule	Description
201	Trailing whitespace
202	Jinja statement should have spaces before and after: {% statement %}
203	Most files should not contain tabs
204	Lines should be no longer that 160 chars
205	Use ".sls" as a Salt State file extension
206	Jinja variables should have spaces before and after {{ var_name }}
207	File modes should always be encapsulated in quotation marks
208	File modes should always contain a leading zero
209	Jinja comment should have spaces before and after: {# comment #}
210	Numbers that start with 0 should always be encapsulated in quotation marks
211	pillar.get or grains.get should be formatted differently
212	Most files should not contain irregular spaces

False Positives: Skipping Rules

Some rules are bit of a rule of thumb. To skip a specific rule for a specific task, inside your state add # noqa [rule_id] at the end of the line. You can skip multiple rules via a space-separated list. Example:

/tmp/testfile:
  file.managed:
    - source: salt://{{unspaced_var}}/example  # noqa: 206

Authors

The project is heavily based on ansible-lint, with the modified work by Warpnet B.V.. ansible-lint was created by Will Thames and is now maintained as part of the Ansible by Red Hat project.