docs/kubernetes-kind.md

@@ -7,17 +7,60 @@
 
 Проект поддерживает автоматическое создание и управление Kubernetes кластерами на базе [Kind](https://kind.sigs.k8s.io/) для тестирования в изолированной лабораторной среде.
 
+## Требования к системе
+
+Для работы с Kubernetes кластерами **на локальной машине** требуется установить:
+
+### 1. Python 3
+
+Port-forward управляется Python скриптом. Установите Python 3:
+
+**macOS:**
+```bash
+brew install python3
+```
+
+**Ubuntu/Debian:**
+```bash
+sudo apt update && sudo apt install -y python3 python3-pip
+```
+
+**CentOS/RHEL:**
+```bash
+sudo yum install -y python3 python3-pip
+```
+
+### 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
+python3 --version
+kubectl version --client
+```
+
 ## Возможности
 
-- Создание Kind кластеров с настраиваемым количеством worker-узлов
+- ✅ Создание Kind кластеров с настраиваемым количеством worker-узлов
-- Автоматическая установка аддонов:
+- ✅ Автоматическая установка аддонов (Ingress NGINX, Metrics Server, Istio, Kiali, Prometheus Stack)
-  - Ingress NGINX Controller
+- ✅ **Автоматический port-forward** для доступа к аддонам
-  - Metrics Server
+- ✅ Работа с Helm (установка, удаление, обновление чартов)
-  - Istio Service Mesh
+- ✅ Работа с Kubernetes манифестами
-  - Kiali (визуализация Istio)
+- ✅ Управление Docker контейнерами в лабораторной сети
-  - Prometheus Stack (Prometheus + Grafana)
+- ✅ Интеграция с Istio Service Mesh
-- Настройка портов для внешнего доступа к аддонам
-- Интеграция с Docker контейнерами в одной лабораторной сети
 
 ## Команды
 
@@ -34,26 +77,148 @@ 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** для доступа к сервисам
+
 ### Управление кластером
 
 ```bash
-# Удаление кластера
+# Удаление кластера (с автоматической очисткой port-forward)
 make k8s destroy [preset]
 
 # Остановка кластера (без удаления)
-make k8s stop [cluster]
+make k8s stop [preset]
 
 # Запуск остановленного кластера
-make k8s start [cluster]
+make k8s start [preset]
 
 # Проверка статуса кластера
-make k8s status [cluster]
+make k8s status [preset]
 
 # Получение kubeconfig для подключения
-make k8s config [cluster]
+make k8s config [preset]
 
-# Открытие shell в контейнере
+# Открытие shell в контейнере k8s-controller
-make k8s shell
+make k8s shell [preset]
+
+# Просмотр узлов кластера
+make k8s nodes [preset]
+```
+
+### Port-Forward (Проброс портов)
+
+Port-forward **создается автоматически** при создании кластера и **удаляется автоматически** при его уничтожении.
+
+```bash
+# Создать port-forward для всех сервисов из preset
+make k8s portforward create [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
+```
+
+**Порты по умолчанию:**
+- **Prometheus:** 9090
+- **Grafana:** 3000
+- **Kiali:** 20001
+- **Ingress HTTP:** 8081
+- **Ingress HTTPS:** 8443
+- **Metrics Server:** 4443
+
+### Установка аддонов из манифестов
+
+```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
+```
+
+### Работа с манифестами
+
+```bash
+# Применить манифест
+make k8s manifest apply [preset] [manifest_url_or_path]
+
+# Удалить ресурсы из манифеста
+make k8s manifest delete [preset] [manifest_url_or_path]
+
+# Обновить манифест (apply с --force)
+make k8s manifest update [preset] [manifest_url_or_path]
+
+# Примеры:
+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
+```
+
+### Работа с Helm
+
+#### Установка и управление релизами
+
+```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]
+
+# Список Helm репозиториев
+make k8s helmrepo list [preset]
+
+# Удалить 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
 ```
 
 ## Конфигурация
@@ -82,18 +247,19 @@ kind_clusters:
       istio: true
       kiali: true
       prometheus_stack: true
-    ingress_host_http_port: 8081
+    # Порты для port-forward
-    ingress_host_https_port: 8443
-    # Порты для внешнего доступа к аддонам
     addon_ports:
+      ingress_http: 8081
+      ingress_https: 8443
       prometheus: 9090
       grafana: 3000
       kiali: 20001
+      metrics_server: 4443
 ```
 
 ## Доступ к аддонам
 
-После создания кластера с аддонами, они доступны на следующих портах:
+После создания кластера с аддонами, они доступны через **автоматический port-forward**:
 
 ### Prometheus
 ```bash
@@ -136,68 +302,112 @@ https://localhost:8443
 ### Создание и настройка кластера
 
 ```bash
-# 1. Создать кластер с аддонами
+# 1. Создать кластер с аддонами (port-forward создастся автоматически!)
 make k8s create kubernetes
 
 # 2. Проверить статус
-make k8s status
+make k8s status kubernetes
 
-# 3. Получить kubeconfig
+# 3. Проверить port-forward
-make k8s config lab
+make k8s portforward list
 
-# 4. Использовать kubeconfig
+# 4. Получить kubeconfig
+make k8s config kubernetes
+
+# 5. Использовать kubeconfig
 export KUBECONFIG=kubeconfig
 kubectl get nodes
 kubectl get pods -A
 
-# 5. Открыть Grafana в браузере
+# 6. Открыть Grafana в браузере
 open http://localhost:3000
 # Логин: admin
 # Пароль: (получить командой выше)
 ```
 
-### Управление кластером
+### Работа с Helm
 
 ```bash
-# Остановить кластер (без удаления)
+# 1. Добавить репозиторий
-make k8s stop lab
+make k8s helmrepo add kubernetes bitnami https://charts.bitnami.com/bitnami
 
-# Запустить остановленный кластер
+# 2. Посмотреть доступные charts
-make k8s start lab
+make k8s helmrepo packages kubernetes bitnami
 
-# Проверить конкретный кластер
+# 3. Установить nginx
-make k8s status lab
+make k8s helm apply kubernetes nginx bitnami/nginx
 
-# Получить kubeconfig для конкретного кластера
+# 4. Проверить статус
-make k8s config lab
+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
+```
+
+### Полное удаление кластера
+
+```bash
+# Удалит кластер, контейнеры и все port-forward
 make k8s destroy kubernetes
 ```
 
 ### Работа внутри контейнера
 
 ```bash
-# Открыть shell в контейнере ansible-controller
+# Открыть shell в контейнере k8s-controller
-make k8s shell
+make k8s shell kubernetes
 
 # Внутри контейнера:
 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
 ```
 
 ## Архитектура
 
 ```
 ┌─────────────────────────────────────────────────────────┐
-│                   Docker Network: labnet                │
+│                   Docker Network: kind                  │
-│                                                         │
-│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐ │
-│  │ Ubuntu22     │  │  Debian12    │  │ Ansible      │ │
-│  │ Container    │  │  Container   │  │ Controller   │ │
-│  └──────────────┘  └──────────────┘  └──────────────┘ │
 │                                                         │
 │  ┌──────────────────────────────────────────────────┐  │
 │  │         Kind Cluster: "lab"                      │  │
@@ -209,19 +419,36 @@ kubectl --context kind-lab get pods -n monitoring
 │  │  │   Worker 2   │                               │  │
 │  │  └──────────────┘                               │  │
 │  │                                                 │  │
-│  │  NodePort Services:                             │  │
+│  │  ClusterIP Services:                            │  │
 │  │  - Prometheus :9090                             │  │
 │  │  - Grafana    :3000                             │  │
 │  │  - Kiali      :20001                            │  │
-│  │  - Ingress    :8081 (HTTP), :8443 (HTTPS)      │  │
+│  │  - 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                       │
 └─────────────────────────────────────────────────────────┘
 ```
 
 ## Настройка портов аддонов
 
-Вы можете настроить порты для внешнего доступа в пресете:
+Вы можете настроить порты для port-forward в пресете:
 
 ```yaml
 kind_clusters:
@@ -231,26 +458,48 @@ kind_clusters:
       prometheus_stack: true
       kiali: true
     addon_ports:
-      prometheus: 9090   # Prometheus UI
+      prometheus: 9090   # Port-forward для Prometheus
-      grafana: 3000      # Grafana UI
+      grafana: 3000      # Port-forward для Grafana
-      kiali: 20001       # Kiali UI
+      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
 ```
 
 ## Best Practices
 
-1. **Минимальные ресурсы:** Для быстрого тестирования используйте `workers: 0` (только control-plane)
+1. **Порты:** Port-forward создается автоматически при создании кластера - не нужно делать это вручную
-2. **Production-like:** Для реалистичных тестов используйте `workers: 2-3`
+2. **Локальные зависимости:** Установите Python 3 и kubectl на локальной машине для работы port-forward
-3. **Аддоны:** Включайте только необходимые аддоны для уменьшения времени создания
+3. **Минимальные ресурсы:** Для быстрого тестирования используйте `workers: 0` (только control-plane)
-4. **Изоляция:** Каждый preset может иметь свой уникальный кластер с разными настройками
+4. **Production-like:** Для реалистичных тестов используйте `workers: 2-3`
-5. **Порты:** Используйте разные порты для разных кластеров, если запускаете несколько
+5. **Аддоны:** Включайте только необходимые аддоны для уменьшения времени создания
+6. **Удаление:** Используйте `make k8s destroy` - он автоматически очистит port-forward
+7. **Helm:** Используйте официальные Helm charts из проверенных репозиториев
+8. **Изоляция:** Каждый preset может иметь свой уникальный кластер с разными настройками
 
 ## Troubleshooting
 
+### Port-forward не работает
+
+```bash
+# Проверить, что порт не занят
+lsof -i :3000
+
+# Пересоздать port-forward
+make k8s portforward recreate
+
+# Проверить активные port-forward
+make k8s portforward list
+
+# Проверить, что kubectl установлен локально
+kubectl version --client
+```
+
 ### Кластер не создается
 
 ```bash
 # Проверить логи
-docker logs ansible-controller
+docker logs k8s-controller
 
 # Проверить доступное место на диске
 df -h
@@ -268,25 +517,32 @@ kubectl get pods -A
 # Проверить сервисы
 kubectl get svc -A
 
-# Проверить порты
+# Проверить логи
-kubectl get svc -n monitoring
+kubectl logs -n monitoring -l app.kubernetes.io/name=grafana
 ```
 
 ### Проблемы с Istio
 
 ```bash
-# Переустановить Istio
+# Открыть shell в контейнере
-istioctl uninstall -y --context kind-lab
+make k8s shell kubernetes
-istioctl install -y --set profile=demo --context kind-lab
+
+# Внутри контейнера:
+istioctl proxy-status --context kind-lab
+istioctl proxy-config --context kind-lab
 ```
 
-### Проблемы с Prometheus Stack
+### Python не установлен
 
 ```bash
-# Переустановить
+# macOS
-helm uninstall monitoring -n monitoring
+brew install python3
-helm upgrade --install monitoring prometheus-community/kube-prometheus-stack \
+
-  --namespace monitoring --kube-context kind-lab
+# Ubuntu/Debian
+sudo apt update && sudo apt install -y python3 python3-pip
+
+# Проверка
+python3 --version
 ```
 
 ## Дополнительные ресурсы
@@ -295,3 +551,4 @@ helm upgrade --install monitoring prometheus-community/kube-prometheus-stack \
 - [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/)