feat: Создана полная документация проекта с централизованным хранением
- Создан новый README.md с полной документацией проекта - Перемещены все MD файлы в папку /docs - Создана структура документации: - docs/universal-lab.md - руководство по лаборатории - docs/presets.md - описание всех 21 пресета - docs/roles.md - структура и создание Ansible ролей - docs/examples.md - практические примеры использования - docs/troubleshooting.md - решение проблем - docs/api.md - справочник по API Основные возможности документации: - Полное описание всех возможностей лаборатории - 21 готовый пресет для различных сценариев - Подробные инструкции по использованию - Примеры создания собственных пресетов - Руководство по созданию Ansible ролей - Troubleshooting для решения проблем - API Reference для всех команд и параметров Структура проекта: - README.md - основная документация с ссылками - docs/ - централизованное хранение документации - molecule/presets/ - 21 готовый пресет - files/ - файлы для ролей и playbooks - scripts/ - скрипты для управления лабораторией Автор: Сергей Антропов Сайт: https://devops.org.ru
This commit is contained in:
652
docs/troubleshooting.md
Normal file
652
docs/troubleshooting.md
Normal file
@@ -0,0 +1,652 @@
|
||||
# Troubleshooting
|
||||
|
||||
## Автор
|
||||
Сергей Антропов
|
||||
Сайт: https://devops.org.ru
|
||||
|
||||
## Описание
|
||||
|
||||
Этот документ содержит решения наиболее распространенных проблем при работе с универсальной лабораторией.
|
||||
|
||||
## Содержание
|
||||
|
||||
- [Общие проблемы](#общие-проблемы)
|
||||
- [Проблемы с Docker](#проблемы-с-docker)
|
||||
- [Проблемы с Kubernetes](#проблемы-с-kubernetes)
|
||||
- [Проблемы с портами](#проблемы-с-портами)
|
||||
- [Проблемы с ресурсами](#проблемы-с-ресурсами)
|
||||
- [Проблемы с сетью](#проблемы-с-сетью)
|
||||
- [Проблемы с Ansible](#проблемы-с-ansible)
|
||||
- [Проблемы с Molecule](#проблемы-с-molecule)
|
||||
- [Проблемы с пресетами](#проблемы-с-пресетами)
|
||||
- [Проблемы с отчетами](#проблемы-с-отчетами)
|
||||
|
||||
## Общие проблемы
|
||||
|
||||
### Проблема: Лаборатория не запускается
|
||||
|
||||
**Симптомы:**
|
||||
- Команда `make lab-up` завершается с ошибкой
|
||||
- Контейнеры не создаются
|
||||
- Ошибки в логах Docker
|
||||
|
||||
**Решение:**
|
||||
```bash
|
||||
# Проверить статус Docker
|
||||
docker ps
|
||||
docker version
|
||||
|
||||
# Перезапустить Docker
|
||||
sudo systemctl restart docker
|
||||
|
||||
# Очистить Docker
|
||||
docker system prune -a
|
||||
|
||||
# Перезапустить лабораторию
|
||||
make lab-reset
|
||||
```
|
||||
|
||||
### Проблема: Команды Make не работают
|
||||
|
||||
**Симптомы:**
|
||||
- `make: command not found`
|
||||
- Ошибки в Makefile
|
||||
|
||||
**Решение:**
|
||||
```bash
|
||||
# Установить Make
|
||||
# Ubuntu/Debian
|
||||
sudo apt-get install make
|
||||
|
||||
# CentOS/RHEL
|
||||
sudo yum install make
|
||||
|
||||
# macOS
|
||||
brew install make
|
||||
|
||||
# Проверить версию
|
||||
make --version
|
||||
```
|
||||
|
||||
### Проблема: Недостаточно прав
|
||||
|
||||
**Симптомы:**
|
||||
- `Permission denied`
|
||||
- Ошибки доступа к файлам
|
||||
|
||||
**Решение:**
|
||||
```bash
|
||||
# Проверить права на файлы
|
||||
ls -la
|
||||
|
||||
# Установить права
|
||||
chmod +x scripts/*.sh
|
||||
chmod 644 *.yml
|
||||
|
||||
# Добавить пользователя в группу docker
|
||||
sudo usermod -aG docker $USER
|
||||
newgrp docker
|
||||
```
|
||||
|
||||
## Проблемы с Docker
|
||||
|
||||
### Проблема: Docker daemon не запущен
|
||||
|
||||
**Симптомы:**
|
||||
- `Cannot connect to the Docker daemon`
|
||||
- `docker: command not found`
|
||||
|
||||
**Решение:**
|
||||
```bash
|
||||
# Запустить Docker daemon
|
||||
sudo systemctl start docker
|
||||
sudo systemctl enable docker
|
||||
|
||||
# Проверить статус
|
||||
sudo systemctl status docker
|
||||
|
||||
# Проверить доступ
|
||||
docker ps
|
||||
```
|
||||
|
||||
### Проблема: Недостаточно места на диске
|
||||
|
||||
**Симптомы:**
|
||||
- `No space left on device`
|
||||
- Ошибки создания контейнеров
|
||||
|
||||
**Решение:**
|
||||
```bash
|
||||
# Проверить использование диска
|
||||
df -h
|
||||
|
||||
# Очистить Docker
|
||||
docker system prune -a
|
||||
docker volume prune
|
||||
docker network prune
|
||||
|
||||
# Удалить неиспользуемые образы
|
||||
docker image prune -a
|
||||
```
|
||||
|
||||
### Проблема: Конфликты портов
|
||||
|
||||
**Симптомы:**
|
||||
- `Port is already in use`
|
||||
- Ошибки привязки портов
|
||||
|
||||
**Решение:**
|
||||
```bash
|
||||
# Найти процесс, использующий порт
|
||||
sudo netstat -tulpn | grep :8080
|
||||
sudo lsof -i :8080
|
||||
|
||||
# Убить процесс
|
||||
sudo kill -9 <PID>
|
||||
|
||||
# Или изменить порт в пресете
|
||||
publish:
|
||||
- "8081:80" # Вместо 8080:80
|
||||
```
|
||||
|
||||
### Проблема: DinD контейнеры не работают
|
||||
|
||||
**Симптомы:**
|
||||
- DinD контейнеры не запускаются
|
||||
- Ошибки Docker-in-Docker
|
||||
|
||||
**Решение:**
|
||||
```bash
|
||||
# Проверить privileged режим
|
||||
docker run --privileged -d docker:dind
|
||||
|
||||
# Проверить доступ к Docker socket
|
||||
docker run -v /var/run/docker.sock:/var/run/docker.sock docker:latest ps
|
||||
|
||||
# Перезапустить с правильными параметрами
|
||||
make lab-reset
|
||||
make lab-create
|
||||
```
|
||||
|
||||
## Проблемы с Kubernetes
|
||||
|
||||
### Проблема: Kind кластер не создается
|
||||
|
||||
**Симптомы:**
|
||||
- `kind create cluster` завершается с ошибкой
|
||||
- Кластер не доступен
|
||||
|
||||
**Решение:**
|
||||
```bash
|
||||
# Проверить Kind
|
||||
kind version
|
||||
|
||||
# Удалить существующие кластеры
|
||||
kind delete cluster --name lab
|
||||
|
||||
# Очистить Docker
|
||||
docker system prune -a
|
||||
|
||||
# Пересоздать кластер
|
||||
make lab-create
|
||||
```
|
||||
|
||||
### Проблема: kubectl не работает
|
||||
|
||||
**Симптомы:**
|
||||
- `kubectl: command not found`
|
||||
- Ошибки подключения к кластеру
|
||||
|
||||
**Решение:**
|
||||
```bash
|
||||
# Установить kubectl
|
||||
curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
|
||||
chmod +x kubectl
|
||||
sudo mv kubectl /usr/local/bin/
|
||||
|
||||
# Проверить конфигурацию
|
||||
kubectl config get-contexts
|
||||
|
||||
# Переключиться на правильный контекст
|
||||
kubectl config use-context kind-lab
|
||||
```
|
||||
|
||||
### Проблема: Pods не запускаются
|
||||
|
||||
**Симптомы:**
|
||||
- Pods в состоянии Pending
|
||||
- Ошибки в логах pods
|
||||
|
||||
**Решение:**
|
||||
```bash
|
||||
# Проверить статус pods
|
||||
kubectl get pods -A
|
||||
kubectl describe pod <pod-name>
|
||||
|
||||
# Проверить события
|
||||
kubectl get events --sort-by=.metadata.creationTimestamp
|
||||
|
||||
# Проверить ресурсы
|
||||
kubectl top nodes
|
||||
kubectl top pods
|
||||
```
|
||||
|
||||
### Проблема: Istio не устанавливается
|
||||
|
||||
**Симптомы:**
|
||||
- Istio компоненты не запускаются
|
||||
- Ошибки в Istio логах
|
||||
|
||||
**Решение:**
|
||||
```bash
|
||||
# Проверить Istio
|
||||
istioctl version
|
||||
|
||||
# Переустановить Istio
|
||||
istioctl uninstall --purge
|
||||
istioctl install --set profile=demo
|
||||
|
||||
# Проверить статус
|
||||
kubectl get pods -n istio-system
|
||||
```
|
||||
|
||||
## Проблемы с портами
|
||||
|
||||
### Проблема: Порт уже используется
|
||||
|
||||
**Симптомы:**
|
||||
- `bind: address already in use`
|
||||
- Ошибки привязки портов
|
||||
|
||||
**Решение:**
|
||||
```bash
|
||||
# Найти процесс
|
||||
sudo lsof -i :8080
|
||||
|
||||
# Убить процесс
|
||||
sudo kill -9 <PID>
|
||||
|
||||
# Или изменить порт в пресете
|
||||
publish:
|
||||
- "8081:80"
|
||||
```
|
||||
|
||||
### Проблема: Port-forward не работает
|
||||
|
||||
**Симптомы:**
|
||||
- Port-forward не устанавливается
|
||||
- Ошибки подключения
|
||||
|
||||
**Решение:**
|
||||
```bash
|
||||
# Остановить все port-forward
|
||||
make kube-pf-stop
|
||||
|
||||
# Проверить доступность сервиса
|
||||
kubectl get svc -n istio-system
|
||||
|
||||
# Перезапустить port-forward
|
||||
make kiali-port-forward CLUSTER=lab
|
||||
```
|
||||
|
||||
## Проблемы с ресурсами
|
||||
|
||||
### Проблема: Недостаточно памяти
|
||||
|
||||
**Симптомы:**
|
||||
- `Out of memory`
|
||||
- Контейнеры завершаются
|
||||
|
||||
**Решение:**
|
||||
```bash
|
||||
# Проверить память
|
||||
free -h
|
||||
docker stats
|
||||
|
||||
# Ограничить ресурсы
|
||||
docker run --memory=512m your-image
|
||||
|
||||
# Или уменьшить количество контейнеров в пресете
|
||||
```
|
||||
|
||||
### Проблема: Недостаточно CPU
|
||||
|
||||
**Симптомы:**
|
||||
- Медленная работа
|
||||
- Высокая нагрузка на CPU
|
||||
|
||||
**Решение:**
|
||||
```bash
|
||||
# Проверить CPU
|
||||
top
|
||||
htop
|
||||
|
||||
# Ограничить CPU
|
||||
docker run --cpus=1.0 your-image
|
||||
|
||||
# Или использовать более легкие образы
|
||||
```
|
||||
|
||||
### Проблема: Недостаточно места на диске
|
||||
|
||||
**Симптомы:**
|
||||
- `No space left on device`
|
||||
- Ошибки записи
|
||||
|
||||
**Решение:**
|
||||
```bash
|
||||
# Проверить место
|
||||
df -h
|
||||
|
||||
# Очистить Docker
|
||||
docker system prune -a
|
||||
docker volume prune
|
||||
|
||||
# Удалить неиспользуемые образы
|
||||
docker image prune -a
|
||||
```
|
||||
|
||||
## Проблемы с сетью
|
||||
|
||||
### Проблема: Контейнеры не могут связаться
|
||||
|
||||
**Симптомы:**
|
||||
- Ping не работает между контейнерами
|
||||
- Ошибки сети
|
||||
|
||||
**Решение:**
|
||||
```bash
|
||||
# Проверить сеть
|
||||
docker network ls
|
||||
docker network inspect labnet
|
||||
|
||||
# Пересоздать сеть
|
||||
docker network rm labnet
|
||||
docker network create labnet
|
||||
|
||||
# Перезапустить лабораторию
|
||||
make lab-reset
|
||||
```
|
||||
|
||||
### Проблема: DNS не работает
|
||||
|
||||
**Симптомы:**
|
||||
- Не удается разрешить имена
|
||||
- Ошибки DNS
|
||||
|
||||
**Решение:**
|
||||
```bash
|
||||
# Проверить DNS
|
||||
nslookup google.com
|
||||
|
||||
# Перезапустить Docker
|
||||
sudo systemctl restart docker
|
||||
|
||||
# Проверить resolv.conf
|
||||
cat /etc/resolv.conf
|
||||
```
|
||||
|
||||
## Проблемы с Ansible
|
||||
|
||||
### Проблема: Ansible не найден
|
||||
|
||||
**Симптомы:**
|
||||
- `ansible: command not found`
|
||||
- Ошибки выполнения playbook
|
||||
|
||||
**Решение:**
|
||||
```bash
|
||||
# Установить Ansible
|
||||
pip install ansible
|
||||
|
||||
# Или через пакетный менеджер
|
||||
sudo apt-get install ansible
|
||||
|
||||
# Проверить версию
|
||||
ansible --version
|
||||
```
|
||||
|
||||
### Проблема: Ошибки в playbook
|
||||
|
||||
**Симптомы:**
|
||||
- Синтаксические ошибки
|
||||
- Ошибки выполнения задач
|
||||
|
||||
**Решение:**
|
||||
```bash
|
||||
# Проверить синтаксис
|
||||
ansible-playbook --syntax-check playbook.yml
|
||||
|
||||
# Запустить в режиме отладки
|
||||
ansible-playbook -vvv playbook.yml
|
||||
|
||||
# Проверить инвентарь
|
||||
ansible-inventory --list
|
||||
```
|
||||
|
||||
### Проблема: Ошибки подключения
|
||||
|
||||
**Симптомы:**
|
||||
- `Connection refused`
|
||||
- Ошибки SSH
|
||||
|
||||
**Решение:**
|
||||
```bash
|
||||
# Проверить подключение
|
||||
ansible all -m ping
|
||||
|
||||
# Проверить SSH ключи
|
||||
ssh-keygen -t rsa -b 4096
|
||||
ssh-copy-id user@host
|
||||
|
||||
# Или использовать пароль
|
||||
ansible all -m ping -k
|
||||
```
|
||||
|
||||
## Проблемы с Molecule
|
||||
|
||||
### Проблема: Molecule не найден
|
||||
|
||||
**Симптомы:**
|
||||
- `molecule: command not found`
|
||||
- Ошибки выполнения molecule
|
||||
|
||||
**Решение:**
|
||||
```bash
|
||||
# Установить Molecule
|
||||
pip install molecule
|
||||
|
||||
# Или через пакетный менеджер
|
||||
sudo apt-get install molecule
|
||||
|
||||
# Проверить версию
|
||||
molecule --version
|
||||
```
|
||||
|
||||
### Проблема: Ошибки в molecule.yml
|
||||
|
||||
**Симптомы:**
|
||||
- Синтаксические ошибки в конфигурации
|
||||
- Ошибки валидации
|
||||
|
||||
**Решение:**
|
||||
```bash
|
||||
# Проверить синтаксис
|
||||
molecule syntax
|
||||
|
||||
# Проверить конфигурацию
|
||||
molecule lint
|
||||
|
||||
# Исправить ошибки
|
||||
molecule validate
|
||||
```
|
||||
|
||||
### Проблема: Ошибки драйвера
|
||||
|
||||
**Симптомы:**
|
||||
- Ошибки Docker драйвера
|
||||
- Проблемы с контейнерами
|
||||
|
||||
**Решение:**
|
||||
```bash
|
||||
# Проверить драйвер
|
||||
molecule driver list
|
||||
|
||||
# Установить Docker драйвер
|
||||
pip install molecule-docker
|
||||
|
||||
# Перезапустить Molecule
|
||||
molecule destroy
|
||||
molecule create
|
||||
```
|
||||
|
||||
## Проблемы с пресетами
|
||||
|
||||
### Проблема: Пресет не найден
|
||||
|
||||
**Симптомы:**
|
||||
- `File not found`
|
||||
- Ошибки загрузки пресета
|
||||
|
||||
**Решение:**
|
||||
```bash
|
||||
# Проверить путь
|
||||
ls -la molecule/presets/
|
||||
|
||||
# Проверить синтаксис YAML
|
||||
yamllint molecule/presets/your-preset.yml
|
||||
|
||||
# Исправить ошибки
|
||||
molecule validate
|
||||
```
|
||||
|
||||
### Проблема: Ошибки в пресете
|
||||
|
||||
**Симптомы:**
|
||||
- Синтаксические ошибки
|
||||
- Ошибки валидации
|
||||
|
||||
**Решение:**
|
||||
```bash
|
||||
# Проверить синтаксис
|
||||
yamllint molecule/presets/your-preset.yml
|
||||
|
||||
# Проверить структуру
|
||||
molecule validate
|
||||
|
||||
# Исправить ошибки
|
||||
molecule syntax
|
||||
```
|
||||
|
||||
## Проблемы с отчетами
|
||||
|
||||
### Проблема: HTML отчет не генерируется
|
||||
|
||||
**Симптомы:**
|
||||
- `File not found`
|
||||
- Ошибки генерации отчета
|
||||
|
||||
**Решение:**
|
||||
```bash
|
||||
# Проверить JSON файл
|
||||
ls -la reports/
|
||||
cat reports/lab-health.json
|
||||
|
||||
# Перезапустить верификацию
|
||||
make lab-verify
|
||||
|
||||
# Сгенерировать отчет
|
||||
make lab-report
|
||||
```
|
||||
|
||||
### Проблема: Отчет пустой
|
||||
|
||||
**Симптомы:**
|
||||
- Отчет не содержит данных
|
||||
- Ошибки в JSON
|
||||
|
||||
**Решение:**
|
||||
```bash
|
||||
# Проверить JSON
|
||||
jq . reports/lab-health.json
|
||||
|
||||
# Перезапустить тест
|
||||
make lab-test
|
||||
|
||||
# Проверить логи
|
||||
make lab-verify
|
||||
```
|
||||
|
||||
## Полезные команды для диагностики
|
||||
|
||||
### Общие команды
|
||||
|
||||
```bash
|
||||
# Проверить статус системы
|
||||
docker ps
|
||||
docker images
|
||||
docker network ls
|
||||
docker volume ls
|
||||
|
||||
# Проверить ресурсы
|
||||
free -h
|
||||
df -h
|
||||
top
|
||||
|
||||
# Проверить сеть
|
||||
netstat -tulpn
|
||||
ss -tulpn
|
||||
```
|
||||
|
||||
### Команды для Kubernetes
|
||||
|
||||
```bash
|
||||
# Проверить кластеры
|
||||
kind get clusters
|
||||
kubectl config get-contexts
|
||||
|
||||
# Проверить ресурсы
|
||||
kubectl get nodes
|
||||
kubectl get pods -A
|
||||
kubectl get svc -A
|
||||
|
||||
# Проверить события
|
||||
kubectl get events --sort-by=.metadata.creationTimestamp
|
||||
```
|
||||
|
||||
### Команды для Ansible
|
||||
|
||||
```bash
|
||||
# Проверить инвентарь
|
||||
ansible-inventory --list
|
||||
ansible all -m ping
|
||||
|
||||
# Проверить playbook
|
||||
ansible-playbook --syntax-check playbook.yml
|
||||
ansible-playbook --check playbook.yml
|
||||
```
|
||||
|
||||
## Получение помощи
|
||||
|
||||
Если проблема не решается:
|
||||
|
||||
1. **Проверьте логи:**
|
||||
```bash
|
||||
docker logs <container-name>
|
||||
kubectl logs <pod-name>
|
||||
```
|
||||
|
||||
2. **Создайте issue:**
|
||||
- Опишите проблему
|
||||
- Приложите логи
|
||||
- Укажите версии компонентов
|
||||
|
||||
3. **Обратитесь к сообществу:**
|
||||
- GitHub Discussions
|
||||
- Discord/Slack каналы
|
||||
- Форумы Ansible
|
||||
|
||||
4. **Проверьте документацию:**
|
||||
- [Основная документация](universal-lab.md)
|
||||
- [Примеры использования](examples.md)
|
||||
- [API Reference](api.md)
|
||||
Reference in New Issue
Block a user