From eca556cca77e347736e5f22a18b0eb891180454c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=D0=A1=D0=B5=D1=80=D0=B3=D0=B5=D0=B9=20=D0=90=D0=BD=D1=82?=
 =?UTF-8?q?=D1=80=D0=BE=D0=BF=D0=BE=D0=B2?=
 <inecs@MacBook-Air-Sergej-3.local>
Date: Sun, 26 Oct 2025 10:23:16 +0300
Subject: [PATCH] =?UTF-8?q?docs:=20=D0=BF=D0=BE=D0=BB=D0=BD=D0=B0=D1=8F=20?=
 =?UTF-8?q?=D0=BF=D0=B5=D1=80=D0=B5=D1=80=D0=B0=D0=B1=D0=BE=D1=82=D0=BA?=
 =?UTF-8?q?=D0=B0=20=D0=B4=D0=BE=D0=BA=D1=83=D0=BC=D0=B5=D0=BD=D1=82=D0=B0?=
 =?UTF-8?q?=D1=86=D0=B8=D0=B8=20=D0=BF=D0=BE=20Kubernetes?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Создана подробная документация по скриптам (k8s-scripts.md)
- Полностью переписана документация kubernetes-kind.md
- Добавлено содержание с навигацией
- Добавлены разделы: Helm, манифесты, Ingress, port-forward
- Добавлена архитектура взаимодействия
- Добавлены Best Practices и Troubleshooting
- Обновлена справка в Makefile
- Удалены устаревшие команды (manifest update, addon)
- Добавлена ссылка на документацию по скриптам
---
 Makefile                |   54 +-
 docs/k8s-scripts.md     |  275 ++++++++++
 docs/kubernetes-kind.md | 1125 +++++++++++++++++++++------------------
 3 files changed, 889 insertions(+), 565 deletions(-)
 create mode 100644 docs/k8s-scripts.md

diff --git a/Makefile b/Makefile
index aa4b2f9..d921a22 100644
--- a/Makefile
+++ b/Makefile
@@ -1160,32 +1160,6 @@ k8s:
 				echo "❌ Не удалось получить kubeconfig"; \
 				rm -f $$KUBECONFIG_FILE; \
 			fi;; \
-		addon) \
-			echo "📦 Установка аддона..."; \
-			PRESET_ARG="$(word 3, $(MAKECMDGOALS))"; \
-			MANIFEST_ARG="$(word 4, $(MAKECMDGOALS))"; \
-			if [ -z "$$PRESET_ARG" ]; then \
-				echo "❌ Ошибка: Укажите пресет"; \
-				echo "💡 Пример: make k8s addon kubernetes https://example.com/manifest.yaml"; \
-				exit 1; \
-			fi; \
-			if [ -z "$$MANIFEST_ARG" ]; then \
-				echo "❌ Ошибка: Укажите URL манифеста"; \
-				echo "💡 Пример: make k8s addon kubernetes https://example.com/manifest.yaml"; \
-				exit 1; \
-			fi; \
-			CONTAINER_NAME=k8s-controller; \
-			if ! docker ps | grep -q $$CONTAINER_NAME; then \
-				echo "❌ Контейнер $$CONTAINER_NAME не запущен"; \
-				echo "💡 Запустите: make k8s create $$PRESET_ARG"; \
-				exit 1; \
-			fi; \
-			CLUSTER_NAME=$$(docker exec $$CONTAINER_NAME kind get clusters | head -1); \
-			echo "📥 Установка аддона из $$MANIFEST_ARG..."; \
-			docker exec $$CONTAINER_NAME bash -c "CLUSTER_NAME=$$CLUSTER_NAME; kubectl --server=https://\$${CLUSTER_NAME}-control-plane:6443 --insecure-skip-tls-verify apply -f $$MANIFEST_ARG"; \
-			echo "✅ Аддон установлен"; \
-			echo "📝 Обновление Ingress хостов..."; \
-			sudo scripts/manage_hosts.py add 2>/dev/null || echo "⚠️  Не удалось обновить Ingress хосты (требуется sudo)";; \
 		nodes) \
 			echo "🖥️  Просмотр узлов кластера..."; \
 			PRESET_ARG="$(word 3, $(MAKECMDGOALS))"; \
@@ -1245,14 +1219,9 @@ k8s:
 					docker exec $$CONTAINER_NAME bash -c "CLUSTER_NAME=$$CLUSTER_NAME; kubectl --server=https://\$${CLUSTER_NAME}-control-plane:6443 --insecure-skip-tls-verify delete -f $$MANIFEST_ARG"; \
 					echo "📝 Обновление Ingress хостов..."; \
 					sudo scripts/manage_hosts.py add 2>/dev/null || echo "⚠️  Не удалось обновить Ingress хосты (требуется sudo)";; \
-				update) \
-					echo "🔄 Обновление манифеста: $$MANIFEST_ARG"; \
-					docker exec $$CONTAINER_NAME bash -c "CLUSTER_NAME=$$CLUSTER_NAME; kubectl --server=https://\$${CLUSTER_NAME}-control-plane:6443 --insecure-skip-tls-verify apply -f $$MANIFEST_ARG --force"; \
-					echo "📝 Обновление Ingress хостов..."; \
-					sudo scripts/manage_hosts.py add 2>/dev/null || echo "⚠️  Не удалось обновить Ingress хосты (требуется sudo)";; \
 				*) \
 					echo "❌ Неизвестная команда: $$MANIFEST_CMD"; \
-					echo "💡 Доступные команды: apply, delete, update"; \
+					echo "💡 Доступные команды: apply, delete"; \
 					exit 1;; \
 			esac;; \
 		helm) \
@@ -1433,17 +1402,15 @@ k8s:
 			echo "  make k8s start [cluster]       - запустить остановленный кластер"; \
 			echo "     💡 Можно указать имя кластера или запустить все"; \
 			echo ""; \
-			echo "  make k8s status [cluster]      - показать статус кластеров"; \
-			echo "     💡 Можно указать имя конкретного кластера"; \
+			echo "  make k8s status [preset]      - детальный отчет о состоянии кластера"; \
+			echo "     💡 Показывает: узлы, pods, сервисы, Ingress, события, Helm релизы и т.д."; \
+			echo "     💡 Требует: пресет"; \
+			echo "     💡 Пример: make k8s status kubernetes"; \
 			echo ""; \
 			echo "  make k8s config [cluster]      - получить kubeconfig для подключения"; \
 			echo "     💡 Сохраняет: kubeconfig в корне проекта"; \
 			echo "     💡 Можно указать имя конкретного кластера"; \
 			echo ""; \
-			echo "  make k8s addon [preset] [url]  - установить аддон из манифеста"; \
-			echo "     💡 Требует: пресет и URL манифеста"; \
-			echo "     💡 Пример: make k8s addon kubernetes https://example.com/manifest.yaml"; \
-			echo ""; \
 			echo "  make k8s nodes [preset]        - показать узлы кластера"; \
 			echo "     💡 Требует: пресет"; \
 			echo "     💡 Пример: make k8s nodes kubernetes"; \
