Ansible-Lint Rule Analysis and Best Practices

# pip (recommended — latest version)
pip install ansible-lint

# RHEL/CentOS
sudo dnf install ansible-lint

# With all optional checkers
pip install ansible-lint[community,yamllint]

# Verify
ansible-lint --version

# Lint a playbook
ansible-lint site.yml

# Lint an entire directory
ansible-lint roles/

# Lint with verbose output
ansible-lint -v site.yml

# List all rules
ansible-lint -L

# List rules with tags
ansible-lint -T

# Auto-fix what can be fixed
ansible-lint --fix site.yml

# Dry-run autofix (show what would change)
ansible-lint --fix=diff site.yml

# .ansible-lint (project root)
---
profile: production  # null, min, basic, moderate, safety, shared, production

# Paths to lint
exclude_paths:
  - .github/
  - .cache/
  - molecule/

# Skip specific rules
skip_list:
  - yaml[line-length]
  - no-changed-when

# Treat warnings as errors
strict: true

# Enable optional rules
enable_list:
  - no-log-password
  - no-same-owner

# Offline mode (skip Galaxy checks)
offline: true

# Mock roles/modules that aren't installed
mock_roles:
  - external_role

mock_modules:
  - custom_module

# Custom rules directory
# rulesdir:
#   - custom_rules/

# ❌ Wrong argument
- ansible.builtin.file:
    path: /tmp/test
    state: directory
    mode: 755           # Should be string '0755'

# ✅ Correct
- ansible.builtin.file:
    path: /tmp/test
    state: directory
    mode: '0755'

# ❌ command-instead-of-module: use apt module
- ansible.builtin.command: apt-get install nginx

# ✅ Use the module
- ansible.builtin.apt:
    name: nginx
    state: present

# ❌ command-instead-of-shell: doesn't need shell
- ansible.builtin.shell: cat /etc/hostname

# ✅ Use command (no shell features needed)
- ansible.builtin.command: cat /etc/hostname

# ❌ deprecated-bare-vars
- ansible.builtin.debug:
    msg: "{{ item }}"
  with_items: mylist     # Bare variable

# ✅ Use proper variable syntax
- ansible.builtin.debug:
    msg: "{{ item }}"
  loop: "{{ mylist }}"

# ❌ deprecated-local-action
- local_action: ansible.builtin.command echo hello

# ✅ Use delegate_to
- ansible.builtin.command: echo hello
  delegate_to: localhost

# ❌ deprecated-module
- ansible.builtin.include:
    file: tasks.yml

# ✅ Use current module
- ansible.builtin.include_tasks:
    file: tasks.yml

# ❌ yaml[truthy]: use true/false not yes/no
become: yes

# ✅ Use boolean
become: true

# ❌ yaml[line-length]: line too long (>160 chars)
- name: This is an extremely long task name that goes on and on and on and describes every little thing about what this task does in excruciating detail

# ✅ Keep lines reasonable
- name: Install web server packages

# ❌ no-tabs
- name: Task with	tabs

# ✅ Use spaces
- name: Task with spaces

# ❌ no-changed-when: command always reports changed
- name: Check disk space
  ansible.builtin.command: df -h

# ✅ Mark as never changing
- name: Check disk space
  ansible.builtin.command: df -h
  changed_when: false

# ✅ Or set proper change detection
- name: Create user
  ansible.builtin.command: useradd testuser
  register: result
  changed_when: result.rc == 0
  failed_when: result.rc not in [0, 9]

# ❌ name[missing]: task without name
- ansible.builtin.apt:
    name: nginx

# ✅ Always name tasks
- name: Install nginx
  ansible.builtin.apt:
    name: nginx

# ❌ name[casing]: should start with uppercase
- name: install nginx
  ansible.builtin.apt:
    name: nginx

# ✅ Capitalize task names
- name: Install nginx
  ansible.builtin.apt:
    name: nginx

# ❌ role-name: invalid characters
# Role: My-Role_v2!

# ✅ Lowercase with underscores
# Role: my_role_v2

# ❌ no-log-password: password visible in logs
- name: Set user password
  ansible.builtin.user:
    name: admin
    password: "{{ vault_password }}"

# ✅ Add no_log
- name: Set user password
  ansible.builtin.user:
    name: admin
    password: "{{ vault_password }}"
  no_log: true

# ❌ ignore-errors: hides real failures
- name: Install package
  ansible.builtin.apt:
    name: maybe-exists
  ignore_errors: true

# ✅ Use failed_when for specific conditions
- name: Install package
  ansible.builtin.apt:
    name: maybe-exists
  register: result
  failed_when:
    - result.rc != 0
    - "'not found' not in result.msg"

# ❌ partial-become: become_user without become
- name: Run as postgres
  ansible.builtin.command: psql -c "SELECT 1"
  become_user: postgres

# ✅ Include become
- name: Run as postgres
  ansible.builtin.command: psql -c "SELECT 1"
  become: true
  become_user: postgres

# ❌ fqcn[action-core]: not using FQCN
- copy:
    src: file.txt
    dest: /tmp/file.txt

# ✅ Use FQCN
- ansible.builtin.copy:
    src: file.txt
    dest: /tmp/file.txt

# ❌ jinja[spacing]: missing spaces in braces
- name: Debug
  ansible.builtin.debug:
    msg: "{{variable}}"

# ✅ Add spaces
- name: Debug
  ansible.builtin.debug:
    msg: "{{ variable }}"

# ❌ jinja[invalid]: invalid Jinja2
- name: Debug
  ansible.builtin.debug:
    msg: "{{ variable | no_such_filter }}"

# ❌ key-order: inconsistent key order
- become: true
  name: Install package
  ansible.builtin.apt:
    name: nginx

# ✅ Standard order: name → module → parameters → modifiers
- name: Install package
  ansible.builtin.apt:
    name: nginx
  become: true

# Fix all auto-fixable issues
ansible-lint --fix .

# Preview fixes without applying
ansible-lint --fix=diff .

# Fix specific file
ansible-lint --fix roles/webserver/tasks/main.yml

# .github/workflows/lint.yml
name: Ansible Lint
on: [push, pull_request]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Run ansible-lint
        uses: ansible/ansible-lint@main

ansible-lint:
  image: python:3.12
  before_script:
    - pip install ansible-lint
  script:
    - ansible-lint --strict .

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/ansible/ansible-lint
    rev: v24.10.0
    hooks:
      - id: ansible-lint
        additional_dependencies:
          - ansible-core>=2.17

pip install pre-commit
pre-commit install

# custom_rules/no_hardcoded_ips.py
from ansiblelint.rules import AnsibleLintRule

class NoHardcodedIPs(AnsibleLintRule):
    id = "custom-no-hardcoded-ip"
    shortdesc = "Do not hardcode IP addresses"
    description = "IP addresses should be in variables or inventory, not hardcoded in tasks"
    tags = ["custom", "security"]

    def matchtask(self, task, file=None):
        import re
        ip_pattern = r'\b\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}\b'
        for key, value in task.get("action", {}).items():
            if isinstance(value, str) and re.search(ip_pattern, value):
                if value not in ("127.0.0.1", "0.0.0.0"):
                    return True
        return False

# .ansible-lint
rulesdir:
  - custom_rules/