фикс ошибок линта и молекулы

docs/troubleshooting.md

@@ -218,3 +218,63 @@ curl -v --proxy hysteria2://pass@<vps-ip>:443?insecure=1 https://example.com
 | `yamllint: wrong indentation` | Исправь отступы, запусти `make molecule-lint` |
 | `ansible-lint: no-changed-when` | Добавь `changed_when: <условие>` |
 | `sysctl: Operation not permitted` | Добавь `privileged: true` в `molecule.yml` |
+
+## Детальная отладка Molecule (addons и cluster)
+
+### 1) Сначала локализуй место падения
+
+```bash
+make molecule-addon-all
+```
+
+`molecule-addon-all` падает на первом сломанном аддоне.  
+После этого запускай конкретный сценарий:
+
+```bash
+make molecule-addon-<addon-name>
+```
+
+### 2) Запуск с продолжением после ошибок
+
+Полезно для обзора нескольких проблем за один прогон:
+
+```bash
+make -k molecule-addon-all
+```
+
+`-k` (keep going) позволит пройти дальше даже после падения отдельных аддонов.
+
+### 3) Типовые причины падений verify
+
+- **Bool как строка**
+  - Симптом: `assert v.flag == true` падает, но в сообщении видно `True`.
+  - Безопасный паттерн:
+    - `(v.flag | string | lower) == 'true'`
+
+- **Multi-document YAML**
+  - Симптом: `from_yaml` не может распарсить файл, где несколько `---`.
+  - Используй:
+    - `from_yaml_all | list`
+
+- **Файлы /tmp и delegate_to**
+  - Симптом: `no such file or directory` в `helm lint/template`.
+  - Причина: файл рендерится на target-host, а читается на localhost.
+  - Решение: рендерить/копировать и читать в одном контексте (чаще всего `delegate_to: localhost`, `run_once: true`).
+
+- **Undefined variables в шаблонах**
+  - Симптом: `AnsibleUndefinedVariable`.
+  - Решение: добавить недостающие vars в `molecule/default/converge.yml` (даже если они есть в role defaults).
+
+### 4) Проверка cluster-сценария (3 master + 2 worker)
+
+```bash
+make molecule-cluster
+```
+
+Если видишь warning:
+
+```text
+'molecule/default/molecule.yml' glob failed
+```
+
+и при этом команда заканчивается `✓ cluster topology: OK`, это служебный warning shared-state Molecule, не функциональная ошибка сценария.