Improve Playbook Debugging Using Ansible Lint

Introduction

Ansible lint is a command-line tool that is crucial in Ansible automation. It acts as a code quality checker, helping users identify errors and providing suggestions for playbook improvements. This tool is indispensable for maintaining the integrity and reliability of Ansible playbooks, reducing debugging time, and ensuring smooth automation processes. In this article, we’ll delve into the world of Ansible lint. We’ll explore how to install it, showcase some practical use cases, and Playbooknstrate how it can prevent errors during playbook execution.

See also: Creating a Custom Ansible Lookup Plugin in Python for Reading a File

Installing Ansible Lint

Before we dive into the benefits of Ansible lint, let’s first install it. There are multiple ways to do this: Using pip: The simplest way to install Ansible lint is via Python Package Manager (pip). Run the following command:

python3 -m pip install --user ansible-lint

On Red Hat Enterprise Linux (RHEL):

If you’re on RHEL systems with a Red Hat Ansible Automation Platform subscription, you can use dnf to install Ansible lint:

dnf install ansible-lint

From the GitHub source repository:

You can also install Ansible lint directly from the source repository on GitHub, but this method requires pip>=22.3.1:

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

With Ansible lint successfully installed, let’s explore its benefits through two practical examples.

Ansible Lint Configuration File

One of the powerful features of Ansible lint is its configuration ability. You can tailor its behavior to your specific needs using a configuration file (.ansible-lint) in your working directory. For instance, you can exclude certain paths from linting:

profile: null
exclude_paths:
  - playbook.yml

In this example, we’ve excluded the playbook.yml path from linting. When you run Ansible lint in this directory, it won't check that specific playbook for errors.

See also: Creating a Custom Ansible Lookup Plugin in Python for retrieving API token

Usage

Let’s showcase the capabilities and features of Ansible in two examples. In the first example, we presented an Ansible playbook snippet to update the APT cache on target hosts using the ansible.builtin.command module. However, Ansible Lint detected an issue and issued a warning. It pointed out that the playbook should use the apt module instead of command for this task. Following Ansible Lint's advice and making the necessary corrections, we ensured our playbook adhered to best practices, eliminating errors. In the second example, we showcased a playbook containing a syntax error. The playbook attempted to set an environment variable but had an indentation issue within the environment block. Ansible lint came to the rescue by pinpointing the exact location of the error. After rectifying the syntax error, our playbook became error-free and ready for smooth execution.

Example 1: Using a Built-in Module

Consider the following Ansible playbook snippet (playbook.yml) for Debian/Ubuntu Linux update:

---
- name: Update apt cache
  hosts: all
  tasks:
    - name: Run apt-get update
      ansible.builtin.command: apt-get update

In this example, we are attempting to update the APT cache using the ansible.builtin.command module. However, Ansible lint identifies an issue:

WARNING  Listing 2 violation(s) that are fatal
command-instead-of-module: apt-get used in place of apt-get module
playbook.yml:5 Task/Handler: Run apt-get update
no-changed-when: Commands should not change things if nothing needs doing
playbook.yml:5 Task/Handler: Run apt-get update

Ansible lint warns us that we should use the apt module instead of the command module for this task. By following Ansible Lint's advice, we can correct the playbook:

---
- name: Update apt cache
  hosts: all
  tasks:
    - name: Run apt-get update
      ansible.builtin.apt:
        update_cache: true

This adjustment adheres to best practices, eliminating errors in our playbook.

Example 2: Playbook Syntax Error

Let’s explore another example where Ansible lint helps us identify a syntax error in a playbook (playbook2.yml) with an environmental variable and a syntax error:

---
- name: Example playbook
  hosts: all
  tasks:
    - name: Set environment variable
      ansible.builtin.shell: echo $MY_ENV_VAR
      environment:
      MY_ENV_VAR: my_value

When we run Ansible lint on this playbook, it detects a syntax error:

The error appears to be in 'playbook2.yml': line 5, column 7, but may
be elsewhere in the file depending on the exact syntax problem.
The offending line appears to be:
tasks:
- name: Set environment variable
^ here

Ansible lint points us to the exact location of the error, which is an indentation issue in the environment block. After fixing the playbook's syntax, it looks like this:

---
- name: Example playbook
  hosts: all
  tasks:
    - name: Set environment variable
      ansible.builtin.shell: echo $MY_ENV_VAR
      environment:
        MY_ENV_VAR: my_value

Now, our playbook is error-free.

Conclusion

Ansible lint is an indispensable tool for anyone working with Ansible playbooks. It ensures code quality, identifies errors, and provides recommendations for improvement. By following its guidance and customizing its behavior through configuration files, you can save valuable debugging time and maintain the integrity of your automation code.

See also: Create Custom Ansible Modules: Python Module Development Guide

Related Articles

• Ansible when conditional guide • environment variables in shell modules of Ansible • handler ordering in Ansible