Find mistakes in your playbooks with Ansible Lint

Reviewing and correcting common mistakes in code or a configuration file is important to ensure that it's readable and easy to maintain.

Although Ansible is a popular open source configuration management tool, it is not immune to mistakes. It is critical that system administrators check and review playbooks, roles, dependencies, and collections to prevent possible bugs and ensure easy maintenance.

[ Take a no-cost technical overview course from Red Hat. Ansible Essentials: Simplicity in Automation Technical Overview. ]

A linter is a tool designed to catch data errors before processing a file. One linter specifically designed for Ansible playbooks is Ansible Lint, a readily available Python command-line tool that helps content creators to write, standardize, and package high-quality Ansible content.

Traditionally, to check for basic syntax errors in an Ansible playbook, you would run the playbook with --syntax-check. However, the --syntax-check flag is not as comprehensive or in-depth as the ansible-lint tool. You can integrate Ansible Lint into a CI/CD pipeline to check for potential issues such as deprecated or removed modules, syntax errors, idempotent playbooks, and more. It offers suggestions as to which Ansible module can best suit a particular situation. Ansible Lint ensures best practices by using a set of default rules built into the tool.

Install Ansible Lint

You can install Ansible Lint with the pip3 or the dnf package manager.

On Red Hat Enterprise Linux (RHEL) systems without the Red Hat Ansible Automation Platform subscription, install ansible-lint in the command line, as shown below:

# pip3 install ansible-lint

On RHEL systems with a Red Hat Ansible Automation Platform subscription, install ansible-lint with this command:

# dnf install ansible-lint

Alternatively, you can install ansible-lint from source using pip3. The installation requires pip>=22.3.1. Use the following command to install from source:

# pip3 install git+https://github.com/ansible/ansible-lint

Use ansible-lint

First, run ansible-lint against a playbook to print all potential rule violations.

In the following example, I created a sample playbook called test.yml, which installs the sos package on localhost:

---
- hosts: localhost
  tasks:
    - name: install package
      shell: |
        yum install -y sos

Next, I will run ansible-lint against this playbook and observe the result:

$ ansible-lint test.yml

The resulting output looks like this:

WARNING  Listing 5 violation(s) that are fatal

name[play]: All plays should be named.
test.yml:2

command-instead-of-module: yum used in place of yum module
test.yml:4 Task/Handler: install package

fqcn[action-core]: Use FQCN for builtin module actions (shell).
test.yml:4 Use `ansible.builtin.shell` or `ansible.legacy.shell` instead.

name[casing]: All names should start with an uppercase letter.
test.yml:4 Task/Handler: install package

no-changed-when: Commands should not change things if nothing needs doing.
test.yml:4 Task/Handler: install package

Read documentation for instructions on how to ignore specific rule violations.

                        Rule Violation Summary                       
 count tag                      profile rule associated tags     
    1 command-instead-of-module basic   command-shell, idiom     
    1 name[play]                basic   idiom                    
    1 name[casing]              moderate   idiom                     
    1 no-changed-when           shared  command-shell, idempotency
    1 fqcn[action-core]         production formatting                

Failed after min profile: 5 failure(s), 0 warning(s) on 1 files.

[ Write your first playbook in this hands-on interactive lab. ]

As shown above, Ansible Lint discovered 5 violations:

1. All plays should be named.

name[play]: All plays should be named.
test.yml:2

As seen in the playbook, the play does not have a name.

2. The yum command is used in place of the yum module.

command-instead-of-module: yum used in place of yum module
test.yml:4 Task/Handler: install package

The yum module should be used instead of the shell module, which is inappropriate for this case.

3. Use the FQCN for built-in module actions.

fqcn[action-core]: Use FQCN for builtin module actions (shell).
test.yml:4 Use `ansible.builtin.shell` or `ansible.legacy.shell` instead.

The fully qualified collection name (FQCN) should be used for the builtin module. In this case, even if I used the shell module, a more proper way is with ansible.builtin.shell

4. All names should start with an uppercase letter.

name[casing]: All names should start with an uppercase letter.
test.yml:4 Task/Handler: install package

The name of a task should start with an uppercase letter. In this playbook, the task should be Install package. This practice ensures standardization across all playbooks.

5. Commands should not change things if nothing needs to be done.

no-changed-when: Commands should not change things if nothing needs doing.
test.yml:4 Task/Handler: install package

This violates of the principle of idempotency, which ensures that a playbook can be applied repeatedly with the same results. The shell module is generally not considered idempotent.

Here is a cleaner way of writing the same playbook:

---
- name: Install sos on servers
  hosts: localhost
  tasks:
    - name: Install package
      ansible.builtin.yum:
        name: sos
        state: present

If you run ansible-lint again, it passes:

$ ansible-lint test.yml

Passed with production profile: 0 failure(s), 0 warning(s) on 1 files.

Wrap up

Ansible Lint allows system administrators to verify that playbooks and other artifacts conform to recommended practices and don't contain errors or bugs. It improves automation functionality, reliability, and the readability and maintainability of your content.

In future articles, I will look at the configuration, rules, and profiles used with Ansible Lint.

[Use the Time Savings Calculator to find out how much time you can save by switching to Ansible Automation Platform. ]