DevOpsLab/docs/linting-guide.md

🔍 Руководство по линтингу ролей

Автор

Сергей Антропов
Сайт: https://devops.org.ru

Обзор

Линтинг ролей - это автоматическая проверка синтаксиса, стиля и соответствия лучшим практикам Ansible. В AnsibleLab используется ansible-lint для обеспечения качества кода.

Команды линтинга

Проверка всех ролей

make role lint

• Проверяет все роли в директории roles/
• Использует конфигурацию из .ansible-lint
• Показывает все найденные ошибки и предупреждения

Проверка конкретной роли

make role lint devops
make role lint ping

• Проверяет только указанную роль
• Автоматически валидирует существование роли
• Показывает доступные роли при ошибке

Профили линтинга

Ansible-lint использует несколько профилей для разных уровней строгости:

Production (по умолчанию)

• Самый строгий профиль
• Проверяет все правила
• Рекомендуется для продакшн кода

Basic

• Базовые правила
• Подходит для разработки
• Менее строгий чем production

Min

• Минимальные правила
• Только критичные ошибки
• Для быстрой проверки

Конфигурация

Линтинг настраивается через файл .ansible-lint:

---
# Профиль по умолчанию
profile: production

# Исключения
skip_list:
  - yaml[line-length]  # Исключить проверку длины строк

# Дополнительные правила
enable_list:
  - name[casing]  # Включить проверку именования

# Игнорирование файлов
exclude_paths:
  - .cache/
  - .github/
  - tests/

Типы ошибок

Синтаксические ошибки

• Неправильный YAML синтаксис
• Ошибки в Jinja2 шаблонах
• Неправильная структура playbook

Стилистические ошибки

• Trailing spaces (лишние пробелы)
• Неправильные комментарии
• Неправильное форматирование

Лучшие практики

• Использование устаревших модулей
• Неправильное использование become
• Отсутствие changed_when для command

Примеры исправлений

Trailing spaces

# ❌ Неправильно
  groups: ["sudo", "docker"]  
  # Лишние пробелы в конце строки

# ✅ Правильно
  groups: ["sudo", "docker"]

Комментарии

# ❌ Неправильно
#Комментарий без пробела

# ✅ Правильно
# Комментарий с пробелом

Changed when

# ❌ Неправильно
- name: "Проверка статуса"
  command: "systemctl status nginx"

# ✅ Правильно
- name: "Проверка статуса"
  command: "systemctl status nginx"
  changed_when: false

Автоматическое исправление

Некоторые ошибки можно исправить автоматически:

# Исправить trailing spaces
sed -i 's/[[:space:]]*$//' roles/*/tasks/*.yml

# Исправить комментарии
sed -i 's/^#\([^ ]\)/# \1/' roles/*/tasks/*.yml

Интеграция с CI/CD

Линтинг автоматически запускается в CI/CD пайплайне:

# .github/workflows/lint.yml
name: Lint
on: [push, pull_request]
jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Run lint
        run: make role lint

Лучшие практики

1. Регулярная проверка

# Проверяйте код перед коммитом
make role lint

# Проверяйте конкретную роль при разработке
make role lint devops

2. Исправляйте ошибки сразу

• Не накапливайте ошибки
• Исправляйте по мере обнаружения
• Используйте автоматические исправления

3. Настройте IDE

• Включите поддержку YAML
• Настройте автоформатирование
• Используйте расширения для Ansible

4. Используйте pre-commit hooks

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/ansible/ansible-lint
    rev: v6.0.0
    hooks:
      - id: ansible-lint

Устранение неполадок

Ошибка "Role not found"

❌ Роль 'nonexistent' не найдена в roles/
📋 Доступные роли:
  - devops
  - ping

Решение: Проверьте правильность имени роли

Ошибка "Docker image not found"

Unable to find image 'ansible-controller:latest' locally

Решение: Соберите Docker образы:

make docker build

Ошибка "Permission denied"

Permission denied: /workspace/roles/

Решение: Проверьте права доступа к файлам

Дополнительные ресурсы

• Ansible Lint Documentation
• Ansible Best Practices
• YAML Style Guide

Поддержка

Если у вас возникли вопросы или проблемы с линтингом:

1. Проверьте документацию выше
2. Запустите make role lint для диагностики
3. Обратитесь к команде разработки

---

Последнее обновление: $(date)
Версия: 1.0.0