Programing languages have compilers or runtimes that can catch logical errors, which syntax highlights in a text editor can't predict. Markup languages might not have such tools like compilers. But a linter is a code analysis tool to spot programming and stylistic errors and to flag not optimal constructs. ansible-lint is a linter designed specifically for ansible.

ansible-lint checks ansible playbooks for practices and behaviour that can be improved. It combines writing ansible playbooks and testing in one application. It helps and trains to write clean playbooks. Ansible-lint is saving your time from execution errors and countless hours of debugging.

The ansible-lint website writes following about its philosophy:

Ansible playbooks, roles, and collections should read like documentation, be production ready, unambiguous, and provide consistent results.

Ansible-lint should be considered a trusted advisor, helping ansible content creators write and package high-quality Ansible content. While not all rules may be applicable in all situations, they should be followed whenever possible.

Installation

Install the package using your linux distribution package-manager, below emerge is the appropriate tool for gentoo:

root # emerge -va ansible-lint

Usage

Ansible-lint is run on top of a ansible directory or in the directory where interesting ansible playbooks reside. Change to the ansible directory where the playbooks are, usually that is the directory ~/ansible:

user % cd ansible

Having ansible directories located in other path f.e. in /mount/ansible/:

user % cd /mount/ansible/

To get an overview over the running options, use -h:

user % ansible-lint -h

After getting familiar with the running options, read about the configuration and running options. Use the online documentation

Configuration

There are 3 different ways of changing ansible-lint's configuration:

  • Using command line parameters ansible-lint -x fcqd[example]
  • Using configuration file /.ansible-list
  • Using selected profiles (f.e.: min, basic...etc.)

CLI Parameters

Skip a particular check using -x option with the id/tag like in the example below. 00-debug.yml is a example network related ansible playbook here:

user % ansible-lint -x fqcn[action] 00-debug.yml

This will skip the fqcn[action] check on a playbook. Further reading on excluding checks

Profiles

After you install and configure ansible-lint, you can apply profiles as follows. View available profiles using the -list-profiles flag option.

user % ansible-lint --list-profiles

Following profiles are available:

  • min
  • basic
  • moderate
  • safety
  • shared
  • production

ansible-lint profiles are inherited, included in each other:

  • min profile is inherited in basic profile
  • min profile is a proper subset of basic profile
  • basic profile includes the min profile
  • basic profile is a super-set of the min profile

Specify a profile with the --profile parameter to lint your content with those rules, for example:

Enforce using the min profile from the command line:

user % ansible-lint --profile=basic

Ensure automation consistency, reliability, and security with the safety profile.

user % ansible-lint --profile=safety

In the default setting the production profile is always chosen.

Ansible lint: applying profiles

Configuration File

ansible-lint can be run from command line using the listed options in the help file. Running options can be configured permanently using ~/.ansible-lint or ~/.config/ansibile-lint.yaml file.

Example lint configuration file. Either set per directory/project or use global configuration method where ~/.ansible-lint configuration file is written in home directory ~/. Symbolic linking using ln -s to the sub-directories for example ~/ansible/ where it is used.

Example configuration file using the production profile, enabling offline, and last option skip_list entry. progressive is set to false:

# .ansible-lint

profile: production# min, basic, moderate, safety, shared, production

# Offline mode disables installation of requirements.yml
offline: true

# Return success if number of violations compared with previous git
# commit has not increased. This feature works only in git
# repositories.
progressive: false

skip_list:
  - fqcn[action]

Running ansible-lint

Example output of running a playbook. Ansible-lint does not get in touch with the productive infrastructure the playbook is targeted for, it runs the output and analyses for syntax pattern used. It's output is verbose at default:

user % ansible-lint 06-ios-show-stp-root.yml

WARNING Overriding detected file kind 'yaml' with 'playbook' for given positional argument: 06-ios-show-stp-root.yml WARNING Listing 1 violation(s) that are fatal fqcn[action-core]: Use FQCN for builtin module actions (debug). 06-ios-show-stp-root.yml:27 Use 'ansible.builtin.debug' or 'ansible.legacy.debug' instead.

You can skip specific rules or tags by adding them to your configuration file: .config/ansible-lint.yml warn_list: # or 'skip_list' to silence them completely - fqcn[action-core] # Use FQCN for builtin actions.

Rule Violation Summary count tag profile rule associated tags 1 fqcn[action-core] production formatting Failed after min profile: 6 failure(s), 1 warning(s) on 1 files.

The ansible-lint output gives a specific work instruction where the violation is to be corrected, and what needs to be done to make it error free:

06-ios-show-stp-root.yml:27 Use `ansible.builtin.debug` or `ansible.legacy.debug` instead.
  • Playbook: 06-ios-show-stp-root.yml
  • Line: 27
  • Change to: ansible.builtin.debug

Did not find a way to automate linting ansible playbooks there is this option -w that writes, but the description is not obvious what it writes the yaml files or kind of report about processed files. Maybe once you have found it out, write me an email.

Profile setting for the rookie

If running ansible-lint for the first time like a rookie like me, my suggestion would be creating a minimal .ansible-lint configuration file using the min profile:

#.ansible-lint

profile: min # min, basic, moderate, safety, shared, production
offline: true
progressive: false

As mentioned already the default profile is set always to production, running ansible-lint on playbooks generates lots of debug, warning, fixing, issues, suggestions output, its output can be overwhelming at first. Setting the profile initially to min is less verbose and can be raised gradually if during usage as issues are fixed.

Summary

ansible-lint

  • Does not require having access to productive/testing/dev infrastructure to be able run
  • 6 different profiles to choose from min to production
  • Analyses all ansible files not only playbooks
  • Outputs, found syntax errors, issues and playbook structure suggestions
  • Suggests efficient placement of used playbook elements tasks/handlers etc.
  • Assures written ansible-playbook runs

ansible-lint makes writing ansible playbooks easier in the long run. It forces to use correct syntax right from the beginning. Using ansible-lint to fix issues in playbooks raises awareness of own most common mistakes, bad scripting habits.

Documentation

Read the command line help for additional configuration and running options:

user % ansible-lint -h

For further running options refer to the ansible-lint online documentation

References