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:
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:
Having ansible directories located in other path f.e. in /mount/ansible/:
To get an overview over the running options, use -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:
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.
Following profiles are available:
- min
- basic
- moderate
- safety
- shared
- production
ansible-lint profiles are inherited, included in each other:
minprofile is inherited inbasicprofileminprofile is a proper subset ofbasicprofilebasicprofile includes theminprofilebasicprofile is a super-set of theminprofile
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:
Ensure automation consistency, reliability, and security with the safety profile.
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:
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
mintoproduction - 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:
For further running options refer to the ansible-lint online documentation