@@ -1453,7 +1420,7 @@ k8s:
 			echo "     💡 Пример: make k8s shell kubernetes"; \
 			echo ""; \
 			echo "  make k8s manifest [cmd] [preset] [url] - работа с манифестами"; \
-			echo "     💡 Команды: apply, delete, update"; \
+			echo "     💡 Команды: apply, delete"; \
 			echo "     💡 Пример: make k8s manifest apply kubernetes https://example.com/deploy.yaml"; \
 			echo ""; \
 			echo "  make k8s helm [cmd] [preset] [release] [chart] - работа с Helm"; \
@@ -1475,7 +1442,7 @@ k8s:
 			echo "   make k8s config kubernetes     # получить kubeconfig для кластера"; \
 			echo "   export KUBECONFIG=kubeconfig   # использовать конфиг"; \
 			echo "   kubectl get nodes              # проверить узлы"; \
-			echo "   make k8s addon kubernetes https://example.com/manifest.yaml  # установить аддон"; \
+			echo "   make k8s manifest apply kubernetes https://example.com/manifest.yaml  # установить манифест"; \
 			echo "   make k8s stop kubernetes       # остановить кластер"; \
 			echo "   make k8s start kubernetes      # запустить кластер"; \
 			echo "   make k8s destroy kubernetes    # удалить кластер с пресетом kubernetes";; \
@@ -1579,10 +1546,13 @@ help:
 	@echo "  make k8s destroy [preset]   - удалить Kind кластер"
 	@echo "  make k8s start [preset]     - запустить Kind кластер"
 	@echo "  make k8s stop [preset]      - остановить Kind кластер"
-	@echo "  make k8s status [preset]    - показать статус кластера"
+	@echo "  make k8s status [preset]    - детальный отчет о состоянии кластера"
 	@echo "  make k8s nodes [preset]     - показать узлы кластера"
 	@echo "  make k8s config [preset]    - получить kubeconfig для подключения"
-	@echo "  make k8s addon [preset] [url] - установить аддон из манифеста"
+	@echo "  make k8s manifest [cmd] [preset] [url] - работа с манифестами (apply, delete)"
+	@echo "  make k8s helm [cmd] [preset] [release] [chart] - работа с Helm"
+	@echo "  make k8s helmrepo [cmd] [preset] [name] [url] - управление Helm репозиториями"
+	@echo "  make k8s portforward [cmd] - управление port-forward (create, list, clear)"
 	@echo "  make k8s shell [preset]     - открыть shell в контейнере k8s"
 	@echo ""
 	@echo "💡 ПРИМЕРЫ ИСПОЛЬЗОВАНИЯ:"
