DevOpsLab/docs/linting-guide.md

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

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

## Обзор

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

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

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

### Проверка конкретной роли
```bash
make role lint devops
make role lint ping
```
- Проверяет только указанную роль
- Автоматически валидирует существование роли
- Показывает доступные роли при ошибке

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

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

### Production (по умолчанию)
- Самый строгий профиль
- Проверяет все правила
- Рекомендуется для продакшн кода

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

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

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

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

```yaml
---
# Профиль по умолчанию
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
```yaml
# ❌ Неправильно
  groups: ["sudo", "docker"]  
  # Лишние пробелы в конце строки

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

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

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

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

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

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

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

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

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

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

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

```yaml
# .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. Регулярная проверка
```bash
# Проверяйте код перед коммитом
make role lint

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

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

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

### 4. Используйте pre-commit hooks
```yaml
# .pre-commit-config.yaml
repos:
  - repo: https://github.com/ansible/ansible-lint
    rev: v6.0.0
    hooks:
      - id: ansible-lint
```

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

### Ошибка "Role not found"
```bash
❌ Роль 'nonexistent' не найдена в roles/
📋 Доступные роли:
  - devops
  - ping
```
**Решение**: Проверьте правильность имени роли

### Ошибка "Docker image not found"
```bash
Unable to find image 'ansible-controller:latest' locally
```
**Решение**: Соберите Docker образы:
```bash
make docker build
```

### Ошибка "Permission denied"
```bash
Permission denied: /workspace/roles/
```
**Решение**: Проверьте права доступа к файлам

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

- [Ansible Lint Documentation](https://ansible.readthedocs.io/projects/lint/)
- [Ansible Best Practices](https://docs.ansible.com/ansible/latest/user_guide/playbooks_best_practices.html)
- [YAML Style Guide](https://yaml.org/spec/1.2/spec.html)

## Поддержка

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

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

---

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