DevOpsLab/docs/kubernetes-kind.md

# Kubernetes Kind Кластеры

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

## Описание

Проект поддерживает автоматическое создание и управление 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-узлов
- ✅ Автоматическая установка аддонов (Ingress NGINX, Metrics Server, Istio, Kiali, Prometheus Stack)
- ✅ **Автоматический port-forward** для доступа к аддонам
- ✅ Работа с Helm (установка, удаление, обновление чартов)
- ✅ Работа с Kubernetes манифестами
- ✅ Управление Docker контейнерами в лабораторной сети
- ✅ Интеграция с Istio Service Mesh

## Команды

### Создание кластера

```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** для доступа к сервисам

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

```bash
# Удаление кластера (с автоматической очисткой port-forward)
make k8s destroy [preset]

# Остановка кластера (без удаления)
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 **создается автоматически** при создании кластера и **удаляется автоматически** при его уничтожении.

```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
```

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

### Пресеты Kubernetes хранятся в `molecule/presets/k8s/`

#### Минимальный кластер (`k8s-minimal.yml`)

```yaml
kind_clusters:
  - name: minimal
    workers: 0  # Только control-plane узел
    api_port: 6443
```

#### Полный кластер с аддонами (`kubernetes.yml`)

```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
spec:
  rules:
  - host: my-app.local
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: my-app-service
            port:
              number: 80
```

2. **Примените манифест:**

```bash
make k8s manifest apply kubernetes my-app-ingress.yaml
```

3. **Добавьте домен в hosts файл:**

**macOS/Linux:**
```bash
echo "127.0.0.1 my-app.local" | sudo tee -a /etc/hosts
```

4. **Откройте приложение через Ingress порт:**

```bash
# HTTP через Ingress
curl http://my-app.local:8081
# или в браузере
open http://my-app.local:8081

# 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
```

### Полное удаление кластера

```bash
# Удалит кластер, контейнеры и все port-forward
make k8s destroy kubernetes
```

### Работа внутри контейнера

```bash
# Открыть shell в контейнере k8s-controller
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: 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                       │
└─────────────────────────────────────────────────────────┘
```

## Настройка портов аддонов

Вы можете настроить порты для port-forward в пресете:

```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
```

## Кроссплатформенность

Port-forward работает одинаково на **macOS** и **Linux**:

### macOS

```bash
# Проверка установки
python3 --version
kubectl version --client

# Работа с port-forward
make k8s portforward create
make k8s portforward list
```

### Linux

```bash
# Проверка установки
python3 --version
kubectl version --client

# Работа с port-forward (то же самое!)
make k8s portforward create
make k8s portforward list
```

**Важно:** Port-forward работает идентично на обеих платформах, так как использует стандартные утилиты:
- `kubectl` (кроссплатформенный)
- Python 3 (кроссплатформенный)
- `kubectl port-forward` команда (кроссплатформенная)

## 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 для прямого доступа к сервисам

## 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 k8s-controller

# Проверить доступное место на диске
df -h

# Проверить Docker ресурсы
docker system df
```

### Проблемы с аддонами

```bash
# Проверить статус подов
kubectl get pods -A

# Проверить сервисы
kubectl get svc -A

# Проверить логи
kubectl logs -n monitoring -l app.kubernetes.io/name=grafana
```

### Проблемы с Istio

```bash
# Открыть shell в контейнере
make k8s shell kubernetes

# Внутри контейнера:
istioctl proxy-status --context kind-lab
istioctl proxy-config --context kind-lab
```

### Python не установлен

```bash
# macOS
brew install python3

# Ubuntu/Debian
sudo apt update && sudo apt install -y python3 python3-pip

# Проверка
python3 --version
```

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

- [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/)