diff --git a/docs/k8s-scripts.md b/docs/k8s-scripts.md
new file mode 100644
index 0000000..c57c976
--- /dev/null
+++ b/docs/k8s-scripts.md
@@ -0,0 +1,275 @@
+# Скрипты управления Kubernetes
+
+**Автор:** Сергей Антропов  
+**Сайт:** https://devops.org.ru
+
+## Обзор
+
+В проекте используются несколько Python скриптов для автоматизации работы с Kubernetes кластерами на базе Kind. Все скрипты находятся в директории `scripts/`.
+
+## Скрипты
+
+### 1. `create_k8s_cluster.py`
+
+**Назначение:** Создание Kind кластера, установка аддонов и создание Docker контейнеров из пресета.
+
+**Принцип работы:**
+
+1. **Парсинг пресета:** Читает YAML файл пресета (например, `molecule/presets/k8s/kubernetes.yml`)
+
+2. **Создание Docker сети:** 
+   - Проверяет наличие сети (по умолчанию `labnet`)
+   - Создает сеть если её нет
+
+3. **Создание Docker контейнеров:**
+   - Читает секцию `hosts` из пресета
+   - Для каждого хоста создает Docker контейнер с настройками из `systemd_defaults`
+   - Использует образы из секции `images`
+
+4. **Создание Kind кластера:**
+   - Генерирует конфигурацию Kind в формате YAML
+   - Настраивает `extraPortMappings` для Ingress портов
+   - Создает кластер через команду `kind create cluster`
+
+5. **Установка аддонов:**
+   - **Ingress NGINX:** Устанавливает ingress-nginx controller через kubectl apply
+   - **Metrics Server:** Устанавливает metrics-server с патчем для insecure TLS
+   - **Istio:** Устанавливает Istio через istioctl с профилем demo
+   - **Kiali:** Устанавливает Kiali через Helm (использует Helm chart)
+   - **Prometheus Stack:** Устанавливает Prometheus + Grafana через Helm (kube-prometheus-stack)
+
+6. **Подключение к сети Kind:** Подключает контейнер `k8s-controller` к сети `kind` для доступа к API серверу
+
+**Параметры:**
+```bash
+python3 scripts/create_k8s_cluster.py <preset_file> <container_name>
+```
+
+**Пример:**
+```bash
+python3 scripts/create_k8s_cluster.py molecule/presets/k8s/kubernetes.yml k8s-controller
+```
+
+---
+
+### 2. `delete_hosts.py`
+
+**Назначение:** Удаление Docker контейнеров, созданных из секции `hosts` пресета.
+
+**Принцип работы:**
+
+1. **Парсинг пресета:** Читает YAML файл пресета
+2. **Получение списка хостов:** Извлекает секцию `hosts`
+3. **Удаление контейнеров:** Для каждого хоста выполняет `docker rm -f <host_name>`
+
+**Параметры:**
+```bash
+python3 scripts/delete_hosts.py <preset_file>
+```
+
+**Пример:**
+```bash
+python3 scripts/delete_hosts.py molecule/presets/k8s/kubernetes.yml
+```
+
+---
+
+### 3. `portforward.py`
+
+**Назначение:** Управление port-forward для доступа к сервисам Kubernetes извне кластера.
+
+**Принцип работы:**
+
+1. **Загрузка пресета:** Читает файл `molecule/presets/k8s/kubernetes.yml`
+
+2. **Получение kubeconfig:**
+   - Копирует kubeconfig из контейнера `k8s-controller` через `docker exec`
+   - Сохраняет во временный файл
+
+3. **Модификация kubeconfig:**
+   - Заменяет `server: https://0.0.0.0:6443` на `server: https://localhost:6443`
+   - Это необходимо для доступа с локальной машины
+
+4. **Создание port-forward:**
+   - Запускает `kubectl port-forward` для каждого сервиса из `addon_ports`
+   - Использует формат: `kubectl port-forward -n <namespace> svc/<service> <local_port>:<remote_port>`
+   - Управляет процессами через PID
+
+**Команды:**
+- `create` - создает port-forward для всех сервисов
+- `list` - показывает список активных портов
+- `clear` - останавливает все port-forward процессы
+- `recreate` - очищает и заново создает port-forward
+- `delete <port>` - удаляет конкретный port-forward
+
+**Пример использования:**
+```bash
+python3 scripts/portforward.py create
+python3 scripts/portforward.py list
+python3 scripts/portforward.py delete 3000
+python3 scripts/portforward.py clear
+```
+
+**Важно:** Скрипт должен запускаться на локальной машине, где установлены `kubectl` и Python 3.
+
+---
+
+### 4. `manage_hosts.py`
+
+**Назначение:** Автоматическое управление записями в `/etc/hosts` для Ingress ресурсов.
+
+**Принцип работы:**
+
+1. **Получение списка Ingress:**
+   - Получает kubeconfig из контейнера `k8s-controller`
+   - Выполняет `kubectl get ingress --all-namespaces`
+   - Извлекает все хосты из Ingress правил
+
+2. **Работа с /etc/hosts:**
+   - Использует метку `#k8s` для различения автоматических и ручных записей
+   - Добавляет записи в формате: `127.0.0.1 <hostname> #k8s`
+   - Удаляет только записи с меткой `#k8s`
+
+3. **Автоматизация:**
+   - Вызывается автоматически после:
+     - `make k8s create` (добавление)
+     - `make k8s destroy` (удаление)
+     - `make k8s manifest apply/delete` (обновление)
+     - `make k8s helm apply/delete/update` (обновление)
+
+**Команды:**
+- `add` - добавляет все Ingress хосты в /etc/hosts
+- `remove` - удаляет все записи с меткой #k8s
+- `cleanup` - удаляет записи если кластер недоступен
+- `list` - показывает текущие k8s записи
+
+**Пример использования:**
+```bash
+sudo python3 scripts/manage_hosts.py add
+sudo python3 scripts/manage_hosts.py list
+sudo python3 scripts/manage_hosts.py remove
+```
+
+**Безопасность:**
+- Работает только с записями, помеченными `#k8s`
+- Не трогает ручные записи пользователя
+- Требует sudo для редактирования `/etc/hosts`
+
+---
+
+### 5. `k8s_status.py`
+
+**Назначение:** Детальный отчет о состоянии Kubernetes кластера.
+
+**Принцип работы:**
+
+1. **Подключение к кластеру:**
+   - Получает имя кластера через `kind get clusters`
+   - Формирует адрес API сервера: `https://<cluster_name>-control-plane:6443`
+   - Выполняет все kubectl команды через `docker exec k8s-controller`
+
+2. **Сбор информации:**
+   - **Общая информация:** версия Kubernetes
+   - **Узлы:** статус, ресурсы, описание каждого узла
+   - **Namespaces:** список всех namespace
+   - **Использование ресурсов:** метрики через metrics-server (если установлен)
+   - **Pods:** поды по каждому namespace
+   - **Deployments:** deployments по namespace
+   - **DaemonSets:** daemonsets по namespace
+   - **StatefulSets:** statefulsets по namespace
+   - **Services:** сервисы по namespace
+   - **Ingress:** ingress ресурсы
+   - **PVC:** PersistentVolumeClaims
+   - **События:** последние 20 событий по namespace
+   - **Helm релизы:** список установленных через Helm
+
+3. **Форматирование вывода:**
+   - Использует секции с разделителями
+   - Группирует информацию по namespace
+   - Показывает только непустые секции
+
+**Пример использования:**
+```bash
+python3 scripts/k8s_status.py
+```
+
+**Интеграция:**
+- Автоматически вызывается командой `make k8s status [preset]`
+
+**Особенности:**
+- Выполняет все команды внутри контейнера `k8s-controller`
+- Использует прямой адрес control-plane для подключения
+- Обходит проблемы с kubeconfig через `--insecure-skip-tls-verify`
+
+---
+
+## Архитектура взаимодействия
+
+```
+┌─────────────────────────────────────────────────────┐
+│                Локальная машина                     │
+│                                                     │
+│  Makefile → Python скрипты → Docker API            │
+│     ↓                    ↓             ↓           │
+│  make k8s    scripts/*.py   docker exec             │
+└─────────────────────────────────────────────────────┘
+                        │
+                        ↓
+┌─────────────────────────────────────────────────────┐
+│              Docker контейнер                       │
+│         k8s-controller                              │
+│  ┌──────────────────────────────────────────┐     │
+│  │ kind, kubectl, helm, istioctl             │     │
+│  └──────────────────────────────────────────┘     │
+└─────────────────────────────────────────────────────┘
+                        │
+                        ↓
+┌─────────────────────────────────────────────────────┐
+│            Docker сеть: kind                        │
+│  ┌──────────────────────────────────────────┐     │
+│  │         Kind Kubernetes Cluster          │     │
+│  │  • Control Plane (6443)                   │     │
+│  │  • Worker Nodes                           │     │
+│  │  • Services (ClusterIP)                   │     │
+│  │  • Ingress                                │     │
+│  └──────────────────────────────────────────┘     │
+└─────────────────────────────────────────────────────┘
+```
+
+## Общие принципы
+
+1. **Изоляция:** Все kubectl команды выполняются внутри контейнера `k8s-controller`
+2. **Безопасность:** Используется `--insecure-skip-tls-verify` для обхода проблем с сертификатами
+3. **Автоматизация:** Скрипты вызываются автоматически через Makefile
+4. **Логгирование:** Все скрипты выводят подробную информацию о своих действиях
+
+## Требования
+
+- Python 3 (на локальной машине)
+- kubectl (на локальной машине, для portforward.py)
+- Docker
+- Docker контейнер `k8s-controller` должен быть запущен
+
+## Отладка
+
+Если что-то не работает:
+
+1. **Проверьте контейнер:**
+   ```bash
+   docker ps | grep k8s-controller
+   ```
+
+2. **Запустите скрипт вручную:**
+   ```bash
+   python3 scripts/k8s_status.py
+   ```
+
+3. **Посмотрите логи:**
+   ```bash
+   docker logs k8s-controller
+   ```
+
+4. **Проверьте кластер:**
+   ```bash
+   docker exec k8s-controller kubectl get nodes
+   ```
diff --git a/docs/kubernetes-kind.md b/docs/kubernetes-kind.md
index 5ea794a..c7f576d 100644
--- a/docs/kubernetes-kind.md
+++ b/docs/kubernetes-kind.md
@@ -3,91 +3,150 @@
 **Автор:** Сергей Антропов  
 **Сайт:** https://devops.org.ru
 
