Avoid errors in your Ansible playbooks with ansible-lint

When developers write code, they might use an integrated development environment (IDE) or a good text editor to catch syntax errors as they write. Similarly, many text editors have special modes and syntax highlighting for popular markup languages such as YAML, which can help you quickly find errors.

[ Download now: A system administrator's guide to IT automation. ]

Coders also have compilers or runtimes that can catch logical errors, which syntax highlights in a text editor can't predict. Markup languages don't generally have compilers, and while there are often processors that fail when attempting to parse your errant file, that's often not when you want to find out that you've made a mistake. A linter is designed to catch errors in data before a file is processed. This saves you (or your automated workflow) from errors during a critical stage of operation.

The ansible-lint command is a linter designed specifically for Ansible playbooks.

Install 

The easiest way to install ansible-lint is with pip:

$ python3 -m pip install --user ansible-lint

Confirm the installation:

$ ansible-lint --version
ansible-lint x.y.z using ansible X.Y.Z

[ Learn more: Ansible vs. Terraform, clarified ]

Ansible-lint

As its name implies, ansible-lint is a YAML linter specific to Ansible playbooks. That means when you lint a playbook, it's not just looking at the markup syntax but also how you're using Ansible modules. For instance, take this simple playbook that creates a set of directories on a host:

---
- hosts: localhost
  tasks:
    - name: Create directories
      ansible.builtin.file:
      path: "{{ item }}"   # this is wrong
      state: directory     # this is wrong
      with_items:
        - '~/Foo'
        - '~/Bar
        - '~/Baz

With this playbook saved as standard_dirs.yaml in the directory structure ~/Ansible/playbooks, run the ansible-lint command:

$ cd ~/Ansible
$ ansible-lint
ERROR! conflicting action statements: ansible.builtin.file, path

The error appears to be in '/home/tux/Ansible/playbooks/standard_dirs.yaml': line 4, column 7, but may be elsewhere in the file depending on the exact syntax problem.

The offending line appears to be:

  tasks:
    - name: Create directories
      ^ here

Finished with 1 failure(s), 0 warning(s) on 2 files.

The linter identified an error beginning with the very first line of the first (and only) task. This tells you where to start looking. In this case, it's pretty obvious to start looking there because there's only one task, but this can be a valuable hint in a complex playbook. As I've already identified the error with comments, you can fix the indentation errors. If you don't know why those are errors, read my YAML for Ansible article. 

[ Learn how to create, scale, and manage automation by registering for the Ansible basics: Automation technical overview course, available on demand. ]

---
- hosts: localhost
  tasks:
    - name: Create directories
      ansible.builtin.file:
        path: "{{ item }}"
        state: directory
      with_items:
        - '~/Foo'
        - '~/Bar
        - '~/Baz

Now rerun the command:

$ cd ~/Ansible
$ ansible-lint
WARNING  Listing 2 violation(s) that are fatal
risky-file-permissions: File permissions unset or incorrect
playbooks/standard_dirs.yaml:4 Task/Handler: Create directories

yaml: no new line character at the end of file (new-line-at-end-of-file)
playbooks/standard_dirs.yaml:12

This time, there's no error but a fatal warning from two separate rules. The risky-file-permissions module warns that I haven't specified file permissions in a task that creates folders. The yaml rule, enabled because I also have yamllint installed on my system, warns that there's no newline character at the end of the file.

Fix the first error by specifying file permissions and the second error by adding a new line at the end of the YAML:

---
- hosts: localhost
  tasks:
    - name: Create directories
      ansible.builtin.file:
        path: "{{ item }}"
        state: directory
        mode: '775'
      with_items:
        - '~/Foo'
        - '~/Bar
        - '~/Baz

One more try:

$ ansible-lint
$ 

No output means no errors.

Lint early, lint often

If you're writing code or markup in a language with a linter, it just makes sense to lint. There are linters specific to YAML, but ansible-lint takes it a step further and checks your Ansible tasks themselves. It's a powerful way to protect yourself from errors during execution and possibly from hours of debugging.