Skip to main content

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

Project description

PyPI GitHub Actions: test GitHub Actions: lint

Salt-lint

salt-lint checks Salt State files (SLS) for best 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.

Demo

salt-lint demo

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 [-h] [--version] [-L] [-r RULESDIR] [-R] [-t TAGS] [-T] [-v] [-x SKIP_LIST] [--nocolor] [--force-color]
                 [--exclude EXCLUDE_PATHS] [--json] [--severity] [-c C]
                 files [files ...]

positional arguments:
  files                 One or more files or paths.

optional arguments:
  -h, --help            show this help message and exit
  --version             show program's version number 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, --nocolour
                        disable colored output
  --force-color, --force-colour
                        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
  --severity            add the severity to the standard output
  -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.

Docker

salt-lint is available on Dockerhub.

Example usage:

docker run -v $(pwd):/data:ro --entrypoint=/bin/bash -it warpnetbv/salt-lint:latest -c 'find /data -type f -name "*.sls" | xargs --no-run-if-empty salt-lint'

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'
severity: True

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

-   repo: https://github.com/warpnet/salt-lint
    rev: v0.4.0
    hooks:
      - id: salt-lint

Optionally override the default file selection as follows:

      ...
      - id: salt-lint
        files: \.(sls|jinja|tmpl)$

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 than 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

Plugins

Currently, there is a salt-lint plugin available for the following applications:

Application GitHub Link Store/Marketplace
Visual Studio Code warpnet/vscode-salt-lint VisualStudio Marketplace
Sublime Text warpnet/SublimeLinter-salt-lint Package Control

Wish to create a salt-lint extension for your favourite editor? We're always looking for contributions!

Fix common issues

sed might be one of the better tools to fix common issues, as shown in commands below.

Note: these commands assume your current working directory is the salt (states) directory/repository.

Fix spacing around {{ var_name }}, eg. {{env}} --> {{ env }}:
sed -i -E "s/\{\{\s?([^}]*[^} ])\s?\}\}/\{\{ \1 \}\}/g" $(find . -name '*.sls')

Make the dir_mode, file_mode and mode arguments in the desired syntax:
sed -i -E "s/\b(dir_|file_|)mode: 0?([0-7]{3})/\1mode: '0\2'/" $(find . -name '*.sls')

Add quotes around numeric values that start with a 0:
sed -i -E "s/\b(minute|hour): (0[0-7]?)\$/\1: '\2'/" $(find . -name '*.sls')

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.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

salt-lint-0.4.2.tar.gz (14.2 kB view details)

Uploaded Source

Built Distribution

salt_lint-0.4.2-py3-none-any.whl (21.5 kB view details)

Uploaded Python 3

File details

Details for the file salt-lint-0.4.2.tar.gz.

File metadata

  • Download URL: salt-lint-0.4.2.tar.gz
  • Upload date:
  • Size: 14.2 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.2.0 pkginfo/1.5.0.1 requests/2.24.0 setuptools/50.3.0 requests-toolbelt/0.9.1 tqdm/4.50.2 CPython/3.8.6

File hashes

Hashes for salt-lint-0.4.2.tar.gz
Algorithm Hash digest
SHA256 85c4b8ae6aba7fe305be4f84809c6b29f93464f3fd12658fc5186fe2f0bde4c3
MD5 dd090874ca832e061bc8ea021e818339
BLAKE2b-256 dcaac7aff0c7dc9f27e424de0c517afbfce66ec808a19b7ccd31257388850941

See more details on using hashes here.

File details

Details for the file salt_lint-0.4.2-py3-none-any.whl.

File metadata

  • Download URL: salt_lint-0.4.2-py3-none-any.whl
  • Upload date:
  • Size: 21.5 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.2.0 pkginfo/1.5.0.1 requests/2.24.0 setuptools/50.3.0 requests-toolbelt/0.9.1 tqdm/4.50.2 CPython/3.8.6

File hashes

Hashes for salt_lint-0.4.2-py3-none-any.whl
Algorithm Hash digest
SHA256 5df6ea4298692fb74d9ef681bb9e17b7326050679d166f5cd0fc1affb1fc816d
MD5 470a2fd8d0fe537fcc9530dad44cdff7
BLAKE2b-256 8f42af4e3f9c726c8f824b4a24b8d80cc18f6bc967d2b38317e203e426af58ff

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page