+## Содержание
+
+- [Описание](#описание)
+- [Требования к системе](#требования-к-системе)
+- [Возможности](#возможности)
+- [Быстрый старт](#быстрый-старт)
+- [Команды управления](#команды-управления)
+- [Работа с Helm](#работа-с-helm)
+- [Работа с манифестами](#работа-с-манифестами)
+- [Управление Ingress](#управление-ingress)
+- [Проброс портов (Port-forward)](#проброс-портов-port-forward)
+- [Мониторинг и логи](#мониторинг-и-логи)
+- [Конфигурация](#конфигурация)
+- [Архитектура](#архитектура)
+- [Доступ к приложениям](#доступ-к-приложениям)
+- [Кроссплатформенность](#кроссплатформенность)
+- [Подробная документация по скриптам](#подробная-документация-по-скриптам)
+- [Best Practices](#best-practices)
+- [Troubleshooting](#troubleshooting)
+
+---
+
 ## Описание
 
 Проект поддерживает автоматическое создание и управление Kubernetes кластерами на базе [Kind](https://kind.sigs.k8s.io/) для тестирования в изолированной лабораторной среде.
 
+Kind позволяет создавать локальные Kubernetes кластеры внутри Docker контейнеров, что идеально подходит для разработки и тестирования без необходимости устанавливать полный Kubernetes.
+
 ## Требования к системе
 
-Для работы с Kubernetes кластерами **на локальной машине** требуется установить:
+### Обязательные требования
 
-### 1. Python 3
+1. **Docker** - для запуска Kind кластеров
+2. **Python 3** - для управления port-forward
+3. **kubectl** - для работы с кластером
 
-Port-forward управляется Python скриптом. Установите Python 3:
-
-**macOS:**
+**Установка на macOS:**
 ```bash
-brew install python3
+brew install docker python3 kubectl
 ```
 
-**Ubuntu/Debian:**
+**Установка на Ubuntu/Debian:**
 ```bash
-sudo apt update && sudo apt install -y python3 python3-pip
+sudo apt update && sudo apt install -y docker.io python3 python3-pip kubectl
 ```
 
-**CentOS/RHEL:**
+**Установка на CentOS/RHEL:**
 ```bash
-sudo yum install -y python3 python3-pip
+sudo yum install -y docker python3 python3-pip kubectl
+sudo systemctl start docker
+sudo systemctl enable docker
 ```
 
-### 2. kubectl
+### Проверка установки
 
-`kubectl` используется для port-forward и работы с кластером. Установите kubectl:
-
-**macOS:**
-```bash
-brew install kubectl
-```
-
-**Linux:**
-```bash
-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/
-```
-
-**Проверка установки:**
 ```bash
+docker --version
 python3 --version
 kubectl version --client
 ```
 
+### Docker группы
+
+На Linux добавьте пользователя в группу docker:
+```bash
+sudo usermod -aG docker $USER
+# Выйдите и войдите заново
+```
+
+---
+
 ## Возможности
 
 - ✅ Создание Kind кластеров с настраиваемым количеством worker-узлов
 - ✅ Автоматическая установка аддонов (Ingress NGINX, Metrics Server, Istio, Kiali, Prometheus Stack)
-- ✅ **Автоматический port-forward** для доступа к аддонам
-- ✅ Работа с Helm (установка, удаление, обновление чартов)
+- ✅ **Автоматический port-forward** для доступа к сервисам
+- ✅ Работа с Helm (установка, удаление, обновление, rollback)
 - ✅ Работа с Kubernetes манифестами
+- ✅ Управление Helm репозиториями
+- ✅ Автоматическое управление `/etc/hosts` для Ingress
 - ✅ Управление Docker контейнерами в лабораторной сети
 - ✅ Интеграция с Istio Service Mesh
+- ✅ Детальный отчет о состоянии кластера
 
-## Команды
+---
+
+## Быстрый старт
+
+### 1. Создание кластера
+
+```bash
+# Создание кластера с полным набором аддонов
+make k8s create kubernetes
+```
+
+### 2. Проверка статуса
+
+```bash
+# Детальный отчет о кластере
+make k8s status kubernetes
+```
+
+### 3. Доступ к аддонам
+
+После создания кластера автоматически создаются port-forward:
+- Grafana: http://localhost:3000
+- Prometheus: http://localhost:9090
+- Kiali: http://localhost:20001
+
+### 4. Удаление кластера
+
+```bash
+make k8s destroy kubernetes
+```
+
+---
+
+## Команды управления
 
 ### Создание кластера
 
 ```bash
-# Создание минимального кластера (без аддонов)
+# Минимальный кластер (без аддонов)
 make k8s create
 
-# Создание кластера с полным набором аддонов
+# Полный кластер с аддонами
 make k8s create kubernetes
 
-# Использование пользовательского пресета
+# Пользовательский пресет
 make k8s create my-custom-preset
 ```
 
-**Что происходит при создании:**
-1. Создается Docker контейнер `k8s-controller` с Kind, kubectl, Helm, Istio CLI
-2. Создаются Docker контейнеры из раздела `hosts` пресета (если есть)
-3. Создается Kind кластер с настройками из пресета
-4. Устанавливаются аддоны (Ingress, Metrics Server, Istio, Kiali, Prometheus)
-5. **Автоматически создается port-forward** для доступа к сервисам
+**Что происходит:**
+1. Создается контейнер `k8s-controller` с инструментами (Kind, kubectl, Helm, Istio CLI)
+2. Создаются Docker контейнеры из раздела `hosts` (если есть)
+3. Создается Kind кластер
+4. Устанавливаются аддоны
+5. Создается автоматический port-forward
+6. Добавляются записи в `/etc/hosts` для Ingress
 
-### Управление кластером
+### Управление жизненным циклом
 
 ```bash
-# Удаление кластера (с автоматической очисткой port-forward)
+# Удаление кластера (с очисткой port-forward и /etc/hosts)
 make k8s destroy [preset]
 
 # Остановка кластера (без удаления)
@@ -96,615 +155,635 @@ make k8s stop [preset]
 # Запуск остановленного кластера
 make k8s start [preset]
 
-# Проверка статуса кластера
+# Детальный отчет о состоянии
 make k8s status [preset]
 
-# Получение kubeconfig для подключения
-make k8s config [preset]
-
-# Открытие shell в контейнере k8s-controller
-make k8s shell [preset]
-
-# Просмотр узлов кластера
+# Показать узлы кластера
 make k8s nodes [preset]
 ```
 
-### Port-Forward (Проброс портов)
-
-Port-forward **создается автоматически** при создании кластера и **удаляется автоматически** при его уничтожении.
+### Получение kubeconfig
 
 ```bash
-# Создать port-forward для всех сервисов из preset
-make k8s portforward create [preset]
+# Сохранить kubeconfig для подключения
+make k8s config [preset]
 
-# Просмотреть активные port-forward
-make k8s portforward list
-
-# Удалить конкретный port-forward по порту
-make k8s portforward delete [port]
-
-# Удалить все port-forward
-make k8s portforward clear
-
-# Пересоздать все port-forward (очистить + создать)
-make k8s portforward recreate
+# Использовать конфиг
+export KUBECONFIG=kubeconfig
+kubectl get nodes
 ```
 
-**Порты по умолчанию:**
-- **Prometheus:** 9090
-- **Grafana:** 3000
-- **Kiali:** 20001
-- **Ingress HTTP:** 8081
-- **Ingress HTTPS:** 8443
-- **Metrics Server:** 4443
-
-### Установка аддонов из манифестов
+### Shell доступ
 
 ```bash
-# Установить аддон из URL манифеста
-make k8s addon [preset] [manifest_url]
-
-# Пример: установить MetalLB
-make k8s addon kubernetes https://raw.githubusercontent.com/metallb/metallb/v0.13.12/config/manifests/metallb-native.yaml
+# Открыть shell в контейнере k8s-controller
+make k8s shell [preset]
 ```
 
-### Работа с манифестами
+---
+
+## Работа с Helm
+
+Helm - это менеджер пакетов для Kubernetes.
+
+### Управление релизами
 
 ```bash
-# Применить манифест
-make k8s manifest apply [preset] [manifest_url_or_path]
+# Установить чарт
+make k8s helm apply kubernetes nginx stable/nginx-ingress
 
-# Удалить ресурсы из манифеста
-make k8s manifest delete [preset] [manifest_url_or_path]
+# Обновить релиз
+make k8s helm update kubernetes nginx stable/nginx-ingress
 
-# Обновить манифест (apply с --force)
-make k8s manifest update [preset] [manifest_url_or_path]
+# Откатить релиз
+make k8s helm rollback kubernetes nginx
 
-# Примеры:
-make k8s manifest apply kubernetes https://example.com/app.yaml
-make k8s manifest apply kubernetes ./manifests/my-app.yaml
-make k8s manifest delete kubernetes ./manifests/my-app.yaml
-```
+# Посмотреть статус релиза
+make k8s helm status kubernetes nginx
 
-### Работа с Helm
+# Удалить релиз
+make k8s helm delete kubernetes nginx
 
-#### Установка и управление релизами
-
-```bash
-# Установить Helm chart
-make k8s helm apply [preset] [release_name] [chart_name]
-
-# Удалить Helm release
-make k8s helm delete [preset] [release_name]
-
-# Обновить Helm release
-make k8s helm update [preset] [release_name] [chart_name]
-
-# Откатить Helm release к предыдущей версии
-make k8s helm rollback [preset] [release_name]
-
-# Список всех Helm releases
-make k8s helm list [preset]
-
-# Статус конкретного Helm release
-make k8s helm status [preset] [release_name]
-
-# Примеры:
-make k8s helm apply kubernetes my-app bitnami/nginx
-make k8s helm status kubernetes my-app
+# Список всех релизов
 make k8s helm list kubernetes
-make k8s helm rollback kubernetes my-app
 ```
 
-#### Управление Helm репозиториями
+### Управление репозиториями
 
 ```bash
-# Добавить Helm репозиторий
-make k8s helmrepo add [preset] [repo_name] [repo_url]
+# Добавить репозиторий
+make k8s helmrepo add kubernetes stable https://charts.helm.sh/stable
 
-# Список Helm репозиториев
-make k8s helmrepo list [preset]
+# Обновить репозиторий
+make k8s helmrepo update kubernetes stable
 
-# Удалить Helm репозиторий
-make k8s helmrepo delete [preset] [repo_name]
-
-# Обновить Helm репозитории
-make k8s helmrepo update [preset]
-
-# Список пакетов (charts) в репозитории
-make k8s helmrepo packages [preset] [repo_name]
-
-# Примеры:
-make k8s helmrepo add kubernetes bitnami https://charts.bitnami.com/bitnami
+# Список репозиториев
 make k8s helmrepo list kubernetes
-make k8s helmrepo packages kubernetes bitnami
-make k8s helmrepo update kubernetes
+
+# Показать доступные чарты
+make k8s helmrepo packages kubernetes stable
+
+# Удалить репозиторий
+make k8s helmrepo delete kubernetes stable
 ```
 
-## Конфигурация
+### Пример: установка MySQL
 
-### Пресеты Kubernetes хранятся в `molecule/presets/k8s/`
+```bash
+# Добавить репозиторий Bitnami
+make k8s helmrepo add kubernetes bitnami https://charts.bitnami.com/bitnami
 
-#### Минимальный кластер (`k8s-minimal.yml`)
+# Установить MySQL
+make k8s helm apply kubernetes mysql bitnami/mysql
+
+# Проверить статус
+make k8s helm status kubernetes mysql
+```
+
+---
+
+## Работа с манифестами
+
+Применение обычных Kubernetes манифестов (без Helm).
+
+```bash
+# Применить манифест из URL
+make k8s manifest apply kubernetes https://example.com/deploy.yaml
+
+# Применить манифест из файла
+make k8s manifest apply kubernetes /path/to/manifest.yaml
+
+# Удалить манифест
+make k8s manifest delete kubernetes https://example.com/deploy.yaml
+```
+
+### Пример: создание Deployment
 
 ```yaml
-kind_clusters:
-  - name: minimal
-    workers: 0  # Только control-plane узел
-    api_port: 6443
+# nginx-deployment.yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: nginx
+spec:
+  replicas: 3
+  selector:
+    matchLabels:
+      app: nginx
+  template:
+    metadata:
+      labels:
+        app: nginx
+    spec:
+      containers:
+      - name: nginx
+        image: nginx:latest
+        ports:
+        - containerPort: 80
 ```
 
-#### Полный кластер с аддонами (`kubernetes.yml`)
+```bash
+# Применить
+make k8s manifest apply kubernetes ./nginx-deployment.yaml
+```
+
+---
+
+## Управление Ingress
+
+### Автоматическое управление /etc/hosts
+
+При создании Ingress ресурсов, их хосты автоматически добавляются в `/etc/hosts` с меткой `#k8s`:
 
 ```yaml
-kind_clusters:
-  - name: lab
-    workers: 2
-    api_port: 6443
-    addons:
-      ingress_nginx: true
-      metrics_server: true
-      istio: true
-      kiali: true
-      prometheus_stack: true
-    # Порты для port-forward
-    addon_ports:
-      ingress_http: 8081
-      ingress_https: 8443
-      prometheus: 9090
-      grafana: 3000
-      kiali: 20001
-      metrics_server: 4443
-```
-
-## Доступ к аддонам
-
-После создания кластера с аддонами, они доступны через **автоматический port-forward**:
-
-### Prometheus
-```bash
-# Web UI доступна на порту 9090
-http://localhost:9090
-```
-
-### Grafana
-```bash
-# Web UI доступна на порту 3000
-http://localhost:3000
-
-# Пароль администратора
-kubectl get secret -n monitoring monitoring-grafana \
-  -o jsonpath="{.data.admin-password}" | base64 -d
-
-# Логин: admin
-# Пароль: (получен выше)
-```
-
-### Kiali
-```bash
-# Web UI доступна на порту 20001
-http://localhost:20001
-
-# Аутентификация: anonymous (отключена по умолчанию)
-```
-
-### Istio Ingress
-```bash
-# HTTP доступен на порту 8081
-http://localhost:8081
-
-# HTTPS доступен на порту 8443
-https://localhost:8443
-```
-
-## Доступ к приложениям
-
-### Доступ через Ingress
-
-Если ваше приложение использует Ingress с доменным именем:
-
-1. **Создайте манифест с Ingress:**
-
-```yaml
-# my-app-ingress.yaml
 apiVersion: networking.k8s.io/v1
 kind: Ingress
 metadata:
-  name: my-app-ingress
+  name: grafana-ingress
+  namespace: monitoring
 spec:
   rules:
-  - host: my-app.local
+  - host: grafana.local
     http:
       paths:
       - path: /
         pathType: Prefix
         backend:
           service:
-            name: my-app-service
+            name: monitoring-grafana
             port:
               number: 80
 ```
 
-2. **Примените манифест:**
-
-```bash
-make k8s manifest apply kubernetes my-app-ingress.yaml
+После применения этого манифеста в `/etc/hosts` автоматически добавится:
+```
+127.0.0.1 grafana.local #k8s
 ```
 
-3. **Добавьте домен в hosts файл:**
+### Доступ к приложению
 
-**macOS/Linux:**
-```bash
-echo "127.0.0.1 my-app.local" | sudo tee -a /etc/hosts
+После установки Ingress и портов, приложение доступно по адресу:
+```
+http://grafana.local
 ```
 
-4. **Откройте приложение через Ingress порт:**
+### Удаление записей
+
+Записи автоматически удаляются при:
+- Удалении кластера (`make k8s destroy`)
+- Удалении Ingress манифеста (`make k8s manifest delete`)
+
+---
+
+## Проброс портов (Port-forward)
+
+Port-forward позволяет получить доступ к ClusterIP сервисам извне кластера.
+
+### Автоматический port-forward
+
+После создания кластера автоматически создаются порты:
+- Ingress HTTP: `8081:80`
+- Ingress HTTPS: `8443:443`
+- Grafana: `3000:80`
+- Prometheus: `9090:9090`
+- Kiali: `20001:20001`
+
+### Управление вручную
 
 ```bash
-# HTTP через Ingress
-curl http://my-app.local:8081
-# или в браузере
-open http://my-app.local:8081
+# Создать port-forward
+make k8s portforward create
 
-# HTTPS через Ingress
-curl -k https://my-app.local:8443
-```
-
-**Важно:** Используйте порт Ingress (8081 для HTTP, 8443 для HTTPS) вместе с доменным именем!
-
-### Доступ через ClusterIP (port-forward)
-
-Если ваше приложение имеет сервис с типом ClusterIP:
-
-1. **Установите приложение (например, через Helm):**
-
-```bash
-make k8s helm apply kubernetes my-app bitnami/nginx
-```
-
-2. **Узнайте имя сервиса:**
-
-```bash
-# Откройте shell в контейнере
-make k8s shell kubernetes
-
-# Посмотрите сервисы
-kubectl get svc -A
-
-# Выход из контейнера
-exit
-```
-
-3. **Создайте port-forward вручную:**
-
-```bash
-# Экспортируйте kubeconfig
-export KUBECONFIG=$(pwd)/kubeconfig
-
-# Создайте port-forward
-# Синтаксис: kubectl port-forward -n <namespace> svc/<service-name> <local-port>:<service-port>
-kubectl port-forward -n default svc/my-app-service 8080:80
-```
-
-4. **Откройте приложение:**
-
-```bash
-# Доступно на localhost:8080
-curl http://localhost:8080
-open http://localhost:8080
-```
-
-**Примечание:** Port-forward запустится в фоне. Для остановки нажмите `Ctrl+C` или найдите процесс и завершите его:
-
-```bash
-# Найти процесс port-forward
-ps aux | grep "kubectl port-forward"
-
-# Завершить процесс (замените PID)
-kill <PID>
-```
-
-### Автоматический port-forward для пользовательских приложений
-
-Если вы хотите, чтобы port-forward создавался автоматически, добавьте порт в пресет:
-
-```yaml
-# molecule/presets/k8s/kubernetes.yml
-addon_ports:
-  # ... существующие порты аддонов
-  my_app: 8080  # Ваш порт
-```
-
-Затем в коде `scripts/portforward.py` добавьте логику для этих портов. Однако, это требует знания имени сервиса и namespace заранее.
-
-**Рекомендация:** Для пользовательских приложений используйте ручной port-forward или Ingress.
-
-## Примеры использования
-
-### Создание и настройка кластера
-
-```bash
-# 1. Создать кластер с аддонами (port-forward создастся автоматически!)
-make k8s create kubernetes
-
-# 2. Проверить статус
-make k8s status kubernetes
-
-# 3. Проверить port-forward
+# Список активных портов
 make k8s portforward list
 
-# 4. Получить kubeconfig
-make k8s config kubernetes
-
-# 5. Использовать kubeconfig
-export KUBECONFIG=kubeconfig
-kubectl get nodes
-kubectl get pods -A
-
-# 6. Открыть Grafana в браузере
-open http://localhost:3000
-# Логин: admin
-# Пароль: (получить командой выше)
-```
-
-### Работа с Helm
-
-```bash
-# 1. Добавить репозиторий
-make k8s helmrepo add kubernetes bitnami https://charts.bitnami.com/bitnami
-
-# 2. Посмотреть доступные charts
-make k8s helmrepo packages kubernetes bitnami
-
-# 3. Установить nginx
-make k8s helm apply kubernetes nginx bitnami/nginx
-
-# 4. Проверить статус
-make k8s helm status kubernetes nginx
-
-# 5. Посмотреть все релизы
-make k8s helm list kubernetes
-
-# 6. Откатить релиз
-make k8s helm rollback kubernetes nginx
-
-# 7. Удалить релиз
-make k8s helm delete kubernetes nginx
-```
-
-### Работа с манифестами
-
-```bash
-# 1. Применить манифест из URL
-make k8s manifest apply kubernetes https://k8s.io/examples/application/deployment.yaml
-
-# 2. Применить манифест из файла
-make k8s manifest apply kubernetes ./manifests/my-app.yaml
-
-# 3. Обновить манифест
-make k8s manifest update kubernetes ./manifests/my-app.yaml
-
-# 4. Удалить ресурсы
-make k8s manifest delete kubernetes ./manifests/my-app.yaml
-```
-
-### Управление портами
-
-```bash
-# Если нужно пересоздать port-forward
-make k8s portforward recreate
-
-# Посмотреть активные port-forward
-make k8s portforward list
-
-# Удалить конкретный порт (например, 3000 для Grafana)
+# Удалить конкретный порт
 make k8s portforward delete 3000
 
-# Удалить все port-forward
+# Очистить все порты
 make k8s portforward clear
+
+# Пересоздать порты
+make k8s portforward recreate
 ```
 
-### Полное удаление кластера
+### Ручной port-forward для своих сервисов
 
 ```bash
-# Удалит кластер, контейнеры и все port-forward
-make k8s destroy kubernetes
+# Подключиться к кластеру
+export KUBECONFIG=$(docker exec k8s-controller cat /root/.kube/config)
+
+# Создать port-forward
+kubectl port-forward -n default svc/my-service 8080:80
 ```
 
-### Работа внутри контейнера
+---
+
+## Мониторинг и логи
+
+### Детальный статус кластера
 
 ```bash
-# Открыть shell в контейнере k8s-controller
+make k8s status kubernetes
+```
+
+Показывает:
+- Узлы кластера
+- Namespaces
+- Pods
+- Services
+- Ingress
+- Deployments
+- DaemonSets
+- StatefulSets
+- PVC
+- События
+- Helm релизы
+- Использование ресурсов
+
+### Доступ к аддонам
+
+**Grafana:**
+```
+URL: http://localhost:3000
+Login: admin
+Password: admin
+```
+
+**Prometheus:**
+```
+URL: http://localhost:9090
+```
+
+**Kiali:**
+```
+URL: http://localhost:20001
+Login: admin
+Password: admin
+```
+
+### Логи контейнера
+
+```bash
+# Логи k8s-controller
+docker logs k8s-controller
+
+# Логи в реальном времени
+docker logs -f k8s-controller
+```
+
+### Логи кластера
+
+```bash
+# Логи конкретного pod
 make k8s shell kubernetes
+kubectl logs -n monitoring <pod-name>
 
-# Внутри контейнера:
-kind get clusters
-kubectl --context kind-lab get nodes
-istioctl --context kind-lab proxy-status
-kubectl --context kind-lab get pods -n monitoring
-helm list --all-namespaces
+# Все логи в namespace
+kubectl logs -n monitoring --all-containers=true --tail=100
 ```
 
+---
+
+## Конфигурация
+
+### Пресеты
+
+Пресеты находятся в `molecule/presets/k8s/`:
+
+**kubernetes.yml** - полный набор аддонов:
+- Ingress NGINX
+- Metrics Server
+- Istio
+- Kiali
+- Prometheus + Grafana
+
+### Структура пресета
+
+```yaml
+k8s_cluster:
+  name: lab
+  nodes: 1
+  
+addons:
+  ingress: true
+  metrics_server: true
+  istio: true
+  kiali: true
+  prometheus_stack: true
+
+addon_ports:
+  ingress_http: 8081
+  ingress_https: 8443
+  prometheus: 9090
+  grafana: 3000
+  kiali: 20001
+  metrics_server: 4443
+
+hosts:
+  - name: test1
+    image: centos8
+    systemd_defaults:
+      container: true
+  
+images:
+  centos8:
+    name: inecs/ansible-lab:centos8-latest
+```
+
+### Пользовательский пресет
+
+Создайте файл `molecule/presets/k8s/my-preset.yml`:
+
+```yaml
+k8s_cluster:
+  name: my-cluster
+  nodes: 2
+
+addons:
+  ingress: true
+  metrics_server: false
+  istio: false
+  kiali: false
+  prometheus_stack: false
+```
+
+Использование:
+```bash
+make k8s create my-preset
+```
+
+---
+
 ## Архитектура
 
 ```
-┌─────────────────────────────────────────────────────────┐
-│                   Docker Network: kind                  │
-│                                                         │
-│  ┌──────────────────────────────────────────────────┐  │
-│  │         Kind Cluster: "lab"                      │  │
-│  │  ┌──────────────┐  ┌──────────────┐             │  │
-│  │  │ Control Plane│  │   Worker 1   │             │  │
-│  │  │ Port 6443    │  │              │             │  │
-│  │  └──────────────┘  └──────────────┘             │  │
-│  │  ┌──────────────┐                               │  │
-│  │  │   Worker 2   │                               │  │
-│  │  └──────────────┘                               │  │
-│  │                                                 │  │
-│  │  ClusterIP Services:                            │  │
-│  │  - Prometheus :9090                             │  │
-│  │  - Grafana    :3000                             │  │
-│  │  - Kiali      :20001                            │  │
-│  │  - Ingress    :80 (HTTP), :443 (HTTPS)         │  │
-│  └──────────────────────────────────────────────────┘  │
-│                                                         │
-│  ┌──────────────┐                                      │
-│  │ k8s-controller│ ← kubectl port-forward             │
-│  │ (Kind, Helm) │                                      │
-│  └──────────────┘                                      │
-└─────────────────────────────────────────────────────────┘
-                              │
-                              │ kubectl port-forward
-                              │ (localhost)
-                              ▼
-┌─────────────────────────────────────────────────────────┐
-│                  Локальная машина                       │
-│                                                         │
-│  • localhost:9090 → Prometheus                          │
-│  • localhost:3000 → Grafana                             │
-│  • localhost:20001 → Kiali                              │
-│  • localhost:8081 → Ingress HTTP                        │
-│  • localhost:8443 → Ingress HTTPS                       │
-└─────────────────────────────────────────────────────────┘
+┌─────────────────────────────────────────────────────┐
+│              Локальная машина                      │
+│                                                     │
+│  ┌──────────────────────────────────────────────┐  │
+│  │  Makefile → Python скрипты → Docker API     │  │
+│  │  kubectl (port-forward)                      │  │
+│  └──────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────┘
+                        │
+                        ↓
+┌─────────────────────────────────────────────────────┐
+│           Docker: k8s-controller                    │
+│  ┌──────────────────────────────────────────────┐  │
+│  │ kind, kubectl, helm, istioctl                │  │
+│  └──────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────┘
+                        │
+                        ↓
+┌─────────────────────────────────────────────────────┐
+│            Docker сеть: kind                        │
+│  ┌──────────────────────────────────────────────┐  │
+│  │         Kind Kubernetes Cluster              │  │
+│  │  • Control Plane (6443)                      │  │
+│  │  • Worker Nodes                              │  │
+│  │  • Services (ClusterIP)                      │  │
+│  │  • Ingress Controller                        │  │
+│  │  • Istio Service Mesh                        │  │
+│  └──────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────┘
 ```
 
-## Настройка портов аддонов
+### Компоненты
 
-Вы можете настроить порты для port-forward в пресете:
+1. **k8s-controller** - контейнер с инструментами управления
+2. **Kind кластер** - Kubernetes кластер в Docker контейнерах
+3. **Port-forward** - локальные процессы на хосте
+4. **Ingress** - маршрутизация трафика внутрь кластера
 
-```yaml
-kind_clusters:
-  - name: lab
-    workers: 2
-    addons:
-      prometheus_stack: true
-      kiali: true
-    addon_ports:
-      prometheus: 9090   # Port-forward для Prometheus
-      grafana: 3000      # Port-forward для Grafana
-      kiali: 20001       # Port-forward для Kiali
-      ingress_http: 8081 # Port-forward для Ingress HTTP
-      ingress_https: 8443 # Port-forward для Ingress HTTPS
-      metrics_server: 4443 # Port-forward для Metrics Server
+---
+
+## Доступ к приложениям
+
+### Доступ через Ingress
+
+1. Создайте Ingress манифест
+2. Примените через `make k8s manifest apply`
+3. Запись автоматически добавится в `/etc/hosts`
+4. Приложение доступно по доменному имени
+
+### Доступ через port-forward
+
+Для ClusterIP сервисов:
+```bash
+kubectl port-forward -n namespace svc/service-name 8080:80
 ```
 
+Доступ: http://localhost:8080
+
+### Доступ внутри кластера
+
+Из другого pod:
+```bash
+kubectl exec -it pod-name -- curl http://service-name.namespace:80
+```
+
+---
+
 ## Кроссплатформенность
 
-Port-forward работает одинаково на **macOS** и **Linux**:
+### Поддерживаемые платформы
 
-### macOS
+- **macOS (Intel & Apple Silicon)** - полная поддержка
+- **Linux (amd64 & arm64)** - полная поддержка
+- **Windows** - через WSL2
 
-```bash
-# Проверка установки
-python3 --version
-kubectl version --client
+### Проблемы на разных платформах
 
-# Работа с port-forward
-make k8s portforward create
-make k8s portforward list
-```
+**Apple Silicon (M1/M2):**
+- Используется ARM64 образы
+- Автоматическое определение архитектуры
 
-### Linux
+**Linux:**
+- Требуются права на Docker socket
+- Возможны проблемы с selinux
 
-```bash
-# Проверка установки
-python3 --version
-kubectl version --client
+---
 
-# Работа с port-forward (то же самое!)
-make k8s portforward create
-make k8s portforward list
-```
+## Подробная документация по скриптам
 
-**Важно:** Port-forward работает идентично на обеих платформах, так как использует стандартные утилиты:
-- `kubectl` (кроссплатформенный)
-- Python 3 (кроссплатформенный)
-- `kubectl port-forward` команда (кроссплатформенная)
+Для подробного описания работы всех скриптов управления Kubernetes смотрите:
+
+📖 [Документация по скриптам Kubernetes](k8s-scripts.md)
+
+Включает:
+- Описание каждого скрипта
+- Принцип работы
+- Примеры использования
+- Архитектура взаимодействия
+- Отладка
+
+---
 
 ## Best Practices
 
-1. **Порты:** Port-forward создается автоматически при создании кластера - не нужно делать это вручную
-2. **Локальные зависимости:** Установите Python 3 и kubectl на локальной машине для работы port-forward
-3. **Минимальные ресурсы:** Для быстрого тестирования используйте `workers: 0` (только control-plane)
-4. **Production-like:** Для реалистичных тестов используйте `workers: 2-3`
-5. **Аддоны:** Включайте только необходимые аддоны для уменьшения времени создания
-6. **Удаление:** Используйте `make k8s destroy` - он автоматически очистит port-forward
-7. **Helm:** Используйте официальные Helm charts из проверенных репозиториев
-8. **Изоляция:** Каждый preset может иметь свой уникальный кластер с разными настройками
-9. **Ingress vs ClusterIP:** Используйте Ingress для доступа по доменным именам, ClusterIP + port-forward для прямого доступа к сервисам
+### 1. Используйте пресеты
+
+Не создавайте кластеры вручную, используйте пресеты для консистентности.
+
+### 2. Очищайте после работы
+
+```bash
+# После тестирования
+make k8s destroy kubernetes
+```
+
+### 3. Проверяйте статус
+
+```bash
+# Регулярно проверяйте статус
+make k8s status kubernetes
+```
+
+### 4. Используйте Helm для сложных приложений
+
+Для многослойных приложений лучше использовать Helm вместо сырых манифестов.
+
+### 5. Логируйте изменения
+
+Все изменения в кластере через `make k8s` автоматически логируются.
+
+---
 
 ## Troubleshooting
 
-### Port-forward не работает
-
-```bash
-# Проверить, что порт не занят
-lsof -i :3000
-
-# Пересоздать port-forward
-make k8s portforward recreate
-
-# Проверить активные port-forward
-make k8s portforward list
-
-# Проверить, что kubectl установлен локально
-kubectl version --client
-```
-
 ### Кластер не создается
 
+**Проблема:** `kind create cluster` завершается с ошибкой
+
+**Решение:**
 ```bash
-# Проверить логи
-docker logs k8s-controller
+# Проверьте Docker
+docker ps
 
-# Проверить доступное место на диске
-df -h
+# Перезапустите Docker
+sudo systemctl restart docker
 
-# Проверить Docker ресурсы
-docker system df
+# Очистите старые кластеры
+kind delete cluster --all
 ```
 
-### Проблемы с аддонами
+### Port-forward не работает
 
+**Проблема:** Невозможно подключиться к порту
+
+**Решение:**
 ```bash
-# Проверить статус подов
-kubectl get pods -A
+# Проверьте процессы
+make k8s portforward list
 
-# Проверить сервисы
-kubectl get svc -A
+# Пересоздайте порты
+make k8s portforward recreate
 
-# Проверить логи
-kubectl logs -n monitoring -l app.kubernetes.io/name=grafana
+# Проверьте, что порт свободен
+lsof -i :3000
 ```
 
-### Проблемы с Istio
+### kubectl не подключается
 
+**Проблема:** `kubectl get nodes` выдает ошибку
+
+**Решение:**
 ```bash
-# Открыть shell в контейнере
+# Проверьте контейнер
+docker ps | grep k8s-controller
+
+# Зайдите в контейнер
 make k8s shell kubernetes
 
-# Внутри контейнера:
-istioctl proxy-status --context kind-lab
-istioctl proxy-config --context kind-lab
+# Проверьте кластер
+kubectl get nodes
+
+# Если не работает, пересоздайте кластер
+make k8s destroy kubernetes
+make k8s create kubernetes
 ```
 
-### Python не установлен
+### Аддоны не устанавливаются
 
+**Проблема:** Grafana/Prometheus/Kiali не доступны
+
+**Решение:**
 ```bash
-# macOS
-brew install python3
+# Проверьте статус кластера
+make k8s status kubernetes
 
-# Ubuntu/Debian
-sudo apt update && sudo apt install -y python3 python3-pip
+# Проверьте pods
+make k8s shell kubernetes
+kubectl get pods -n monitoring
+kubectl logs -n monitoring <pod-name>
 
-# Проверка
-python3 --version
+# Пересоздайте кластер
+make k8s destroy kubernetes
+make k8s create kubernetes
 ```
 
-## Дополнительные ресурсы
+### Ingress не работает
 
-- [Kind Documentation](https://kind.sigs.k8s.io/docs/)
-- [Istio Documentation](https://istio.io/latest/docs/)
-- [Kiali Documentation](https://kiali.io/documentation/)
-- [Prometheus Operator](https://prometheus-operator.dev/)
-- [Helm Documentation](https://helm.sh/docs/)
+**Проблема:** Доменные имена не резолвятся
+
+**Решение:**
+```bash
+# Проверьте /etc/hosts
+cat /etc/hosts | grep k8s
+
+# Добавьте вручную
+sudo scripts/manage_hosts.py add
+
+# Проверьте Ingress
+make k8s shell kubernetes
+kubectl get ingress --all-namespaces
+```
+
+### Helm чарты не устанавливаются
+
+**Проблема:** `helm install` завершается с ошибкой
+
+**Решение:**
+```bash
+# Проверьте репозитории
+make k8s helmrepo list kubernetes
+
+# Обновите репозитории
+make k8s helmrepo update kubernetes stable
+
+# Проверьте логи
+make k8s shell kubernetes
+kubectl logs -l app=<release-name>
+```
+
+### Контейнер k8s-controller не запускается
+
+**Проблема:** `docker: Error response from daemon: ...`
+
+**Решение:**
+```bash
+# Проверьте образ
+docker images | grep k8s
+
+# Пересоберите образ
+make docker build-image IMAGE=k8s-amd64
+make docker build-image IMAGE=k8s-arm64
+
+# Проверьте Docker
+docker system prune -f
+```
+
+---
+
+## Контакты
+
+- **Автор:** Сергей Антропов
+- **Сайт:** https://devops.org.ru
+- **GitHub:** https://github.com/your-repo
+
+---
+
+## Лицензия
+
+MIT